VSCode中的JSDoc注释与智能提示

VSCode 对 JSDoc 支持扎实，规范书写即可触发类型提示、参数说明和自动补全；需用 /* / 紧贴声明上方，正确使用 @param、@returns、@type 等标签，并配合 jsconfig.json 或 tsconfig.json 配置以确保最佳效果。

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} names、@param {import('./types').User} user
• 对象参数可用 @param {{ id: number; name: string }} opts 直接内联定义
• 返回 Promise 时写 @returns {Promise}，调用处 `.then()` 的参数就能获得 string 提示

利用 @type 给变量加类型提示

普通 JS 变量默认无类型推导，但加上 @type 就能激活智能提示。适合配置对象、回调函数、第三方库返回值等场景。

神卷标书

神卷标书，专注于AI智能标书制作、管理与咨询服务，提供高效、专业的招投标解决方案。支持一站式标书生成、模板下载，助力企业轻松投标，提升中标率。

210

查看详情

• /** @type {HTMLButtonElement} */
  const btn = document.querySelector('button'); → 后续访问 btn.click() 就有完整方法提示
• /** @type {(id: string) => Promise} */
  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，并把提示自然地送过来——不复杂但容易忽略细节。

以上就是VSCode中的JSDoc注释与智能提示的详细内容，更多请关注php中文网其它相关文章！