VSCode悬停显示完整文档的关键在于JSDoc注释格式正确、语言服务就绪且配置对齐:必须用/* /包裹,@param、@returns等标签紧贴函数上方无空行,配合jsconfig.json/tsconfig.json启用checkJs,并确保保存后触发解析。

VSCode 悬停提示默认能显示函数签名,但要看到完整文档(参数说明、返回值、示例等),关键不在“开不开 hover”,而在于语言服务能否解析到结构化注释——@param、@returns 这类标签必须写对,且语言模式、项目配置、扩展三者得对齐。
JSDoc / docstring 注释必须严格符合格式规范
VSCode 不会从任意注释里提取文档,只认特定语法和位置。哪怕多一个空格、少一个星号,整个悬停内容就退化为 function add(a, b) 这种裸签名。
-
/** */是唯一被 JS/TS 识别的 JSDoc 容器,/* */或//注释里的@param完全无效 - 注释必须紧贴函数/变量定义上方,中间不能有空行;箭头函数不支持直接挂 JSDoc,得改用
function声明或加@type - Python 的 docstring 必须用 Google/NumPy 风格,且含
Args:和Returns:字段,纯描述性字符串(如"""计算和""")Pylance 不解析 - C/C++ 同样依赖
/** */+@param标签,且@后必须紧跟字母,不能有空格(@ param是错的)
语言服务没就绪,悬停就是空的
注释写对了,但悬停仍不显示文档?大概率是语言服务器(LSP)压根没加载成功,或者没拿到足够语义信息。
- JS/TS 项目必须有
jsconfig.json或tsconfig.json(哪怕空文件),否则类型推导不启用,@param {number}就只是文本 - 右下角状态栏显示
Plain Text或Unknown→ 点击它手动切到正确语言模式(如JavaScript、Python) - Python 必须装
Pylance(不是官方 Python 扩展),且确保python.defaultInterpreterPath指向有效环境 - 首次打开大型项目时,状态栏右下角出现旋转图标或
Language Server initializing...,此时按Ctrl+K Ctrl+I也白搭,等 3–5 秒再试
MDN 链接干扰了你的自定义文档
在 HTML/CSS 文件里悬停 document.getElementById,弹出来的是 MDN 页面链接,而不是你写的 @param?这不是 hover 设置问题,而是内置建议开关没关准。
- 别动
editor.hover.enabled——关了它,连变量值预览、类型提示都消失 - 精准屏蔽:设置里搜
html.suggest.html5→ 设为false;再搜css.mdnsuggest→ 同样设为false - 改完后必须执行
Developer: Reload Window(不是重启编辑器),否则不生效 - 某些 AI 插件(Copilot、Sesame AI)会劫持 hover 事件,如果提示内容突变成“AI 生成摘要”,先禁用它们测试
修改注释后悬停不更新?保存才是触发点
很多人改完 JSDoc 或 docstring,立刻悬停,发现还是旧内容——VSCode 不监听未保存的注释变更,它只在文件保存后重新解析 AST。
- 改完注释,务必按
Ctrl+S(或Cmd+S),否则悬停永远不刷新 - 如果用了符号链接或远程开发(SSH/WSL),检查文件系统是否支持 inotify,否则保存事件可能未被监听到
- 对 TS 项目,若
tsconfig.json里设了"skipLibCheck": true,@types包里的 JSDoc 可能被跳过,建议设为false
最常被忽略的一点:悬停提示是“静态分析结果”,不是实时运行反馈。它不会执行代码,也不关心变量当前值,只信任你写的注释和类型声明。一旦注释格式错、语言服务卡住、或插件覆盖了 hover 提供器,它就只能退回最简签名——这时候别怀疑设置,先看光标下是不是真有一个被 LSP 认出的符号。











