文档生成：使用 TypeDoc 自动生成 API 文档

在开发一个高质量的 TypeScript 工具库时，清晰、准确、自动化的 API 文档是开发者体验（DX）的核心组成部分。手动编写文档不仅耗时，而且极易与代码脱节。

TypeDoc 是专为 TypeScript 设计的文档生成工具，它能：

• 自动解析源码中的类型、函数、类、接口
• 提取 JSDoc 注释生成富文本说明
• 生成结构化的 HTML 文档网站
• 实时反映代码变更，确保文档与实现同步

为什么选择 TypeDoc？

优势	说明
类型即文档	泛型、联合类型、交叉类型等 TS 特性自动渲染
零维护成本	文档随代码提交自动更新
开发者友好	支持 IDE 提示、跳转定义
集成简单	一行命令生成静态网站

对比：JSDoc 仅支持 JavaScript，而 TypeDoc 深度支持 TypeScript 类型系统。

1. 安装与配置

安装 TypeDoc

npm install --save-dev typedoc

配置 typedoc.json

{
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "name": "My Utility Library",
  "readme": "README.md",
  "excludePrivate": true,
  "excludeProtected": true,
  "excludeInternal": true,
  "includeVersion": true,
  "plugin": ["typedoc-plugin-markdown"],
  "theme": "default",
  "sort": ["kind", "alphabetical"],
  "hideGenerator": false,
  "gitRevision": "main"
}

关键配置项

配置	说明
entryPoints	文档入口文件，通常是 src/index.ts
out	输出目录
readme	主页内容
excludePrivate/Protected/Internal	过滤非公开 API
plugin	支持导出 Markdown（便于 GitHub/GitLab 展示）

2. 编写可文档化的代码

TypeDoc 能自动提取类型，但高质量的 JSDoc 注释能让文档更具可读性。

示例：src/function/pipe.ts

/**
 * 将多个函数组合成一个流水线函数，数据从左到右传递。
 *
 * @example
 * 
 * const add1 = (x: number) => x + 1;
 * const mul2 = (x: number) => x * 2;
 * const fn = pipe(add1, mul2);
 * fn(3); // 返回 8
 * 
*
* @param fns - 要组合的函数列表，前一个函数的输出是下一个的输入
* @returns 一个接受初始值并返回最终结果的函数
* @typeParam T - 输入和输出的通用类型（支持类型推导）
* @since 1.0.0
  */
  export function pipe<A, B, C>(
  fn1: (a: A) => B,
  fn2: (b: B) => C
  ): (a: A) => C;

export function pipe<A, B, C, D>(
fn1: (a: A) => B,
fn2: (b: B) => C,
fn3: (c: C) => D
): (a: A) => D;

function pipe(...fns: Array<Function>) {
return <T>(value: T) => fns.reduce((acc, fn) => fn(acc), value);
}

示例：src/object/omit.ts

/**
 * 从对象中排除指定的键，返回一个新对象。
 *
 * @example
 * ```ts
 * const user = { id: 1, name: 'Alice', password: '123' };
 * const safeUser = omit(user, ['password']);
 * // safeUser: { id: 1, name: 'Alice' }
*
* @param obj - 源对象
* @param keys - 要排除的键数组
* @returns 新对象，不包含指定的键
* @typeParam T - 源对象类型
* @typeParam K - 要排除的键类型，必须是 T 的键
* @since 1.0.0
  */
  export function omit<T extends object, K extends keyof T>(
  obj: T,
  keys: K[]
  ): Omit<T, K> {
  // 实现...
  }

3. 生成文档

添加 npm 脚本

{
  "scripts": {
    "docs": "typedoc",
    "docs:watch": "typedoc --watch"
  }
}

运行生成

npm run docs

输出：

TypeDoc version 0.25.2
Loading TypeScript files...
Rendering [========================================] 100%
Documentation generated at ./docs

4. 文档网站预览

打开 docs/index.html 或启动本地服务器：

npx serve docs

生成的文档结构

My Utility Library
├── Functions
│   ├── pipe
│   ├── omit
│   ├── deepGet
│   └── debounce
├── Modules
│   ├── function
│   ├── object
│   └── type
├── Index

功能亮点

• 类型超链接：点击 Omit<T, K> 可跳转到 TypeScript 内置类型定义。
• 代码块高亮：@example 自动渲染为可复制的代码块。
• 版本标记：@since 1.0.0 显示函数引入版本。
• 响应式设计：移动端友好。

5. 高级功能

支持 Markdown 输出

安装插件：

npm install typedoc-plugin-markdown

生成 README.md 风格文档，适合 GitHub 仓库。

自定义主题

npm install typedoc-default-themes

支持夜间模式、自定义 CSS。

集成 GitHub Pages

# .GitHub/workflows/docs.yml
name: Deploy Docs
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install
      - run: npm run docs
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs

访问 https://<user>.github.io/<repo>/ 查看在线文档。

6. 最佳实践

实践	说明
为每个公开函数添加 JSDoc	包括 @param, @returns, @example
使用 @internal 标记私有 API	TypeDoc 会自动排除
保持 README.md 为入口指南	TypeDoc 生成详细 API
在 CI 中自动部署文档	确保最新代码有最新文档
定期审查生成的文档	确保排版和链接正确

结语：文档是代码的“用户界面”

代码是给机器执行的，而文档是给人阅读的。

TypeDoc 让我们摆脱了“写完代码再写文档”的痛苦循环，实现了：

• 一致性：文档与代码同步更新
• 准确性：类型错误在编译阶段暴露
• 效率：一次编写，自动成文

当你运行 npm run docs 并看到 pipe 函数的泛型参数、示例代码、类型链接完整呈现时，你就知道：这个库已经准备好迎接真正的开发者了。

好的工具库，不仅功能强大，更要易于理解和使用。 而 TypeDoc，正是连接“实现”与“使用”的桥梁。