如何使用内联 JSDoc 指示 param 是可选的？

根据用于 @ param的 JSDoc wiki，可以使用

/**
@param {String} [name]
*/
function getPerson(name) {
}

并且可以使用

function getPerson(/**String*/ name) {
}

我可以像下面这样把它们组合起来，这样就可以了。

/**
@param [name]
*/
function getPerson(/**String*/name) {
}

但是如果可能的话，我想知道是否有一种方法可以做到这一切。

80169 次浏览
小开
最佳答案

我找到了一种使用 Google Closure Compiler 类型表达式实现这一点的方法。在类型后面放一个等号，像这样: function test(/**String=*/arg) {}

小开

经过一番挖掘，我发现这些也没什么问题

/**
* @param {MyClass|undefined}
* @param {MyClass=}
* @param {String} [accessLevel="author"] The user accessLevel is optional.
* @param {String} [accessLevel] The user accessLevel is optional.
*/

只是在视觉上比 function test(/**String=*/arg) {}更吸引人

小开

来自 正式文件:

可选参数

一个名为 foo 的可选参数。

@param {number} [foo]
// or:
@param {number=} foo

默认值为1的可选参数 foo。

@param {number} [foo=1]
小开

如果您正在函数参数上使用内联类型注释，并且想知道如何在该注释中将函数参数标记为可选参数，那么我发现将默认值赋给可选参数是有效的。如果你想默认为 undefined，你必须显式地设置它，否则参数将不会被标记为可选的(即使它之前已经有可选的参数) :

function demo(
/** @type {String} */ mandatory,
/** @type {Number} */ optional1 = 0,
/** @type {Number} */ optional2 = undefined
)

如果在 IDE 中将鼠标悬停在 demo上，现在应该会看到 optional1和 optional2都显示为可选项。在参数名称后面由 ?指示的 VSCode 中(TypeScript 符号)。如果你从 optional2中移除 = undefined，你会看到只有 optional1是可选的，这当然是无意义的，所以这里的默认值必须是明确的，就像我在上面的段落中提到的。

小开

最完整的答案将来自 正式打字稿文件。

// Parameters may be declared in a variety of syntactic forms
/**
* @param {string}  p1 - A string param.
* @param {string=} p2 - An optional param (Google Closure syntax)
* @param {string} [p3] - Another optional param (JSDoc syntax).
* @param {string} [p4="test"] - An optional param with a default value
* @returns {string} This is the result
*/
小开

对于 TypeScript 对 JSDoc 的处理，这是不可能的: https://github.com/microsoft/TypeScript/issues/47653

虽然可以将参数标记为 @type { ... | undefined }，但其可选性不会改变，因为 所有参数是可选的。

标记可选性/非可选性的方法是将参数名放在括号中，但是在这个语法中没有参数名，所以只修改类型(而不是以你无法控制的方式修改可选性)是最直观的做法。

因此，对于 TS，您将使用 有来处理外部 @param注释块。


提交答案