文档注释语法

API 提取器解析您的 TypeScript 代码注释以获取文档和附加类型信息。它期望您的代码注释使用 TSDoc 格式。我们不会在此提供语法的完整描述；相反，请参考 TSDoc 项目。）如果您使用过 JSDoc 用于 JavaScript 源代码，则 TSDoc 将非常相似，但请注意，存在一些语法差异。

TSDoc 语言可以通过定义自定义标签来扩展。API 提取器特定的 TSDoc 方言称为“AEDoc”。（对 TSDoc 的支持是在 API 提取器 6.x 中引入的。在早期版本中，API 提取器使用了一种专有的语法，也被称为“AEDoc”，但现在已过时。）

TSDoc Playground
顺便说一下，TSDoc Playground 网站提供了一种交互式方式来试验代码注释，以查看它们将如何被解析。试试看吧！

API 提取器解析哪些注释？

为了让 API 提取器解析代码注释，以下所有条件必须为真

注释必须出现在您类的已发出 .d.ts 文件中
注释必须以特殊的 /** 分隔符（两颗星）开头
注释必须出现在导出声明之前；或者注释出现在入口点文件的顶部，并且包含 @packageDocumentation 标签

请注意，如果声明具有多个注释块，则只会考虑最靠近的注释块。例如

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

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

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

注释结构

TSDoc 注释的整体结构包含以下组件

摘要部分：第一个块标签之前的文档内容称为“摘要”。摘要部分应该简短。在文档网站上，它将显示在一个列出许多不同 API 项的摘要的页面上。在单个项目的详细信息页面上，摘要将显示在备注部分（如果有）之后。
备注块：“备注”块以 @remarks 块标签开头。与摘要不同，备注可以包含冗长的文档内容。备注部分不应重复摘要中的信息，因为摘要部分将在备注部分出现的所有位置始终显示。
其他块：其他 TSDoc 块通常在 @remarks 块之后。每个块都由一个块标签引入，例如 @param、@returns、@example 等。
修饰符标签：修饰符标签通常最后出现。修饰符标签没有关联的块内容；相反，它们的存在表示声明的某个方面。修饰符标签的一些示例是：@public、@beta 和 @virtual。
内联标签：内联标签可以出现在任何部分，并且始终由 { 和 } 字符分隔。标签名称之后和 } 分隔符之前的附加内容可以出现。它的格式是特定于标签的。内联标签的示例是 {@link} 和 {@inheritDoc}。

以下是一些示例代码，说明了文档注释语法的各种组件

/**
 * The base class for all widgets.
 *
 * @remarks
 * For details, see {@link https://example.com/my-protocol | the protocol spec}.
 *
 * @public
 */
export abstract class BaseWidget {
  /**
   * Draws the widget.
   * @remarks
   *
   * The `draw` member implements the main rendering for a widget.
   *
   * @param force - whether to force redrawing
   * @returns true, if rendering occurred; false, if the view was already up to date
   *
   * @beta @virtual
   */
  public draw(force: boolean): boolean {
    . . .
  }

  /**
   * Whether the widget is currently visible.
   *
   * @example
   * Here's some example code to hide a widget:
   *
   * ```ts
   * let myWidget = new MyWidget();
   * myWidget.visible = false;
   * ```
   *
   * @defaultValue `true`
   */
  public visible: boolean = true;

  /**
   * Gets or set the title of this widget
   */
  public get title(): string {
    . . .
  }

  // NOTE: API Extractor considers your property getter and setter functions to be
  // a single API item.  Don't write any documentation for the setter.
  public set title(value: string) {
    . . .
  }
}

发布标签

四个发布标签是：@internal、@alpha、@beta、@public。它们应用于 API 项目，例如类、成员函数、枚举等。API 提取器根据其预期支持级别分别对每个导出 API 项目进行分类

internal：表示 API 项目仅供相同维护者的其他 NPM 包使用。第三方永远不应使用“内部”API。为了强调这一点，使用下划线前缀表示具有（显式）@internal 标签的项目。
alpha：表示 API 项目最终打算公开发布，但目前处于开发的早期阶段。第三方不应使用“alpha”API。
beta：表示 API 项目已发布为预览版或用于实验目的。鼓励第三方尝试它并提供反馈。但是，“beta”API 不应在生产环境中使用，因为它可能会在将来的版本中更改或删除。
public：表示 API 项目已正式发布，现在是包的受支持契约的一部分。如果使用 SemVer 版本控制方案，则 API 签名不能在没有进行 MAJOR 版本递增的情况下更改。

注意：TypeScript 的 public/protected/private 关键字与 AEDoc 发布标签无关。例如，成员函数通常具有 public TypeScript 关键字，无论它在文档注释中是否被分类为 @public 或 @internal。

当 API 首次引入时，它通常从 alpha 开始。随着设计的成熟，它从 alpha --> beta --> public 升级。internal 指定主要用于解决管道问题，通常不在任何成为公开发布的路线图上。（还有一个 @deprecated 标签，但它是一个可以与上述任何标签结合使用的选项。）

发布标签递归地应用于容器的成员（例如类或接口）。例如，如果类被标记为 @beta，则其所有成员自动具有此状态；您不需要将 @beta 标签添加到每个成员函数。但是，您可以将 @internal 添加到成员函数以赋予它不同的发布状态。

注意：如果容器（例如类或接口）具有 @internal 标签，则应将其名称添加下划线前缀，但其成员不需要下划线。例如，如果将 @internal 应用于 @beta 类的成员函数，则内部函数应该具有下划线前缀。

最后，请注意，某些逻辑规则适用。例如，@public 函数不应返回 @beta 类型。@beta 类不应从 @internal 基类继承。等等。API 提取器目前不验证这些规则，但很快就会验证。

API 提取器解析哪些注释？​

注释结构​

发布标签​

另请参阅​

API 提取器解析哪些注释？

注释结构

发布标签

另请参阅