code-documentation

代码文档

此技能可帮助 AI Agent 分析源代码，并以多种格式生成高质量文档。它涵盖从单个函数文档字符串到完整项目 README 的各种内容，确保人类开发者和下游工具（IDE、文档生成器）都能获得一致、准确的描述。

工作流

1. 盘点代码库：遍历项目目录，列出公开模块、类、函数、常量和类型定义。记录哪些符号已有文档，以及哪些文档缺失或已过时。

2. 确定文档范围：根据用户的请求，决定生成内联文档字符串、独立 API 参考、项目级 README，还是组合生成。输出格式应符合项目现有惯例（JSDoc、Google 风格 Python 文档字符串、TypeDoc、RDoc 等）。

3. 分析签名和行为：检查每个符号的参数类型、返回类型、默认值、引发的异常和副作用。如有相关测试文件，请阅读以了解预期用法和边界情况。

4. 生成文档：编写的文档应包含单行摘要、逻辑较复杂时的扩展说明、带类型的参数和返回值说明、异常／错误说明，以及至少一个面向公开 API 的用法示例。

5. 就地插入或更新：对于内联文档（文档字符串、JSDoc 注释），将生成的文本直接插入相关符号的上方或内部。对于独立文件（README、API 参考），在项目根目录或 docs/ 目录中创建或更新 Markdown 文件。

6. 验证并交叉引用：确认文档中的参数名称与实际签名一致、引用的类型确实存在，并且示例语法有效。标记任何不一致之处，供用户检查。

支持的格式

• Python：Google 风格文档字符串、NumPy 风格文档字符串、Sphinx reStructuredText
• JavaScript / TypeScript：JSDoc（@param、@returns、@throws）、TypeDoc 注解
• Java：Javadoc（@param、@return、@throws）
• Go：Godoc 注释惯例（紧邻声明上方的注释块）
• Rust：带 Markdown 的 /// 文档注释、#[doc] 属性
• Ruby：YARD（@param、@return、@example）
• Markdown：README 文件、CHANGELOG 条目、架构决策记录（ADR）

用法

将文件、目录或特定符号指定给 Agent，并说明需要哪种文档。以下是有效请求示例：

• “为 src/services/ 中的每个公开函数添加 Google 风格文档字符串。”
• “根据项目结构和 package.json 为此项目生成 README。”
• “使用 JSDoc 为此类编写文档，并为每个方法添加示例。”

Agent 将遵循项目中现有的文档风格。如果未检测到惯例，它会询问要使用哪种格式，或默认采用该语言最常见的风格。

示例

示例 1 — 使用 Google 风格文档字符串为 Python 类编写文档

用户请求：“为此类及其方法添加文档字符串。”

之前：

class TokenBucket:
    def __init__(self, capacity, refill_rate):
        self.capacity = capacity
        self.tokens = capacity
        self.refill_rate = refill_rate
        self._last_refill = time.monotonic()

    def consume(self, tokens=1):
        self._refill()
        if self.tokens >= tokens:
            self.tokens -= tokens
            return True
        return False

    def _refill(self):
        now = time.monotonic()
        elapsed = now - self._last_refill
        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
        self._last_refill = now

之后：

class TokenBucket:
    """A token-bucket rate limiter.

    Tokens are added at a constant rate and consumed by callers.
    When the bucket is empty, requests are rejected until enough
    tokens have accumulated.

    Args:
        capacity: Maximum number of tokens the bucket can hold.
        refill_rate: Tokens added per second.

    Example:
        >>> bucket = TokenBucket(capacity=10, refill_rate=2)
        >>> bucket.consume(3)
        True
    """

    def __init__(self, capacity: float, refill_rate: float) -> None:
        self.capacity = capacity
        self.tokens = capacity
        self.refill_rate = refill_rate
        self._last_refill = time.monotonic()

    def consume(self, tokens: int = 1) -> bool:
        """Attempt to consume tokens from the bucket.

        Triggers an internal refill based on elapsed time before
        checking availability.

        Args:
            tokens: Number of tokens to consume. Defaults to 1.

        Returns:
            True if the tokens were available and consumed, False otherwise.
        """
        self._refill()
        if self.tokens >= tokens:
            self.tokens -= tokens
            return True
        return False

    def _refill(self) -> None:
        """Refill the bucket based on time elapsed since the last refill."""
        now = time.monotonic()
        elapsed = now - self._last_refill
        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
        self._last_refill = now

示例 2 — 根据项目结构生成项目 README

用户请求：“为此项目生成 README。”

假设项目具有以下目录结构：

myapi/
├── package.json          (name: @acme/myapi, scripts: dev, build, test)
├── src/
│   ├── index.ts          (Express app entry point)
│   ├── routes/
│   │   ├── users.ts
│   │   └── orders.ts
│   └── middleware/
│       └── auth.ts
├── tests/
│   └── users.test.ts
└── Dockerfile

生成的 README.md：

# @acme/myapi

A RESTful API service built with Express and TypeScript.

## Getting Started

### Prerequisites

- Node.js >= 18
- npm or yarn

### Installation

git clone https://github.com/acme/myapi.git
cd myapi
npm install

### Running Locally

npm run dev        # Start the dev server with hot reload
npm run build      # Compile TypeScript to dist/
npm test           # Run the test suite

### Docker

docker build -t myapi .
docker run -p 3000:3000 myapi

## API Endpoints

| Method | Path           | Description           |
|--------|----------------|-----------------------|
| GET    | /users         | List all users        |
| POST   | /users         | Create a new user     |
| GET    | /orders        | List all orders       |
| POST   | /orders        | Create a new order    |

## Project Structure

- `src/index.ts` — Application entry point and server bootstrap.
- `src/routes/` — Route handlers grouped by resource.
- `src/middleware/auth.ts` — JWT authentication middleware.
- `tests/` — Jest test files.

## License

MIT

最佳实践

• 遵循项目现有的风格。 如果代码库使用 NumPy 风格的文档字符串，就不要在项目中途改用 Google 风格。保持一致比个人偏好更重要。
• 记录“为什么”，而不只是“是什么”。 参数类型通常能从签名中看出来；应重点说明意图、约束和不明显的行为。
• 为每个公共 API 符号至少提供一个示例。 示例是文档中阅读量最高的部分，也能发现细微的误解。
• 让 README 文件便于快速浏览。 使用标题、表格和代码块。开发者通常会快速浏览，因此应将最重要的信息（安装、运行、部署）放在前面。
• 除非用户提出要求，否则不要记录私有实现细节。 过度记录实现细节会增加维护负担，也可能误导读者，让他们依赖不稳定的 API。
• 代码变更时重新生成文档。 过时的文档比没有文档更糟。优先使用能在 CI 阶段根据签名验证文档的工具。

边缘情况

• 动态生成的 API：如果路由或方法是在运行时注册的（例如通过装饰器或插件系统），静态分析可能会遗漏它们。请提醒用户，并建议使用运行时自省或手动注释。
• 重载或泛型函数：对于 TypeScript 重载或 Python @overload，应分别记录每个签名变体，并为其提供独立的参数说明和示例。
• 单体仓库：如果仓库包含多个包，应生成一个链接到各包 README 的根 README，而不是一份庞大的文档。
• 非英语代码库：如果变量名和现有注释使用其他语言，请询问用户，文档应使用英语还是项目的主要语言。
• 专有或敏感代码：避免在生成的 README 中加入可能公开的内部 URL、凭据或业务逻辑细节。必要时应进行脱敏或概括。