TypeScript 文档：高级技术与工具

轻松学习Python，无需理论负担。在浏览器中直接解决带自动检查的实践任务，无需安装任何东西。

为 TypeScript 项目编写文档：高级水平

高质量的文档不仅仅是函数的描述，更是一个强大的工具，能将代码转化为团队和用户都能理解的产品。在 TypeScript 中，得益于严格的类型系统，文档变得更有价值：它不仅解释逻辑，还充当数据结构的事实来源。在高级水平上，文档超越了注释的范畴，包括自动生成、支持复杂类型以及与开发工具的集成。在本文中，我们将探讨如何使用现代方法和工具为 TypeScript 项目创建文档。

1. JSDoc 和 TypeDoc 的高级使用

JSDoc 是一种注释标准，TypeScript 对其有很好的支持。在高级水平上，重要的不仅仅是描述参数，而是充分利用标签系统的所有功能。

1.1. 复杂类型的标签

使用 @template 描述泛型，使用 @typeParam 明确类型参数，使用 @callback 定义回调函数的签名。

/** * 从存储中获取值的通用函数。 * * @template T - 返回值的类型。 * @param key - 用于查找的键。 * @returns 类型为 T 的值，如果未找到键则返回 undefined。 */function getValue<T>(key: string): T | undefined {    // 实现}

/** * @callback FetchCallback * @param data - 获取到的数据。 * @param error - 如果发生错误，则为错误对象。 * @returns void */type FetchCallback<T> = (data: T, error?: Error) => void;

1.2. 文档化函数重载

TypeScript 允许函数重载。在文档中需要分别描述每个重载。

/** * 从数字创建字符串。 * @param a - 第一个数字。 * @param b - 第二个数字。 * @returns 连接数字的字符串。 */function combine(a: number, b: number): string;/** * 从字符串创建字符串。 * @param a - 第一个字符串。 * @param b - 第二个字符串。 * @returns 连接后的字符串。 */function combine(a: string, b: string): string;function combine(a: any, b: any): string {    return `${a}${b}`;}

1.3. 自定义 TypeDoc 修饰符

TypeDoc（TypeScript 的主要文档生成器）支持自定义标签，可以通过配置文件 typedoc.json 进行设置。

// typedoc.json{  "blockTags": ["@example", "@since", "@deprecated"],  "modifierTags": ["@internal", "@public", "@experimental"]}

自定义标签的使用示例：

/** * 执行 HTTP 请求。 * * @since 2.1.0 * @experimental - API 将来可能会更改。 * @example * ```typescript * const result = await httpRequest('https://api.example.com'); * ``` */async function httpRequest(url: string): Promise<Response> {    // ...}

2. 文档化复杂类型和接口

高级文档不仅应描述函数，还应描述复杂的数据结构，尤其是当它们在多个地方使用时。

2.1. 条件类型和映射类型

文档化条件类型，以便开发人员理解它们的工作原理。

/** * 提取数组元素的类型。 * @template T - 数组的类型。 */type ArrayElement<T> = T extends (infer U)[] ? U : never;

/** * 使对象的所有属性变为可选（Partial）。 * @template T - 原始对象类型。 */type DeepPartial<T> = {    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];};