随着前端技术的不断进步，为了提升团队协作效率以及保证代码质量，代码规范和文档化显得越来越重要。在 TypeScript 的应用下，开发者不但能够更规范的书写代码，同时也能够利用其强大的类型检查功能生成类型安全的 API 文档，从而提高代码可读性和维护性。
本文将详细介绍如何通过 TypeScript 来生成类型安全的 API 文档，包括如何使用 JSDoc 注释、如何使用 TSDoc 并结合工具使生成出的文档具有更良好的可读性和交互性。
JSDoc 注释
JSDoc 注释是以 /** 开头的注释块，用于描述代码的文档信息，并且通过编写规范的 JSDoc 注释，TypeScript 可以自动从代码中提取和生成如下信息：
- 变量、函数和类的参数和返回值类型。
- 继承和实现关系。
- 声明的命名空间和函数的文档说明。
- 定义的类型说明等。
下面是一个简单的示例：
-- -------------------- ---- ------- --- - -------------- - ------ -------- -------- ---- - ------ -------- ------- ---- - -------- -------- --------- -- -------- -------------------------------- ------- -------- -------- ------ - ------ --------- - --------- - -------- - --------------- - ---- -展开代码
在这个示例中，我们使用了 JSDoc 注释来描述函数的文档信息，包括函数名称、参数和返回值类型、文档说明。通过这些注释，TypeScript 可以运行提取并生成出以下 API 文档：
/** * 根据两次单价计算出价格差异率 * @param {number} original 原始单价 * @param {number} current 当前单价 * @returns {string} 比率，保留两位小数 */ function calculatePriceDiffRate(original: number, current: number): string;
通过在函数前添加 JSDoc 注释，我们用最小的代码量生成了具有类型提示和文档说明的函数，而且这个文档可以被大多数编辑器和 IDE 准确地解析和展示。
TSDoc
TypeScript 是一种类型安全的超集，不仅可以使用 JSDoc 注释来生成 API 文档，还可以使用其官方的 TSDoc 标准。与 JSDoc 不同的是，TSDoc 不仅支持 JSDoc 注释的格式，还支持优化后的注释格式，能够生成更具有可读性、可交互性的文档。
与 JSDoc 注释不同，TSDoc 独有的标记格式和类型标记具有更好的可读性和可交互性。在 TSDoc 中，我们可以使用属性标记来描述可以在不同上下文（如文档、代码等）中使用的属性。
TSDoc 的标记主要有以下几个：
@param：参数描述。@returns：函数的返回值描述。@type：返回值的类型描述。@template：泛型类型的描述。@inheritDoc：继承或实现的文档描述信息。
下面是一个简单的示例：
-- -------------------- ---- ------- --- - --- - - --------- - ---- -- ------ ----- ------ - --- - --- -- - ------ --- - -- - -------- ---------- ---- - ----- -- ------ --- -------- - ------ ---- - -展开代码
在这个示例中，我们使用了 TSDoc 的标记格式和类型标记，使用了 @template 标记来添加泛型类型的描述信息，使用了 @returns 和 @type 标记来指定函数返回值的类型描述信息。通过 TSDoc 和一些文档化工具的支持，我们可以生成更具有可读性、可交互性的文档。
文档化工具
在 TypeScript 中，除了使用 JSDoc 或者 TSDoc 标记来手动编写文档外，还可以通过文档化工具来自动生成文档。
TypeDoc
TypeDoc 是一个类型化的文档生成工具，可以从代码中自动生成 API 文档，并且具有诸如样式、主题等自定义选项。
TypeDoc 的使用非常简单，首先使用npm安装 TypeDoc，然后在项目根目录下使用以下命令生成文档即可：
npx typedoc --out ./doc ./src
其中 ./doc 是指生成的文档输出路径，./src 是指代码路径。执行完命令后，在 ./doc 目录下就会生成类似以下的文档。
DocFX
DocFX 是一个 Microsoft 开发的文档化工具，可以从代码注释中自动生成 API 文档，并且支持多种输出格式。其中最常用的一种就是生成 Markdown 格式的文档。
与 TypeDoc 相比，DocFX 更加适合面向 .NET 平台的应用程序，但是其也拥有多种输出选项以适应各种不同的应用场景。同时，DocFX 还可以与 Azure DevOps 等集成，方便开发者上传生成的文档。
小结
文档化是一个需要持续投入精力的过程，但是好的 API 文档和文档化实践可以有效提升团队协作效率和代码质量。在 TypeScript 的应用下，不仅能够编写更规范的代码，同时还能够利用强大的类型检查功能生成更好的 API 文档。同时，结合文档化工具，可以使用自动生成文档的方式，提高文档编写效率。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/67ca1b27e46428fe9e20c0e2
