如何使用 JSDocs 描述具有默认值的可选 object 参数

Question

如果标题正确表达了我想做的事情，我不会。但是我有以下功能：

/**
 * @param {any} param1
 * How to describe the second parameter??
 * @returns {Object}
 */
function doSomething (param1, { property1 = null, property2 = null }){
  // do stuff
  return something
}

如评论中所问，使用 JSDocs，我将如何描述第二个参数？

Answer 1

可选参数可以放在[]方括号

/**
 * @param {any} param1
 * @param {Object} [param2]
 * 
 * @returns {Object}
 */
function doSomething (param1, { property1 = null, property2 = null }) {}

但是，我认为 param2 不能像那样是可选的和解构的。那不行。

Answer 2

默认值、可选参数等可以参考js doc官网。参考：https://jsdoc.app/tags-param.html#optional-parameters-and-default-values

寻找 Parameters with properties.

Answer 3

使用方括号[]表示可选参数。像这样：

/**
 * @param {any} param1
 * @param {Object} somethingWithProps - Some description
 * @param {string} [somethingWithProps.property1] - First property
 * @param {string} [somethingWithProps.property2] - Second property
 * @returns {Object}
 */
function doSomething (param1, { property1 = null, property2 = null }){
    // do stuff
    return something
}

来自文档： Optional parameters and Documenting a destructuring parameter

Answer 4

如果您正在为 Closure 编译器编写 JSDoc，您应该使用 = 来表示可选参数：

* @param {string=} property1

https://github.com/google/closure-compiler/wiki/Types-in-the-Closure-Type-System#optional

但对于对象属性，您可以使用具有 |undefined:

的记录类型

/** @param {{required:string, optional:(string|undefined)}} props */

https://github.com/google/closure-compiler/wiki/A-word-about-the-type-Object#records

Here's a version in the Closure Compiler API thingy

注意：我确实认为这可能是编译器中一个相对较新的功能，因此您的情况可能会有所不同。

如何使用 JSDocs 描述具有默认值的可选 object 参数

How to describe an optional object parameter with default values using JSDocs

javascript

jsdoc