mcpField
C
code-documenter

code-documenter

github.com/farmage开发224313 次安装5 周前更新
代码仓库

关于 code-documenter

Code Documenter 面向编写代码文档、API 规范和开发者指南的任务。它涵盖格式选择、框架识别、示例验证和文档覆盖率汇总。

主要功能

  1. 01编写代码内文档
  2. 02制作 API 规范和开发者指南
  3. 03识别语言与框架
  4. 04验证文档中的代码示例
  5. 05汇总文档覆盖率

适用场景

  1. 01为公开函数和类编写文档
  2. 02为项目整理 API 规范
  3. 03创建开发者指南和文档站点

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/farmage/opencode-skills --skill code-documenter

安装后在 Claude Code 中输入/code-documenter确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
api-docs-fastapi-django.md
api-docs-nestjs-express.md
coverage-reports.md
documentation-systems.md
interactive-api-docs.md
python-docstrings.md
typescript-jsdoc.md
user-guides-tutorials.md

详细介绍

代码文档编写器

专注于内联文档、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.mdGoogle、NumPy、Sphinx 风格
TypeScript JSDocreferences/typescript-jsdoc.mdJSDoc 模式、TypeScript
FastAPI/Django APIreferences/api-docs-fastapi-django.mdPython API 文档
NestJS/Express APIreferences/api-docs-nestjs-express.mdNode.js API 文档
覆盖率报告references/coverage-reports.md生成文档报告
文档系统references/documentation-systems.md文档站点、静态生成器、搜索、测试
交互式 API 文档references/interactive-api-docs.mdOpenAPI 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

文档

评论

支持 Markdown