DocBlockr插件需正确安装、语法模式设为JavaScript等支持语言、光标置于函数行或其正上方空行三者缺一不可；默认不生成类型占位符，需手动配置jsdoc_template添加。
能一键生成函数注释，但“一键”不是按一个键就完事——必须装对插件、设对语法、放对光标位置，三者缺一不可。
怎么装 DocBlockr 才不踩坑
别搜“DocBlockr”直接装，容易装到已停止维护的旧版；Sublime Text 3/4 应装社区活跃分支：
- 按
Ctrl+Shift+P（Mac 为Cmd+Shift+P）打开命令面板 - 输入
Package Control: Install Package回车 - 搜索
DocBlockr（作者是 nikhilm，GitHub 仓库名sublimetext-docblockr） - 安装后建议重启 Sublime，部分版本不重启不加载新插件
验证是否生效：新建一个 .js 文件，写 function foo(a, b) {}，光标停在函数上方空行，输入 /** 后按 Enter —— 若生成带 @param 的块，说明装对了。
为什么 /** + Enter 没反应
最常见原因不是插件坏了，而是环境没配准：
- 右下角语法模式必须是
JavaScript、PHP、Python等支持语言，不能是Plain Text（点它手动切换） - 光标必须在函数定义行（如
function bar()或def baz():所在行）的任意位置，或其正上方的空行；在函数体内部、变量行、注释行都不触发 - 默认监听的是
Enter，不是Tab；Tab是在已生成的注释里跳字段用的 - 检查是否有其他插件（比如 Emmet）劫持了
Enter行为；可临时禁用其他插件测试
若仍无效，进 Preferences → Package Settings → DocBlockr → Settings – User，确认 "auto_indent": true 没被设为 false。
哪些函数签名 DocBlockr 解析不了
它靠正则匹配，不跑代码也不读类型系统，所以这些写法大概率失败：
- JavaScript 箭头函数：
const fn = (a, b) => {}（需改写为function fn(a, b) {}或额外配置jsdocs_extra_tags） - 带解构/默认值的复杂参数：
function f({ x }, [y] = [])可能只识别出{ x }和[y]，不拆结构 - TypeScript/Python 类型提示：
def g(x: int) -> str:中的int和str不会被自动填进@param {int}或@return {str} - PHP 7+ 返回类型：
function h(): ?string中的?string不会转成@return string|null
遇到这类情况，先手写标准函数声明再触发，或生成后手动补全类型和描述。
怎么让 @param 自动带 {type} 占位符
默认模板不带类型占位符，但可通过用户设置强制加上：
进 Preferences → Package Settings → DocBlockr → Settings – User，添加：
{
"jsdoc_template": "/**\n * ${1:description}\n${2: * @param {${3:type}} ${4:name} - ${5:description}\n}${6: * @return {${7:type}} ${8:description}\n} */"
}
注意几点：
- 该配置仅对 JavaScript 生效；PHP/Python 需分别配置
phpdoc_template或pydoc_template - 修改后保存，不用重启，但已有打开的文件可能需重载语法（右下角切一下再切回来）
- 占位符
${3:type}是纯提示，不会自动从代码中提取类型——仍得手动填
真正难的从来不是加一行配置，而是每次写函数时，下意识把光标挪到对的位置、确保语法模式亮着、避开那些正则认不出的写法。这些细节不盯住，装再好的插件也白搭。
