How to document a function's parameters if some are deconstructed while others are not (JSDoc)

Question

How to document deconstructed parameters with JsDoc explains how to document params if there is only a single argument, which is being deconstructed.

I have this class to create custom events:

const EVENT_CONFIG_DEFAULTS = Object.freeze({
    bubbles: true,
    composed: true,
});
/**
 * class for all FW custom events
 */
export class FWEvent extends CustomEvent {
    #sourceEvent = null;
    #sourceElement = null;
    /**
     *
     * @param {string} name name of the event, see fw-events.js
     * @param {EventInit} eventInit event configuration
     * @param {Event} [sourceEvent] optional source event
     * @param {HTMLElement} [sourceElement] optional source element to circumvent event retargeting
     */
    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;
    }
}

So I have an optional third parameter which I cannot name due to limitations in destructuring.

How do I document this properly? The JSDoc shown obviously is incorrect.

score 1 · Accepted Answer · answered Sep 07 '21 at 08:32

You document them in the same way as you would for nested properties:

/**
 * @param {boolean} x
 * @param {boolean} y
 * @param {Object} [stuff]
 * @param {string} [stuff.bar]
 * @param {string} [stuff.baz]
 */
function foo(x, y, {bar, baz}) {

}

Here's a screenshot of the tooltip displayed by VS Code IntelliSense when I mouse over foo:

How to document a function's parameters if some are deconstructed while others are not (JSDoc)

1 Answers1