如果一些被解构而另一些没有被解构，如何记录函数的参数（JSDoc）

Posted 2023-03-15

【中文标题】如果一些被解构而另一些没有被解构，如何记录函数的参数（JSDoc）

【英文标题】：How to document a function's parameters if some are deconstructed while others are not (JSDoc)

【发布时间】：2021-11-03 07:28:18

【问题描述】：

How to document deconstructed parameters with JsDoc 解释了如果只有一个正在解构的参数，如何记录参数。

我有这个class 来创建自定义事件：

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;
    

所以我有一个可选的第三个参数，由于解构的限制，我无法命名。

我如何正确记录这一点？显示的 JSDoc 显然是不正确的。

【参考方案1】：

您以与嵌套属性相同的方式记录它们：

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

这是我将鼠标悬停在foo 上时 VS Code IntelliSense 显示的工具提示的屏幕截图：