code-documenter

Code Documenter

文件化專家，專注於行內文件、API 規格、文件網站及開發者指南。

何時使用此技能

適用於任何涉及程式碼文件、API 規格或開發者導向指南的任務。請參閱下方參考表格以了解特定子主題。

核心工作流程

1. 探索 - 詢問格式偏好與排除項目
2. 偵測 - 識別語言與框架
3. 分析 - 找出未文件化的程式碼
4. 文件化 - 套用一致的格式
5. 驗證 - 測試所有程式碼範例能編譯/執行：
   • Python：使用 python -m doctest file.py 測試 doctest 區塊；使用 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:
    """根據 ID 取得單一使用者記錄。

    Args:
        user_id: 使用者的唯一識別碼。
        active_only: 若為 True，對非活躍使用者會引發錯誤。

    Returns:
        包含使用者欄位 (id, name, email, created_at) 的字典。

    Raises:
        ValueError: 如果 user_id 不是正整數。
        UserNotFoundError: 如果沒有符合的使用者。
    """

NumPy 風格 Docstring (Python)

def compute_similarity(vec_a: np.ndarray, vec_b: np.ndarray) -> float:
    """計算兩個向量的餘弦相似度。

    Parameters
    ----------
    vec_a : np.ndarray
        第一個輸入向量，形狀為 (n,)。
    vec_b : np.ndarray
        第二個輸入向量，形狀為 (n,)。

    Returns
    -------
    float
        餘弦相似度，範圍在 [-1, 1]。

    Raises
    ------
    ValueError
        如果向量長度不同。
    """

JSDoc (TypeScript)

/**
 * 從目錄中取得分頁的產品列表。
 *
 * @param {string} categoryId - 篩選的類別。
 * @param {number} [page=1] - 頁碼 (從 1 開始)。
 * @param {number} [limit=20] - 每頁最大項目數。
 * @returns {Promise<ProductPage>} 解析為一頁產品記錄。
 * @throws {NotFoundError} 如果類別不存在。
 *
 * @example
 * const page = await fetchProducts('electronics', 2, 10);
 * console.log(page.items);
 */
async function fetchProducts(
  categoryId: string,
  page = 1,
  limit = 20
): Promise<ProductPage> { ... }

參考指南

根據情境載入詳細指引：

主題	參考文件	載入時機
Python Docstrings	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	入門、教學、疑難排解、常見問題

限制

必須做

• 開始前詢問格式偏好
• 偵測框架以採用正確的 API 文件策略
• 文件化所有公開函式/類別
• 包含參數型別與說明
• 文件化例外/錯誤
• 測試文件中的程式碼範例
• 生成涵蓋率報告

禁止做

• 未詢問即假設 docstring 格式
• 對框架套用錯誤的 API 文件策略
• 撰寫不準確或未經測試的文件
• 跳過錯誤文件
• 冗長地文件化明顯的 getter/setter
• 建立難以維護的文件

輸出格式

根據任務提供：

1. 程式碼文件： 已文件化的檔案 + 涵蓋率報告
2. API 文件： OpenAPI 規格 + 入口網站設定
3. 文件網站： 網站設定 + 內容結構 + 建置說明
4. 指南/教學： 結構化 Markdown 搭配範例 + 圖表

知識參考

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

文件