Enhance documentation for atom.commands.dispatch() method

[trusktr]

Add comments to clarify that atom.commands.dispatch() can pass arguments to commands.

I haven't tested it yet, but this detail arg seems to allow for the following ability:

atom.commands.add(`selector`, {
  'my:custom-command': event => console.log(event.detail),
})

And this:

atom.commands.onDidDispatch(event => {
  console.log(event.type, event.detail)
});

Technically we can dispatch a command like this too:

class MyCustomEvent extends Event {
  foo = 123
  bar = 456

  constructor(foo, bar) {
    this.foo = foo ?? this.foo
    this.bar = bar ?? this.bar
    super('my:custom-command')
  }
}

const event = MyCustomEvent(42, 84)

Object.defineProperty(event, 'target', { value: atom.workspace.element });
atom.commands.handleCommandEvent(event);

and the command handler could use those properties:

atom.commands.add('selector', {
  'my:custom-command': ({foo, bar}) => console.log(foo, bar), // logs "42 84"
})

A separate PR should be able to add arg support for key maps if it doesn't exist already (or document that if it does). For keymaps, the .detail property makes sense, as there'd be no way to handle custom event classes via static JSON (unless we maintained a map of class by their class name, and use their class name in the JSON).

[Copilot]

Pull request overview

Enhances the inline API documentation for CommandRegistry::dispatch() to clarify that command dispatch can carry arguments via event detail.

Changes:

• Add explanatory notes describing using dispatch() to pass arguments when keymaps can’t.
• Document the detail parameter as being assigned to the dispatched event’s .detail.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.