Add support for documenting EventTarget events

[Symbitic]

Search Terms

EventTarget, Event, events, dispatch, dispatches

Problem

Many APIs have classes that inherit EventTarget, but there is no easy way to document the events that it dispatches. I would like a way to document what the events are and what argument they take.

There are several problems with the current @event keyword. Many classes override addEventListener through a separate EventMap class so the event names may not be declared inside the class. It also provides no information about the event being dispatched.

Suggested Solution

Since the event keyword is already taken, my suggestion would be a @dispatches keyword for a class that extends EventTarget. It takes the event name, the event object dispatched (which, if it exists, should be a link), and a description. A possible example:

export class StatsEvent extends CustomEvent {
  constructor(os: string, time: Date, running) {
    super("stats", {
      detail: { os, time, running }
    });
  }
}

/**
 * The main application.

 * @dispatches "initialized" Event The object has been constructed.
 * @dispatches "stats" StatsEvent Periodic information about the state of the program.
 */
export class App extends EventTarget {
  constructor() {
    super();
    this.dispatchEvent(new Event("initialized"));
    this.dispatchEvent(new StatsEvent(process.os, new Date, false));
  }
}

[Gerrit0]

Something I always look at when considering additional tags is how it displays in VSCode/other editors. Here's what the @dispatches methods looks like:

Here's another option, using markdown headers and an explicit @link tag:

/**
 * The main application.
 *
 * ### Events
 * - "initialized" {@link Event} The object has been constructed.
 * - "stats" {@link StatsEvent} Periodic information about the state of the program.
 */

With the syntax which is understood by TypeScript (and therefore VSCode), both your editor and TypeDoc will show (roughly) the same thing today, which is a large pull...

I think without some large improvement on how these events could be rendered using the custom tag, I'm leaning towards not implementing this.

[Gerrit0]

I've thought about this a few different times in the past couple weeks, and haven't come up with a compelling reason to add special syntax for this that won't be understood by other tooling, going to mark this as wontfix