代码库文档生成器

概述

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

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

在为初学者编写代码文档时，请遵循以下基本原则：

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

文档类型及其适用场景

1. 自述文档

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

应遵循的结构：

# 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]

最佳实践：

• 开篇阐明项目核心价值
• 提供经过验证的配置说明（务必测试！）
• 展示项目结构的可视化概览
• 为进阶主题提供深层文档链接
• 根目录自述文档应聚焦入门指南

2. 架构文档

创建时机：适用于多模块项目、复杂数据流或非直观设计决策。

应遵循的结构：

# 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. 代码注释

何时创建：针对复杂逻辑、非显而易见的算法或需要背景信息的代码。

注释模式：

函数/方法文档：

/**
 * 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)
 */

复杂逻辑文档：

# 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方法或公共接口。

遵循的结构：

## 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. 识别入口点- 主文件、索引文件、应用初始化文件
2. 梳理依赖关系- 模块间的关联方式
3. 确定核心概念- 用户需要理解的关键抽象概念
4. 定位配置信息- 环境设置、配置文件
5. 审阅现有文档- 基于现有内容扩展，避免重复

步骤二：选择文档类型

根据用户需求和代码库分析结果确定：

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

第三步：生成文档

使用以下模板作为起点：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)

记录设计决策

捕捉架构选择背后的“原因”：

## 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的命令："为此项目创建一个README文件，帮助新开发者快速上手"

记录架构的命令："记录此代码库的架构，说明不同模块之间如何交互"

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

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