DocBlockr 是 Sublime 中生成函数级注释块的最佳插件,能自动识别函数签名、参数类型和返回值并生成带 @param 和 @returns 的结构化注释;需正确配置语法、启用 jsdocs_python(Python)、设置 jsdocs_extra_tags 自定义标签,且与 Ctrl+Shift+/ 块注释及 LSP 互补不冲突。

用 DocBlockr 插件生成函数级注释块
Sublime 原生不支持自动补全代码块注释(比如 /** ... */),必须靠插件。DocBlockr 是目前最稳定、适配语言最多、配置最灵活的方案,它不是简单插入模板,而是能识别函数签名、参数类型、返回值并自动生成占位符。
常见错误现象:/** 回车后没反应,或只生成空的 /** */ —— 大概率是当前文件语法没识别对(右下角显示 Plain Text 或 JavaScript 拼错),或者没装 DocBlockr。
- 安装路径:按
Ctrl+Shift+P→ 输入Install Package→ 搜索DocBlockr(注意不是 DocBlocker 或 JSDocs) - 确认生效:在
.js或.py文件中,光标位于函数定义行上方,输入/**后按Enter,应自动展开带@param和@returns的结构 - Python 支持需额外配置:DocBlockr 默认不解析
def签名,要在Preferences → Package Settings → DocBlockr → Settings - User中加"jsdocs_python": true - 如果函数有类型注解(如
def foo(x: str) -> int:),DocBlockr 能提取str和int填入@param和@returns,但要求语法高亮为Python,不是Python Improved或其他变体
块注释 ≠ 函数注释:别混淆 Ctrl+Shift+/ 和 DocBlockr
Ctrl+Shift+/ 是 Sublime 内置的「块注释」快捷键,作用是用 /* */ 或 """ """ 包裹选中代码,它不生成文档式注释,也不感知函数结构——它只是文本包裹工具。
容易踩的坑:Ctrl+Shift+/ 在 Python 文件里默认不响应(原生模式无 block_comment 配置),强行配了 """ 也只会机械包裹,不会加空行、缩进或 Args: 标题;而 DocBlockr 是语义级的,只在函数/类定义前触发,和选中范围无关。
- 验证
Ctrl+Shift+/是否可用:打开一个.js文件,选中几行,按快捷键,看是否出现/*和*/;若无反应,说明当前语法未定义block_comment字段 - 想让 Python 也支持
Ctrl+Shift+/块注释?得手动编辑 Python 插件的配置,路径是Packages/Python/Python.sublime-settings,加"block_comment": ["\"\"\"", "\"\"\""],但注意这和 DocBlockr 完全无关 - 二者可共存:你仍可用
Ctrl+Shift+/临时禁用一段逻辑,再用 DocBlockr 给函数加正式文档
自定义注释模板要改 jsdocs_extra_tags,不是改 snippet
很多人想加 @author 或 @date,就去改 sublime-snippet 文件,结果发现 /** 回车后不生效——因为 DocBlockr 不读 snippet,它读的是自己的 JSON 配置项 jsdocs_extra_tags。
性能影响很小,但配置错字段名(比如写成 extra_tags 漏掉 jsdocs_ 前缀)会导致整个插件静默失效,连基础 @param 都不生成。
- 正确配置位置:
Preferences → Package Settings → DocBlockr → Settings - User - 示例(兼容 JS/TS/Python):
{ "jsdocs_extra_tags": ["@author ${1:your_name}", "@date {{datetime}}"], "jsdocs_function_description": true, "jsdocs_notation": "jsdoc" } -
{{datetime}}是 DocBlockr 内置变量,会转成2026-11-04T13:57:00+0800;${1:...}是 Sublime 占位符,Tab 可跳转编辑 - 删掉不需要的字段(如
@version)比留着更安全,避免生成空行或误导性标签
LSP 补全不负责注释,别指望它替代 DocBlockr
有人装了 LSP + pylsp,发现输 /** 还是没反应,就怀疑 LSP 配置错了——其实 LSP 根本不处理注释生成,它的职责是函数签名提示、跳转定义、悬停文档,和注释块自动补全是两条技术路径。
复杂点在于:如果你同时开了 LSP 和 DocBlockr,且都监听 . 或 /,可能触发冲突(比如输 os. 时弹出 LSP 方法列表,但 /** 回车却卡住)。这不是 bug,是设计使然。
- DocBlockr 依赖语法作用域(
source.python)和光标上下文(必须在def或function关键字正上方) - LSP 依赖语言服务器进程和
textDocument/completion请求,它不会拦截/**这种非标识符输入 - 两者真正重叠的只有「悬停提示」:DocBlockr 生成的
@param注释,LSP 能在调用时读出来显示在 tooltip 里;但生成动作本身,LSP 不参与

















