typescript-docs

TypeScript 文档

为不同受众生成采用分层架构、可用于生产环境的 TypeScript 文档。支持使用 TypeDoc 编写 API 文档、ADR 和框架特定模式。

概述

使用 JSDoc 注释编写内联文档，使用 TypeDoc 生成 API 参考文档，并使用 ADR 跟踪设计决策。

主要功能：

• 配置 TypeDoc 并生成 API 文档
• 适用于所有 TypeScript 结构的 JSDoc 模式
• 创建和维护 ADR
• 框架特定模式（NestJS、React、Express、Angular、Vue）
• 用于保障文档质量的 ESLint 验证规则
• 配置 GitHub Actions 流水线

适用场景

创建 API 文档、架构决策记录、代码示例，或为 NestJS、Express、React、Angular、Vue 编写框架特定模式时，使用此技能。

快速参考

工具	用途	命令
TypeDoc	生成 API 文档	npx typedoc
Compodoc	Angular 文档	npx compodoc -p tsconfig.json
ESLint JSDoc	文档验证	eslint --ext .ts src/

JSDoc 标签

标签	使用场景
@param	说明参数
@returns	说明返回值
@throws	说明错误情况
@example	提供代码示例
@remarks	添加实现说明
@see	交叉引用相关项目
@deprecated	标记已弃用的 API

操作说明

1. 配置 TypeDoc

npm install --save-dev typedoc typedoc-plugin-markdown

{
  "entryPoints": ["src/index.ts"],
  "out": "docs/api",
  "theme": "markdown",
  "excludePrivate": true,
  "readme": "README.md"
}

2. 添加 JSDoc 注释

/**
 * Service for managing user authentication
 *
 * @remarks
 * Handles JWT-based authentication with bcrypt password hashing.
 *
 * @example
 * ```typescript
 * const authService = new AuthService(config);
 * const token = await authService.login(email, password);
 * ```
 *
 * @security
 * - Passwords hashed with bcrypt (cost factor 12)
 * - JWT tokens signed with RS256
 */
@Injectable()
export class AuthService {
  /**
   * Authenticates a user and returns access tokens
   * @param credentials - User login credentials
   * @returns Authentication result with tokens
   * @throws {InvalidCredentialsError} If credentials are invalid
   */
  async login(credentials: LoginCredentials): Promise<AuthResult> {
    // Implementation
  }
}

3. 创建 ADR

# ADR-001: TypeScript Strict Mode Configuration

## Status
Accepted

## Context
What is the issue motivating this decision?

## Decision
What change are we proposing?

## Consequences
What becomes easier or more difficult?

4. 设置 CI/CD 流水线

name: Documentation
on:
  push:
    branches: [main]
    paths: ['src/**', 'docs/**']

jobs:
  generate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run docs:generate
      - run: npm run docs:validate

5. 验证文档

{
  "rules": {
    "jsdoc/require-description": "error",
    "jsdoc/require-param-description": "error",
    "jsdoc/require-returns-description": "error",
    "jsdoc/require-example": "warn"
  }
}

**如果验证失败：**检查 ESLint 错误，修复 JSDoc 注释（补充缺失的说明，以及缺少的 @param/@returns/@throws），然后重新运行 eslint --ext .ts src/，直到所有错误都解决后再提交。

示例

编写 React Hook 文档

/**
 * Custom hook for fetching paginated data
 *
 * @remarks
 * This hook manages loading states, error handling, and automatic
 * refetching when the page or filter changes.
 *
 * @example
 * ```tsx
 * function UserList() {
 *   const { data, isLoading, error } = usePaginatedData('/api/users', {
 *     page: currentPage,
 *     limit: 10
 *   });
 *
 *   if (isLoading) return <Spinner />;
 *   if (error) return <ErrorMessage error={error} />;
 *   return <UserTable users={data.items} />;
 * }
 * ```
 *
 * @param endpoint - API endpoint to fetch from
 * @param options - Pagination and filter options
 * @returns Paginated response with items and metadata
 */
export function usePaginatedData<T>(
  endpoint: string,
  options: PaginationOptions
): UsePaginatedDataResult<T> {
  // Implementation
}

编写工具函数文档

/**
 * Validates email addresses using RFC 5322 specification
 *
 * @param email - Email address to validate
 * @returns True if email format is valid
 *
 * @example
 * ```typescript
 * isValidEmail('[email protected]'); // true
 * isValidEmail('invalid-email');      // false
 * ```
 *
 * @performance
 * O(n) where n is the email string length
 *
 * @see {@link https://tools.ietf.org/html/rfc5322} RFC 5322 Specification
 */
export function isValidEmail(email: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

NestJS 控制器文档

/**
 * REST API endpoints for user management
 *
 * @remarks
 * All endpoints require authentication via Bearer token.
 * Rate limiting: 100 requests per minute per user.
 *
 * @example
 * ```bash
 * curl -H "Authorization: Bearer <token>" https://api.example.com/users/123
 * ```
 *
 * @security
 * - All endpoints use HTTPS
 * - JWT tokens expire after 1 hour
 * - Sensitive data is redacted from logs
 */
@Controller('users')
export class UsersController {
  /**
   * Retrieves a user by ID
   * @param id - User UUID
   * @returns User profile (password excluded)
   */
  @Get(':id')
  async getUser(@Param('id') id: string): Promise<UserProfile> {
    // Implementation
  }
}

最佳实践

1. 记录公开 API：为所有公开方法、类和接口编写文档
2. 使用 @example：为复杂函数提供可运行的示例
3. 添加 @throws：记录所有可能出现的错误
4. 添加 @see：交叉引用相关函数和类型
5. 使用 @remarks：补充实现细节和说明
6. 记录泛型：说明泛型约束和用法
7. 说明性能：记录时间和空间复杂度
8. 添加安全警告：突出安全注意事项
9. 保持更新：代码变更时同步更新文档
10. 不要为显而易见的代码编写文档：关注原因，而非内容

限制和警告

• 私有成员：使用 @private，或从 TypeDoc 输出中排除
• 复杂类型：说明泛型约束和类型参数
• 破坏性变更：使用 @deprecated 并提供迁移指导
• 安全信息：切勿在文档中包含机密或凭据
• 链接有效性：确保 @see 引用指向有效位置
• 示例代码：所有示例都应可运行且经过测试
• 版本管理：确保文档与代码版本保持同步

参考资料

• references/jsdoc-patterns.md — 接口、函数、类、泛型和联合类型的 JSDoc 模式
• references/framework-patterns.md — NestJS、React、Express 和 Angular 的框架特定模式
• references/adr-patterns.md — ADR 模板和示例
• references/pipeline-setup.md — 文档 CI/CD 流水线配置
• references/validation.md — ESLint 规则和验证清单
• references/typedoc-configuration.md — 完整的 TypeDoc 配置选项
• references/examples.md — 其他代码示例