在VSCode中编写JSDoc注释，自动生成功能其实并不复杂。关键在于几个前提条件：文件后缀必须是.js或.ts，语言模式设置正确，光标放置在函数声明开头，然后输入/**并按下回车，即可自动生成基础框架。不过，对于箭头函数、解构参数等场景，自动生成效果有限，此时需要借助插件或手动补充。在TypeScript项目中，类型系统优先，JSDoc更多作为说明文档使用。
VSCode 里按 Ctrl+Shift+P 无法生成 JSDoc 注释？先检查插件和语言模式
默认情况下，VSCode并不自带JSDoc自动生成功能，需要依赖插件或内置支持。文档中常提到的Document This插件已停止更新，目前更稳定的方案是VSCode自带的JavaScript (ES6) Language Features。在JS/TS文件中，输入/**加回车，即可智能生成。
常见问题主要集中在以下几点：
- 文件后缀不是
.js或.ts，或者语言模式设置错误——右下角显示Plain Text而非JavaScript，则无法正常生成。 - 光标未放置在函数名正上方，或者没有紧贴函数声明行的开头。即使有缩进后输入
/**，有时也会失效。 - 箭头函数且没有函数名，例如
const fn = () => {}，VSCode默认不生成。若希望生成，可改用function声明，或手动触发。
/** + Enter 为什么只生成空块，缺少参数和返回值？
VSCode自动生成JSDoc的行为，很大程度上依赖AST解析能力。它能提取形参名称，返回类型在TS环境下也较准确，但在复杂场景下表现有限。
- 函数体为空，或仅包含
return字面量时，可能遗漏@returns标签。 - 参数使用解构，比如
({ a, b }) => {}，或默认值(x = 1) => {}，VSCode通常只生成@param {any} x，不解析默认值含义。 - 在TS中，参数未显式标注类型，例如
function f(x)，会标记为@param {any} x，不会从上下文推断。 - 异步函数
async function会自动添加@returns {Promise}，但不会展开泛型，比如Promise需要手动补充。
想统一规范 JSDoc 格式？用 jsdoc-snippets 插件定制模板
VSCode内置生成器的格式固定，无法添加作者、日期、版本等字段。要统一团队风格，轻量插件jsdoc-snippets非常实用。启用后，在函数上方输入jsdoc加Tab，即可插入预设模板。
关键配置项位于settings.json中：
"jsdoc.snippets.author": "Your Name"——自动填充作者。"jsdoc.snippets.includeDescription": true——强制保留描述空行。"jsdoc.snippets.perferredLanguage": "zh-CN"——使用中文注释字段名，如@描述。- 自定义模板路径通过
"jsdoc.snippets.customTemplatePath"指向本地.jsdoc文件。
举个例子，光标放置在function getData(id)上方，生成效果如下：
/**
* @description
* @author Your Name
* @date 2024-05-20
* @param {string} id -
* @returns {Promise}
*/
TS 项目里 JSDoc 和类型定义重复？优先信 @type 还是接口？
在TypeScript中混用JSDoc和类型系统，容易引发维护冲突。例如函数参数使用@param {User} user，但实际调用处传入结构不符的对象——TS编译器不会校验JSDoc中的类型，只识别interface User或类型注解。
实际协作中，建议遵循以下原则：
- 纯JS项目：JSDoc是唯一的类型文档，务必确保
@param/@returns与运行时一致。 - TS项目：JSDoc仅用于说明性内容，如用途、副作用、业务约束。删除所有
@param {xxx}类型声明，让TS自行推导。 - 如需兼容JS用户，可使用
@typedef+@type定义复杂类型，但必须与interface同步更新，否则极易过期。 - VSCode对
@type的提示支持有限，例如/** @type {import('./types').Config} */可能无法触发跳转。
归根结底，JSDoc本质上是给人阅读的文档，而非机器契约。生成快捷键能节省时间，但字段是否准确、描述是否清晰，仍需开发者紧盯函数逻辑本身。
