如何使用JSDoc标注类可监听的事件？

对于继承自EventEmitter的类，即便事件是内部逻辑（比如串口回调）触发的，依然可以通过@event和@fires标签完成规范标注，以下是修改后的示例代码：

/**
 * 串口包装类，继承自EventEmitter
 * @extends EventEmitter
 * @fires MyWrap#open - 串口打开成功时触发
 * @fires MyWrap#close - 串口关闭时触发
 * @fires MyWrap#data - 收到串口数据时触发
 * @fires MyWrap#error - 串口发生错误时触发
 * @fires MyWrap#log - 输出日志时触发
 */
class MyWrap extends EventEmitter {
    #port
    /**
     * @typedef {Object} ConstructorObject
     * @property {string} path - 串口路径
     * @property {number} [baudRate=9600] - 波特率，默认值9600
     */
    /**
     * @param {ConstructorObject} options - 构造参数
     */
    constructor({
        path,
        baudRate = 9600,
    }) {
        super()
        this.#port = new SerialPort({ path: path, baudRate: baudRate})
        this.#port.on('data', response => {
            /**
             * 串口数据事件
             * @event MyWrap#data
             * @type {Buffer} 收到的串口原始数据
             */
            this.emit('data', response)
        })
        this.#port.on(
            'open', 
            () => {
                this.#log(`${this.#port.path} open successful`)
                /**
                 * 串口打开成功事件
                 * @event MyWrap#open
                 */
                this.emit('open')
            }
        )
        this.#port.on(
            'close', 
            () => {
                this.#tryOpen()
                this.#log(`${this.#port.path} closed`)
                /**
                 * 串口关闭事件
                 * @event MyWrap#close
                 */
                this.emit('close')
            }
        )
        this.#port.on('error', this.#error)
    }

    /**
     * 处理串口错误并触发error事件
     * @param {Error} error - 错误对象
     * @fires MyWrap#error
     */
    #error(error) {
        /**
         * 串口错误事件
         * @event MyWrap#error
         * @type {string} 格式化后的错误信息
         */
        this.emit('error', `${this.#port.path}: ${error?.message ?? error}`)
    } 

    /**
     * 生成日志并触发log事件
     * @param {string} message - 日志内容
     * @fires MyWrap#log
     */
    #log(message) {
        /**
         * 日志输出事件
         * @event MyWrap#log
         * @type {string} 日志消息
         */
        this.emit('log', message)
    } 
    // ...
 }

标注说明 #

1. @extends EventEmitter：明确类的继承关系，让JSDoc工具识别这是一个事件发射器类。
2. @event：定义事件本身，格式为@event <类名>#<事件名>，搭配@type可以标注事件携带的参数类型，让使用者清楚事件触发时会传递什么数据。
3. @fires：在触发事件的方法（包括私有方法）上标注，说明该方法会触发哪个事件，即使事件是内部间接触发的，也可以用这个标签关联触发动作和事件定义。
4. 类的主文档块中集中列出所有@fires，可以让使用者快速了解该类支持监听的所有事件；每个emit处的@event则提供事件的详细参数说明，两者结合能提供完整的事件文档。

内容的提问来源于stack exchange，提问作者yujen