如何为解构函数参数定义可选函数类型的JSDoc及非函数默认值？

核心问题分析 #

你当前的问题出在：给可选参数func1设置了false作为默认值，但JSDoc仅标注了function类型，导致VSCode会根据默认值的类型将func1识别为布尔值。要解决这个问题，JSDoc必须明确标注联合类型，覆盖函数和布尔值两种情况。

正确的JSDoc写法与代码修正 #

需要把func1的类型标注为「目标函数类型 | boolean」，同时细化函数签名（比如你的场景里func1是接收数字、返回数字的函数），另外修正代码里的拼写错误（va1改为val1），并优化条件判断的严谨性：

/**
 * @description 执行特定数值计算逻辑的函数
 * @param {Object} params - 函数的参数对象
 * @param {number} [params.val1=0] - 参与计算的基础数值
 * @param {((num: number) => number)|boolean} [params.func1=false] - 可选的数值处理函数，未传入时默认值为false
 * @returns {number} 最终计算结果
 */
function f({ val1 = 0, func1 = false }) {
    if (val1 !== 0) {
        // 执行自定义逻辑
    }
    
    // 用typeof判断更严谨，避免函数本身返回假值时误判
    if (typeof func1 === 'function') {
        val1 += func1(val1);
    }
    return val1;
}

关键说明 #

1. 联合类型标注：((num: number) => number)|boolean明确告诉VSCode，func1要么是符合签名的函数，要么是布尔值false，解决类型识别混乱的问题。
2. 无需使用void：void通常用于标记无返回值的函数或无需传入的参数，这里用false作为默认占位，直接标注联合类型更贴合实际逻辑。
3. 严谨的条件判断：把if (func1)改成typeof func1 === 'function'，避免因函数本身返回假值、或其他意外情况导致的逻辑错误。

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