node.jsjsdoc

How to use JSDoc to express what events a class can listen to


How to use JSDoc to express what events a class can listen to
This is a simplified example

//event: 'open', 'log', 'data', 'error', 'close'  
class MyWrap extends EventEmitter {
    #port
    /**
     * @typedef {Object} ConstructorObject
     * @property {string} path
     * @property {number} [baudRate=9600] 
     */
    /**
     * @param {ConstructorObject} options 
     */
    constructor({
        path,
        baudRate = 9600,
    }) {
        super()
        this.#port = new SerialPort({ path: path, baudRate: baudRate})
        this.#port.on('data', response => this.emit('data', response))
        this.#port.on(
            'open', 
            () => {
                this.#log(`${this.#port.path} open successful`)
                this.emit('open')
            }
        )
        this.#port.on(
            'close', 
            () => {
                this.#tryOpen()
                this.#log(`${this.#port.path} closed`)
                this.emit('close')
            }
        )
        this.#port.on('error', this.#error)
    }

    #error(error) {
        this.emit('error', `${this.#port.path}: ${error?.message ?? error}`)
    } 

    #log(message) {
        this.emit('log', message)
    } 
    .....
 }

I only found the usage of @fires
but it not triggered by calling a function
so i am not sure how to do


Solution

  • Using @fires is thre right way. You add all the events as part of the class definition. In your case:

    /**
     * @fires MyWrap#open
     * @fires MyWrap#log
     * @fires MyWrap#data.... and so on
     */
    class MyWrap extends EventEmitter {
    ..
    }
    

    If you want to docuemnt the event content types, just add this (can be written anywhere in the file)

    /**
     * @event MyWrap#log
     * @type {string}
     */
    
    /**
     * @event MyWrap#data
     * @type {Object}
     */