Codebase Documenter

代码库文档生成器

概述

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

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

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

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

文档类型及使用时机

1. README 文档

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

遵循的结构：

# 项目名称

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

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

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

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

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

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

最佳实践：

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

2. 架构文档

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

遵循的结构：

# 架构概述

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

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

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

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

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

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

最佳实践：

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

3. 代码注释

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

注释模式：

函数/方法文档：

/**
 * 计算部分计费周期的按比例订阅费用。
 *
 * 为什么存在：用户可以在月中订阅，因此我们只需要
 * 向他们收取当前计费周期剩余天数的费用。
 *
 * @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 天）
 */

复杂逻辑文档：

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

最佳实践：

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

4. API 文档

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

遵循的结构：

## 端点名称

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

### 端点
`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）

记录设计决策

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

## 为什么我们使用 Redux

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

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

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

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

输出指南

在生成文档时：

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

快速参考

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

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

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

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