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 コメントを追加

/**
 * ユーザー認証を管理するサービス
 *
 * @remarks
 * bcryptパスワードハッシング付きのJWTベース認証を処理します。
 *
 * @example
 * ```typescript
 * const authService = new AuthService(config);
 * const token = await authService.login(email, password);
 * ```
 *
 * @security
 * - bcryptでパスワードをハッシュ化(コスト係数 12)
 * - JWTトークンをRS256で署名
 */
@Injectable()
export class AuthService {
  /**
   * ユーザーを認証してアクセストークンを返す
   * @param credentials - ユーザーログイン認証情報
   * @returns トークン付き認証結果
   * @throws {InvalidCredentialsError} 認証情報が無効な場合
   */
  async login(credentials: LoginCredentials): Promise<AuthResult> {
    // 実装
  }
}

3. ADR を作成

# ADR-001: TypeScript ストリクトモード設定

## ステータス
承認済み

## コンテキスト
この決定を促す問題は何ですか?

## 決定
何を提案していますか?

## 結果
何が簡単または難しくなりますか?

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 フックのドキュメント化

/**
 * ページネーション付きデータ取得カスタムフック
 *
 * @remarks
 * このフックは読み込み状態、エラーハンドリング、および
 * ページまたはフィルタが変更されたときの自動再取得を管理します。
 *
 * @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エンドポイント
 * @param options - ページネーションおよびフィルタオプション
 * @returns アイテムとメタデータを含むページネーション応答
 */
export function usePaginatedData<T>(
  endpoint: string,
  options: PaginationOptions
): UsePaginatedDataResult<T> {
  // 実装
}

ユーティリティ関数のドキュメント化

/**
 * RFC 5322仕様を使用してメールアドレスを検証
 *
 * @param email - 検証するメールアドレス
 * @returns メール形式が有効な場合はtrue
 *
 * @example
 * ```typescript
 * isValidEmail('user@example.com'); // true
 * isValidEmail('invalid-email');      // false
 * ```
 *
 * @performance
 * O(n) (n はメール文字列の長さ)
 *
 * @see {@link https://tools.ietf.org/html/rfc5322} RFC 5322仕様
 */
export function isValidEmail(email: string): boolean {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

NestJS コントローラーのドキュメント化

/**
 * ユーザー管理用の REST API エンドポイント
 *
 * @remarks
 * すべてのエンドポイントはBearer トークン経由の認証が必要です。
 * レート制限: ユーザーあたり1分間に100リクエスト。
 *
 * @example
 * ```bash
 * curl -H "Authorization: Bearer <token>" https://api.example.com/users/123
 * ```
 *
 * @security
 * - すべてのエンドポイントはHTTPSを使用
 * - JWTトークンは1時間後に期限切れ
 * - 機密データはログから削除
 */
@Controller('users')
export class UsersController {
  /**
   * IDでユーザーを取得
   * @param id - ユーザーUUID
   * @returns ユーザープロフィール(パスワード除外)
   */
  @Get(':id')
  async getUser(@Param('id') id: string): Promise<UserProfile> {
    // 実装
  }
}

ベストプラクティス

1. 公開 API をドキュメント化: すべてのpublicメソッド、クラス、およびインターフェース
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 — 追加コード例