在 JavaScript 项目中使用 JSDoc 为回调函数声明参数类型，可提升代码可维护性与 IDE 智能提示准确性；正确写法是用 (paramName:Type) 语法标注回调签名，而非 Function 或 Function(param:Type) 等错误形式。

在 javascript 项目中使用 jsdoc 为回调函数声明参数类型，可提升代码可维护性与 ide 智能提示准确性；正确写法是用 `(paramname:type)` 语法标注回调签名，而非 `function` 或 `function(param:type)` 等错误形式。

JSDoc 支持通过 @param 标签为函数参数提供类型信息，当参数本身是一个函数（如回调）时，需使用函数类型字面量（function type literal） 显式声明其签名。标准格式为：

@param {(paramName:ParamType, ...rest:RestType[]) => ReturnType} paramName

或更简洁的无返回值形式（常见于事件监听器）：

@param {(ev:Event) => void} callback

✅ 正确示例：

Expanso json-flatten

通过 CLI 或 MCP 服务器，使用 Expanso Edge 管道扁平化嵌套 JSON 对象。

下载

/**
 * 添加滚动事件监听器
 * @param {(ev: Event) => void} callback - 触发时传入原生 Event 对象的回调函数
 */
static addScrollListener(callback) {
    Input.scrollListeners.push(callback);
}

⚠️ 常见错误及说明：

• @param {Function<event>}</event> → ❌ JSDoc 不识别泛型化 Function<t></t> 语法，会被解析为 any；
• @param {Function(ev:Event)} → ❌ Function(...) 不是合法 JSDoc 类型表达式，解析失败；
• @param {void<event>}</event> → ❌ void<t></t> 无意义，且非标准类型语法。

? 进阶建议：

• 若回调有多个参数，可完整写出：@param {(x: number, y: number, e: MouseEvent) => boolean} handler
• 支持可选参数与剩余参数：(ev: Event, ...args: string[])
• 配合 TypeScript 项目时，JSDoc 类型注解可被 TS 编译器识别，实现跨工具链的类型保障。

最终效果：VS Code、WebStorm 等主流编辑器将准确推导 callback 的形参名、类型与调用签名，大幅提升公共 API 的可用性与协作效率。