@event

Table of Contents

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.
 */

© 2011–2017 the contributors to the JSDoc 3 documentation project
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://jsdoc.app/tags-event.html