jsdoc

JSDoc

JSDoc は、慎重に読んでも名前や型だけでは意図、制約、失敗時の動作が推測できない場合にのみ追加します。形状の表現には TypeScript の型を優先し、JSDoc では「なぜ」「いつ」「何が壊れるか」を説明します。

ドキュメントを記述する場合

次のいずれかに当てはまるシンボルには、ドキュメントを記述します。

• 制御フロー、アルゴリズム、状態機械が、ひと目で理解できない。
• 動作が不変条件、順序、タイミング、冪等性、並行性に依存する。
• 副作用が重要である（I/O、変更、キャッシュ、ネットワーク、タイマー、グローバル状態）。
• 失敗時の動作、例外のスロー、空の結果、部分的な成功が契約の一部である。
• 単位、範囲、形式、ドメイン上の意味が型から明らかでない。
• 呼び出し元が実装を読まずに使う、公開またはエクスポートされた API である。
• 非推奨化、移行、セキュリティ、互換性に関する制約がある。

ドキュメントを記述しない場合

次の場合は JSDoc を省略します。

• 名前と TypeScript の型で、シンボルの意味がすでに説明されている。
• 本体が単純な getter、setter、パススルー、または一行の map/filter である。
• コメントがパラメーターや戻り値の型を言い換えるだけである。
• 次の行で行うことを説明している（// increment i）。
• 生成コード、自己説明的なフィクスチャを使ったテスト、ベンダー提供のファイルである（公開テストヘルパーの説明を除く）。

既定では、コメントを付けません。雑音になるくらいなら、何も書かない方がよいでしょう。

TypeScript のルール

1. 形状は型で表します。 シグネチャに id: string とある場合、JSDoc で型を重複して記述しないでください（@param {string} id）。
2. 意味は JSDoc で伝えます。 型では表現できない動作について、説明文と必要なタグを使います。
3. TS のドキュメントでは、型の波括弧を付けずに @param name / @returns の説明を記述します。
4. 最初の文は、動作や目的の要約とし、シンボル名の言い換えにしないでください。
5. 自明でないジェネリクスには、T が何を表すか、また型制約以外にどのような制約があるかを短く記述します。
6. オーバーロードでは、異なる呼び出しパターンごとに説明します。共通する注意事項は、実装または主要なエクスポートに記載します。
7. プロジェクト内で既存の JSDoc スタイル（タグの種類、句読点、@returns と @return の使い分け）が主流であれば、それに合わせます。

ドキュメントを記述するシンボルに必要な内容

追加する JSDoc ブロックには、すべて次の内容を含める必要があります。

1. 要約 — 何をするのか、またはなぜ存在するのかを示す一文（「この関数は…」のような不要な前置きは避けます）。
2. 自明でない詳細 — 不変条件、順序、副作用、エッジケース、単位、セキュリティなど、読者が見落とす内容に限ります。

タグは、必要な場合にのみ追加します。

タグ	使用する場合
@param	型だけでは表せない、パラメーターの意味、単位、有効範囲、「…でなければならない」という制約
@returns	値の意味、空またはセンチネルの場合、「戻らない」といった契約
@throws	呼び出し元が対処すべき、明記されたエラー条件
@example	型だけでは伝わらない、複雑な使用例（短く記述し、通常は一例で十分です）
@see	関連するシンボル、RFC、チケット、アルゴリズムの出典
@deprecated	置き換え先と削除の意図
@template	JS ファイル、またはジェネリクスの役割を説明する場合のみ使用します。.ts では型パラメーターを優先します。

プロジェクトで使用実績のないタグを新たに導入しないでください。標準的な JSDoc/TS 対応タグを優先します。

ワークフロー

1. 範囲を決める — ユーザーが指定したファイル、シンボル、または「公開 API のみ」を対象とします。不明確な場合は、非公開ヘルパーよりも、エクスポートされたシンボルや複雑なシンボルを優先します。
2. 候補を調べる — 「ドキュメントを記述する場合」の一覧を使って候補を見つけます。明白なコードは対象外にします。
3. 既存の JSDoc を監査する — 型を言い換えている、動作と一致しない、明白な内容を説明しているコメントは削除または書き直します。
4. 記述する — 簡潔なブロックを追加し、別のドキュメントファイルではなく、シンボルの箇所を直接編集することを優先します。
5. 検証する — 新しいチームメンバーが、すべての呼び出し先を開かなくても難しい部分を理解できるかを読み返します。型と説明の内容が一致していることも確認します。

品質基準

良い JSDoc：

• シグネチャからは分からない制約や失敗のパターンを説明しています。
• 実装の詳細が変わっても、同じ契約のもとで正確さを保ちます。
• 可能な限り、説明対象のコードより短くなっています。

悪い JSDoc：

• @param id - The id
• シグネチャにすでに記載されているのに、@returns {Promise<User>} と書く
• 関数本体を重複して説明する長文
• コードと矛盾する古いコメント（削除するか修正し、誤った説明を残さないでください）

例

具体的な良い／悪いパターン：examples.md。

完了時

対象範囲のドキュメント作成を依頼された場合は、以下を簡潔に報告してください。

• ドキュメントを作成した対象と、その対象が基準を満たした理由。
• ドキュメントを作成しなかった対象（意図的な判断であることも明記してください）。
• ノイズとして削除した JSDoc、または誤りとして修正した JSDoc。