VSCode悬停内容由语言服务器解析注释生成，非用户直接配置；JS/TS需标准JSDoc，Python需匹配风格的docstring并配Pylance，且文件语法必须正确。
悬停内容不能直接“自定义”，但能精准控制它显示什么
VSCode 的悬停（Hover）不是靠用户配置项开关或编辑模板来定制的，而是由语言服务器根据代码中已有的结构化信息自动生成。你真正能干预的，只有两件事：写对注释、配对扩展。比如 add 函数悬停里出现“计算两个数的和”，不是 VSCode 决定的，是你写的 /** ... */ 注释被 Pylance 或 TypeScript 服务解析出来的。
常见错误现象：
- 悬停只显示
function add(a: any, b: any): any，没说明文字 → 缺 JSDoc / docstring 或格式不被识别 - 悬停弹出 MDN 页面链接（如
console.log）而不是本地类型签名 → 当前文件语言模式是 HTML/CSS，不是 JS/TS - 鼠标停半天没反应 → 右下角显示
Plain Text或Python (Jedi)，不是Python (Pylance)
JavaScript/TypeScript 必须用 JSDoc 注释才能让悬停有描述
仅靠函数签名，悬停最多显示参数类型；要带语义说明，必须写标准 JSDoc。VSCode 不解析普通单行注释（//），也不认非标准块注释（/* ... */）。
正确写法示例：
/**
* 计算两个数字的和，支持负数和小数
* @param {number} a - 被加数，必须为有效数字
* @param {number} b - 加数，可为负值
* @returns {number} 和值，不会返回 NaN（输入非法时抛错）
*/
function add(a, b) {
return a + b;
}
关键点：
-
@param和@returns字段名必须与函数参数名完全一致（区分大小写） - TypeScript 项目需有
tsconfig.json或jsconfig.json，哪怕只含{"compilerOptions": {"allowJs": true}} - 修改完 JSDoc 后，悬停可能仍缓存旧内容 → 按
Ctrl+Shift+P输入Documentation: Show Documentation强制刷新
Python 悬停依赖 docstring 风格 + Pylance 解析能力
Python 的悬停内容质量，直接受 python.languageServer 设置和 docstring 格式影响。Pylance 支持 Google、NumPy、Sphinx 三种风格，但不支持任意格式的三引号字符串。
有效示例（Google 风格）：
def load_config(path: str, encoding: str = "utf-8") -> dict:
"""加载配置文件并解析为字典。
<pre class="brush:php;toolbar:false;">Args:
path: 配置文件路径，必须存在且可读
encoding: 文件编码，默认 utf-8
Returns:
解析后的配置字典，键全为字符串
Raises:
FileNotFoundError: path 不存在
"""
...
容易踩的坑：
- 写了 docstring，但悬停仍只显示
load_config(arg0, arg1)→ 参数缺少类型提示（path: str这种），Pylance 推不出参数名 - 第三方库（如
cv2.imread）悬停无说明 → 安装对应类型包：pip install types-opencv-python - docstring 写在函数体第一行但缩进不对（如多了一个空格），Pylance 会直接忽略整段
别试图关掉 MDN 链接来“净化”悬停
HTML/CSS 文件中悬停出现 MDN 链接，是因为内置的 html.suggest.html5 和 css.mdnsuggest 扩展在工作。但这和 JS/Python 的悬停逻辑完全隔离——关掉它们，JS 函数的 JSDoc 不会因此变多，反而可能丢失 HTML 元素属性提示。
真正该做的是：
- 确认当前文件右下角语言模式是
JavaScript或TypeScript，不是HTML - 在 JS 文件里调用
fetch()时想看浏览器 API 文档？那是正常行为，MDN 链接本身就有价值 - 如果只想看类型签名不想要链接，可在设置中关闭
html.suggest.html5，但请意识到：这仅影响 .html 文件，对 .js/.ts 无任何作用
最常被忽略的一点：悬停内容是否完整，不取决于你按了多少快捷键，而取决于光标所在位置的 AST 是否健全。语法错误、未闭合括号、模板字符串中断（`${foo(}`）都会导致整个文件的悬停降级为“仅签名”。先修复报错，再谈文档。
