博客站

生成 TypeScript 文档可以帮助你更好地维护和共享代码库。以下是几种常见的生成 TypeScript 文档的方法和工具：

1. 使用 TypeDoc

TypeDoc 是一个流行的 TypeScript 文档生成工具，它可以根据 TypeScript 代码中的注释生成 HTML 文档。

安装 TypeDoc

首先，安装 TypeDoc：

npm install --save-dev typedoc

配置 TypeDoc

在项目根目录下创建一个 typedoc.json 文件，并配置 TypeDoc。

示例

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "exclude": ["**/__tests__/**/*"],
  "includeVersion": true,
  "name": "My Project",
  "readme": "README.md"
}

在这个例子中，entryPoints 指定了入口文件，out 指定了输出目录，exclude 指定了要排除的文件，includeVersion 指定了是否包含版本信息，name 指定了项目名称，readme 指定了 README 文件。

生成文档

运行以下命令生成文档：

npx typedoc

生成的文档会输出到 docs 目录中。

2. 使用 JSDoc

JSDoc 是一个 JavaScript 文档生成工具，它也支持 TypeScript。你可以使用 JSDoc 注释来生成文档。

安装 JSDoc

首先，安装 JSDoc：

npm install --save-dev jsdoc

编写 JSDoc 注释

在 TypeScript 代码中编写 JSDoc 注释。

示例

/**
 * Adds two numbers.
 * @param a - The first number.
 * @param b - The second number.
 * @returns The sum of the two numbers.
 */
function add(a: number, b: number): number {
    return a   b;
}

生成文档

运行以下命令生成文档：

npx jsdoc -c jsdoc.json

你需要创建一个 jsdoc.json 配置文件来指定生成文档的选项。

示例

{
  "source": {
    "include": ["src"],
    "exclude": ["node_modules"]
  },
  "opts": {
    "destination": "docs",
    "recurse": true,
    "template": "templates/default"
  }
}

在这个例子中，source 指定了源代码目录，opts 指定了输出目录和其他选项。

3. 使用 API Extractor

API Extractor 是一个用于生成 API 文档的工具，它支持 TypeScript。API Extractor 可以生成 Markdown 文档，并可以与 API Documenter 结合使用生成更复杂的文档。

安装 API Extractor

首先，安装 API Extractor：

npm install --save-dev @microsoft/api-extractor

配置 API Extractor

在项目根目录下创建一个 api-extractor.json 文件，并配置 API Extractor。

示例

{
  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
  "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
  "bundledPackages": [],
  "compiler": {
    "tsconfigFilePath": "<projectFolder>/tsconfig.json"
  },
  "apiReport": {
    "enabled": true,
    "reportFolder": "<projectFolder>/temp/"
  },
  "docModel": {
    "enabled": true,
    "apiJsonFilePath": "<projectFolder>/temp/<unscopedPackageName>.api.json"
  },
  "dtsRollup": {
    "enabled": true,
    "untrimmedFilePath": "<projectFolder>/dist/<unscopedPackageName>.d.ts"
  },
  "tsdocMetadata": {
    "enabled": true
  },
  "messages": {
    "compilerMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    },
    "extractorMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    },
    "tsdocMessageReporting": {
      "default": {
        "logLevel": "warning"
      }
    }
  }
}

在这个例子中，mainEntryPointFilePath 指定了入口文件，compiler 指定了 tsconfig.json 文件，apiReport 指定了 API 报告的输出目录，docModel 指定了文档模型的输出路径，dtsRollup 指定了类型定义的输出路径。

生成文档

运行以下命令生成文档：

npx api-extractor run

生成的文档会输出到 temp 目录中。

4. 使用 VSCode 的 TSDoc 插件

如果你使用 VSCode，可以安装 TSDoc 插件来帮助编写和预览 TSDoc 注释。

安装 TSDoc 插件

在 VSCode 中搜索并安装 TSDoc 插件。

编写 TSDoc 注释

在 TypeScript 代码中编写 TSDoc 注释。

示例

/**
 * Adds two numbers.
 * @param a - The first number.
 * @param b - The second number.
 * @returns The sum of the two numbers.
 */
function add(a: number, b: number): number {
    return a   b;
}

预览 TSDoc 注释

在 VSCode 中，你可以将鼠标悬停在函数或类上，查看 TSDoc 注释的预览。

总结

生成 TypeScript 文档可以帮助你更好地维护和共享代码库。你可以使用 TypeDoc、JSDoc、API Extractor 或 VSCode 的 TSDoc 插件来生成和编写文档。理解这些工具的使用场景和配置方法，可以帮助你生成高质量的 TypeScript 文档。