docblockr 是 sublime text 中唯一稳定支持一键生成函数文档注释的插件，需正确安装（认准作者 nikhilm）、设置语法为 javascript/php/python 等、光标置于函数上方空行或定义行，输入 /** + enter 即可生成含 @param/@return 的模板。
DocBlockr 是目前 Sublime Text 中唯一能真正实现“一键生成函数文档注释”的插件，其他插件要么功能残缺，要么已停止维护。它不是“可能行”，而是只要三件事对了——插件装对、语法设对、光标放对——/** + Enter 就能出完整 @param/@return 模板。
怎么装 DocBlockr 才不装错旧版
别直接搜“DocBlockr”点安装，Sublime Package Control 里有多个同名但不同作者的版本，容易误装已归档的旧分支。
- 必须用命令面板：
Ctrl+Shift+P（Mac 为Cmd+Shift+P）→ 输入Package Control: Install Package→ 等列表加载完再搜DocBlockr - 认准作者是
nikhilm，GitHub 仓库名是sublimetext-docblockr（不是docblockr或docblockr-plus） - 装完建议重启 Sublime，部分 ST4 版本不重启插件不注册命令，
docblockr命令不可用 - 验证方式：新建
.js文件，写function foo(a, b) {}，光标停在函数上方空行，输入/**回车 —— 若生成带@param的块，说明装对了
为什么 /** + Enter 没反应
90% 的失效不是插件问题，而是环境没配准。它不看文件后缀，只认右下角显示的语法名。
- 右下角必须显示
JavaScript、PHP、Python等支持语言，不能是Plain Text或Unsupported syntax（点它手动切换） - 光标必须在函数定义行（如
function bar() {或def baz():）的任意位置，或其正上方**紧邻的空行**；在函数体内部、变量行、已有注释行都不触发 -
Enter是默认触发键，不是Tab；Tab只在注释生成后用于跳字段 - 检查是否有插件劫持
Enter（比如 Emmet），可临时禁用其他插件测试 - 进
Preferences → Package Settings → DocBlockr → Settings – User，确认"auto_indent": true没被设成false
怎么让生成的注释带类型提示（比如 {string}）
默认不推类型，@param 后全是 {any}，得手动配或靠语言特性辅助。
- JavaScript/TypeScript 项目：启用
"jsdoc_enable_types": true（加到用户设置里），插件会尝试从参数名、JSDoc 已有类型或简单赋值中推测，但不保证 100% 准确 - Python：插件默认跳过
self，但不会跳cls；若想统一处理，需配合"jsdocs_autoadd_method_tag": true并自定义模板 - PHP：对
function test(string $name, int $age)这种带类型声明的，能直接提取出{string}和{int} - 最稳的方式：在用户设置里补全
"jsdoc_template"，例如添加"@param {string} ${1:name} ${2:description}"占位符，避免每次手敲
快捷键和模板定制怎么配才实用
默认操作够用，但稍加配置能省掉大量重复劳动。
- 快捷键绑定：打开
Preferences → Key Bindings，右侧加一行：{"keys": ["ctrl+alt+/"], "command": "docblockr"}，以后光标在函数上方直接按组合键 - 自动加作者/日期：在
Settings – User里加"author_tag": " * @author yourname <email>\n"</email>和"date_format": "%Y-%m-%d" - 加版权或版本信息：用
"custom_tags"数组，比如[" * @version 1.0.0", " * @copyright 2026 Your Co"] - 注意：所有自定义字段都必须以换行符
\n结尾，否则会挤在最后一行里
复杂点在于它完全依赖语法识别精度和光标上下文，不是“全局生效”的智能工具；容易被忽略的是右下角语法模式——哪怕你写的是 .js 文件，如果它显示 Plain Text，/** 就永远没反应。
