accelint-ts-documentation

コードドキュメントスキル

JSDoc コメント、コメントマーカー、コメント全般の品質など、JavaScript／TypeScript のドキュメントを改善するための包括的なスキルです。

このスキルを有効にするタイミング

タスクに以下が含まれる場合に使用します。

JSDoc ドキュメント

• エクスポートされた関数、型、インターフェース、クラスに JSDoc コメントを追加する
• JSDoc の完全性を検証する（@param、@returns、@template タグの不足など）
• JSDoc の @example タグで適切なコードフェンスが使われていることを確認する
• ドット記法を使って、分割代入を伴うオブジェクトパラメーターをドキュメント化する

コメントの品質

• 適切なマーカー（TODO、FIXME、HACK、NOTE、PERF、REVIEW、DEBUG、REMARK）を使ってコメントを特定し、分類する
• 不要なコメント（コメントアウトされたコード、編集履歴、明白な記述）を削除する
• 重要なコメント（マーカー、リンター指示、ビジネスロジック）を保持する
• コメントの位置を改善する（行末コメントをコードの上に移動する）

ドキュメントの監査

• コードのドキュメントが十分か確認する
• エクスポートされたコードに包括的なドキュメントがあることを確認する
• 内部コードに最低限必要なドキュメントがあることを確認する

このスキルを有効にしないケース

以下の場合は有効にしないでください。

• 一般的なコード品質の問題（代わりに accelint-ts-best-practices を使用）
• パフォーマンスの最適化（代わりに accelint-ts-performance を使用）
• 型安全性の改善（代わりに accelint-ts-best-practices を使用）
• フレームワーク固有のドキュメント（React PropTypes、Vue props など）

使用方法

1. タスクの種類に応じてリファレンスを読み込む

JSDoc の追加／検証の場合：

必須：実装する前に jsdoc.md を最後まで読んでください。 重要な内容：@example のコードフェンス構文（ここでよく失敗します）、オブジェクトパラメーターのドット記法、@template の要件、エッジケース。

タスクでコメントマーカー（TODO、FIXME など）やコメント品質の問題が明示的に扱われていない限り、 comments.md は読み込まないでください。

コメント品質の監査の場合：

必須：実装する前に comments.md を最後まで読んでください。 重要な内容：コメントマーカーの基準、削除するコメントと保持するコメント、配置ルール。

タスクで JSDoc タグ（@param、@returns など）や関数／型のドキュメントが明示的に扱われていない限り、 jsdoc.md は読み込まないでください。

質問に答えるだけの場合（変更を実装しない場合）や、タスクが一般的なコード品質に関するものである場合は、 リファレンスを読み込まないでください。

2. 専門家の判断フレームワーク

監査の前に、次の思考フレームワークを適用してください。

質問 1：読者は誰ですか？

• API の利用者：実装のコンテキストを知りません → 包括的にドキュメント化する
• チームメンバー：コードベースのコンテキストを把握しています → 自明でない動作だけをドキュメント化する
• 6 か月後の自分：細かな判断を忘れています → 理由をドキュメント化する

質問 2：不透明さと複雑さのどちらですか？

• 不透明さ ＝ 意図が隠れている → ドキュメント化が必要（例：cache.invalidate() - なぜか？ パフォーマンスのためか？ 正しさのためか？）
• 複雑さ ＝ 実装が入り組んでいる → JSDoc ではなく、実装についてのコメントを付ける

質問 3：保守コストとのトレードオフはどうですか？

• 変更頻度の高いコード：ドキュメントは最小限にする（正確さを保てないため）
• 安定した API：包括的にドキュメント化する（正確さを保てるため）
• 内部ユーティリティ：簡潔にドキュメント化する（読者数が少なく、利用頻度も低い ＝ 投資対効果が最小限）

2 段階の判断ルール

思考フレームワークを適用した後、次のように判断してください。

これはエクスポートされていますか（パブリック API）？ → はい：包括的なドキュメントが必須です

• すべての @param、@returns、@template、@throws、@example
• 「明白」であっても記載する（利用者はあなたのコンテキストを知りません）

これは内部コードですか？ → 次の情報から自明でない内容を判断して、ドキュメント化します。

1. 関数名と型シグネチャ
2. パラメーター名と型
3. コードベース内の標準的なパターン

目安：「なぜ？」や「エッジケースは何ですか？」と、十分な知識を持つチームメンバーが尋ねそうなら、ドキュメント化してください。「明白です」と言いそうなら、省略してください。

3. ドキュメントの十分性を評価する

この判断ツリーを使用して、ドキュメントが完全かどうかを判断します。

ステップ 1：可視性ティアを判断する

Is it exported (public API)?
  YES → Tier 1: Comprehensive documentation required
  NO  → Tier 2: Judgment-based minimal documentation

ステップ 2：エンティティ固有の要件を適用する

ティア 1（エクスポート対象）— 常に必須：

• 説明（目的、使用状況、適切なエンティティでは「いつ使うか」）
• すべての @param。オブジェクトの場合はプロパティの説明も含めます
• @returns（void の場合を除く）
• ジェネリクスの場合は、制約の説明を含む @template
• 発生条件を記載した @throws
• 現実的な @example を少なくとも 1 つ

ティア 2（内部）— 判断に基づく：

• 簡潔な説明（1 行でも可）
• 自明でないパラメーターのみ @param を記載
• 自明でない場合は @returns を記載
• ジェネリクスの場合は @template を記載
• 動作が複雑な場合のみ @example を記載

エンティティ固有の追加要件：

• クラス（ティア 1）：コンストラクターのドキュメント、パブリックメソッドのドキュメント、インスタンス化の例
• 型／インターフェース（ティア 1）：すべてのパブリックプロパティの説明
• 定数／変数：該当する場合は単位／制約（例：「ミリ秒」、「正の値であること」）

十分性チェックリスト：

ドキュメントを「十分」と判定する前に、次の項目を確認します。

• すべてのエクスポート対象に包括的なドキュメントがある
• すべての @param タグで、パラメーターの役割が説明されている（型情報だけではない）
• すべての @returns タグで、各状況で何が返されるかが説明されている
• すべての @example タグで、言語識別子を含む適切なコードフェンスが使われている
• void 関数に @returns がない
• ジェネリック関数で、各型パラメーターに @template がある
• オブジェクトパラメーターのプロパティの説明にドット表記が使われている
• 説明が HOW ではなく WHAT／WHY に重点を置いている

4. 参考資料が不十分な場合

参考資料や標準的なパターンで対応できない状況に遭遇した場合は、次のようにします。

フォールバック戦略：

1. エクスポート対象と内部要素の 2 段階ルールを基本として適用する
2. 完全性より明確さを優先する — 構文を推測するより、分かっていることを記載する
3. TypeScript／JSDoc の公式ドキュメントにある標準的な JSDoc 規約を使用する
4. 不確かな点には NOTE マーカーを付けて記録する：// NOTE: JSDoc syntax may need review for [specific case]
5. 本当に曖昧な場合は、推測せずにユーザーに確認する

よくある未対応の状況：

• 特殊な TypeScript 機能（マップ型、条件型、テンプレートリテラル型）
• フレームワーク固有のパターン（ジェネリクスを使う React フック、Vue コンポーザブル）
• 複数のオーバーロードを持つ複雑なコールバックシグネチャ

このような場合は、不完全な JSDoc タグを付けるのではなく、自然言語で明確に説明します。

4. レポートテンプレートを使用する（明示的な監査依頼の場合）

ユーザーがドキュメント監査を明示的に依頼した場合、またはスキルを直接呼び出した場合（/accelint-ts-documentation <path>）は、標準化されたレポート形式を使用します。

テンプレート： assets/output-report-template.md

監査レポートの形式には、次の内容が含まれます。

• 修正前／修正後の明確な例を示した番号付きの指摘事項
• 分類（不足、不完全、構文の誤り、品質、内部）
• 詳細なガイダンス（jsdoc.md、comments.md）への参照
• すべての問題を追跡するための概要表

監査テンプレートを使用する場合：

• /accelint-ts-documentation <path> でスキルを直接呼び出した場合
• ユーザーが「ドキュメント監査」または「ドキュメントを監査」と明示的に依頼した場合
• ユーザーがファイル全体の「すべてのドキュメントをレビュー」するよう依頼した場合

監査テンプレートを使用しない場合：

• ユーザーが「この関数に JSDoc を追加して」と依頼した場合（直接実装する）
• ユーザーが「このコメントのどこが問題ですか？」と質問した場合（質問に回答する）
• ユーザーが具体的な修正を依頼した場合（正式なレポートを作成せず、修正を直接適用する）

ドキュメント監査で避けるべきアンチパターン

ドキュメント監査を行う際は、次のよくある間違いを避けてください。

❌ 誤り：内部コードを過剰にドキュメント化する

// Internal utility with verbose documentation
/**
 * Internal helper function that validates input
 * @internal
 * @param x - The input value
 * @returns True if valid, false otherwise
 * @example
 * ```typescript
 * if (isValid(data)) { ... }
 * ```
 */
function isValid(x: unknown): boolean {
  return x != null;
}

これが誤りである理由：内部ドキュメントは、頻繁に変更される実装に隣接しているため、公開 API のドキュメントよりも早く古くなります。チームメンバーは、古くなったドキュメントを読んで混乱するより、実際の実装を読んだほうが早く理解できます。実装にアクセスできない利用者向けに、安定したエクスポート済み API の包括的なドキュメントを用意してください。

✅ 正しい例：内部ドキュメントは最小限に、公開 API のドキュメントは包括的にする

// Internal utility - minimal documentation
/** Checks if value is not null/undefined */
function isValid(x: unknown): boolean {
  return x != null;
}

// Public API - comprehensive documentation even if "obvious"
/**
 * Validates user input data
 * @param data - User input to validate
 * @returns True if data is defined and not null
 * @example
 * ```typescript
 * if (validateInput(userData)) {
 *   processData(userData);
 * }
 * ```
 */
export function validateInput(data: unknown): boolean {
  return data != null;
}

❌ 誤り：WHAT／WHY ではなく HOW をドキュメント化する

// JSDoc describes implementation details
/**
 * Loops through array using reduce to accumulate values into a sum
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

これが誤りである理由：JSDoc は、実装にアクセスできない API 利用者の IDE の自動補完に表示されます。JSDoc で HOW を説明すると、混乱を招きます（「自動補完に実装の詳細が表示されるのはなぜ？」）。また、リファクタリングの対象範囲も広がります。実装を変更するたびにドキュメントも更新する必要があり、内容にずれが生じます。

✅ 正しい例：実装ではなく、目的と振る舞いを説明する

/**
 * Calculates the sum of all numbers in the array
 * @param numbers - Array of numbers to sum
 * @returns The total sum, or 0 for empty array
 */
function sum(numbers: number[]): number {
  return numbers.reduce((a, b) => a + b, 0);
}

❌ 誤り：曖昧なコメントマーカーを使う

// Not actionable
// TODO: fix this
// TODO: improve performance

これが誤りである理由：「TODO: fix this」は、責任の所在を曖昧にします。数か月たつと、まだ対応が必要なのか、誰が修正すべきなのか、「this」が何を指すのか、誰にもわからなくなります。曖昧なマーカーがノイズとして蓄積すると、すべてのマーカーへの信頼が損なわれ、開発者は重要なマーカーまで無視するようになります。

✅ 正しい例：担当者と背景を明記した具体的なマーカーを使う

// TODO(username): Replace with binary search for O(log n) lookup
// FIXME(username): Throws error on empty array, add guard clause

ドキュメントの品質例

優れた公開 API ドキュメント

/**
 * Fetches user profile data from the authentication service
 *
 * Automatically retries up to 3 times on network failures with exponential
 * backoff. Throws if user is not authenticated or profile doesn't exist.
 *
 * @param userId - Unique identifier for the user profile to fetch
 * @param options - Configuration for fetch behavior
 * @param options.includeMetadata - Include account metadata (creation date, last login)
 * @param options.timeout - Request timeout in milliseconds (default: 5000)
 * @returns User profile with email, name, and optional metadata
 * @throws {AuthenticationError} When user session is expired or invalid
 * @throws {NotFoundError} When user profile doesn't exist
 * @throws {NetworkError} When all retry attempts are exhausted
 *
 * @example
 * ```typescript
 * // Basic usage
 * const profile = await fetchUserProfile('user-123');
 * console.log(profile.email);
 *
 * // With metadata and custom timeout
 * const profile = await fetchUserProfile('user-123', {
 *   includeMetadata: true,
 *   timeout: 10000
 * });
 * ```
 */
export async function fetchUserProfile(
  userId: string,
  options?: { includeMetadata?: boolean; timeout?: number }
): Promise<UserProfile> {
  // implementation
}

優れている理由：

• 表に出ない振る舞い（指数バックオフによる再試行ロジック）を説明している
• オブジェクトのパラメーターをドット記法（options.*）でドキュメント化している
• @throws に、発生条件とともに考えられるすべてのエラーを記載している
• @example で、基本的な使用パターンと高度な使用パターンの両方を示している
• デフォルト値と制約（タイムアウトのデフォルト値：5000）に触れている
• HOW（実装の詳細）ではなく、WHAT／WHY（ユーザーのニーズ）に重点を置いている

競合を解決するための原則

判断が分かれる場合は、次の優先順位に従ってください。

1. 完璧さより一貫性：既存のコードベースのパターンに従う
2. メンテナーより利用者：公開 API のドキュメントは、あなたが持つ背景情報のない利用者向けです。包括的に記述する
3. 実装より意図：HOW ではなく、WHAT／WHY をドキュメント化する
4. 頻繁な変更より安定性：安定したコードには包括的なドキュメントを、変更頻度の高いコードには最小限のドキュメントを用意する
5. 将来の明確さを確認する：「6 か月後の自分に役立つか？」いいえなら、削除する

エッジケースではリファレンスの読み込みが必要

複雑なケース（非推奨 API、オーバーロード関数、ジェネリックユーティリティ型、コールバックパラメーター、ビルダーパターン、イベントエミッター）では、構文に関する詳細な指針が必要です。これらに遭遇した場合は、次の手順を実施してください。

jsdoc.md のリファレンスを読み込む — すべてのエッジケースについて、正しい構文パターンを使った包括的な例が記載されています。

重要な原則：エッジケースでも 2 階層ルール（エクスポート対象か内部か）に従いますが、構文の詳細がより重要です。推測せず、リファレンスを読み込んでください。