如何用JSDoc官方方式为函数类型参数的参数编写文档？

当然有啦！JSDoc本身就提供了官方的语法来给函数类型参数的内部参数写文档，而且有两种常用的方式，看你的需求来选：

方式一：直接在@param标签中定义函数类型细节 #

这种方式适合回调逻辑比较简单、不需要复用的场景，直接在@param的类型部分写明函数的参数和返回值，再在描述里拆分每个内部参数的说明：

/**
 * 执行指定操作并触发回调函数
 * @param {function(string, number): boolean} fn - 处理操作结果的回调函数：
 *   - 第一个参数：`message`（字符串类型）- 操作返回的状态消息
 *   - 第二个参数：`statusCode`（数字类型）- 操作的状态码
 *   - 返回值：布尔类型，表示回调处理是否成功
 */
function doSomething(fn) {
  // 函数内部逻辑，调用传入的回调
  fn("操作执行完毕", 200);
}

方式二：用@callback定义可复用的回调类型 #

如果这个回调类型会在多个地方用到，或者内部参数的说明比较复杂，推荐先通过@callback单独定义一个回调类型，再在@param里引用它，这样文档结构更清晰、也更易维护：

/**
 * 操作结果处理回调的类型定义
 * @callback ResultHandler
 * @param {string} message - 操作返回的状态消息
 * @param {number} statusCode - 操作的状态码
 * @returns {boolean} 返回布尔值表示处理是否成功
 */

/**
 * 执行指定操作并触发回调函数
 * @param {ResultHandler} fn - 用于处理操作结果的回调函数，遵循ResultHandler类型定义
 */
function doSomething(fn) {
  fn("操作执行完毕", 200);
}

这两种写法都是JSDoc官方认可的标准语法，主流IDE（比如VS Code）都能识别并给出准确的代码提示，完全能满足你记录函数类型参数内部参数的需求。

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