VSCode悬浮提示只识别/*.../JSDoc风格注释,普通/.../被忽略;需紧贴声明无空行,且符合语言服务器规则(如JS/TS原生支持,C/C++需clangd及Doxygen格式)。

VSCode 悬浮提示不显示多行注释?先确认是不是用了 /* ... */ 而不是 /** ... */
VSCode 的悬停(hover)提示只识别 **JSDoc 风格的多行注释**,也就是以 /** 开头、*/ 结尾的块注释。普通多行注释 /* ... */(哪怕跨多行)会被语言服务器忽略,完全不会出现在悬停框里。
常见错误现象:
- 写了
/* @param x {number} */,悬停时空白或只显示类型,不显示描述 - 用
///(TypeScript 单行文档注释)注释函数,但语言模式是 JavaScript,导致不生效 - 注释和函数声明之间有空行,部分语言服务器(如 C/C++ 的 clangd)会中断关联
不同语言对 /** 注释的解析差异很大
不是所有 /** 都能触发悬停说明,实际效果取决于当前文件的语言模式和启用的语言服务器:
- JavaScript/TypeScript:原生支持,只要
/**紧贴函数/变量声明上方(无空行),就能解析@param、@returns等标签 - C/C++:需安装并启用
clangd或C/C++扩展,且注释必须严格符合 Doxygen 格式(如/**后换行再写描述,@param前必须有*和空格) - Python:依赖
Pylance,只认三引号 docstring 或"""包裹的函数内首行字符串;/**在 .py 文件里无效 - Go/Rust 等:各自语言服务器有独立规则,不通用
/**
/** 注释里哪些写法会让悬停失效
即使用了正确的开头,细节错误也会让整个注释被跳过:
-
@param标签后漏掉参数名,比如写成@param {string} 描述(正确应为@param name {string} 描述) - 星号
*和文字之间没空格,例如/**@param x{number}*/→ 必须是/** @param x {number} */ - 输入法残留全角字符(如中文冒号、空格),尤其在 Windows 中用中文输入法敲出的空格无法被解析
- 注释块中混入未闭合的
/*或嵌套/**,导致语法解析中断
验证是否生效的最快方式
别等写完一整页再测试,用最小可复现片段当场验证:
/**
* 计算两数之和
* @param {number} a 第一个数
* @param {number} b 第二个数
* @returns {number} 和
*/
function add(a, b) {
return a + b;
}
把这段粘进一个 .js 文件,把光标放在 add 上悬停 —— 如果看到完整描述,说明环境正常;如果只看到 function add(a: number, b: number): number,大概率是注释格式或位置不对。
真正容易被忽略的是:C/C++ 项目里即使装了 clangd,也得确保 compile_commands.json 存在且路径正确,否则注释解析直接降级为纯语法高亮,hover 里什么都不会多出来。











