Docs As Code for Style3D
本扩展提供了一个结构化的代码文档注释模板,帮助开发者维护一致的代码文档风格。
使用方法
在支持的编程语言文件中,输入以下任一触发词然后按 Tab 键(或上下选择按 Enter 键),即可插入对应的注释模板:
模板插入后,可以通过 Tab 键在各个字段之间快速切换,填写相应内容。
特性
一、代码注释模板
这个扩展提供了四种不同类型的注释模板:
1. 方案概要模板
在当前需求相关的"核心代码修改处"填写,比如控制器入口、服务/组件主要方法等。每个需求仅需要一个概要文档。
// 模板
// @summary(需求ID) <输入此“方案概要”的标题>
// - context: [必填]背景与上下文,解释这个功能在哪个大环境下
// - why: [必填]需求背景/为什么需要这个方案
// - how: [必填]技术实现方案概述
// - domain: [可选]关联领域ID,如"user,order,payment"
// @endSummary
// 示例
// @summary(CLOUD-123) 购物车本地缓存方案
// - context: 购物车数据需要在多个页面共享,且需要离线访问
// - why: 为了提升用户体验,减少网络请求
// - how: 使用 localStorage 缓存购物车数据,定时同步到服务器 (timeInterval)
// - domain: cart,storage
// @endSummary
2. 决策点注释模板
记录方案实施中的关键决策点和风险,以及一些重要设计决策。
// 模板
// @decision <输入此“决策点”的标题>
// - why: [必填]为什么要做这个决策
// - how: [必填]概括此决策的实现
// - risk: [可选]潜在的风险点描述
// - req: [可选]关联需求ID,如"CLOUD-123,CLOUD-456"
// - domain: [可选]关联领域ID,如"user,order,payment"
// @endDecision
// 示例
// @decision 选择使用 RESTful API 而非 gRPC
// - req: CLOUD-123
// - why: 因为 RESTful API 更易于开发和快速迭代,无需频繁更新客户端
// - how: 使用框架集成的 HTTP Client
// - risk: 暂无
// - domain: api,network
// @endDecision
3. 测试重点模板
记录需要重点测试的功能点或场景。推荐关联需求 ID 以便解析导出。
// 模板
// @testFocus <输入此“测试重点”的标题>
// - req: [可选]关联需求ID,如"CLOUD-123,CLOUD-456"
// - usecase: [必填]一句话说清测试场景
// - businessRule: [必填]可执行描述
// - checkMethod: [必填]针对性验证方法
// - risk: [可选]潜在的风险点描述
// - domain: [可选]关联领域ID,如"user,order,payment"
// @endTestFocus
// 示例
// @testFocus 验证用户登录逻辑处理
// - req: CLOUD-101, CLOUD-102
// - usecase: 验证用户多次输入错误密码时的账户锁定机制
// - businessRule:
// - 用户连续输入错误密码超过 5 次,账户将被锁定 30 分钟
// - 锁定期间,用户无法登录
// - 登录成功后,锁定时间将重置
// - checkMethod: 使用自动化测试模拟连续登录失败场景
// - risk: 锁定机制可能影响合法用户的登录体验
// - domain: user,security
// @endTestFocus
4. BUG修复注释模板
记录BUG修复方案,问题发生的原因、后续改进等。
// 模板
// @fix(BUG编号) <输入此“BUG修复”的标题>
// - why: [必填]BUG原因/为什么要改这里
// - how: [必填]具体修复方案
// - risk: [可选]潜在的风险点描述
// - req: [可选]关联需求ID,如"CLOUD-123,CLOUD-456"
// - domain: [可选]关联领域ID,如"user,order,payment"
// @endFix
// 示例
// @fix(BUG-456) 修复订单金额计算错误
// - why: 当订单包含多种折扣类型时,计算顺序错误导致最终价格不准确
// - how: 修改折扣计算顺序,先应用固定金额折扣,再应用百分比折扣
// - risk: 可能影响历史订单数据的一致性
// - req: CLOUD-789, CLOUD-321
// - domain: order,payment
// @endFix
二、注释高亮显示
为了提高代码文档的可读性,本扩展集成了注释高亮功能,支持以下注释标记的高亮显示:
- 注释类型标记和对应预置颜色:
@summary
使用蓝色 (#3498DB):表示概述,给人冷静和信息性的感觉
@decision
使用橙色 (#F39C12):表示决策点,需要引起注意
@testFocus
使用绿色 (#98C379):表示测试重点,与测试成功相关联
@fix
使用红色 (#FF2D00):表示问题修复,警示性强
- 字段标记:
req
会被严格解析,用来跟踪关联需求
domain
会被解析,用于关联领域,领域范围未来将读取项目中的 .style3d/docs/domain.yaml
文件
- 其余字段在注释内容中使用
- <字段名>:
来识别(实际解析时,每个类型标记内部将整体当作 markdown)
注释高亮功能依赖于 Better Comments Next 扩展,插件会自动检查并应用高亮配置。
(如要再次定制可自行修改配置项 better-comments.tags
里 source: "s3d-docs:*"
部分)
三、生成变更文档
该插件还提供了自动生成变更文档的功能,可以提取代码中的特殊注释标记,生成一份完整的变更文档:
- 在 VS Code 命令面板中(按下
Ctrl+Shift+P
或 Cmd+Shift+P
),输入 s3d-docs.readComments
- 输入
<Git 分支名>
或 <Commit ID>
用于 diff 与当前分支的文件变更(例如: master / HEAD / 4efa151)
- 可选:输入需求 ID 或 BUG ID 进行过滤(例如:
CLOUD-123,CLOUD-456
留空则读取所有文档注释)
- 插件会自动扫描和比对指定 commit 中的变更文件,提取标准格式的注释内容,生成一份 Markdown 格式的文档
支持的编程语言
- JavaScript
- TypeScript
- Go
- PHP
- Java
- C++
扩展设置
TODO