Codebase Documenter

---
name: codebase-documenter
description: 代码库文档生成器 - 适用于为代码库编写文档，包括README文件、架构文档、代码注释和API文档。当用户请求帮助记录代码、创建入门指南、解释项目结构或使代码库对新开发者更友好时使用此技能。该技能提供模板、最佳实践和结构化方法来创建清晰、适合初学者的文档。
---

# 代码库文档生成器

## 概述

本技能用于为代码库创建全面的、对初学者友好的文档。它提供了结构化的模板和最佳实践，用于编写 README、架构指南、代码注释和 API 文档，帮助新用户快速理解项目并为项目做出贡献。

## 面向初学者的文档核心原则

在为新用户记录代码时，请遵循以下基本原则：

1. **从“为什么”开始** - 在深入实现细节之前解释目的
2. **使用渐进式披露** - 从简单到复杂分层呈现信息
3. **提供上下文** - 不仅解释代码做什么，还要解释为什么存在
4. **包含示例** - 为每个概念展示具体的使用示例
5. **假设没有先验知识** - 定义术语，尽可能避免行话
6. **视觉辅助** - 使用图表、流程图和文件树结构
7. **快速成功** - 帮助用户在 5 分钟内运行起来

## 文档类型及使用时机

### 1. README 文档

**何时创建：** 用于项目根目录、主要功能模块或独立组件。

**遵循的结构：**
```markdown
# 项目名称

## 这是什么
[1-2 句话的通俗解释]

## 快速开始
[让用户在 < 5 分钟内运行项目]

## 项目结构
[带有解释的可视化文件树]

## 核心概念
[用户需要理解的核心概念]

## 常见任务
[常见操作的逐步指南]

## 故障排除
[常见问题和解决方案]
```

**最佳实践：**
- 以项目的价值主张开头
- 包含实际可行的设置说明（测试它们！）
- 提供项目结构的可视化概述
- 链接到更深入的文档以获取高级主题
- 根 README 专注于入门

### 2. 架构文档

**何时创建：** 用于具有多个模块、复杂数据流或非显而易见的设计决策的项目。

**遵循的结构：**
```markdown
# 架构概述

## 系统设计
[高级图表和解释]

## 目录结构
[每个目录用途的详细说明]

## 数据流
[数据如何在系统中流动]

## 关键设计决策
[为什么做出某些架构选择]

## 模块依赖
[不同部分如何交互]

## 扩展点
[在哪里以及如何添加新功能]
```

**最佳实践：**
- 使用图表展示系统组件和关系
- 解释架构决策背后的“为什么”
- 记录正常路径和错误处理
- 标识模块之间的边界
- 包含带注释的可视化文件树结构

### 3. 代码注释

**何时创建：** 用于复杂逻辑、不明显的算法或需要上下文的代码。

**注释模式：**

**函数/方法文档：**
```javascript
/**
 * 计算部分计费周期的按比例订阅费用。
 *
 * 为什么存在：用户可以在月中订阅，因此我们只需要
 * 向他们收取当前计费周期剩余天数的费用。
 *
 * @param {number} fullPrice - 正常的月度订阅价格
 * @param {Date} startDate - 用户订阅的开始日期
 * @param {Date} periodEnd - 当前计费周期的结束日期
 * @returns {number} 按比例计算的金额
 *
 * @example
 * // 用户在 1 月 15 日订阅，周期在 1 月 31 日结束
 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
 * // 返回：16.13（31 天中的 17 天）
 */
```

**复杂逻辑文档：**
```python
# 为什么需要这个检查：API 对已删除的用户返回 null，
# 但对从未设置名称的用户返回空字符串。我们需要
# 在审计日志中区分这些情况。
if user_name is None:
    # 用户已被删除 - 将此记录为安全事件
    log_deletion_event(user_id)
elif user_name == "":
    # 用户从未完成注册 - 可以安全跳过
    continue
```

**最佳实践：**
- 解释“为什么”而不是“是什么” - 代码已经展示了它做什么
- 记录边缘情况和业务逻辑
- 为复杂函数添加示例
- 解释不言自明的参数
- 注意任何陷阱或反直觉的行为

### 4. API 文档

**何时创建：** 用于任何 HTTP 端点、SDK 方法或公共接口。

**遵循的结构：**

```markdown
## 端点名称

### 功能
[端点功能的通俗解释]

### 端点
`POST /api/v1/resource`

### 身份验证
[需要什么认证以及如何提供]

### 请求格式
[JSON 模式或示例请求]

### 响应格式
[JSON 模式或示例响应]

### 使用示例
[带有 curl/代码的具体示例]

### 常见错误
[错误代码及其含义]

### 相关端点
[链接到相关操作]
```

**最佳实践：**
- 提供可用的 curl 示例
- 展示成功和错误响应
- 清楚说明身份验证方式
- 记录速率限制和约束
- 包含常见问题的故障排除

## 文档工作流程

### 第 1 步：分析代码库

在编写文档之前：

1. **识别入口点** - 主文件、索引文件、应用初始化
2. **映射依赖** - 模块如何相互关联
3. **找到核心概念** - 用户需要理解的关键抽象
4. **定位配置** - 环境设置、配置文件
5. **审查现有文档** - 在现有基础上构建，不要重复

### 第 2 步：选择文档类型

根据用户请求和代码库分析：

- **新项目或缺少 README** → 从 README 文档开始
- **复杂架构或多个模块** → 创建架构文档
- **令人困惑的代码部分** → 添加内联代码注释
- **HTTP/API 端点** → 编写 API 文档
- **需要多种类型** → 按顺序处理：README → 架构 → API → 注释

### 第 3 步：生成文档

使用 `assets/templates/` 中的模板作为起点：

- `assets/templates/README.template.md` - 用于项目 README
- `assets/templates/ARCHITECTURE.template.md` - 用于架构文档
- `assets/templates/API.template.md` - 用于 API 文档

根据具体代码库自定义模板：

1. **填写项目特定信息** - 用实际内容替换占位符
2. **添加具体示例** - 使用项目中的真实代码
3. **包含视觉辅助** - 创建文件树、图表、流程图
4. **测试说明** - 验证设置步骤实际可行
5. **链接相关文档** - 将文档片段连接在一起

### 第 4 步：审查清晰度

在完成文档之前：

1. **以初学者身份阅读** - 没有项目上下文时是否有意义？
2. **检查完整性** - 解释中是否有空白？
3. **验证示例** - 代码示例是否实际可行？
4. **测试说明** - 有人可以按照设置步骤操作吗？
5. **改进结构** - 信息是否容易找到？

## 文档模板

本技能在 `assets/templates/` 中包含几个模板作为起点：

### 可用模板

- **README.template.md** - 综合的 README 结构，包含快速开始、项目结构和常见任务部分
- **ARCHITECTURE.template.md** - 架构文档模板，包含系统设计、数据流和设计决策
- **API.template.md** - API 端点文档，包含请求/响应格式和示例
- **CODE_COMMENTS.template.md** - 有效内联文档的示例和模式

### 使用模板

1. **从 `assets/templates/` 阅读相应模板**
2. **针对具体项目自定义** - 用实际信息替换占位符
3. **添加项目特定部分** - 根据需要扩展模板
4. **包含真实示例** - 使用代码库中的实际代码
5. **删除不相关的部分** - 删除不适用的部分

## 最佳实践参考

有关详细的文档最佳实践、样式指南和高级模式，请参阅：

- `references/documentation_guidelines.md` - 综合样式指南和最佳实践
- `references/visual_aids_guide.md` - 如何创建有效的图表和文件树

在以下情况下加载这些参考：
- 为复杂企业级代码库创建文档时
- 处理多个利益相关者需求时
- 需要高级文档模式时
- 在大型项目中标准化文档时

## 常见模式

### 创建文件树结构

文件树帮助新用户理解项目组织：

```
project-root/
├── src/                    # 源代码
│   ├── components/        # 可复用的 UI 组件
│   ├── pages/             # 页面级组件（路由）
│   ├── services/          # 业务逻辑和 API 调用
│   ├── utils/             # 辅助函数
│   └── types/             # TypeScript 类型定义
├── public/                # 静态资源（图片、字体）
├── tests/                 # 测试文件，镜像 src 结构
└── package.json           # 依赖和脚本
```

### 解释复杂数据流

使用带图表的编号步骤：

```
用户请求流：
1. 用户提交表单 → 2. 验证 → 3. API 调用 → 4. 数据库 → 5. 响应

[1] components/UserForm.tsx
    ↓ 验证输入
[2] services/validation.ts
    ↓ 发送到 API
[3] services/api.ts
    ↓ 查询数据库
[4] 数据库（PostgreSQL）
    ↓ 返回数据
[5] components/UserForm.tsx（更新 UI）
```

### 记录设计决策

捕捉架构选择背后的“为什么”：

```markdown
## 为什么我们使用 Redux

**决策：** 使用 Redux 进行状态管理而不是 Context API

**背景：** 我们的应用有 50+ 个组件需要访问用户
认证状态、购物车和 UI 偏好。

**推理：**
- 上下文 API 会导致这么多组件不必要的重新渲染
- Redux DevTools 帮助调试复杂的状态变化
- 团队具有现有的 Redux 专业知识

**权衡：**
- 更多的样板代码
- 新学习曲线更陡
- 值得：性能、调试、团队熟悉度
```

## 输出指南

在生成文档时：

1. **为目标受众编写** - 根据文档是面向初学者、中级还是高级用户来调整复杂度
2. **使用一致的格式** - 遵循 markdown 惯例，一致的标题层次结构
3. **提供可用的示例** - 测试所有代码片段和命令
4. **在文档之间链接** - 创建文档导航结构
5. **保持可维护性** - 文档应易于在代码变更时更新
6. **添加日期和版本** - 注意文档的最后更新时间

## 快速参考

**生成 README 的命令：**
“为这个项目创建一个 README 文件，帮助新开发者入门”

**记录架构的命令：**
“记录此代码库的架构，解释不同模块如何交互”

**添加代码注释的命令：**
“为此文件添加解释性注释，帮助新开发者理解逻辑”

**记录 API 的命令：**
“为此文件中的所有端点创建 API 文档”