DocBlockr仅生成函数上方的JSDoc/PHPDoc文档块,不处理代码块注释;真要注释代码需用Ctrl+Shift+/或Comment-Snippets插件,二者分工明确、互不冲突。

别装 DocBlockr 当块注释插件用——它根本不是干这个的。 它只负责生成函数上方的 JSDoc/PHPDoc 风格文档块(即 /** ... */),不处理代码逻辑屏蔽、临时禁用、多行包裹等“块注释”需求。真要一键注释/取消一段代码,得靠原生快捷键或更合适的插件。
Ctrl+Shift+/ 是原生块注释快捷键,但有硬限制
这个组合键触发的是 Sublime 的 toggle_comment 命令并传入 {"block": true} 参数,本质是调用当前语言语法定义的 block_comment 规则。它不是万能的:
- JavaScript、CSS、C++ 文件中选中任意连续几行,按
Ctrl+Shift+/会套上/* */ - Python 文件默认不响应——因为原生 Python 语法没定义
block_comment,得装Python Improved插件或手动配置 - 选区跨空行、含已有注释行、或首尾缩进不一致时,Sublime 可能直接不执行,或退化为逐行加
# - HTML 中它生成
,但若光标在标签属性里,可能只注释属性值而非整行
Comment-Snippets 才是真正靠谱的块注释增强方案
它比原生 Ctrl+Shift+/ 多一层上下文识别:光标在函数内就自动扩到整个函数体,选中 if 块中间两行也能智能包裹到 if 和 };还支持自定义模板,比如让 JSON 文件临时用 // 注释(需配合 JSONC 语法)。
- 安装方式同其他插件:
Ctrl+Shift+P→Package Control: Install Package→ 搜Comment-Snippets - 装完无需重启,直接在 JS/Python/HTML 文件中选中代码 → 右键 →
Comment Selection或用默认快捷键Ctrl+Shift+7 - 不依赖文件右下角语法是否准确——即使显示
Plain Text,只要内容能被识别为某种结构(如函数、对象、标签对),它仍能工作 - 和 DocBlockr 无冲突,可共存:一个管文档注释,一个管逻辑屏蔽
DocBlockr 装了却没反应?大概率卡在这三个地方
很多人装完 DocBlockr,在函数前敲 /** 回车没反应,不是插件坏了,而是触发条件没满足:
- 当前文件右下角必须显示
JavaScript、PHP、TypeScript等支持语言,Plain Text或Unsupported syntax下完全静默 - 必须在函数定义的正上方一行输入
/**后按Enter—— 按Tab是跳字段,不是生成注释 - 确认装的是 nikhilm 维护的
sublimetext-docblockr,不是旧版 spadgos 的jsdocs(后者已停更,ST4 上常报错) - 检查
Preferences → Package Settings → DocBlockr → Settings - User里没把"auto_indent"设为false,否则连基础结构都不补全
块注释和文档注释是两类事,混用插件只会反复踩坑。用 Ctrl+Shift+/ 或 Comment-Snippets 处理代码屏蔽,把 DocBlockr 留给函数说明——边界划清了,反而最省事。











