mcpField
C
code-documenter

code-documenter

github.com/jeffallan开发12.1k5.8k 次安装今天更新
代码仓库

关于 code-documenter

Code Documenter 是面向开发者的文档编写技能，可用于代码与 API 文档、指南和文档站点。它提供从识别未文档化代码、统一格式到验证示例和汇总覆盖率的工作流。

主要功能

  1. 01文档字符串与内联文档
  2. 02OpenAPI、Swagger 和 JSDoc 规范
  3. 03REST 与 GraphQL API 文档
  4. 04开发者指南与文档站点
  5. 05示例验证与覆盖率报告

适用场景

  1. 01为公开函数和类编写文档
  2. 02为服务创建 API 规范
  3. 03编写安装指南和教程
  4. 04检查示例与文档覆盖率

安装

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

$npx skills add https://github.com/jeffallan/claude-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 规范、文档站点和开发者指南的文档专家。

何时使用此技能

  • 为函数、类和模块添加文档字符串
  • 编写 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 风格文档字符串（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.md使用 Google、NumPy、Sphinx 风格时
TypeScript JSDocreferences/typescript-jsdoc.md使用 JSDoc 模式、TypeScript 时
FastAPI/Django APIreferences/api-docs-fastapi-django.md编写 Python API 文档时
NestJS/Express APIreferences/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

由 @jeffallan 维护，他是 Synergetic Solutions 的首席顾问。

文档

评论

支持 Markdown