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

The @event tag in both JSDuck and jsdoc-toolkit are meant for the same thing - documenting events that get fired by a class.

Although jsdoc-toolkit docs look a bit confusing on this part, saying @event "describes an event handled by a class", which might make it look as if it's meant for documenting listeners. But looking at jsdoc-toolkit issue log we can see the feature was inspired by events in YUI, and as ExtJS is also grown out from YUI, it confirms the semantic equality of @event tag in both jsdoc-toolkit and JSDuck.

You however seem to be asking about event handlers - methods that are registered to handle the events fired by other classes. Like you have a showPopup method and you want to document that this method handles the click event on some button. That's the opposite of what @event tag is meant for.

But you really shouldn't document your event handlers in any special way - just documenting them as normal methods should be enough. It's the same as documenting which other methods call a particular method - it might be useful to provide this information sometimes, but doing it for all the methods is just silly.

In short. Methods and events are an interface to a class - they should get documented. Registering event handlers and calling methods is how you use the interface - that's an implementation detail, don't document it (at least not on the same level as your API documentation).

Answer 2

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.