<p>VSCode 对 JSDoc 支持扎实，规范书写即可触发类型提示、参数说明和自动补全；需用 /* / 紧贴声明上方，正确使用 @param、@returns、@type 等标签，并配合 jsconfig.json 或 tsconfig.json 配置以确保最佳效果。</p>
VSCode 对 JSDoc 的支持很扎实，只要写法规范，就能直接触发类型提示、参数说明和自动补全，不用装额外插件（TypeScript 项目或启用了 JS 语言服务时效果最佳）。
基础写法决定提示是否出现
JSDoc 注释必须紧贴函数、变量或类的上方，且用 /** */ 包裹（不是 /* */ 或 //）。光标停在函数名或调用处时，Hover 就能显示文档内容。
- ✅ 正确：
/**
* 计算两个数的和
* @param {number} a 第一个数
* @param {number} b 第二个数
* @returns {number}
*/
function add(a, b) { return a + b; } - ❌ 无效：注释和函数之间有空行、用了单行注释、或者 JSDoc 没闭合
@param 和 @returns 类型要写对
VSCode 不做类型校验，但会按你写的类型文本去匹配已知类型（如 string、number、Promise），甚至支持泛型和交叉类型。写错类型名（比如拼成 numberr）会导致提示不准确或消失。
- 推荐用标准类型： @param {Array<string>} names、@param {import('./types').User} user
- 对象参数可用 @param {{ id: number; name: string }} opts 直接内联定义
- 返回 Promise 时写 @returns {Promise<string>}，调用处 `.then()` 的参数就能获得 string 提示
利用 @type 给变量加类型提示
普通 JS 变量默认无类型推导，但加上 @type 就能激活智能提示。适合配置对象、回调函数、第三方库返回值等场景。
-
/** @type {HTMLButtonElement} */
const btn = document.querySelector('button'); → 后续访问 btn.click() 就有完整方法提示 -
/** @type {(id: string) => Promise<User>} */
const fetchUser = async (id) => { ... }; - 配合 @typedef 可定义复用类型：/** @typedef {{ name: string; age: number }} Person */
小技巧让提示更准更稳
有些情况提示“失灵”，往往不是 VSCode 问题，而是上下文没对上。
- 确保文件是 .js 或 .mjs，且没有被 // @ts-nocheck 禁用 JS 语言服务
- 大型项目建议配 jsconfig.json（JS）或 tsconfig.json（TS），开启 "checkJs": true 和 "allowJs": true
- VSCode 设置里确认 JavaScript > Suggest: Auto Imports 是开启状态，这样从 JSDoc 推导出的类型也能参与自动导入
基本上就这些。写得规范，VSCode 就能“读懂”你的 JSDoc，并把提示自然地送过来——不复杂但容易忽略细节。
