What is the best way to use jsduck to document event handlers?

Question

What is the best sort of jsduck header to put over a method of a class (such as a ExtJS subclass) that handles an event? Jsduck seems to support the same tags as jsdoc, but I'm not sure if the @event tag is appropriate.

Answer 1

An event handler should be documented the same as any other method (@method, etc.). @event is tag you would use for a listenable event:

function Foo() {
    /**
     * Fired when a sandwich is made
     * @event sandwich-made
     * @param {my.ns.Sandwich} sandwich
     */
    this.listen('sandwich-made', this.onSandwichMade, this);
}

Where you document your events is subjective. You might do it like I did above if that is the only entry point to that event, or as is shown in the JsDuck docs, when event names are actually declared, if you do add them formally with an addEvents(events) method.

The docs are not explicit, but presumably any @event tag occurring in the context of a given object will be associated with that object.