DocBlockr对复杂函数注释生成支持有限,因不解析AST而仅用正则匹配形参,遇解构、类型注解等即失效;需手动调优模板、明确光标位、补全部分字段。

DocBlockr 对复杂函数(解构参数、默认值、箭头函数、类型注解)的注释生成支持有限,不能靠默认配置“一键填全”,必须手动调优模板 + 明确光标位置 + 接受部分字段需手补。
为什么 /** + Enter 在复杂函数上只生成空 @param?
DocBlockr 不解析 AST,只用正则粗匹配形参名。遇到以下写法基本失效:
-
function foo({ id, name }, [a, b] = [1, 2])→ 只捕获{ id, name }和[a, b],不展开结构 -
const bar = (x: number, y?: string) => void→ TypeScript 类型和可选符全被忽略 -
export default function baz(...args: unknown[])→...args被当作文本,不识别为 rest 参数
它不是 bug,是设计限制:插件定位是“快速起手模板”,不是“类型感知文档生成器”。
怎么让 @param 至少带 {type} 占位符?
在 Preferences → Package Settings → DocBlockr → Settings - User 中添加模板覆盖项:
{
"jsdoc_template": [
"/**",
" * ${1:description}",
"${2: * @param {${3:any}} ${4:name} ${5:--}}",
"${6: * @return {${7:void}}}",
" */"
],
"jsdocs_spacer_between_sections": true,
"jsdocs_indentation_spaces": 2
}
关键点:
-
${3:any}是可跳转占位符,按 Tab 可快速改类型,比手打快 - 不要删掉
${2: * @param ...}前的${2:},否则整行失去焦点跳转能力 - 该模板对所有语言生效,但 PHP/Python 的类型声明仍不会自动填入,仅提供结构便利
箭头函数和导出函数怎么加注释?
原生 DocBlockr 不识别 const fn = (a, b) => {} 或 export function foo() 这类语法。可行方案只有两个:
- 改写为传统函数:把
const fn = (a, b) => {}临时改成function fn(a, b) {},加完注释再改回去 - 启用
jsdocs_extra_tags并配合自定义正则(高阶用法):在用户设置里加"jsdocs_extra_tags": ["export", "default"],但需搭配修改源码级正则,稳定性差,不推荐日常使用 - 接受现实:对箭头函数,直接在函数上方手敲
/** */,用 Tab 在${3:any}和${4:name}间跳转补全——这反而是最稳的方式
最易被忽略的一点:模板里写的 {${3:any}} 看似只是占位,但它决定了你后续编辑时 Tab 跳转的粒度。少一个 $ 编号,就少一次快速聚焦机会;多一层嵌套(比如试图自动展开解构),反而让模板不可维护。简单、可控、可跳转,才是复杂场景下的真实效率。











