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

Question

根据 @param 的 JSDoc wiki，您可以使用 @param 来指示 @param 是可选的

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

，并且您可以指示参数 内联 使用

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

我可以将它们组合起来，如下所示，效果很好。

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

但我想知道是否有一种方法可以在可能的情况下内联完成这一切。

Answer 1

来自官方文档：

可选参数

名为 foo 的可选参数。

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

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

@param {number} [foo=1]

Answer 2

经过一番挖掘后，我发现这些也还可以，

/**
 * @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) {} 在视觉上更具吸引力

Answer 3

我找到了一种使用 Google Closure Compiler 类型表达式。您可以在类型后面添加等号，如下所示：
函数测试(/**String=*/arg) {}

Answer 4

如果您在函数参数上使用内联类型注释，并且想知道如何在该表示法中将函数参数标记为可选，我发现只需为可选参数分配默认值就可以了。如果您希望默认值是未定义，您也必须显式设置它，否则参数将不会被标记为可选（即使它前面已经是可选参数）：

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

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

Answer 5

最完整的答案将来自 官方打字稿文档。

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

Answer 6

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

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

标记可选性/非可选性的方式是通过是否将参数名称放在括号中，但此语法中没有参数名称，因此仅修改类型（而不是同时以您可以的方式修改可选性） t 控制）是最直观的事情。

因此，对于 TS，您必须使用外部@param 注释块。