@use JSDoc

语法

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

概述

@event 标记允许你记录一个可以触发的事件。一个典型的事件由一个具有已定义属性集的对象表示。

一旦你使用 @event 标记定义了一个特定类型的事件，你就可以使用 @fires 标记来表示一个方法可以触发该事件。你还可以使用 @listens 标记来表示一个符号侦听该事件。

JSDoc 会自动在前缀每个事件的名称中添加命名空间 event:。通常，当你链接到另一个文档中的事件时，你必须包含此命名空间。（@fires 标记是一个值得注意的例外；它允许你省略命名空间。）

注意：JSDoc 3 使用 @event 文档记录事件的内容。相反，JSDoc Toolkit 2 使用 @event 文档记录当同名事件发生时可以触发的函数。

示例

以下示例展示了如何在 Hurl 类中记录一个名为 snowball 的事件。该事件包含一个具有单个属性的对象。

将函数调用记录为事件
/**
 * 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
    });
};
使用命名文档记录事件
/**
 * 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.
 */