jsdoc 注释块默认不可折叠，因 vscode 不原生识别注释为折叠结构；可靠方法是用 // #region 包裹或改 foldingstrategy 为 indentation，但后者不稳定。
JSDoc 注释块默认不能用 Ctrl+Shift+[ 折叠
VSCode 不把 // 或 /** */ 注释识别为原生可折叠结构，哪怕它是格式标准的 JSDoc。光标停在 /** 行按 Ctrl+Shift+[ 没反应，不是快捷键坏了，是语言服务压根没注册这个折叠点。
常见错误现象：选中整个 JSDoc 块再按快捷键，依然不折叠；或者只折了第一行，剩下几行“掉出来”——这说明折叠边界没对齐，不是操作问题，是机制限制。
让 JSDoc 可折叠的两种可靠方式
必须显式告诉 VSCode “这里是一块”，它才认：
- 用
// #region包裹（推荐）：JSDoc 前加// #region API docs，后面紧接// #endregion，中间保持纯注释行。JS/TS 文件里立刻生效，左侧出现折叠箭头，Ctrl+Shift+[也响应 - 改折叠策略为
indentation：在设置里搜editor.foldingStrategy，改成indentation。之后只要 JSDoc 所有行缩进一致（比如都顶格或都缩进 2 空格），且上下没空行，Ctrl+Shift+[就可能把它当一块折 —— 但不稳定，混入空行或缩进错一位就失效
注意：/* #region */ 这种写法在 JS/TS 中不被识别，必须是单行注释开头的 // #region。
批量给已有 JSDoc 加 #region 标记（不用插件）
手动补太慢？用 VSCode 自带替换功能：
- 打开替换面板（
Ctrl+H），开启正则模式（点.*按钮） - 查找：
/\*\*[\s\S]*?\*/（匹配/** ... */块） - 替换为：
// #region jsdoc\n$&\n// #endregion - 务必先按
Alt+Enter预览所有匹配项，确认没误伤/* 一些普通注释 */或代码里的字符串
Python 文件同理，但要把 // 换成 #，且确保已启用官方 Python 扩展和 python.foldingStrategy: "indentation"。
为什么鼠标点折叠箭头有时比快捷键更靠谱
Ctrl+Shift+[ 要求光标落在“可折叠结构起始行”，而 JSDoc 没有语法起始概念。但一旦你加了 // #region，VSCode 就会在该行左侧渲染折叠控件（▶），此时鼠标点一下比反复调光标位置更直接。
真正容易被忽略的是：区域标记必须成对、无嵌套错位、且不能跨文件作用域——比如在一个 .js 文件里写的 // #region，不会影响隔壁 .ts 文件的折叠行为，哪怕它们内容一样。
