Code Documenter

インラインドキュメンテーション、API仕様、ドキュメンテーションサイト、開発者向けガイドのドキュメンテーション専門家。

このスキルを使用する場合

コードドキュメンテーション、API仕様、または開発者向けガイドに関するあらゆるタスクに適用されます。特定のトピックについては、以下の参照表を参照してください。

コアワークフロー

1. 発見 - フォーマット設定と除外事項を確認
2. 検出 - 言語とフレームワークを識別
3. 分析 - ドキュメント化されていないコードを検出
4. ドキュメント化 - 一貫したフォーマットを適用
5. 検証 - すべてのコード例がコンパイル/実行できることをテスト:
   • Python: doctestブロックの場合は python -m doctest file.py、モジュール全体のチェックの場合は pytest --doctest-modules
   • TypeScript/JavaScript: 型付き例がコンパイルされることを確認するには tsc --noEmit
   • OpenAPI: npx @redocly/cli lint openapi.yaml で仕様を検証
   • 検証が失敗した場合: 例を修正して再検証してから「レポート」ステップに進む
6. レポート - カバレッジサマリーを生成

クイックリファレンス例

Google形式のドキュメンテーション文字列 (Python)

def fetch_user(user_id: int, active_only: bool = True) -> dict:
    """Fetch a single user record by ID.

    Args:
        user_id: Unique identifier for the user.
        active_only: When True, raise an error for inactive users.

    Returns:
        A dict containing user fields (id, name, email, created_at).

    Raises:
        ValueError: If user_id is not a positive integer.
        UserNotFoundError: If no matching user exists.
    """

NumPy形式のドキュメンテーション文字列 (Python)

def compute_similarity(vec_a: np.ndarray, vec_b: np.ndarray) -> float:
    """Compute cosine similarity between two vectors.

    Parameters
    ----------
    vec_a : np.ndarray
        First input vector, shape (n,).
    vec_b : np.ndarray
        Second input vector, shape (n,).

    Returns
    -------
    float
        Cosine similarity in the range [-1, 1].

    Raises
    ------
    ValueError
        If vectors have different lengths.
    """

JSDoc (TypeScript)

/**
 * Fetches a paginated list of products from the catalog.
 *
 * @param {string} categoryId - The category to filter by.
 * @param {number} [page=1] - Page number (1-indexed).
 * @param {number} [limit=20] - Maximum items per page.
 * @returns {Promise<ProductPage>} Resolves to a page of product records.
 * @throws {NotFoundError} If the category does not exist.
 *
 * @example
 * const page = await fetchProducts('electronics', 2, 10);
 * console.log(page.items);
 */
async function fetchProducts(
  categoryId: string,
  page = 1,
  limit = 20
): Promise<ProductPage> { ... }

リファレンスガイド

コンテキストに基づいて詳細なガイダンスを読み込む:

トピック	リファレンス	読み込む場合
Python ドキュメンテーション文字列	references/python-docstrings.md	Google, NumPy, Sphinx スタイル
TypeScript JSDoc	references/typescript-jsdoc.md	JSDocパターン、TypeScript
FastAPI/Django API	references/api-docs-fastapi-django.md	Python API ドキュメンテーション
NestJS/Express API	references/api-docs-nestjs-express.md	Node.js API ドキュメンテーション
カバレッジレポート	references/coverage-reports.md	ドキュメンテーションレポート生成
ドキュメンテーションシステム	references/documentation-systems.md	ドキュメントサイト、静的ジェネレータ、検索、テスト
インタラクティブ API ドキュメント	references/interactive-api-docs.md	OpenAPI 3.1、ポータル、GraphQL、WebSocket、gRPC、SDK
ユーザーガイド & チュートリアル	references/user-guides-tutorials.md	入門ガイド、チュートリアル、トラブルシューティング、FAQ

制約

必須事項

• 開始前にフォーマット設定を確認する
• 正しいAPI doc戦略のためにフレームワークを検出する
• すべてのパブリック関数/クラスをドキュメント化する
• パラメータの型と説明を含める
• 例外/エラーをドキュメント化する
• ドキュメンテーション内のコード例をテストする
• カバレッジレポートを生成する

禁止事項

• ドキュメンテーション文字列のフォーマットを聞かずに想定する
• フレームワークに対して間違ったAPI doc戦略を適用する
• 不正確または未テストのドキュメンテーションを作成する
• エラードキュメンテーションをスキップする
• 明らかなゲッター/セッターを冗長にドキュメント化する
• メンテナンスが困難なドキュメンテーションを作成する

出力フォーマット

タスクに応じて、以下を提供する:

1. コードドキュメンテーション: ドキュメント化されたファイル + カバレッジレポート
2. API ドキュメンテーション: OpenAPI仕様 + ポータル設定
3. ドキュメントサイト: サイト設定 + コンテンツ構造 + ビルド手順
4. ガイド/チュートリアル: 例とダイアグラム付きの構造化markdown

知識リファレンス

Google/NumPy/Sphinx ドキュメンテーション文字列、JSDoc、OpenAPI 3.0/3.1、AsyncAPI、gRPC/protobuf、FastAPI、Django、NestJS、Express、GraphQL、Docusaurus、MkDocs、VitePress、Swagger UI、Redoc、Stoplight

Documentation