介绍
# Codebase Documenter
## 概述
此技能能够为代码库创建全面、易于初学者理解的文档。它提供了编写 README、架构指南、代码注释和 API 文档的结构化模板及最佳实践，帮助新用户快速理解项目并做出贡献。
## 面向初学者的文档核心原则
在为新用户编写代码文档时，请遵循以下基本原则：
1. **从“为什么”开始** - 在深入实现细节之前先解释目的 2. **使用渐进式披露** - 从简单到复杂分层展示信息 3. **提供背景** - 解释代码不仅做什么，还要解释为什么存在 4. **包含示例** - 为每个概念展示具体的使用示例 5. **假设读者没有先验知识** - 尽可能定义术语并避免使用行话 6. **视觉辅助** - 使用图表、流程图和文件树结构 7. **快速见效** - 帮助用户在 5 分钟内运行起来
## 文档类型及使用时机
### 1. README 文档
**何时创建：** 针对项目根目录、主要功能模块或独立组件。
**遵循结构：** ```markdown # Project Name
## What This Does [1-2 sentence plain-English explanation]
## Quick Start [Get users running the project in < 5 minutes]
## Project Structure [Visual file tree with explanations]
## Key Concepts [Core concepts users need to understand]
## Common Tasks [Step-by-step guides for frequent operations]
## Troubleshooting [Common issues and solutions] ```
**最佳实践：** - 以项目的价值主张开头 - 包含切实可用的安装说明（请测试！） - 提供项目结构的视觉概览 - 链接到针对高级主题的深入文档 - 保持根目录 README 专注于快速上手
### 2. 架构文档
**何时创建：** 针对包含多个模块、复杂数据流或非显而易见的设计决策的项目。
**遵循结构：** ```markdown # Architecture Overview
## System Design [High-level diagram and explanation]
## Directory Structure [Detailed breakdown with purpose of each directory]
## Data Flow [How data moves through the system]
## Key Design Decisions [Why certain architectural choices were made]
## Module Dependencies [How different parts interact]
## Extension Points [Where and how to add new features] ```
**最佳实践：** - 使用图表展示系统组件和关系 - 解释架构决策背后的“原因” - 记录正常流程和错误处理 - 识别模块之间的边界 - 包含带有注释的视觉文件树结构
### 3. 代码注释
**何时创建：** 针对复杂逻辑、非显而易见的算法或需要上下文的代码。
**注释模式：**
**函数/方法文档：** ```javascript /** * Calculates the prorated subscription cost for a partial billing period. * * Why this exists: Users can subscribe mid-month, so we need to charge * them only for the days remaining in the current billing cycle. * * @param {number} fullPrice - The normal monthly subscription price * @param {Date} startDate - When the user's subscription begins * @param {Date} periodEnd - End of the current billing period * @returns {number} The prorated amount to charge * * @example * // User subscribes on Jan 15, period ends Jan 31 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31')) * // Returns: 16.13 (17 days out of 31 days) */ ```
**复杂逻辑文档：** ```python # Why this check exists: The API returns null for deleted users, # but empty string for users who never set a name. We need to # distinguish between these cases for the audit log. if user_name is None: # User was deleted - log this as a security event log_deletion_event(user_id) elif user_name == "": # User never completed onboarding - safe to skip continue ```
**最佳实践：** - 解释“为什么”而不是“是什么” - 代码本身展示了它做什么 - 记录边缘情况和业务逻辑 - 为复杂函数添加示例 - 解释那些不言自明的参数 - 注意任何陷阱或反直觉的行为
### 4. API 文档
**何时创建：** 针对任何 HTTP 端点、SDK 方法或公共接口。
**遵循结构：**
```markdown ## Endpoint Name
### What It Does [Plain-English explanation of the endpoint's purpose]
### Endpoint `POST /api/v1/resource`
### Authentication [What auth is required and how to provide it]
### Request Format [JSON schema or example request]
### Response Format [JSON schema or example response]
### Example Usage [Concrete example with curl/code]
### Common Errors [Error codes and what they mean]
### Related Endpoints [Links to related operations] ```
**最佳实践：** - 提供可用的 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/ # Source code │ ├── components/ # Reusable UI components │ ├── pages/ # Page-level components (routing) │ ├── services/ # Business logic and API calls │ ├── utils/ # Helper functions │ └── types/ # TypeScript type definitions ├── public/ # Static assets (images, fonts) ├── tests/ # Test files mirroring src structure └── package.json # Dependencies and scripts ```
### 解释复杂数据流
使用带图表的编号步骤：
``` User Request Flow: 1. User submits form → 2. Validation → 3. API call → 4. Database → 5. Response
[1] components/UserForm.tsx ↓ validates input [2] services/validation.ts ↓ sends to API [3] services/api.ts ↓ queries database [4] Database (PostgreSQL) ↓ returns data [5] components/UserForm.tsx (updates UI) ```
### 记录设计决策
捕捉架构选择背后的“原因”：
```markdown ## Why We Use Redux
**Decision:** State management with Redux instead of Context API
**Context:** Our app has 50+ components that need access to user authentication state, shopping cart, and UI preferences.
**Reasoning:** - Context API causes unnecessary re-renders with this many components - Redux DevTools helps debug complex state changes - Team has existing Redux expertise
**Trade-offs:** - More boilerplate code - Steeper learning curve for new developers - Worth it for: performance, debugging, team familiarity ```
## 输出指南
生成文档时：
1. **为目标受众写作** - 根据文档是面向初学者、中级还是高级用户来调整复杂度 2. **使用一致的格式** - 遵循 markdown 约定，一致的标题层级 3. **提供可用的示例** - 测试所有代码片段和命令 4. **在文档之间建立链接** - 创建文档导航结构 5. **保持可维护性** - 文档应易于随着代码更改而更新 6. **添加日期和版本** - 注明文档上次更新的时间
## 快速参考
**生成 README 的命令：** "Create a README file for this project that helps new developers get started"
**记录架构的命令：** "Document the architecture of this codebase, explaining how the different modules interact"
**添加代码注释的命令：** "Add explanatory comments to this file that help new developers understand the logic"
**记录 API 的命令：** "Create API documentation for all the endpoints in this file"