JSDoc生成静态文档时柯里化函数触发解析错误，求排查

问题重现 #

你遇到的情况我之前也碰见过：代码本身能正常运行，但执行jsdoc命令生成静态文档时，只有柯里化函数的位置抛出大量解析错误。你的代码和注释如下：

/**
 * Responsible for fetch the data that will be loaded in the graph within the dialog
 * @param {function} dispatch redux dispatch function
 * @param {String} timeMode time mode used on metric page Example: 'Mensal'
 * @param {String} dialogType type of the dialog used to request de correct data and render the body Example: 'WARN_NETWORK_DRIVE'
 * @returns {(timeMode: String) => (dialogType: String) => Promise<void>}
 */
export const fetchGraphicData = dispatch => timeMode => async dialogType => {
  // ...function logic
}

原因分析 #

这大概率不是你的使用问题，而是JSDoc对ES6+柯里化箭头函数的解析兼容性局限：

• 早期版本的JSDoc类型解析器对多层嵌套箭头函数的类型标注支持不完善，虽然你的代码符合ES语法规范，但JSDoc无法正确识别这种嵌套结构的返回类型写法。
• 原注释里把后续柯里化函数的参数直接写在了fetchGraphicData的@param里，这种写法也会干扰JSDoc的解析逻辑，进一步触发报错。

可行解决方案 #

方案1：用@typedef预定义嵌套函数类型 #

先把多层函数的类型单独定义，再在@returns里引用，能大幅降低JSDoc的解析难度：

/**
 * @typedef {function(string): Promise<void>} DialogTypeHandler
 * @typedef {function(string): DialogTypeHandler} TimeModeHandler
 */

/**
 * Responsible for fetch the data that will be loaded in the graph within the dialog
 * @param {function} dispatch redux dispatch function
 * @returns {TimeModeHandler}
 */
export const fetchGraphicData = dispatch => timeMode => async dialogType => {
  // ...function logic
}

注：这里移除了原注释里的@param timeMode和@param dialogType，因为这两个参数属于后续返回的函数，不属于fetchGraphicData本身的入参，原写法会误导JSDoc解析。

方案2：升级JSDoc到最新稳定版 #

JSDoc在v3.6.7及以上版本中，优化了对ES6+箭头函数的解析支持，很多柯里化相关的解析Bug已经被修复。你可以通过以下命令升级：

npm install jsdoc@latest --save-dev

升级后重新运行jsdoc命令，大概率能直接解决问题。

方案3：用@callback定义回调类型 #

这种写法可读性更强，也更符合JSDoc的类型系统规范：

/**
 * @callback DialogTypeCallback
 * @param {string} dialogType
 * @returns {Promise<void>}
 */

/**
 * @callback TimeModeCallback
 * @param {string} timeMode
 * @returns {DialogTypeCallback}
 */

/**
 * Responsible for fetch the data that will be loaded in the graph within the dialog
 * @param {function} dispatch redux dispatch function
 * @returns {TimeModeCallback}
 */
export const fetchGraphicData = dispatch => timeMode => async dialogType => {
  // ...function logic
}

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