Skip to content
| Marketplace
Sign in
Visual Studio Code>Snippets>CoDocNew to Visual Studio Code? Get it now.
CoDoc

CoDoc

Jay Youngn

|
13 installs
| (0) | Free
A VS Code extension for generating structured code documentation comments
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

CoDoc

Version VSCode License

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

🔍 什么是 CoDoc?

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

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

为什么选择 CoDoc?

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

📋 快速使用指南

1. 插入文档注释

在支持的编程语言文件中,输入以下任一触发词后按下 Tab 键(或使用上下键选择后按 Enter 键):

触发词 描述 适用场景
doc-summary 方案概要模板 记录需求的核心实现思路和上下文
doc-decision 决策点注释 记录关键技术选型和设计决策
doc-testFocus 测试重点注释 标注需要重点测试的功能场景
doc-fix BUG修复注释 记录问题修复原因和方案
doc-feature 特性点注释 标记新功能的实现要点

注释模板插入后,可通过 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

🎨 注释高亮显示

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

注释类型 颜色 含义
@summary 蓝色 (#3498DB) 方案概述,冷静和信息性
@decision 橙色 (#F39C12) 决策点,需要引起注意
@testFocus 绿色 (#98C379) 测试重点,与测试成功相关联
@fix 红色 (#FF2D00) 问题修复,警示性强
@feature 紫色 (#CE91C8) 新功能或特性点,体现创新

注释高亮功能依赖 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 将自动激活并准备就绪
  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
© 2025 Microsoft