How to document an event emitter returned

Question

How to document the events emitted by stream returned in MyFunc() with JSDoc?

/**
 * [MyFunc description]
 * @param  {Object} opts - [description]
 * @return {Stream} - [description]
 */
function MyFunc (opts) {
  // stream is an EventEmitter
  var stream = new MyEventEmitter();

  stream.emit('event1', ... );
  stream.emit('event2', ... );

  return stream;
}

Answer 1

You can document these behaviors by documenting your events (event1, event2, ...) as @event MyFunc#event1 and MyFunc, or whoever does the emitting, with @fires MyFunc#event1.

You can also document functions that listen to those events with @listens MyFunc#event:event1.

Here are the official JSDoc pages for the aforementioned tags:

• https://jsdoc.app/tags-event.html
• https://jsdoc.app/tags-fires.html
• https://jsdoc.app/tags-listens.html

Do note some nuance around "event" mentioned in the tags event page, repeating here:

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.)