在 JavaScript 项目中使用 JSDoc 为回调函数声明参数类型，可提升代码可维护性与 IDE 智能提示准确性；正确写法是用 (paramName:Type) 语法标注回调签名，而非 Function 或 Function(param:Type) 等错误形式。
在 javascript 项目中使用 jsdoc 为回调函数声明参数类型，可提升代码可维护性与 ide 智能提示准确性；正确写法是用 `(paramname:type)` 语法标注回调签名，而非 `function
JSDoc 支持通过 @param 标签为函数参数提供类型信息，当参数本身是一个函数（如回调）时，需使用函数类型字面量（function type literal） 显式声明其签名。标准格式为：
@param {(paramName:ParamType, ...rest:RestType[]) => ReturnType} paramName
或更简洁的无返回值形式（常见于事件监听器）：
@param {(ev:Event) => void} callback
✅ 正确示例：
/**
* 添加滚动事件监听器
* @param {(ev: Event) => void} callback - 触发时传入原生 Event 对象的回调函数
*/
static addScrollListener(callback) {
Input.scrollListeners.push(callback);
}
⚠️ 常见错误及说明：
-
@param {Function→ ❌ JSDoc 不识别泛型化} Function语法，会被解析为any； -
@param {Function(ev:Event)}→ ❌Function(...)不是合法 JSDoc 类型表达式，解析失败； -
@param {void→ ❌} void无意义，且非标准类型语法。
? 进阶建议：
- 若回调有多个参数，可完整写出：
@param {(x: number, y: number, e: MouseEvent) => boolean} handler - 支持可选参数与剩余参数：
(ev: Event, ...args: string[]) - 配合 TypeScript 项目时，JSDoc 类型注解可被 TS 编译器识别，实现跨工具链的类型保障。
最终效果：VS Code、WebStorm 等主流编辑器将准确推导 callback 的形参名、类型与调用签名，大幅提升公共 API 的可用性与协作效率。
