DocBlockr 是 Sublime Text 中开箱即用的注释自动生成插件，安装需先配置 Package Control，支持 JS/PHP 函数签名解析并生成结构化注释，但不识别解构参数和 TypeScript 类型注解。
DocBlockr 是 Sublime Text 中最稳定、开箱即用的注释自动生成器，不用配环境变量、不依赖外部工具，装完就能在 /** 回车后生成带 @param 和 @returns 的结构化注释。
安装 DocBlockr 前必须确保 Package Control 已就位
没有 Package Control，就无法安装任何插件。验证方式：按 Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS），弹出命令面板即说明已安装；若无反应，需先手动安装：
- 菜单栏打开 Tools → Install Package Control，等待提示“Installation successful”
- 重启 Sublime Text（部分版本需重启才生效）
- 再次调出命令面板，输入
Package Control: Install Package并回车
安装 DocBlockr 并验证是否生效
安装过程本身极快，但生效依赖文件类型识别：
- 输入
Package Control: Install Package→ 搜索DocBlockr→ 回车确认 - 新建一个
.js或.php文件（注意后缀），写一个函数，例如：function fetchData(url, timeout) { return Promise.resolve(); } - 在函数上方空行输入
/**，然后直接按Enter—— 如果看到自动展开的注释块，说明插件已工作 - 若无反应，检查右下角状态栏显示的语言模式是否为
JavaScript或PHP；不是则点击切换
自定义注释模板时容易忽略的两个关键点
修改 Preferences → Package Settings → DocBlockr → Settings - User 时，常见错误是格式错位或字段名拼错：
-
"jsdocs_extra_tags"是数组，每个元素必须是字符串，且以@开头，例如：["@author Alice", "@date {{date}}"] -
"jsdocs_function_description"设为false可禁用首行空描述行，避免生成冗余的*占位符 - 时间变量用
{{date}}（年月日）或{{datetime}}（含时分秒），不能写成{{now}}或${date}，否则留空 - 保存配置后无需重启，但已有打开的文件需重新触发一次
/**才会应用新模板
Tab 键跳转字段和参数识别的边界情况
DocBlockr 能自动提取函数签名中的参数名和类型，但只在特定语法下可靠：
- 支持
function name(a, b, c)、const fn = (x, y) => {}、method(p1, p2)（类内） - 不识别解构参数：
function foo({id, name})会被当成单个参数arg0 - 不解析 TypeScript 类型注解：
function bar(id: number)中的number不会填入@param类型字段 - 按
Tab可顺序聚焦到每个@param描述位置，但光标停在@returns后再按Tab会跳出注释块 —— 这是设计行为，不是 bug
真正麻烦的是多行参数或带默认值的函数，比如 function init(opts = {}, debug = false)，DocBlockr 会把 = {} 当作参数名一部分，需要手动删掉。这类细节不看源码很难意识到，但改起来就一行事。
