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)：表示问题修复，警示性强@feature 使用紫色 (#CE91C8)：表示新功能或特性点，体现创新
- 字段标记：
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 进行过滤
- 可多选需要导出的注释类型
- 插件会自动扫描和比对指定 commit 中的变更文件，提取标准格式的注释内容，生成一份 Markdown 格式的文档
支持的编程语言
- JavaScript
- TypeScript
- Go
- PHP
- Java
- C++
扩展设置
TODO
