tsdoc.json

TSDoc は、TypeScript の Doc コメントのための標準構文です。カスタムタグ定義で拡張できます。API Extractor のカスタムタグは、「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 Extractor はこれらの定義を .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 Extractor を呼び出します。

$ cd your-project-folder

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

**tsdoc.json** ファイルの詳細については、@microsoft/tsdoc-config のドキュメントを参照してください。