JSDoc如何同时为普通参数和未命名解构参数编写规范文档

解决方案 #

对于这种包含普通参数+未命名可选解构参数的场景，你可以在JSDoc中为解构的外层对象定义一个虚拟参数名（该名称仅用于文档标注，不影响实际代码逻辑），再通过@property声明解构内部的属性即可，同时要注意实际代码中需要给解构参数加默认空对象，避免不传该参数时运行报错。

修改后的完整代码如下：

const EVENT_CONFIG_DEFAULTS = Object.freeze({
    bubbles: true,
    composed: true,
});
/**
 * 所有FW自定义事件的基类
 */
export class FWEvent extends CustomEvent {
    #sourceEvent = null;
    #sourceElement = null;
    /**
     * @param {string} name 事件名称，参考fw-events.js
     * @param {EventInit} eventInit 事件配置
     * @param {Object} [extraOptions] 额外可选配置项
     * @param {Event} [extraOptions.sourceEvent] 可选源事件
     * @param {HTMLElement} [extraOptions.sourceElement] 可选源元素，用于规避事件重定向
     */
    constructor(name, eventInit, { sourceEvent, sourceElement } = {}) {
        super(name, { ...EVENT_CONFIG_DEFAULTS, ...eventInit });

        this.#sourceEvent = sourceEvent || null;
        this.#sourceElement = sourceElement || null;
    }

    get sourceEvent() {
        return this.#sourceEvent;
    }

    get sourceElement() {
        return this.#sourceElement;
    }
}

标注说明 #

• 外层的@param {Object} [extraOptions] 声明了第三个参数是可选的对象类型，extraOptions是自定义的虚拟参数名，可替换为任意符合语义的名称
• 内部属性通过[虚拟参数名.属性名]的格式声明，和普通对象属性的JSDoc标注规则完全一致，主流IDE均可正常识别并给出智能提示
• 实际代码中补充的= {}默认值是必须的，否则调用时如果不传入第三个参数，JS会尝试对undefined做解构，直接抛出类型错误

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