RFC: Core set of tags for TSDoc

[octogonz]

TSDoc should define a core set of tags for very common scenarios, so their semantics can be standardized across all tools.

Ignoring the syntax details for a moment, which tags should be included in this list?

Here's some suggestions from AEDoc:

• @param
• @returns
• {@link}
• {@inheritdoc}
• @remarks

Any others?

[aciccarello]

Since @internal is recognized by the TypeScript compiler, I think it would be good to define its documentation behavior.

The @depricated tag seems common and significant in docs. (related TC39 proposal)

JSDoc supports @ignore while TypeDoc supports @hidden to remove an API from documentation.

JSDoc and JavaDoc support @see, @since, @throws, and @author. I'm not partial to any of them but they are worth noting.

Is @remarks/@summary separation necessary. I haven't used that pattern so I'm wondering how helpful it is.

[MartynasZilinskas]

@aciccarello @deprecated *

• @see linking to a specific symbol or resource
• @example could be used with markdown code samples
• @template for documenting type parameters
• @throws

I think these tags are worth using.

[octogonz]

We eliminated the @see tag because the usage was unclear. Consider some documentation like this:

---

Widget.render()

The Widget.render() method draws the widget. See the IRenderable interface for more about rendering. Blah blah blah...

See Also

• The IRenderable interface
• The Rendering section of the Widget tutorial
• (2003). Widgets: Rendering Them. Lawrence, KS: University Press of Kansas. ISBN 9738-0-706-0899-7.

---

Consider this naive representation:

/**
 * The `Widget.render()` method draws the widget.  See the {@link IRenderable}
 * interface for more about rendering.  Blah blah blah...
 *
 * ## See Also
 *
 * - The {@link IRenderable} interface
 * - The {@link http://example.com | Rendering} section of the Widget tutorial
 * - (2003). *Widgets: Rendering Them.* Lawrence, KS: University Press of Kansas.
 *   ISBN 9738-0-706-0899-7.
 */

How would you use the @see tag to represent this? What would be the advantage?

[MartynasZilinskas]

The advantage is a standardized way to make the section "see also" and it's up to documentation generator to output it.

 /**
 * The `Widget.render()` method draws the widget.  See the {@link IRenderable}
 * interface for more information about rendering.  Blah blah blah...
 *
 * @see {@link IRenderable | The interface}
 * @see {@link http://example.com | The rendering section of the Widget tutorial} 
 * @see (2003). *Widgets: Rendering Them.* Lawrence, KS: University Press of Kansas. ISBN 9738-0-706-0899-7.
 */

Usage

• @see {@link <internal symbol>}
• @see {@link <https://domain.com>}
• @see <text>

---

The Widget.render() method draws the widget. See the IRenderable interface for more about rendering. Blah blah blah...

See also

• The IRenderable interface
• The Rendering section of the Widget tutorial

• (2003). Widgets: Rendering Them. Lawrence, KS: University Press of Kansas. ISBN 9738-0-706-0899-7.

[octogonz]

Seems reasonable. However strict mode should enforce that @see always appears at the start of a line, and always after the main content. Before we eliminated it, we found a lot of people writing this kind of thing:

/**
 * The `Widget.render()` method draws the widget.  @see the {@link IRenderable}
 * interface for more about rendering.  It has more info about stuff you might like
 * 
 * Blah blah...
 */

[aciccarello]

The Angular application documentation tool Compodoc uses a limited subset of JSDoc tags

• @returns
• @ignore
• @param
• @link (with several different syntaxes)
• @example

That page references the JSDoc support in JavaScript in the TypeScript wiki which I hadn't previously seen.

[octogonz]

That page references the JSDoc support in JavaScript in the TypeScript wiki which I hadn't previously seen.

The compiler people were planning to follow up with more details about that. I believe they were out of office for various reasons last week. Spring time is busy. :-)

[BnayaZil]

Please consider: async public private

[karol-majewski]

Please consider allowing the user to extend the list with their own tags, which in turn could be utilized by third party tools. Couple examples that come to my mind:

Tag	Usage	Notes
@browserspecific	Browser-specific hacks and workarounds. Should be able to accept arguments.	First seen in tslint-microsoft-contrib
@impure @emits	Emits side effects.	Think TSLint rule that strictly forbids side effects unless the function/method is explicitly marked as @impure.
@mocked @hardcoded @stubbed	Allows you to distinguish between real data and stubs that ought to be removed one day.	When building a web application for which there is no data source yet, it's easy to lose track of what's real and what's been mocked.
@debt @dangerous	A candidate for refactoring.	Keep track of technical debt being accumulated in your project. Right now one can achieve a similar effect by exploiting the @deprecated tag along with TSLint's "deprecation": { "severity": "warning" } rule, but deprecation is not the same as technical debt.
@experimental	API not stable or hidden behind a feature flag.
@vulnerability	Security issues ahead.

[DovydasNavickas]

@BnayaZil all of your listed tags would be redundant, because TypeScript already has both visibility modifiers and async keywords.

@karol-majewski this issue concerns only core set of tags. Additional tags will be supported, but not specified in tsdoc documentation.

[BnayaZil]

@DovydasNavickas do you mean to async/await as async keyword?

[DovydasNavickas]

@BnayaZil Yes. Do you have something else in mind?

[BnayaZil]

yes, I thought about callbacks and etc but I see now that JSDoc ask to prevent this kind of use

[DovydasNavickas]

Yeah... I'm happy that JSDoc discourages that because having multiple ways to declare asynchronousy makes it harder to use. And async/await is available everywhere with the help of TypeScript's downleveling.

[DanielRosenwasser]

Many of the things that the compiler supports are more to understand JavaScript code better. Keep in mind they're not necessarily all used for language service support with TypeScript code. So for instance, we show documentation in tooltips using @param tags, but we don't use the @extends tag for anything since it's not super useful.

[c69]

@deprecated for me was probably the third most frequently used tag, after param and return, in 6 years if using JSDoc.

@experimental is a nice to have dual to it. (Not sure about @beta - it implies the degree of readiness, and naturally you start thinking - "where is my @rc or @alpha".

@example is nice to have, but unclear how and when should it stop.

@template or @config - some way to describe the elements in the object param is needed.

@link or @ref - yes. @see is too vague.

@pure / @impure / @recursive - maybe not in the core set.

@todo maybe its anti-pattern... but its very frequently used 😆

P.s.: would be cool to have @assert with runnable unit test (python style), but that probably does not belong to core.

[EisenbergEffect]

Any thoughts on an @include, @external or similar tag to allow associating a separate documentation file with an API. The idea being that you might want to write a more extensive narrative or set of examples in an external Markdown file, but have the doc build pull that in and merge it with the docs as if it had been embedded into the code.

[dend]

@EisenbergEffect that seems like a nifty idea, but I am not sure whether it's something that needs to be part of TSDoc vs. say, the publishing pipeline that ingests TSDoc output.

@pgonzal thoughts?

[EisenbergEffect]

@dend Good point. It would be enough for me if the output of TSDoc simply represented the concept of an associated external file. Then, 3rd party processors could use that information in domain-specific ways. I could do this by convention tool. So, it's not a deal breaker if it doesn't get in. Just tossing scenarios out there.

[octogonz]

@MartynasZilinskas could you give an example of the syntax for @template? Is the syntax analogous to @param?

[octogonz]

(I've split off some of the other topics into separate GitHub issues.)

@experimental is a nice to have dual to it. (Not sure about @beta - it implies the degree of readiness, and naturally you start thinking - "where is my @rc or @Alpha".

@c69 I think this reflects two different usage scenarios. A large library with commercial support contracts needs something like the AEDoc @alpha -> @beta -> @public graduation. Whereas for smaller community projects, @experimental is probably sufficient and avoids implying a beta process. I'd vote to support both.

@todo maybe its anti-pattern... but its very frequently used

I agree that @todo is an antipattern. Code comments aren't great for work tracking. However, the "lax" mode parser should recognize this notation to avoid accidentally including the todo items in the published API docs.

[MartynasZilinskas]

@pgonzal Yes, a @template tag should have the same syntax as @param.

[octogonz]

PR https://github.com/Microsoft/tsdoc/pull/50 introduces definitions for the subset of core tags required by API Extractor. As part of this work, we're separating the tag definitions into four "standardization groups":

• Core: Important tags that every TSDoc implementor should support.
• Extended: Optional tags that, if supported, have a standardized syntax and semantics.
• Discretionary: Tags that have a standardized syntax, but whose semantics may differ between implementations. They are included primarily to encourage consistency between different implementors.
• None: All other tags that are not part of the standard. The syntax and semantics are completely user-defined.

Feel free to provide comments/feedback. No aspects of the standard are finalized yet. Right now I'm focused on porting API Extractor to use the TSDoc parser instead of the old custom parser. Based on what we learn from that experience, I'll start trying to lock down various aspects of the specification.

[aciccarello]

For a generic type definition, it can be helpful to document what the generic type is used for. Using @template was mentioned in some previous comments but I wonder if @typeparam would be better. Either way, I think this would be a good candidate for inclusion of the standard tags.

VS Code already has some support for @template and there has been a request for TypeDoc to support that as well (TypeStrong/typedoc#860). TypeDoc currently supports @typeparam T - Description and @param <T> - Description.

/**
 * Alias for array
 * 
 * @typeparam T - Type of objects the list contains
 */
type List<T> = Array<T>;

/**
 * Wrapper for an HTTP Response
 * @typeparam B - Response body
 * @param <H> - Headers
 */
interface HttpResponse<B, H> {
    body: B;
    headers: H;
    statusCode: number;
}

[octogonz]

I've split @typeparam into its own issue https://github.com/Microsoft/tsdoc/issues/72 so it doesn't get overlooked. A few other people have asked about this already, so I think it's worth including.

[bookmoons]

I vote for @throws, or some other way to document exceptions. Really useful when coding against a procedure to know which kind of errors I should be handling.

[bookmoons]

Suggested in microsoft/vscode#77261 something like @extended and @extendedExample that's intended to land in docs but not be shown in smaller contexts like IntelliSense.

/**
 * Take over the specified world.
 * 
 * @param world - The world to dominate.
 * 
 * @remarks
 * Optimizes for minimum loss of life, minimum reputation harm, and maximum deviousness.
 * Leverages all available capital and human resources without remorse.
 *
 * @extended
 * The development of this procedure began with the Sumerian kings.
 * [... long history ...]
 * 
 * @extendedExample
 * // Example of error handling based on the latest best practices
 * while (!retired) {
 *   try { takeOverWorld(earth) } catch (error) {
 *     if (error instanceof InsurrectionError) squashInsurrection()
 *     else if (error instanceof CoupError) decimateCoup()
 *     else if (error instanceof GlobalThermonuclearWarError) retire()
 *     [.. long example list .. ]
 *   }
 * }
 *
 * @beta
 */
export function takeOverWorld(world: World): void;

[octogonz]

I'm going to close this RFC, since the core set of tags has stabilized. The inventory of tags is more accurately tracked by the file StandardTags.ts.

Going forward, if people want to suggest new tags (or modify existing ones), let's open separate issues so they can be discussed individually.

[octogonz]

@bookmoons I created https://github.com/microsoft/tsdoc/issues/170 and https://github.com/microsoft/tsdoc/issues/171 for the two questions you asked.

[Mouvedia]

I would love to have something like @caution or @note.

@debt

That one would be useful.