sublime text原生不支持docblock注释自动补全，必须依赖docblockr插件或自定义snippet；docblockr通过正则匹配函数声明行生成带@param占位符的结构化注释，但不解析类型注解且要求光标位于函数定义行开头。
Sublime Text 本身不提供开箱即用的 DocBlock 注释块（如 /** */ 或 /** @param ... */）自动补全，原生 Ctrl+Shift+/ 只能插入基础块注释（/* */），且不识别函数签名、参数、返回值等语义。要实现「输入 /** + Enter 自动展开为带参数占位符的文档注释」，必须依赖插件或手动配置 snippet —— 没有捷径，也别指望改几个键绑定就能搞定。
DocBlockr 插件是唯一靠谱的起点
原生 Sublime 不解析 JS/PHP/Python 的函数定义，所以无法自动生成 @param 列表。DocBlockr 是目前最稳定、适配语言最多、更新持续的插件，它通过正则匹配函数声明行（如 function foo($a, $b) 或 def bar(x: int) -> str:）来推导参数名和类型。
- 安装后，光标停在函数名上方，输入
/**再按Enter，就会生成结构化注释模板 - 支持 JavaScript、TypeScript、PHP、Python（需额外配置）、Go、Rust 等主流语言
- 不依赖语法高亮模式（syntax），但要求当前文件已正确设为对应语言（右下角显示
JavaScript而非Plain Text） - 若生成结果为空或字段错乱，大概率是函数签名格式不符合插件预设正则——比如 JS 中用了箭头函数且无显式
function关键字，或 Python 中类型提示写法太新（def f(x: Annotated[int, "id"]) -> None:）
不装插件？用 snippet 手动兜底
如果你只在固定几种场景用 DocBlock（比如只写 JS 函数文档），snippet 是轻量、可控、不冲突的替代方案。它不自动推导参数，但能保证格式统一、快捷触发。
- 打开
Tools → Developer → New Snippet... - 填入内容（以 JS 为例）：
<snippet><content><tabtrigger>doc</tabtrigger><scope>source.js</scope></content></snippet>
- 保存为
Packages/User/js-doc.sublime-snippet - 在 JS 文件中输入
doc+Tab，即可插入预设结构 -
<scope></scope>必须写对：JS 是source.js，Python 是source.python，PHP 是source.php—— 错了就触发不了
为什么 Ctrl+Shift+/ 总是生成空 /* */？
这个快捷键调用的是 Sublime 原生的 toggle_comment 命令，参数为 {"block": true}。它只做一件事：在选中文本前后插入语言定义的 comment_block_start 和 comment_block_end 符号（如 JS 是 /* 和 */）。它完全不分析代码结构，也不补任何字段。
- 你没选中任何文本时按
Ctrl+Shift+/，Sublime 会把整行当“选中内容”，结果就是/* console.log("x"); */ - 你选中了函数体（不含函数声明），它照样只包一层
/* ... */，不会加@param - 如果当前语法没定义
comment_block_start（比如某些自定义 .env 语法），该快捷键直接静默失效 - 想让它“智能”，只能换插件；想让它“可靠”，就老实用 snippet
容易被忽略的细节：作用域与激活时机
DocBlockr 和 snippet 都极度依赖 Sublime 的 scope 机制。不是“文件后缀对就行”，而是光标所在位置的 scope 必须匹配规则。比如：
- 在 JS 文件里，函数内部写
/**+Enter，可能触发失败——因为光标 scope 是source.js meta.function.js，而插件只监听source.js下的函数声明行（meta.function.js entity.name.function.js） - Python 中用了
async def，默认 DocBlockr 可能不识别，需在插件设置里启用enable_async_def - snippet 的
<scope></scope>值必须精确到子 scope，比如 Vue 单文件组件里的<script></script>区域要用source.js.embedded.html，而非简单写source.js
