CoDoc

一站式代码注释文档管理解决方案，助力团队高效实践"文档即代码"理念

🔍 什么是 CoDoc？

CoDoc (Code Documentation) 是一款专为开发团队设计的代码文档管理工具，它将代码注释与文档管理完美融合。通过结构化的注释标签系统，CoDoc 让开发者能在编写代码的同时生成高质量的技术文档，实现真正的"文档即代码"(Docs as Code)实践。

无论是需求实现的技术方案、关键设计决策，还是测试重点和问题修复记录，CoDoc 都能以统一的方式进行管理和展示，使团队成员轻松了解代码背后的思考过程和业务逻辑。

为什么选择 CoDoc？

• 无缝融入开发流程：直接在代码中编写文档，无需在代码和外部文档间切换
• 标准化文档模板 - 提供多种场景下的标准化注释模板，确保团队文档风格统一
• 可视化文档管理 - 集成文档树视图，直观展示和管理代码中的文档注释
• 多维度组织与管理 - 按需求、领域或文档类型灵活组织和查询文档
• 自动文档生成 - 自动提取代码注释，一键导出技术方案变更文档
• 高亮注释提示 - 集成注释高亮功能，提高代码文档可读性

📋 快速使用指南

1. 插入文档注释

在支持的编程语言文件中，输入以下任一触发词后按下 Tab 键（或使用上下键选择后按 Enter 键）：

注释模板插入后，可通过 Tab 键在各字段间快速切换，填写相应内容。所有文档注释都遵循统一的结构，让团队成员能够轻松找到所需信息。

2. 在侧边栏查看和管理文档

1. 点击 VS Code 侧边栏中的 CoDoc 图标
2. 在树视图中可以看到项目中所有的文档注释
3. 使用顶部的工具栏按钮：
   • ↻扫描文档注释 - 更新最新的文档注释
   • ᯤ筛选文档 - 按条件筛选显示的文档
   • ⤴︎导出文档注释 - 导出选中的文档注释

3. 导出文档注释

1. 在项目注释扫描完成以后，点击工具栏「⤴︎导出文档注释」
2. 在筛选界面中选择需要导出的:
   • 需求 ID / BUG ID（多选）
   • 注释类型（多选）
3. 插件会自动生成完整的 Markdown 格式变更文档

📝 注释模板详解

方案概要模板

在需求相关的核心代码处填写，说明整体实现思路，每个需求仅需一个概要文档。

// 示例

// @summary(JIRA-123) 购物车本地缓存方案
//  - context: 购物车数据需要在多个页面共享，且需要离线访问
//  - why: 为了提升用户体验，减少网络请求
//  - how: 使用 localStorage 缓存购物车数据，定时同步到服务器
//  - domain: cart,storage
// @endSummary

决策点注释模板

记录方案实施中的关键技术决策和设计考量。

// 示例

// @decision 选择使用 RESTful API 而非 gRPC
//  - req: JIRA-123
//  - why: 因为 RESTful API 更易于开发和快速迭代，无需频繁更新客户端
//  - how: 使用框架集成的 HTTP Client
//  - risk: 暂无
//  - domain: api,network
// @endDecision

测试重点模板

标记需要重点测试的功能点或场景，便于测试团队定向验证。

// 示例

// @testFocus 验证用户登录逻辑处理
//  - req: JIRA-101, JIRA-102
//  - usecase: 验证用户多次输入错误密码时的账户锁定机制
//  - businessRule:
//    - 用户连续输入错误密码超过 5 次，账户将被锁定 30 分钟
//    - 锁定期间，用户无法登录
//    - 登录成功后，锁定时间将重置
//  - checkMethod: 使用自动化测试模拟连续登录失败场景
//  - risk: 锁定机制可能影响合法用户的登录体验
//  - domain: user,security
// @endTestFocus

BUG修复注释模板

记录BUG修复的原因、方案和影响范围。

// 示例

// @fix(BUG-456) 修复订单金额计算错误
//  - why: 当订单包含多种折扣类型时，计算顺序错误导致最终价格不准确
//  - how: 修改折扣计算顺序，先应用固定金额折扣，再应用百分比折扣
//  - risk: 可能影响历史订单数据的一致性
//  - req: JIRA-789, JIRA-321
//  - domain: order,payment
// @endFix

特性点注释模板

标记重要功能点或特性实现。

// 示例

// @feature 用户登录状态持久化
//  - req: JIRA-101
//  - 实现方式: 使用 JWT 令牌存储在 localStorage 中
//  - 安全考量: 添加令牌失效机制，最长保持登录状态 7 天
// @endFeature

🎨 注释高亮显示

为提高代码可读性，本扩展集成了注释高亮功能，不同类型的注释标记使用不同颜色显示：

注释高亮功能依赖 Better Comments Next 扩展，插件会自动检查并应用高亮配置。

⚙️ 扩展设置

在 VS Code 设置中可以自定义以下选项：

// TODO

🔧 支持的编程语言

• JavaScript / TypeScript / React
• Go
• PHP
• Java
• ...

📈 开发路线图

• [ ] 支持项目级统一配置、解析业务领域ID
• [ ] 支持注释块内的内容提示和自动补全
• [ ] 统计各类文档覆盖率和质量指标
• [ ] 集成Jira，联动需求/缺陷信息

🔌 安装与依赖

1. 在 VS Code 扩展市场中搜索并安装 CoDoc
2. 插件会自动检查并提示安装依赖扩展 Better Comments Next
3. 重启 VS Code 后，CoDoc 将自动激活并准备就绪