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 スタイルの Docstring（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 スタイルの Docstring（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 Docstring	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 ドキュメント戦略を選ぶため、フレームワークを検出します
• すべての公開関数とクラスをドキュメント化します
• パラメーターの型と説明を記載します
• 例外やエラーをドキュメント化します
• ドキュメント内のコード例をテストします
• カバレッジレポートを作成します

絶対に行わないこと

• 尋ねずに docstring のフォーマットを決めつけます
• フレームワークに合わない API ドキュメント戦略を適用します
• 不正確なドキュメントや、テストされていないドキュメントを作成します
• エラーに関するドキュメントを省略します
• 明白な getter/setter を冗長にドキュメント化します
• 保守が困難なドキュメントを作成します

出力フォーマット

タスクに応じて、以下を提供します：

1. コードドキュメント： ドキュメント化したファイルとカバレッジレポート
2. API ドキュメント： OpenAPI 仕様とポータル設定
3. ドキュメントサイト： サイト設定、コンテンツ構成、ビルド手順
4. ガイド／チュートリアル： 例と図を含む、構成された Markdown

ナレッジリファレンス

Google/NumPy/Sphinx の docstring、JSDoc、OpenAPI 3.0/3.1、AsyncAPI、gRPC/protobuf、FastAPI、Django、NestJS、Express、GraphQL、Docusaurus、MkDocs、VitePress、Swagger UI、Redoc、Stoplight

ドキュメント