为 TypeScript 项目编写文档：从 A 到 Z

引言：为什么 TypeScript 项目需要文档

高质量的文档不仅仅是一个锦上添花的附加项，而是任何专业 TypeScript 项目中至关重要的元素。它充当着开发者之间的桥梁，简化了新团队成员的入职流程，并有助于避免在使用 API 时出错。TypeScript 凭借其强大的类型系统，为生成精确且自文档化的文档提供了独特的机会。在本文中，我们将剖析完整的流程：从在代码中编写注释到发布最终的文档。

基础：JSDoc 和 TypeScript 的注解

TypeScript 支持 JSDoc 语法，允许直接在代码中添加结构化的注释。这是创建既易于人类理解又便于工具解析的文档的基础。

基本的 JSDoc 标签

从一个简单的两数相加函数示例开始：

/**\n * 将两个数字相加。\n * @param a - 第一个加数。\n * @param b - 第二个加数。\n * @returns 两个数字的和。\n */\nfunction add(a: number, b: number): number {\n    return a + b;\n}

关键标签：

\n
• @param — 描述函数参数。建议指明类型和用途。
\n
• @returns — 描述返回值。
\n
• @throws — 指明函数可能抛出的异常。
\n
• @example — 展示使用示例。
\n

记录复杂类型

对于接口和类型，使用 @property 或在块内描述字段：

interface UserConfig {\n    /** 用户名 */\n    name: string;\n    /** 用户年龄（可选） */\n    age?: number;\n    /** 系统角色 */\n    role: 'admin' | 'user';\n}\n\n/**\n * 创建用户配置。\n * @param config - 包含用户设置的对象。\n * @returns 配置对象。\n */\nfunction createUser(config: UserConfig): UserConfig {\n    return config;\n}

对泛型使用 @template：

/**\n * 用于存储值的包装器。\n * @template T - 存储值的类型。\n */\nclass Box<T> {\n    /** 存储的值 */\n    value: T;\n    constructor(value: T) {\n        this.value = value;\n    }\n}

文档生成工具：TypeDoc

TypeDoc 是从 TypeScript 中的 JSDoc 注释自动生成文档的主要工具。它会创建一个带有便捷导航的静态 HTML 网站。

安装与配置

将 TypeDoc 安装为开发依赖项：

npm install --save-dev typedoc

在项目根目录创建配置文件 typedoc.json：

{\n  "entryPoints": ["src/index.ts"],\n  "out": "docs",\n  "theme": "default",\n  "excludePrivate": true,\n  "excludeProtected": false,\n  "includeVersion": true,\n  "categorizeByGroup": true\n}

配置参数：

\n
• entryPoints — 项目的入口点（通常是主导出文件）。
\n
• out — 生成文档的输出文件夹。
\n
• excludePrivate — 隐藏类的私有成员。
\n
• includeVersion — 在文档中包含项目版本。
\n

运行生成

在 package.json 中添加脚本：

{\n  "scripts": {\n    "docs:generate": "typedoc"\n  }\n}

执行命令：

npm run docs:generate

之后，docs 文件夹中会出现一个静态网站。在浏览器中打开 docs/index.html。

编写文档的最佳实践

为了使文档有用，请遵循以下几个规则。

1. 编写注释