docblockr按tab无反应的根本原因是触发范围错误：仅在函数/类定义行上方空行或定义行开头才生效，变量、语句、注释中均不触发，且需检查快捷键是否被emmet等插件劫持。
DocBlockr 插件安装后为什么按 Tab 没反应？
根本原因通常是触发范围没对上：DocBlockr 只在函数、类、方法定义行上方的空行或紧贴定义行的位置，按 Tab 才会生成注释块。它不识别变量、普通语句或注释中间。
- 确保光标停在函数声明正上方的空行，或直接放在
function/def/class那一行的开头（如function foo() {） - JavaScript 中需写全
function关键字；箭头函数const foo = () => {}默认不触发，得手动输入/**再按Tab - Python 要求函数/类定义语法正确，且缩进无误；如果光标在
def foo():行末尾，Tab也能触发，但在行中任意位置可能失效 - 检查是否被其他插件劫持了
Tab快捷键（比如 Emmet），可在Preferences → Key Bindings搜索docblockr确认绑定是否存在
如何让 DocBlockr 生成符合 JSDoc / PHPDoc 规范的参数描述？
它默认能解析常见语言的函数签名，但依赖格式清晰、无歧义。参数名和类型必须显式可读，否则会漏掉或填错 @param。
- JavaScript 示例：
function getUser(id, options) {→ 会生成两个@param，但不会自动推断类型；若写成function getUser(/** @type {number} */ id, /** @type {Object} */ options) {，DocBlockr 仍只取变量名，类型得手补 - PHP 中
public function find($id, $with = [])会被识别为两个参数，$with = []的默认值不会自动转成@param array $with [optional]，需后续手动加 - Python 的
def process(data: list, timeout: int = 30)能提取data和timeout，但类型提示仅作参考，不会自动写进@param的{list}里，得自己补 - 想强制补全类型，可在生成后快速用
Ctrl+Shift+P→DocBlockr: Expand Abbreviation（部分版本支持），或直接敲@param后按Tab补默认模板
自定义模板时 docblockr.sublime-settings 哪些字段最常改？
多数人卡在改了设置不生效——因为 Sublime 的 package settings 加载优先级高，用户级配置必须放在 Preferences → Package Settings → DocBlockr → Settings – User，且不能有语法错误。
-
"jsdoc_extra_tags"：追加常用标签，比如加"@since": ""或"@deprecated": ""，避免每次手打 -
"jsdoc_indentation"：设为2或4控制注释内缩进，不匹配项目风格会导致 ESLint 报jsdoc/indent错误 -
"jsdoc_parse_param_description"：设为true后，它会尝试从函数体第一行注释（如// id: user ID string）提取参数说明，但准确率一般，慎开 - PHP/Python 模板单独用
"phpdoc_..."/"pydoc_..."前缀字段控制，混用 JS 设置无效
为什么生成的注释里 @return 总是 {void}？
DocBlockr 不分析函数体逻辑，只看语言层面的返回关键词是否存在。它看到 return 就写 @return，但类型全靠猜；没看到显式 return 就默认 void。
- JavaScript 中
function calc() { if (x) return 1; }会被判为可能无返回，仍标@return {void}；得手动改成@return {(number|undefined)} - PHP 的
function test() { return $this->data ?? null; }无法推断$this->data类型，@return留空或写@return mixed更稳妥 - Python 的
return语句若带类型注解（-> str:），DocBlockr 不读这个，所以@return字段仍为空，得补全 - 别依赖它填准
@return，把它当占位符，生成后立刻检查并修正类型——这是最容易被跳过、也最影响下游工具（如 TypeScript 生成、IDE 跳转）的一环
实际用起来，最常被忽略的是函数签名的“可解析性”：哪怕只多一个括号不匹配、少一个冒号，DocBlockr 就放弃推导，静默退化成空模板。与其反复调参数，不如先保证定义本身干净。
