JSDoc中重载函数的描述应放置在何处？

对于带@overload标注的函数，通用描述需要放在第一个@overload注释块的最顶部，而不是最后对应函数实现的注释块里——这就是你之前写法无法生效的原因。

正确示例：通用描述放在首个@overload块 #

/**
 * 这是foo函数的通用描述，所有重载形式都会继承该说明
 * @overload
 * @param {string} arg0
 * @return {void}
 *//**
 * @overload
 * @param {number} arg0
 * @param {number} arg1
 * @return {void}
 *//**
 * @param {string | number} arg0
 * @param {number} [arg1]
 */
function foo(arg0, arg1) {
  // ...
}

进阶：给特定重载添加专属描述 #

如果需要为某一个重载形式单独补充说明，可以在对应的@overload块内添加描述（或使用@description标签）：

/**
 * foo函数用于处理不同类型的参数组合
 * @overload
 * @description 仅接收单个字符串参数的重载形式
 * @param {string} arg0
 * @return {void}
 *//**
 * @overload
 * @description 接收两个数字参数的重载形式
 * @param {number} arg0
 * @param {number} arg1
 * @return {void}
 *//**
 * @param {string | number} arg0
 * @param {number} [arg1]
 */
function foo(arg0, arg1) {
  // ...
}

关键注意点 #

• 不要把通用描述放在最后对应函数实现的注释块中：重载场景下，JSDoc工具和代码编辑器会优先解析@overload块的信息，实现块的描述不会被关联到各个重载形式上，导致无法生效。
• 首个@overload块的顶部描述会作为所有重载的通用说明，后续@overload块的专属描述会补充该通用说明。

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