@microsoft/tsdoc-config

NPM 包
CHANGELOG.md

@microsoft/tsdoc-config 包是用于加载 tsdoc.json 文件格式的可选附加组件，使用户能够定义自定义 TSDoc 标签。（此功能已移至其自己的包中，因为它需要外部依赖项，例如 NodeJS 和 ajv，而主包是完全独立的。）

创建配置文件

tsdoc.json 文件是可选的。使用时，它应与项目的 tsconfig.json 文件位于同一文件夹中。加载器通过在目录树中向上查找来找到它，直到找到包含 tsconfig.json 或 package.json 的文件夹，然后尝试从该位置加载 tsdoc.json。

tsdoc.json 文件符合 tsdoc.schema.json JSON 模式。它使用与 @microsoft/tsdoc 中的 TSDocParser 使用的 TSDocTagDefinition API 类似的字段来定义标签。

这是一个简单的例子

tsdoc.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "tagDefinitions": [
    {
      "tagName": "@myTag",
      "syntaxKind": "modifier"
    }
  ]
}

如果要在同一位置定义自定义标签并在多个项目之间共享它们，则 extends 字段指定将与当前文件混合的路径列表

tsdoc.json

{
  "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json",
  "extends": [
    "my-package/dist/tsdoc-base.json",
    "./path/to/local/file/tsdoc-local.json"
  ]
}

注意：extends 路径使用 NodeJS 模块解析来解析，因此本地路径必须以 ./ 开头，以避免被解释为 NPM 包名称。

API 用法

下面的代码示例说明了如何调用 @microsoft/tsdoc-config API 来加载 tsdoc.json 文件

import * as path from 'path';
import { TSDocParser, TSDocConfiguration } from '@microsoft/tsdoc';
import { TSDocConfigFile } from '@microsoft/tsdoc-config';

// Sample source file to be parsed
const mySourceFile: string = 'my-project/src/example.ts';

// Load the nearest config file, for example `my-project/tsdoc.json`
const tsdocConfigFile: TSDocConfigFile = TSDocConfigFile.loadForFolder(path.dirname(mySourceFile));
if (tsdocConfigFile.hasErrors) {
  // Report any errors
  console.log(tsdocConfigFile.getErrorSummary());
}

// Use the TSDocConfigFile to configure the parser
const tsdocConfiguration: TSDocConfiguration = new TSDocConfiguration();
tsdocConfigFile.configureParser(tsdocConfiguration);
const tsdocParser: TSDocParser = new TSDocParser(tsdocConfiguration);