docblockr是开箱即用的主流语言函数注释生成插件，输入/**回车即可生成@param/@return模板；常见失效原因包括右下角语法名错误、光标位置不当、输入法干扰或插件冲突，需手动切换语法模式或配置快捷键绑定。
DocBlockr 是目前最稳的函数注释生成插件
它不是“可用”，而是几乎所有主流语言下都开箱即用，且不依赖额外配置就能识别 function、def、public function 等常见定义结构。只要光标停在函数上方、输入 /** 后回车，就能生成带 @param 和 @return 的模板——不需要记命令、不弹窗、不打断编码节奏。
容易踩的坑：
- 右下角语法名必须是正确语言（比如写 JS 却显示
Plain Text，/**回车后啥也不出） - 函数参数名含下划线或驼峰但没类型提示时，
@param类型可能被推成{any}，得手动改或配jsdocs_autoadd_method_tag - Python 中若用
self作首参，插件默认跳过它；但cls不跳，行为不一致
Ctrl+/ 失效？先看右下角语法名和输入法
这不是插件问题，是 Sublime 的底层机制：它只查右下角显示的语法名（如 JavaScript），不看文件后缀，也不猜语言。一旦显示 Plain Text 或 Unsupported syntax，Ctrl+/ 就静默失效——按了没反应，也不报错。
真实场景下的应对方式：
- 点右下角 → 搜索并选中对应语法（如
JavaScript、Python、Shell-Unix-Generic） - Windows 用户务必切英文输入法，中文输入法下
Ctrl+/常被拦截 - 打开的是
.env或无后缀配置文件？手动切语法比改文件名更直接 - 装了 Emmet、Vintage 或自定义键绑定插件？临时禁用它们验证是否冲突
想统一用 /* */ 块注释？别靠 Ctrl+Shift+/ 猜
Ctrl+Shift+/（Win/Linux）或 Cmd+Option+/（macOS）不是通用块注释键，它只在当前语法明确定义了 comment_start 和 comment_end 时才生效。JS、CSS、Java 支持，Python、HTML、JSONC 则基本无效。
真正可控的做法：
- 选中目标代码块（必须是完整逻辑行，不能只选半行）
- 确认右下角是
JavaScript或CSS等支持块注释的语法 - 再按
Ctrl+Shift+/—— 若仍失败，说明该语言包没启用 block 模式 - 不想折腾？用 snippet：新建
Tools → Developer → New Snippet，写死/* $0 */绑快捷键
自定义快捷键让注释行为更确定
靠 Sublime 默认行为容易翻车，尤其在混用脚本、配置文件、前端组件时。最省心的方式是绕过语法自动匹配，直接绑定具体动作。
例如，在用户键绑定里加这条：
{
"keys": ["ctrl+alt+/"],
"command": "docblockr"
}
或者强制所有 .sh 和 .env 文件用 # 注释：
{
"keys": ["ctrl+/"],
"command": "toggle_comment",
"args": {"block": false},
"context": [
{"key": "selector", "operator": "equal", "operand": "source.shell, text.env"}
]
}
这种写法不依赖右下角语法名，也不怕输入法干扰，是团队规范落地最可靠的路径。
复杂点在于：不同语言对“参数类型推断”的逻辑藏在语法包内部，DocBlockr 只负责读取，没法强行覆盖。所以命名不规范的函数，生成的 @param {string} 很可能不准——这得靠人来盯，不是插件能兜底的。
