@event

(Updated for JSDuck 4)

Synopsis:

@event
Documentation for the event.

@event name
Documentation for the event.

Documents an event (the name of the event can be left for auto-detection).

Example:

/**
 * @event click
 * Fired when element is clicked on.
 * @param {Ext.Element} el Target element of the click.
 * @param {Ext.EventObject} e The event object.
 */

See @param for further details on documenting event parameters.

Auto-detection

The @event tag is completely auto-detected when the doc-comment is followed by this.fireEvent() call:

/**
 * Fired when element is clicked on.
 * @param {Ext.Component} this
 * @param {String} value
 */
this.fireEvent("click", this, value);

The parameters still need to be documented explicitly, but @event tag won't be needed.

Event name is auto-detected when doc-comment with @event is followed by a string:

this.addEvents(
    /**
     * @event
     * Fired when element is clicked on.
     */
    "click"
);

or when followed by a property literal key:

this.addEvents({
    /**
     * @event
     * Fired when element is clicked on.
     */
    click: true
});

But in both cases the @event tag itself can't be left off - JSDuck won't otherwise understand that it's dealing with an event.

Ext4 event options

In Ext JS 4 each event gets a special event-options object automatically appended to its parameters list. This is the configuration object that was used for setting up a listener for the event.

JSDuck automatically detects if you are using Ext4 (by checking if any of the classes are defined with Ext.define) and then automatically appends the extra argument.

So if you wrote the first example at the top of this page in Ext 4 context, it will show up in documentation as if you had written:

/**
 * @event click
 * Fired when element is clicked on.
 * @param {Ext.Element} el Target element of the click.
 * @param {Ext.EventObject} e The event object.
 * @param {Object} eOpts The options object passed to {@link Ext.util.Observable#addListener}.
 */

The auto-detection can go wrong though. Especially as the Ext.define() construct has been back-ported to Ext JS 3.4.1. In such cases the auto-detection can be overridden with --ext4-events to force addition of the event options parameter, or with --no-ext4-events to force skipping the addition of it.

Preventable events

Ext 4 also more concretely defines a concept of preventable events. Returning false from such an event will stop the action, that is supposed to follow the event, from happening. JSDuck supports a special @preventable tag to mark up such events:

/**
 * @event beforeexpand
 * Fired before panel gets expanded.
 * @preventable
 */