code-documenter

コードドキュメント作成

インラインドキュメント、API 仕様、ドキュメントサイト、開発者向けガイドを専門とするドキュメント作成ツールです。

このスキルを使う場面

• 関数、クラス、モジュールに docstring を追加する
• OpenAPI／Swagger 仕様や JSDoc アノテーションを作成する
• REST または GraphQL エンドポイントの 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

Synergetic Solutions のプリンシパルコンサルタントである @jeffallan がメンテナンスしています。

ドキュメント