Add @fires and @listens tags to document events

[AndyOGo]

Search Terms

Event, fire, dispatch, listen, on

Problem

At the moment it can‘t be documented which events are fired or listened to.

Suggested Solution

• @fires tag: https://jsdoc.app/tags-fires
• @Listens tag: https://jsdoc.app/tags-listens

[Gerrit0]

I'm leaning towards a no for both this and #3082.

TypeDoc already natively supports some 55 tags (more if you don't logically group some together). If it supported all of JSDoc's tags, it would be >100 tags.

Adding an additional tag to TypeDoc incurs some costs:

• The tag must be documented on the site
• The tag must be added to the list of default tags & tsdoc config
• The tag must be tested to confirm the configuration is supported
• Users contributing translations to TypeDoc have an additional key that they need to translate for a complete translation
• Any behavior attached to the tag in other documentation systems needs to be either understood and implemented, or documented as not implemented.

When a tag is very widely used (e.g. @author, with 1.9 million uses) the trade-off makes sense to implement, even if TypeDoc will attach no special behavior to the tag. For less common tags like @fires (62k), and especially scarcely used tags like @modifies (1k), I'm not sure the benefit is there.

TypeDoc supports defining custom tags which will be recognized when parsing your documentation. For tags which don't have any special behavior, I think this is generally a better path forward than having TypeDoc recognize and effectively ignore the tags by default.

I'm also reluctant to add support for JSDoc tags which are defined in a way which is unfriendly to implementing in a generic way. The @see tag is an example of this where TypeDoc implements the parse behavior of the tag which is easy to do, and ignores the implicit linking behavior that can't benefit from using TypeScript's symbol resolution. This unfortunately causes somewhat regular confusion from people who see a JSDoc example without the explicit link and expect it to work in TypeDoc. Implementing either @fires or @listens would add another tag which is likely to cause confusion for users as TypeDoc would not implement automatic linking to the event.