tsdoc.json

TSDoc 是 TypeScript 文档注释的标准语法。它可以扩展自定义标签定义。API 提取器的自定义标签称为“AEDoc”标签。它们在文件 extends/tsdoc-base.json 中定义。

如果您的代码注释由其他与 TSDoc 兼容的工具处理，您可以在项目中添加一个 tsdoc.json 配置文件。这使不同的工具能够就如何解析注释达成一致。如果您使用的是 eslint-plugin-tsdoc 插件，它还使 ESLint 能够报告对未定义（例如拼写错误）或不受支持（例如您的工具未实现的标准化标签）的标签的警告。

在您的项目中添加类似这样的文件

<your-project-folder>/tsdoc.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",

  // Inherit the TSDoc configuration for API Extractor
  "extends": [ "@microsoft/api-extractor/extends/tsdoc-base.json" ]
}

定义您自己的 TSDoc 标签

您也可以在 tsdoc.json 中定义您自己的标签，ESLint 插件将对其进行验证。API 提取器将这些定义序列化到 .api.json 输出文件（在 "tsdocConfig" 字段中），以便使用 @microsoft/api-extractor-model 库的工具（通过 ApiDocumentedItem.tsdocComment API）可以访问它们。

自定义标签定义可能看起来像这样

<your-project-folder>/tsdoc.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",

  // Include the definitions that are required for API Extractor
  "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"],

  // noStandardTags: false,

  "tagDefinitions": [
    // Define a custom tag and specify how it should be parsed
    {
      "tagName": "@myCustomTag",
      "syntaxKind": "block",
      "allowMultiple": true,
    }
  ],

  "supportForTags": {
    // Indicate that the custom tag is supported by your tooling.  (Without this, warnings may
    // be reported saying that the tag is unsupported.)
    "@myCustomTag": true
  }
}

生成的 TSDoc 配置将包括通过 "extends" 合并的 AEDoc 定义，以及 TSDoc 解析器预定义的标准标签。要查看项目的最终 TSDoc 配置，请使用 --diagnostics 命令行选项调用 API 提取器

$ cd your-project-folder

# Look for the "DIAGNOSTIC: TSDoc configuration" in the console output
$ api-extractor run --local --diagnostics

有关 tsdoc.json 文件的更多详细信息，请参阅 @microsoft/tsdoc-config 文档。