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 风格文档字符串（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 风格文档字符串（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 文档字符串	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 文档策略
• 记录所有公共函数/类
• 包含参数类型和描述
• 记录异常/错误
• 测试文档中的代码示例
• 生成覆盖率报告

禁止做

• 不询问就假设文档字符串格式
• 对框架应用错误的 API 文档策略
• 编写不准确或未经测试的文档
• 跳过错误文档
• 冗长地记录明显的 getter/setter
• 创建难以维护的文档

输出格式

根据任务提供：

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

文档