如何使用JSDoc为React useCallback包裹的箭头函数编写注释？

@callback标签的设计用途是定义可复用的函数类型签名，通常用来声明作为参数传递的回调函数类型，并非给直接赋值的函数变量添加文档注释。当该标签被直接写在变量的注释块中时，VSCode内置的TypeScript语言服务无法将这段注释和floopPig变量做绑定，因此悬浮时不会显示注释内容。

直接把JSDoc注释块写在useCallback调用语句的正上方即可，不需要加@callback标签，和普通箭头函数的JSDoc写法完全一致，VSCode会自动把注释绑定到外层的floopPig变量：

/**
 * 激活指定猪的floop技能
 * @param {number} pigKey 每头猪对应的唯一标识key
 * @param {number} floopCost 激活技能所需消耗的魔法值
 * @returns {*} 猪技能激活后的返回结果
 * @throws {Error} 当前魔法点数不足时抛出错误，提示信息为"Not enough magic points"
 */
const floopPig = useCallback((pigKey, floopCost) => {
  const pigAbility = pigs[pigKey];
  if (pigAbility.floopCost < magicPoints) {
    return pigAbility.activate()
  } else {
    throw new Error('Not enough magic points');
  }
}, [pigs, magicPoints])

编写注意事项 #

• 注释块必须紧贴赋值语句上方，中间不能插入空行、其他代码，否则会导致注释绑定失效
• @returns、@throws标签为可选补充项，添加后可以获得更完整的类型提示和文档说明

当你需要定义一个可复用的函数类型，供多个位置的类型声明引用时，才需要使用@callback，示例如下：

/**
 * 猪floop技能激活处理函数的类型定义
 * @callback PigFloopHandler
 * @param {number} pigKey 猪的唯一标识key
 * @param {number} floopCost 技能消耗魔法值
 * @returns {*} 技能激活返回结果
 */

/**
 * 批量注册猪的floop技能处理器
 * @param {Record<number, PigFloopHandler>} handlerMap 猪key对应处理函数的映射表
 */
const registerFloopHandlers = (handlerMap) => {
  // 业务逻辑省略
}

内容的提问来源于stack exchange，提问作者AncientSwordRage