标签种类

TSDoc 区分三种标签：块标签、修饰符标签和内联标签。

标签名称以 at 符号 (@) 开头，后跟使用“驼峰式”大小写的 ASCII 字母。

一个标签被定义为恰好具有这三种形式之一。 例如，@link 标签不能写成块标签，因为它被定义为内联标签。

块标签

块标签应始终作为行中的第一个元素出现。 在规范化形式中，一个块标签应该是其行中唯一的元素，除了某些标签对其文本的第一行赋予特殊含义。 例如，@example 和 @throws 标签将其第一行解释为节标题。

块标签之后的所有文本，直到下一个块标签或修饰符标签的开始，都被认为是块标签的标签内容。 内容可能包括 Markdown 元素和内联标签。 在第一个块标签之前出现的任何内容都将被解释为特殊的“摘要”部分。

块标签的示例

/**
 * This is the special summary section.
 *
 * @remarks
 * This is a standalone block.
 *
 * @example Logging a warning
 * ```ts
 * logger.warn('Something happened');
 * ```
 *
 * @example Logging an error
 * ```ts
 * logger.error('Something happened');
 * ```
 */

修饰符标签

修饰符标签指示 API 的特殊性质。 修饰符标签通常与块标签的解析方式相同，期望它们的标签内容为空。 如果在修饰符标签之后找到标签内容，则解析器可以选择丢弃它，或者（在提高兼容性的情况下）将其与之前的块标签关联。

在规范化形式中，修饰符标签出现在文档注释底部的单行中。

修饰符标签的示例

/**
 * This is the special summary section.
 *
 * @remarks
 * This is a standalone block.
 *
 * @public @sealed
 */

在上面的示例中，@public 和 @sealed 是修饰符标签。

内联标签

内联标签与 Markdown 表达式一起作为内容元素出现。 内联标签始终用 { 和 } 字符包围。 @link 和 @inheritDoc 标签是内联标签的示例。

内联标签的示例

class Book {
  /**
   * Writes the book information into a JSON file.
   *
   * @remarks
   * This method saves the book information to a JSON file conforming to the standardized
   * {@link http://example.com/ | Example Book Interchange Format}.
   */
  public writeFile(options?: IWriteFileOptions): void {
    . . .
  }

  /**
   * {@inheritDoc Book.writeFile}
   * @deprecated Use {@link Book.writeFile} instead.
   */
  public save(): void {
    . . .
  }
}

另请参阅

• RFC #21: 支持自定义 TSDoc 标签