@event ​

Document an event.

Syntax ​

@event <className>#[event:]<eventName>

Overview ​

The @event tag allows you to document an event that can be fired. A typical event is represented by an object with a defined set of properties.

Once you have used the @event tag to define a specific type of event, you can use the @fires tag to indicate that a method can fire that event. You can also use the @listens tag to indicate that a symbol listens for the event.

JSDoc automatically prepends the namespace event: to each event's name. In general, you must include this namespace when you link to the event in another doclet. (The @fires tag is a notable exception; it allows you to omit the namespace.)

Note: JSDoc 3 uses @event doclets to document the content of an event. In contrast, JSDoc Toolkit 2 used @event doclets to identify a function that can be fired when an event of the same name occurs.

Examples ​

The following examples show how to document an event in the Hurl class called snowball. The event contains an object with a single property.

Documenting a function call as an event

/**
 * Throw a snowball.
 *
 * @fires Hurl#snowball
 */
Hurl.prototype.snowball = function() {
    /**
     * Snowball event.
     *
     * @event Hurl#snowball
     * @type {object}
     * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
     */
    this.emit('snowball', {
        isPacked: this._snowball.isPacked
    });
};

Using a named doclet to document an event

/**
 * Throw a snowball.
 *
 * @fires Hurl#snowball
 */
Hurl.prototype.snowball = function() {
    // ...
};

/**
 * Snowball event.
 *
 * @event Hurl#snowball
 * @type {object}
 * @property {boolean} isPacked - Indicates whether the snowball is tightly packed.
 */