likes
comments
collection
share

规范你的Typescript注释，一步一步教你生成API文档

作者站长头像
站长
· 阅读数 17

我报名参加金石计划1期挑战——瓜分10万奖池，这是我的第2篇文章，点击查看活动详情

话说近年来typescript作为javascript的第二语言越来越流行，听说你是TS高手，但是你的TS注释规范吗？

规范的TS注释不仅能说明代码意图、直接生成API文档，还能为IDE工具提供更智能的提示：

规范你的Typescript注释，一步一步教你生成API文档

如图所示，调用即将被废弃的substr(0)方法会自动加上删除线。

JSDoc

JSDoc是Javascript注释规范标准，Typescript出现之后，虽然JSDoc也一直在兼容TS，但无奈这2种语言一种是弱类型，一种是强类型，注释对它们的意义大相径庭，所以JSDoc并不适合TS使用。

JSDoc语法没有严格规定，而是从特定实现的行为中推断出来的。大多数标准 JSDoc 标签都专注于为纯 JavaScript 提供类型注释，这对于 TypeScript 等强类型语言来说不是主要关注点。

TSDoc

于是Typescript东家就联合了一些社区组织，推出了TS注释规范标准：TSDoc。

export class Statistics {
  /**
   * Returns the average of two numbers.
   *
   * @remarks
   * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
   *
   * @param x - The first input number
   * @param y - The second input number
   * @returns The arithmetic mean of `x` and `y`
   *
   * @beta
   */
  public static getAverage(x: number, y: number): number {
    return (x + y) / 2.0;
  }
}

TSDoc 列出了如下目标：

  • 专为 TypeScript 设计：同时尽可能与我们熟悉和喜爱的 JSDoc 符号保持一致。
  • Markdown 集成：文档注释可以为富文本元素（例如粗体、代码围栏、标题、表格等）。
  • 通用核心：通用标签，例如@param和@returns将在所有工具中具有一致的行为。
  • 可扩展：每个工具都可以用自定义标签来补充核心标签，用于专门的场景。
  • 互操作性：TSDoc 标准保证不受支持的自定义标签不会干扰其他内容的解析。TSDoc 还消除了 Markdown 的歧义。
  • 多包支持：许多团队发布了一组 NPM 包，这些包可以一起工作并作为一组记录。
  • 开放标准：TSDoc 是一个开源、社区驱动的标准。我们鼓励您贡献自己的想法和拉取请求。

TSDoc的一些常用标签大家可以直接查看官网...

TSDoc解析器

需要注意的是，TSDoc只是一个格式标准，东家另外提供了一个开源的TS代码注释解析器：@microsoft/tsdoc

API信息提取器

@microsoft/tsdoc也只是一个注释语法解析引擎，并不能干具体的活，比如提取API信息、统计报告、注释检查、文档生成等等。

官方推荐了一个封装好的第三方库：api-extractor，该库可以：

  • 提取 API 信息 - 为您的每个项目生成一个“文档模型”JSON 文件。此 JSON 文件包含提取的类型签名和文档注释。
  • API 报告 - 跟踪您项目主要入口点的所有导出，并生成一份报告，用作 API 审查工作流程的基础。
  • 合并类型文件 - 类似于Webpack可以将所有 JavaScript 文件“汇总”到单个包中以进行分发，API Extractor 可以将您的 TypeScript 声明汇总到单个 .d.ts 文件中。

api-extractor官网：api-extractor.com/

个人感觉api-extractor有个特别爽的地方是可以统计API信息、检查注释规范，并给出各种warning。 比如有一个忘了加注释@public的类型，被某个加了@public的类型间接引用，此时它会贴心的提醒你忘了加@public注释。

使用方法

  1. npm install @microsoft/api-extractor
  2. 建立配置文件：api-extractor.json
  3. 先执行 tsc 命令为项目生成 d.ts 类型文件
  4. 然后执行 api-extractor run 命令。该命令会提取 d.ts 中的注释信息，生成一个JSON文件。

详细配置说明请查其看官网，在此不多说...

文档生成器

将API信息提取为JSON之后，还不够，我们还需要根据这个JSON文件来生成具体的文档。

  • api-documenter 是一个简单的文档生成器，它可以根据api-extractor生成的JSON文件进一步生成markdown和yaml格式的文档。

使用方法

  1. npm install @microsoft/api-documenter
  2. 执行 api-documenter markdown 可生成 markdown 格式文档
  3. 执行 api-documenter yaml 可生成 yaml 格式文档

详细命令参数可查看：

站点生成器

好了，现在你生成了一堆API的markdown文档，下一步你可能需要打造API站点。

将markdown生成站点的工具就有很多了，比如

具体使用方法请查看官网...

检查注释规范

为了防止你的TSDoc注释不符合规范，或者标签写错了，官网还贴心的提供了eslint-plugin-tsdoc

安装和配置方法：github.com/microsoft/t…

TypeDoc

以上一顿操作下来，感觉有些繁琐，有没有更简洁的方法一步到位生成API站点呢？

有，比如：TypeDoc，它集成了API信息提取、文档生成、站点生成：

TypeDoc也是TSDoc标准的参与者，TypeDoc可以完全兼容TSDoc标准，但比TSDoc更宽松，这意味着TypeDoc可以使用更多非标准的标签。

TypeDoc默认提供了一套API站点的简洁主题，当然你也可以修改和定制。它供了两种途径：

  • 主题，主题会覆盖 API 文档的默认呈现方式
  • 插件，插件可以进行其他更改

使用方法

  1. npm install typedoc
  2. 配置typedoc.json
  3. 执行命令：typedoc --out api src/index.ts 生成API站点

也可以执行命令：typedoc --plugin typedoc-plugin-markdown --out api src/index.ts --hideSources --theme markdown 生成 markdown 文件

范例

最后提供本人一个使用TSDoc的实际项目：

好了，先讲到这里，相关内容资源比较分散，外链较多，记得点赞收藏哦^o^....