vs code 内置功能可一键生成 jsdoc 注释：光标置于函数名上方输入/**后回车，自动补全@param和@returns模板，仅限js/ts文件且需语言模式为typescript；better comments仅高亮不生成文档，doxygen插件在js/python中参数解析弱、泛型支持差。
Better Comments 是目前最实用、开箱即用的注释高亮插件，但它不生成标准文档；真正能一键生成函数/类级标准注释文档的，是 Comment Anchors + 手动触发 Insert JSDoc Comment（VS Code 内置）。
如何用 VS Code 内置功能生成 JSDoc 注释
VS Code 原生支持 JSDoc 模板插入，无需额外插件即可生成结构化注释。光标放在函数名上方，输入 /** 后回车，编辑器自动补全基础模板，包括 @param 和 @returns 占位符。
- 只对 JavaScript/TypeScript 文件生效；若在
.vue或.ts的 SFC script setup 中失效，需确认文件语言模式是否为typescript（不是vue） - 不识别自定义类型别名（如
type UserId = string），@param会显示原始类型string，而非UserId - 生成的注释默认不带 author/date 字段，如需统一添加，可在
settings.json配置："javascript.suggest.autoImports": false避免干扰，再配合editor.action.insertSnippet绑定自定义代码片段
Better Comments 为什么不能替代 JSDoc 生成
Better Comments 只做视觉增强，它不解析语义、不校验参数名是否匹配函数签名、也不生成文档入口。你写 // ! 这里可能崩，它标红；但写 // @param name {string}，它完全无视。
- 常见误用：以为启用
Better Comments后// TODO:就能被 ESLint 的no-warning-comments规则识别——其实不会，ESLint 看的是注释内容，不是颜色 - Vue 单文件中
<script setup></script>区域若未设语言为typescript，/**回车不触发 JSDoc，此时Better Comments的*标记虽能上色，但和文档生成无关 - 团队项目中若混用
Better Comments和Colorful Comments，二者对todo的触发前缀不同（前者要小写todo，后者认TODO），容易漏高亮
Doxygen 插件在非 C++ 项目中的实际限制
Doxygen Documentation Generator 插件对 Python/JS 支持较弱：Python 函数参数顺序无法自动映射到 @param，JS 的箭头函数 const fn = (a, b) => {} 无法被正确解析出参数名。
- 配置项如
doxdocgen.c.commentPrefix对 TypeScript 无效，强行设为*会导致所有/**块被套两层星号 - 生成的注释块末尾固定为
*/（空格+星号+空格+斜杠），与 Prettier 默认的*/格式冲突，保存时会被自动删掉空格，破坏 Doxygen 解析 - 不支持 TS 的泛型约束（如
<t extends record any>></t>），@template字段只能手写
真正影响长期可维护性的，不是注释有没有颜色，而是注释是否与函数签名保持同步。JSDoc 模板由编辑器原生驱动，只要函数改了参数，编辑器就能提示注释未更新；而任何靠人工打 ! ? * 的方式，都无法建立这种绑定关系。
