如何使用 JSDocs 描述具有默认值的可选对象参数答案

【问题标题】：How to describe an optional object parameter with default values using JSDocs如何使用 JSDocs 描述具有默认值的可选对象参数
【发布时间】：2019-11-16 01:12:56
【问题描述】：

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

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

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

【问题讨论】：

标签： javascript jsdoc

【解决方案1】：

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

/**
 * @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 和 Documenting a destructuring parameter

【讨论】：

【解决方案2】：

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

寻找Parameters with properties。

【讨论】：

【解决方案3】：

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

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

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

【讨论】：

【解决方案4】：

如果你正在为 Closure Compiler 编写 JSDocs，你应该使用 = 来表示可选参数：

* @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

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

【讨论】：