RFC: Support for custom TSDoc tags

In RFC: Core set of tags for TSDoc, @karol-majewski brought up the topic of custom tags. Extensiblity is a primary goal of TSDoc. The challenge is that JSDoc's tags have inconsistent tag-specific syntaxes, whereas a custom tag needs to be safely skippable by parsers that are unaware of the tag.

Kinds of tags

Here's some proposed core tags that we already discussed supporting, grouped by their type of syntax:

Standalone tags

These act as simple on/off switches. In terms of parser ambiguity, it doesn't matter too much where they appear inside the doc comment:

• @readonly
• @public
• @internal
• @alpha
• @beta
• @ignore

Section-starter tags

These probably will act as delimiters that start blocks of rich text content (which possibly may include inline tags). Probably they should appear at the start of their line. Their captured content will probably terminate with the first TSDoc tag that is not an inline tag:

• @remarks
• @returns
• @deprecated

Tags with unusual syntax

These are like section starter tags, but with special meaning for the "-" delimiter:

• @param variable.member - description
• @template TThing - description

These act like bullet items, so they must appear at the start of the line and must appear as a group. Otherwise they are like section-starter tags:

• @see {@link <https://domain.com>} and other resources

Inline tags

These use curly braces to delimit their content. Within the curly braces, highly specialized parsing rules apply:

• {@inheritdoc @scope/my-package/components:Foo.member}
• {@link @scope/my-package/components:Foo.member | the thing}

{@link http://blarg | the thing}

Custom tag syntaxes

Custom inline tags should be fairly easy to support. Some interesting design questions:

• Should we assume that unrecognized tags are standalone tags by default?

• If we want to support custom section-starter tags, what would the notation look like?

• For an unrecognized tag, should its content be included in the API documentation? Or should it be omitted? Is the answer different for different custom tag kinds?

Start with the linked RFC discussion and review the proposed standalone, section-starter, unusual-syntax, and inline tag categories. The open design questions cover how custom tags are recognized, how their content is parsed or omitted, and how unknown tags remain safely skippable; done requires an agreed custom-tag syntax and behavior.