DocBlockr 不自动识别类型签名，仅靠正则匹配参数名，无法解析 TypeScript/Python/PHP 的类型注解；需光标位于函数定义行开头才能正确插入注释，箭头函数需额外配置；自定义模板可为@param添加{type}占位符，但不支持跨语言统一。
DocBlockr 本身不自动为函数生成完整注释，它只在光标位于函数定义行时按 Tab 或 Enter 插入基础模板，参数/返回值需手动补全或依赖函数签名解析能力（且仅限部分语言）。
为什么 typed function signature 没被自动识别
DocBlockr 对 JavaScript、PHP、Python 等语言的函数签名解析能力有限：它不运行代码，也不读取类型注解（如 TypeScript 的 : string 或 Python 的 -> dict），仅靠正则粗略匹配形参名。若函数写法稍复杂（如解构参数、默认值带括号、多行声明），/** */ 按下后很可能只生成空 @param 行，或漏掉某些参数。
- JavaScript 示例中
function foo({ a, b }, [c, d] = [])→ DocBlockr 通常只识别出{ a, b }和[c, d]两个参数名，但不会拆解对象/数组结构 - Python 中
def bar(x: int, y: Optional[str] = None) -> List[dict]:→ DocBlockr 基本忽略所有类型提示，只提取x和y - PHP 7+ 的
function baz(string $s, array $data = []): ?int→ 能识别$s和$data，但返回类型?int不会转成@return int|null
如何让 @param/@return 出现在正确位置
DocBlockr 默认在函数定义行上方插入块注释，但若光标不在定义行开头（比如缩进后、或在函数名中间），可能插到错误位置，甚至触发错误补全。必须确保光标停在函数关键字（function、def、const 等）所在行的任意位置，且该行确实构成可识别的函数声明。
- ✅ 正确：光标在
function handleEvent(e) {这一行任意位置，按Tab - ❌ 错误：光标在
handleEvent函数体内部，或在export default function的default上，此时可能生成空块或报错No function signature found - ⚠️ 注意：ES6 箭头函数
const fn = (a, b) => {}不被 DocBlockr 原生支持，需额外配置jsdocs_extra_tags或改用const fn = function(a, b) {}
自定义模板让 @param 类型提示自动带冒号
DocBlockr 允许通过用户设置覆盖默认模板，比如让 JavaScript 的 @param 自动加 {string} 占位符。需修改 Preferences > Package Settings > DocBlockr > Settings – User，添加：
{
"jsdocs_indentation_spaces": 4,
"jsdocs_spacer_between_sections": true,
"jsdocs_extra_tags": [
["param", "{*} ${1:name} - ${0:description}"]
]
}
这样每次生成 @param 都会带 {*}，你只需把 * 改成实际类型（如 {string}），再 Tab 到下一项。但注意：这个改动对 Python/PHP 模板无效，它们各自用 pydocs_* / phpdocs_* 前缀配置。
真正省事的方式不是依赖自动识别，而是养成「先写签名，再按 Tab，最后补类型」的习惯——因为哪怕最聪明的插件，也猜不出你传进去的是 URLSearchParams 还是 FormData，更没法知道 @returns 是 resolve 一个 Promise 还是直接 throw error。
