如何为带回调的Socket.io emit方法编写可被WebStorm识别的JSDoc标注

问题根源说明 #

你之前用@param不生效是因为@param仅用于标注函数声明的入参，不能直接作用于函数调用时的传入参数，Socket.io的emit方法默认是泛型无固定事件签名，所以IDE无法自动推导特定事件的参数类型。

可行的两种标注方案 #

写法1：内联标注（仅对当前单次调用生效，最快实现）

直接给入参与回调参数加内联JSDoc即可：

// 先给appversion变量标注类型（如果之前没有标注的话）
/** @type {string} */
const appversion = "你的应用版本号";

// 调用emit时给回调的入参加内联类型标注
_sock.emit('app_version', appversion, /** @param {string} response */ (response) => {
  console.log(response)
})

写法2：全局声明Socket事件映射（对所有同实例的调用生效，更规范）

如果你希望所有对_sock的emit调用都能自动识别对应事件的参数类型，可以提前给Socket实例声明事件类型映射：

/**
 * 自定义Socket事件签名映射
 * @typedef {Object} CustomSocketEvents
 * @property {(event: 'app_version', payload: string, callback: (res: string) => void) => void} emit
 * // 后续其他事件的签名也可以在这里扩展
 */

// 给Socket实例叠加自定义的事件类型
/** @type {import('socket.io-client').Socket & CustomSocketEvents} */
const _sock = io("你的服务端地址");

// 之后所有调用都会自动识别类型，不需要再单独标注
_sock.emit('app_version', appversion, (response) => {
  // 这里IDE会自动识别response为string类型
  console.log(response)
})

注意：如果WebStorm还是识别异常，可以重启IDE的索引服务（File > Invalidate Caches... 然后重启），确保类型解析生效。

内容的提问来源于stack exchange，提问作者Rudy Darmawan Kartono