How do I JSDoc custom EventEmitter on events in Visual Studio Code?

Question

I've been working on a Node.js project and only just noticed that Visual Studio Code provides information about base EventEmitter objects. So I imagine it should be possible to provide JSDoc for custom ones too.

I've already attempted following the JSDoc http://usejsdoc.org/tags-event.html documentation but doesn't seem to pick up.

I don't know if this is effecting it but I'm using the ES6 class where the events get processed in a function outside it but it's inside the same script.

This is the test code.

// voice
if (voice) {
  try {
    /**
     * Voice event.
     *
     * @event TelegramBot#voice
     * @type {object}
     * @property {object} chat - [object Chat]
     * @property {number} date - Date when content was sent.
     * @property {object} from - [object User]
     * @property {number} message_id - Message id.
     * @property {string} caption - Caption added to message. Value is undefined if none is added.
     * @property {object} voice - [object Voice]
     */
    context.emit('voice', chat, date, from, message_id, caption, voice)
  } catch (error) {
    context.emit('error', error)
  }
}

Answer 1

I found this question while attempting to do the same, so I kept searching and I found a possible solution, by overriding the addListener methods, and documenting them.

I successfully made it work for both NodeJS and browser JS.

Result in VSCode

Typedef

First, create the typedef with your events names :

/**
 * @typedef {["someEvent" | "someOtherEvent", ...any[]]} eventsDef
 */

I am using the spread syntax since I don't know how many arguments the user will pass to the method.

Implementation

For NodeJS:

The class needs to override the on and addListener methods, document the arguments, and simply call the parent's own method :

class Test extends EventEmitter {

  /**
   * @param {eventsDef} args
   */
  addListener(...args) {
    super.addListener(...args);
  }

  /**
   * @param {eventsDef} args
   */
  on(...args) {
    super.on(...args);
  }

  fireEvent() {
    this.emit("someEvent", "someValue");
  }
}

Then you can use this class like so :

const t = new Test();

t.on("someEvent", (val) => console.log(val));

t.fireEvent(); // Outputs "someValue"

For the browser:

The class needs to extends EventTarget and override the addEventListener method.

Here is the snippet :

class Test extends EventTarget {
  /**
   * @param {["someEvent" | "someOtherEvent", ...any[]]} args
   */
  addEventListener(...args) {
    super.addEventListener(...args);
  }
  
  fireEvent() {
    this.dispatchEvent(new CustomEvent("someEvent", {detail: "someValue"}))
  }
}

const t = new Test();

t.addEventListener("someEvent", val => console.log(val.detail));


document.querySelector("button").addEventListener("click", () => {
  t.fireEvent();
})

<button>Fire event</button>