Rush StackShopBlogEvents
Skip to main content

Doc comment syntax

API Extractor parses your TypeScript code comments to obtain documentation and additional type information. It expects your code comments to use TSDoc format. We won't provide a full description of the grammar here; instead, please refer to the TSDoc project.) If you've used JSDoc for JavaScript source code, TSDoc will be very similar, but be aware that there are some syntax differences.

The TSDoc language can be extended by defining custom tags. API Extractor's particular dialect of TSDoc is referred to as "AEDoc". (Support for TSDoc was introduced with API Extractor 6.x. In earlier releases, API Extractor used a proprietary syntax that was also called as "AEDoc", but this is now obsolete.)

TSDoc Playground

By the way, the TSDoc Playground website provides an interactive way to experiment with code comments to see how they will be parsed. Give it a try!

Which comments are parsed by API Extractor?​

In order for API Extractor to parse a code comment, all of the following must be true:

  • The comment must appear in the emitted .d.ts file for your class
  • The comment must begin with the special /** delimiter (two stars)
  • The comment must appears immediately before an exported declaration; OR the comment appears at the top of the entry point file and contains a @packageDocumentation tag

Note that if a declaration has multiple comment blocks, only the closest one will be considered. For example:

/**
 * Comment for f1.
 */
export function f1(): void {}

/**
 * THIS COMMENT WILL BE IGNORED ENTIRELY.
 */

/**
 * Comment for f2.
 */
export function f2(): void {}

Comment structure​

The overall anatomy of a TSDoc comment has these components:

  • The summary section: The documentation content up until the first block tag is called the "summary". The summary section should be brief. On a documentation web site, it will be shown on a page that lists summaries for many different API items. On a detail page for a single item, the summary will be shown followed by the remarks section (if any).
  • The remarks block: The "remarks" block starts with the @remarks block tag. Unlike the summary, the remarks may contain lengthy documentation content. The remarks section should not restate information from the summary, since the summary section will always be displayed wherever the remarks section appears.
  • Additional blocks: Other TSDoc blocks typically follow the @remarks block. Each block is introduced by a block tag such as @param, @returns, @example, etc.
  • Modifier tags: The modifier tags typically come last. Modifier tags don't have an associated block of content; instead, their presence indicates an aspect of the declaration. Some examples of modifier tags are: @public, @beta, and @virtual.
  • Inline tags: Inline tags can appear inside any section, and are always delimited by { and } characters. Additional content can appear after the tag name and before the } delimiter. Its format is tag-specific. Examples of inline tags are {@link} and {@inheritDoc}.

Here's some sample code that illustrates all the various components of the doc comment syntax:

/**
 * The base class for all widgets.
 *
 * @remarks
 * For details, see {@link https://example.com/my-protocol | the protocol spec}.