marginalia

Marginalia

このスキルを使うと、読者、IDE、宣言ファイル、生成される API ドキュメントに役立つ、要点を押さえた JSDoc を追加できます。目標は、あらゆる場所にコメントを書くことではなく、適切な境界に簡潔なドキュメントを添えることです。JSDoc が長すぎると IDE のホバー表示が使いにくくなるため、不足している文脈を説明する最短のコメントを優先してください。

TypeScript パッケージの API では、JSDoc を API リファレンスの一次情報として扱い、執筆済みのドキュメントの代わりにはしないでください。Props、エクスポートされる型、デフォルト値、制約、コールバックの契約、非推奨化に関する情報は、公開宣言の近くに記述し、IDE のホバー表示、.d.ts の出力、生成されるドキュメントの内容が一致するようにしてください。使い方ガイド、例、概念の説明、移行に関する注記、レシピなどは、通常 README またはサイトのドキュメントに記載します。

開始

呼び出されたとき：

1. marginalia スキルを使用していることを伝えます。
2. ドキュメントの対象を特定します。
   • 公開パッケージ API
   • パッケージまたはモジュール内のすべてのエクスポート
   • 複雑な内部コードのみ
   • React コンポーネント、フック、ユーティリティ、クラス、型
   • 生成されるドキュメントまたは IDE のホバー表示の品質
3. ユーザーがファイル、シンボル、パッケージ、スコープを指定していない場合は、編集を始める前に、簡潔な確認質問を 1 つ尋ねます。依頼でパッケージのドキュメント、公開用ドキュメント、生成される API ドキュメント、またはパッケージの IDE ホバー表示の品質が明確に言及されている場合に限り、公開 API の確認と推定します。
4. 編集前に、適切な範囲を読み込みます。
   • 対象を絞った確認：依頼されたファイル／シンボル、関連する型、利用可能であれば関連する使用例またはテストを 1 つ
   • 公開 API の確認：package.json の exports／types、公開エントリポイント、バレルファイル、tsconfig*、ドキュメントツール、README／例、代表的な呼び出し箇所
   • 複雑な内部コードの確認：実装、テスト、挙動を明らかにする呼び出し元

名前だけから挙動を推測しないでください。実装と、利用可能であれば少なくとも 1 つの利用経路を確認してください。

ドキュメントの密度

依頼を満たす最小限の密度を選びます。

• 公開 API の確認： パッケージのエントリポイントから到達できるすべてのエクスポート対象シンボルを検討します。挙動、制約、使い方、API の意図を説明する場合にのみ JSDoc を追加し、明白なエクスポートは「対応不要」と記録します。
• 意味のある範囲の確認： エクスポートされるシンボルに加えて、複雑な内部関数、扱いに注意が必要な型、オーバーロード、状態機械、ライフサイクルの挙動、副作用、明白でない制約を文書化します。
• 対象を絞った確認： 指定されたファイル、コンポーネント、シンボルのみを文書化します。

意味のある範囲の確認と対象を絞った確認では、パッケージ API ワークフローのステップ 2〜4（判断、記述、検証）を再利用し、ステップ 1 の公開 API 全体の棚卸しは行いません。

自明なローカル変数、単純な 1 行のラッパー、型シグネチャだけで十分に説明できるコードに、画一的なコメントを付けるのは避けてください。

文書化する内容

次の項目を優先します。

• エクスポートされる関数、クラス、意味が明白でない定数、React コンポーネント、フック、型
• オーバーロード、ジェネリクス、条件型、マップ型、ブランド型、コールバックの契約
• IDE の補完で利用者を案内する必要があるオプションオブジェクトや設定フィールド
• 副作用、スローされるエラー、非同期の挙動、キャッシュ、ライフサイクル、クリーンアップ、順序、冪等性
• 単位、範囲、デフォルト値、安定性の保証、実行環境、SSR／クライアントの制約
• リポジトリでそうした規約を採用している場合の、非推奨化、実験的 API、内部専用のエクスポート

公開パッケージでは、exports と生成される .d.ts ファイルに含まれるシンボルに重点を置きます。保守担当者にも役立つほど複雑な場合に限り、内部ヘルパーに JSDoc を追加してください。

生成される API ドキュメントでは、型だけでは分からないデフォルト値や動作上の制約を、コメントで明確にしてください。リポジトリのツールが認識する場合は、@remarks、@defaultValue、@example、@deprecated、@see、リリースタグなど、標準的な TSDoc 互換タグを優先してください。

コメントのルール

型システムでは表現できない情報を補うコメントを書きます。IDE のホバーで役立つ程度に短く保ちます。

簡潔さのルール：

• シンプルな公開 API には、1 文を優先します。
• 動作や制約を説明する場合は、短い概要と短い段落を 1 つ使います。
• 例は控えめにし、誤用を防ぐのに役立つ場合のみ含めます。
• 長い概念的な説明は JSDoc に含めず、外部ドキュメントに分けます。
• ホバーが記事のように感じられる場合は、短くします。

良い JSDoc：

/**
 * Builds a stable cache key for a request.
 *
 * The key includes the normalized URL and sorted query params so equivalent
 * requests dedupe even when callers pass params in different orders.
 */
export function createRequestKey(input: RequestInput): string {
  // ...
}

避ける例：

/** Gets the user. */
export function getUser(id: string): User;

ルール：

• 簡潔な概要文から始めます。
• 動作、制約、重要な例を説明する場合のみ、2 つ目の段落を追加します。
• TypeScript の名前と型から明らかな場合は、冗長な @param タグより説明文を優先します。
• パラメーターの意味が名前だけでは十分に明らかでない場合や、関数に位置引数、コールバック、オプション、単位、デフォルト値、副作用、または複数の意味がある場合は、公開 API に @param を使用します。
• 戻り値の意味が型から明らかでない場合のみ、@returns を使用します。
• エクスポートされたジェネリクスの役割、制約、推論の動作、デフォルト値、または型パラメーター間の関係が明らかでない場合は、@typeParam を使用します。
• リポジトリのツールやドキュメントで使用されている場合は、@throws、@deprecated、@example、@remarks、@defaultValue、@see、@internal、@public、@alpha、@beta を使用します。
• TypeScript のソースでは、宣言済みの型を @param や @returns の注釈に重複して記述しないでください。プレーンな JavaScript では、JSDoc の型注釈が IDE と checkJs に型情報を提供するため、保持し、必要に応じて追加します。
• 関数名を言い換えただけのコメントは追加しないでください。
• ドキュメントを作成する際に、実行時の動作を変更しないでください。

TypeDoc、API Extractor、または TSDoc の規約がある場合は、リポジトリで確立されたタグのスタイルに従い、リリースタグを保持し、設定されていない非標準のタグを避け、実行可能であれば既存のドキュメントまたは API レポートのチェックを実行します。

生成される API リファレンス

ドキュメントの対象が生成 API ドキュメント、または単一ソースのパッケージドキュメントである場合：

• 公開ソースの宣言を、API リファレンスの正式な入力として扱います。
• TypeDoc、API Extractor、React docgen、宣言ファイルの集約、カスタムサイトジェネレーターなど、既存のドキュメントツールを最初に確認します。
• アドホックな文字列照合でコメントを解析するより、構造化されたツールを優先します。
• 生成された API の表やリファレンスデータは、作成した例、ガイド、概念的な説明とは分けて管理します。
• 作業完了とする前に、パッケージの宣言またはドキュメントのパイプラインでコメントが保持されることを確認します。
• ドキュメントツールがない場合は、生成ドキュメントの計画を提案しますが、ユーザーが実装を依頼していない限り、新しいツールは追加しません。

一般的な分け方：

• JSDoc/TSDoc： API の表、プロパティの説明、エクスポートされた型のドキュメント、コールバックの契約、デフォルト値、制約、IDE のホバーテキスト。
• 作成するドキュメント： インストール、クイックスタート、構成の例、設計の根拠、移行ガイダンス、レシピ、スクリーンショット。

パッケージ API の作業手順

1. 公開 API を洗い出す

次を通じて公開されるシンボルを一覧にします：

• package.json の exports
• types、typings、または宣言ファイルのエントリーポイント
• ルートのバレルファイル
• 意図的に公開されているサブパス

検索に役立つもの：

rg '^\s*export\b' -g '*.{ts,tsx,js,jsx,mts,cts,d.ts}'
rg '"(exports|types|typings|main|module|browser)"' -g 'package.json'
rg '^\s*(module\.exports|exports\.)' -g '*.{js,cjs,cts}'
rg '@public|@internal|@deprecated|@alpha|@beta|@remarks|@example' -g '*.{ts,tsx,js,jsx}'

公開シンボルごとに、役立つ JSDoc がすでにあるか、また宣言ファイルの出力でその内容が保持されるかを記録します。

パッケージ全体に変更を加える前に、簡易的な一覧を作成します：

| Symbol | Source file | Export path | Existing JSDoc | Decision | Reason |
| --- | --- | --- | --- | --- | --- |

2. JSDoc が必要な箇所を判断する

候補を分類します：

• 追加：役立つ公開 API ドキュメントがない
• 改善：既存のコメントが古い、曖昧、または型の重複になっている
• そのまま：シグネチャと名前だけで十分に伝わる
• 対象外：隠れた重要な動作のない、プライベートまたはシンプルなヘルパー

ユーザーが「すべて」と依頼した場合、網羅的なコメントを明示的に求められていない限り、意味のあるエクスポート済みまたは公開済みのシンボルすべてを指すものとして解釈します。

3. コメントを書く

利用者が目にするエクスポートされた宣言の近くにコメントを配置します。オーバーロードの場合は、共通の説明を最初のオーバーロードまたはエクスポートされた宣言に記載し、動作が異なるオーバーロードにはそれぞれ固有の説明を記載します。また、利用者向けの説明に実装シグネチャの JSDoc を当てにしないでください。

React コンポーネントとフックの場合：

• コンポーネント／フックの目的と主要な動作を説明します
• エクスポートされた props インターフェースがある場合は、重要な props を説明します
• 制御あり／制御なしの動作、アクセシビリティに関する要件、SSR／クライアント側の要件、副作用について記載します
• prop 名と型だけで十分に伝わる場合は、すべての見た目に関する prop を説明するのは避けます

型とインターフェースの場合：

• インターフェースの目的を説明します
• 利用者が選択するフィールド、既定値が重要なフィールド、実行時の動作に影響するフィールド、コールバックの契約を定義するフィールドについて説明します
• 構造から明らかなフィールドの説明は省略します
• 複雑な設定オブジェクトには、例を優先します

パッケージ API の一部である場合は、エクスポートされた const アサーション、トークンマップ、スキーマ、名前空間のようなオブジェクト、判別可能なユニオン、推論される公開型も確認します。

4. 検証する

package.json のスクリプト、ワークスペースパッケージのスクリプト、または既存の CI／ドキュメント設定からコマンドを選びます。コメントを検証するためだけに、新しいツールを考案しないでください。

必要最小限で意味のあるチェックを実行します：

• 変更したパッケージの型チェック
• コメントが lint の対象であれば、lint／フォーマット
• 宣言ファイルの出力が重要であれば、パッケージのビルド
• リポジトリで TypeDoc、API Extractor などを使用している場合は、API ドキュメントの生成
• 公開時や IDE のホバー品質が目的であれば、生成された .d.ts またはドキュメントの出力を確認

宣言のコメント保持を確認するには、removeComments、宣言ファイルの出力、生成された .d.ts のエントリーポイント、再エクスポートされたシンボル、stripInternal、API Extractor のロールアップ、バレルまたはサブパスのエクスポート生成後もコメントが保持されるかなど、関連するコンパイラー／ドキュメント設定を確認します。

実行した正確なコマンドを報告します。チェックが利用できない場合や範囲が広すぎる場合は、何を検証し、何を検証しなかったかを正確に報告します。

出力

計画を立てる際は、以下を提示します：

• 確認した公開 API
• 説明を追加するシンボル、改善するシンボル、現状のままにするシンボル、対象外とするシンボル
• 検証計画

パッケージ全体または複数モジュールにわたる作業では、ユーザーが計画を求めている場合、編集前に候補となる公開 API と、想定する説明の詳しさを提示します。ドキュメントの追加または改善を求める依頼は、対象範囲内の編集をすでに許可しています。

実装する際は、最後に以下を提示します：

• 変更したファイル
• ドキュメントを追加した API の種類
• 検討した公開シンボル、JSDoc を追加したシンボル、JSDoc を改善したシンボル、説明を付けなかったシンボルとその理由
• 検証結果

ガードレール

• 見せかけのドキュメントを作らないでください。コメントは、読者に役立つ情報を伝える必要があります。
• 古くなる推測を加えないでください。動作が不明確な場合は、説明を書く前に使用箇所やテストを確認します。
• 有用な情報が埋もれるような長いコメントを書かないでください。重要な点が最初の1、2文で伝わらない場合は、書き直します。
• 複雑さに見合う理由がない限り、非公開ヘルパーを網羅的に説明しないでください。
• 不適切な名前を JSDoc で補わないでください。ユーザーがリファクタリングを求めた場合、または名前の変更が必要かつ安全な場合に限り、名前を変更します。
• 型チェックされていない例や、実際の使用法と整合しない例を追加しないでください。
• ユーザーから求められた場合、またはリポジトリで既に使用している場合を除き、ドキュメント生成ツールを導入しないでください。
• 明示的に求められていない限り、JSDoc の追加に際して公開 API を変更しないでください。リリースタグと非推奨タグは保持します。また、API のステータス変更が求められている場合を除き、@internal、@public、@alpha、@beta、@deprecated を追加または削除しないでください。これらは出力される宣言や利用者への診断に影響する場合があります。

完了チェック

作業を終える前に、以下を確認します：

• ユーザーが求めた公開シンボルを検討した
• コメントで動作、制約、例、または IDE で役立つ使用法を説明している
• ホバー時の明瞭さを損なわない、簡潔なコメントになっている
• 明らかな名前や TypeScript の型を言い換えただけのコメントがない
• 重要な場合、生成された宣言／ドキュメントにコメントが保持されている
• 検証を実行したか、実行できなかった場合はその理由を報告している