TypeDoc 简介 #

┌─────────────────┐
│   TypeScript    │
│   源代码 + 注释  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    TypeDoc      │
│   解析与生成     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   HTML 文档      │
│   可浏览的网站    │
└─────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                        TypeDoc                               │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  类型解析    │  │  注释提取    │  │  HTML 生成   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  主题定制    │  │  插件扩展    │  │  搜索功能    │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘

2013年 ─── TypeDoc 项目启动
    │
    │      Sebastian Lasse 创建
    │      专为 TypeScript 设计
    │      基于 TypeScript Compiler API
    │
2015年 ─── TypeDoc 0.4
    │
    │      支持更多 TypeScript 特性
    │      改进的模板系统
    │
2017年 ─── TypeDoc 0.9
    │
    │      插件系统引入
    │      主题定制功能
    │
2019年 ─── TypeDoc 0.15
    │
    │      支持 TypeScript 3.x
    │      性能优化
    │
2021年 ─── TypeDoc 0.20
    │
    │      完全重写的解析器
    │      更好的类型支持
    │
2022年 ─── TypeDoc 0.23
    │
    │      支持 TypeScript 4.x
    │      新的主题系统
    │
2024年 ─── TypeDoc 0.25+
    │
    │      支持 TypeScript 5.x
    │      ESM 模块支持
    │      持续更新迭代

// 手动维护文档，容易与代码不同步
/**
 * 用户服务 - 手动文档
 * 
 * 方法：
 * - getUser(id: number): User - 获取用户
 * - createUser(data: UserData): User - 创建用户
 * - updateUser(id: number, data: UserData): User - 更新用户
 * 
 * 问题：
 * 1. 参数类型变更后文档需要手动更新
 * 2. 容易遗漏新增的方法
 * 3. 返回类型描述可能过时
 */
export class UserService {
  // 实现代码...
}

// 代码即文档，自动同步
/**
 * 用户服务 - 提供用户相关的 CRUD 操作
 * 
 * @example
 * ```typescript
 * const userService = new UserService();
 * const user = await userService.getUser(1);
 * ```
 */
export class UserService {
  /**
   * 根据ID获取用户信息
   * @param id - 用户唯一标识
   * @returns 用户对象
   * @throws {NotFoundError} 用户不存在时抛出
   */
  async getUser(id: number): Promise<User> {
    // 实现...
  }
}
// TypeDoc 自动生成完整文档，包含类型信息

// 自动识别类型信息
interface User {
  id: number;
  name: string;
  email: string;
}

// 自动提取类型参数
function createUser<T extends User>(data: Omit<T, 'id'>): T {
  return { id: generateId(), ...data } as T;
}

/**
 * 计算两个数的和
 * 
 * @param a - 第一个加数
 * @param b - 第二个加数
 * @returns 两数之和
 * 
 * @example
 * ```typescript
 * const result = add(1, 2); // 3
 * ```
 * 
 * @see {@link https://example.com | 参考文档}
 */
function add(a: number, b: number): number {
  return a + b;
}

// TypeDoc 自动生成文档，包含完整类型信息
export type Result<T> = 
  | { success: true; data: T }
  | { success: false; error: string };

export async function fetchData<T>(url: string): Promise<Result<T>> {
  // TypeDoc 会展示：
  // - 泛型参数 T
  // - 联合类型 Result<T>
  // - Promise 返回类型
}

┌─────────────────────────────────────────────────────────────┐
│                    TypeDoc 默认主题                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────┐  ┌─────────────────────────────────────────┐  │
│  │ 导航栏   │  │              主内容区                    │  │
│  │         │  │                                         │  │
│  │ 模块列表 │  │  类/接口/函数定义                        │  │
│  │ 类列表   │  │  参数说明                               │  │
│  │ 接口列表 │  │  返回类型                               │  │
│  │ 函数列表 │  │  示例代码                               │  │
│  │         │  │                                         │  │
│  └─────────┘  └─────────────────────────────────────────┘  │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                    搜索功能                          │   │
│  └─────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

# 常用插件
typedoc-plugin-markdown    # Markdown 输出
typedoc-theme-hierarchy    # 层级主题
typedoc-plugin-merge-modules  # 模块合并
typedoc-plugin-external-module-name  # 自定义模块名

// 文档中所有内容都可搜索
// - 类名、方法名、属性名
// - 注释内容
// - 类型定义

// 为开源库生成专业文档
/**
 * @packageDocumentation
 * 
 * 这是一个工具库，提供常用的工具函数。
 * 
 * @example
 * ```typescript
 * import { debounce, throttle } from 'my-utils';
 * 
 * const debouncedFn = debounce(() => {}, 300);
 * ```
 */

export function debounce(fn: Function, delay: number): Function {
  // ...
}

// 为团队内部项目生成 API 文档
/**
 * 内部服务 API
 * 
 * @module InternalAPI
 * @internal
 */

/**
 * 获取系统配置
 * @internal 仅内部使用
 */
export function getSystemConfig(): SystemConfig {
  // ...
}

// 为 React/Vue 组件库生成文档
/**
 * 按钮组件
 * 
 * @example
 * ```tsx
 * <Button variant="primary" onClick={handleClick}>
 *   点击我
 * </Button>
 * ```
 */
export interface ButtonProps {
  /** 按钮变体样式 */
  variant?: 'primary' | 'secondary' | 'danger';
  /** 点击事件处理 */
  onClick?: () => void;
  /** 子元素 */
  children: React.ReactNode;
}

export const Button: React.FC<ButtonProps> = (props) => {
  // ...
};

// 为 SDK 生成完整的 API 参考
/**
 * SDK 客户端
 * 
 * @example
 * ```typescript
 * const client = new SDKClient({
 *   apiKey: 'your-api-key',
 *   endpoint: 'https://api.example.com'
 * });
 * 
 * const result = await client.query({ ... });
 * ```
 */
export class SDKClient {
  /**
   * 创建 SDK 客户端实例
   * @param config - 配置选项
   */
  constructor(private config: SDKConfig) {}
  
  /**
   * 执行查询
   * @param params - 查询参数
   * @returns 查询结果
   */
  async query<T>(params: QueryParams): Promise<QueryResult<T>> {
    // ...
  }
}

my-project/
├── src/
│   ├── index.ts          # 入口文件
│   ├── utils/
│   │   ├── index.ts
│   │   └── helpers.ts
│   └── services/
│       ├── index.ts
│       └── api.ts
├── docs/                  # 生成的文档
├── typedoc.json          # TypeDoc 配置
└── package.json

// typedoc.json
{
  "entryPoints": ["src/index.ts"],
  "out": "docs"
}

// 或多个入口点
{
  "entryPoints": [
    "src/core/index.ts",
    "src/utils/index.ts",
    "src/plugins/index.ts"
  ]
}

/**
 * 简短描述
 * 
 * 详细描述，可以包含更多说明。
 * 支持多行文本。
 * 
 * @param name - 参数说明
 * @returns 返回值说明
 * @throws 可能抛出的异常
 * 
 * @example
 * ```typescript
 * // 使用示例
 * ```
 * 
 * @see 相关引用
 * @since 版本信息
 * @deprecated 弃用说明
 */

┌─────────────────────────────────────────────────────────────┐
│                    TypeDoc 工作流程                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 读取配置                                                │
│     ┌─────────────────┐                                    │
│     │  typedoc.json   │                                    │
│     └────────┬────────┘                                    │
│              │                                              │
│              ▼                                              │
│  2. 解析 TypeScript                                        │
│     ┌─────────────────┐                                    │
│     │  TypeScript     │                                    │
│     │  Compiler API   │                                    │
│     └────────┬────────┘                                    │
│              │                                              │
│              ▼                                              │
│  3. 提取信息                                                │
│     ┌─────────────────┐                                    │
│     │  类型信息       │                                    │
│     │  JSDoc 注释     │                                    │
│     │  导出声明       │                                    │
│     └────────┬────────┘                                    │
│              │                                              │
│              ▼                                              │
│  4. 生成文档                                                │
│     ┌─────────────────┐                                    │
│     │  HTML 模板      │                                    │
│     │  主题渲染       │                                    │
│     └────────┬────────┘                                    │
│              │                                              │
│              ▼                                              │
│  5. 输出文件                                                │
│     ┌─────────────────┐                                    │
│     │  HTML/CSS/JS    │                                    │
│     │  静态网站       │                                    │
│     └─────────────────┘                                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

✅ 原生 TypeScript 支持
   - 自动类型推断
   - 完整类型信息
   - 泛型支持

✅ 零配置快速开始
   - 开箱即用
   - 合理默认值
   - 简单易用

✅ 美观的默认主题
   - 专业外观
   - 响应式设计
   - 搜索功能

✅ 强大的插件系统
   - 丰富的插件生态
   - 自定义主题
   - 扩展功能

✅ 活跃的社区
   - 持续更新
   - 问题响应快
   - 文档完善

⚠️ 大型项目性能
   - 文件多时编译较慢
   - 可通过增量编译优化

⚠️ 复杂类型支持
   - 某些高级类型可能显示不完美
   - 类型体操结果可能难以展示

⚠️ 自定义主题复杂度
   - 需要了解 Handlebars
   - 主题 API 较底层

⚠️ Markdown 渲染
   - 某些 Markdown 语法支持有限
   - 代码高亮需要配置

入门阶段
├── TypeDoc 简介（本文）
├── 安装与配置
└── 基本使用

进阶阶段
├── 配置详解
├── 注解标签
└── 主题定制

高级阶段
├── 插件开发
├── 自定义主题
└── CI/CD 集成

实战阶段
├── 开源库文档
├── 组件库文档
└── 最佳实践