typescript-docs

TypeScript ドキュメント

複数の読者層に向けた、階層化アーキテクチャを備えた本番環境向けの TypeScript ドキュメントを生成します。TypeDoc による API ドキュメント、ADR、フレームワーク固有のパターンに対応しています。

概要

インラインドキュメントには JSDoc アノテーションを、API リファレンスの生成には TypeDoc を、設計上の選択の記録には 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 フックのドキュメント化

/**
 * 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 — その他のコード例