name: documentation description: 从代码、API 和上下文生成或更新文档。用于记录代码、编写 README、API 文档或保持文档与实现同步。
文档
从代码、OpenAPI/架构和项目上下文生成和更新文档。保持文档与实现同步。
何时使用
- 用户需要 README、API 文档或内联文档
- 用户请求记录模块、函数或 API
- 用户在代码更改后需要更新文档
- 新项目需要初始文档
工作流程
- 确定目标: 需要记录什么？（仓库、模块、API、CLI）
- 收集来源: 代码、类型、OpenAPI/架构、现有文档
- 选择格式: README、JSDoc/TSDoc、API 参考、用户指南
- 草稿: 先构建结构，然后从代码/上下文填充内容
- 验证: 链接、代码块、命令是否实际运行
文档类型
| 类型 | 何时使用 | 输出 |
|---|---|---|
| README | 项目或包概览 | 包含安装、使用、API 摘要的 README.md |
| API 参考 | 函数、端点、类型 | JSDoc，或 docs/api.md，或从 OpenAPI 派生 |
| 用户指南 | 如何使用功能或产品 | 分步指南、示例、故障排除 |
| 内联文档 | 函数、类、导出 | JSDoc/TSDoc、docstrings |
| 变更日志 | 发布历史 | CHANGELOG.md 格式 |
README 结构
# 项目名称
[一行描述]
## 安装
\`\`\`bash
npm install <包名>
\`\`\`
## 快速开始
[最小示例以开始运行]
## 使用
[主要用例示例]
## API
[摘要或链接到完整 API 文档]
## 配置
[选项、环境变量、配置文件]
## 贡献 / 许可证
[简要说明或链接]
从以下推断内容：package.json（名称、描述、脚本）、主入口、现有测试。
API 文档
对于 代码 API（导出、函数）:
- 使用 JSDoc/TSDoc:
@param、@returns、@example - 一句总结，然后参数、返回、抛出、示例
- 保持示例可运行且简短
对于 HTTP/REST API:
- 如果存在 OpenAPI/Swagger，从它派生部分
- 包括：端点、方法、参数、请求体架构、响应、示例
- 按资源或标签分组
对于 CLI:
- 文档命令、选项、子命令
- 每个常见用例一个示例
- 如果有不明显的退出代码或错误，则包括它们
内联文档 (JSDoc/TSDoc)
/**
* 通过 ID 获取用户。如果未找到，返回 null。
*
* @param id - 用户 UUID
* @param options - 可选获取设置
* @returns 用户或 null
* @throws {NetworkError} 当请求失败时
*
* @example
* const user = await getUser("abc-123");
*/
export async function getUser(id: string, options?: FetchOptions): Promise<User | null> {
从签名中提取类型；不要在散文中重复它们。专注于意图、边缘情况和示例。
保持文档同步
- 重构后：更新 README 示例、API 部分和受影响的 JSDoc
- 添加参数或返回类型时：更新 JSDoc 和任何 API.md
- 更改 CLI 标志时：更新 CLI 文档和 README 使用说明
检查：代码块是否运行？链接的文件是否存在？版本号是否最新？
语气和风格
- 现在时态（“返回用户”而不是“将返回”）
- 面向用户的第二人称（“你可以传递…”或“传递一个路径到…”）
- 短句子；使用列表的要点
- 代码示例优先于冗长散文
反模式
- ❌ 只写“参见代码”的 README
- ❌ 没有解释只复制类型签名的 API 文档
- ❌ 过时无法运行的示例
- ❌ 缺少包安装或运行说明