在 JavaScript 中使用 JSDoc 为回调函数标注参数名称与类型，可提升公共 API 的可读性与 IDE 智能提示准确性；正确写法是用 (paramName:Type) 语法定义函数签名，而非 Function 或 Function(param:Type) 等无效形式。
在 javascript 中使用 jsdoc 为回调函数标注参数名称与类型，可提升公共 api 的可读性与 ide 智能提示准确性；正确写法是用 `(paramname:type)` 语法定义函数签名，而非 `function
JSDoc 支持通过 @param 标签直接描述回调函数的完整签名，其标准语法为：
@param {(paramName:ParamType, ...): ReturnType} paramName
例如，为监听滚动事件的回调明确声明其接收一个 Event 类型参数 ev，应写作：
/**
* Adds an event listener to track scroll events
* @param {(ev: Event) => void} callback - Called when scroll occurs; receives the native Event object.
*/
static addScrollListener(callback) {
Input.scrollListeners.push(callback);
}
✅ 正确要点：
- 使用
(ev: Event) => void显式声明函数签名（推荐箭头函数语法，语义清晰）； - 参数名（如
ev）和类型（如Event）之间用英文冒号:分隔； - 返回类型（如
void）不可省略，有助于类型推导与错误检查； - 可附加简短描述（如
- Called when...），增强可维护性。
❌ 常见错误写法及原因：
-
@param {Function→} callback Function是泛型构造器，不支持 -
@param {Function(ev:Event)} callback→Function(...)不是合法 JSDoc 类型表达式； -
@param {(Event)} callback→ 缺失参数名，IDE 无法准确提示参数含义。
⚠️ 注意事项：
- 若回调有多个参数，如
(ev: Event, target: HTMLElement)，需全部列出； - 在 TypeScript 项目中，此 JSDoc 注解可被 TS 编译器识别并参与类型检查（需启用
checkJs和JSDoc相关配置）； - VS Code、WebStorm 等主流编辑器均能基于该语法提供精准的参数提示与自动补全。
总结：为回调函数添加自文档化类型信息，核心在于使用 (param:Type) => Return 这一标准 JSDoc 函数类型语法——它既轻量、兼容原生 JS，又具备专业工具链支持，是公开库开发中不可或缺的实践规范。
