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

Question

根据JSDoc @param 的维基页面，您可以使用来指示@param是可选的。

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

你可以使用 行内 参数指示符。

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

我可以像下面这样组合它们，这样做可以正常运行。

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

但我想知道是否有一种可能的方式可以全部内联实现。

- studgeek

Answer 1

从官方文档中：

可选参数

一个名为foo的可选参数。

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

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

@param {number} [foo=1]

- czerny

---

我想知道如何内联操作。你提供的例子似乎与我在问题中展示的相同。 - studgeek

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) {}略微更具视觉吸引力。

- vvMINOvv

---

这些是有效的（并且在JSDoc帮助文档中有记录），但它们不是内联的，而这正是我正在寻找的。 - studgeek

问题是关于内联JSDoc符号的。这是有趣的信息，但并没有回答问题。 - Ken Bellows

Answer 3

我找到一种使用Google Closure Compiler的方式来实现这一点，即使用类型表达式。您可以在类型后面放置等号，如下所示：

function test(/**String=*/arg) {}

- studgeek

---

WebStorm/IntelliJ IDEA 支持这种表示法。 - Peter Aron Zentai

@PeterAronZentai，因为我提交了一个功能请求，所以我添加了WebStorm/IntelliIDEA的支持 :)。它们现在支持大部分Google Closure Compiler类型表达式，这非常不错。 - studgeek

对于可选的第二个参数，对我不起作用。 - DaveWalley

@studgeek 真是个牛人！ - Jacob

Answer 4

如果您正在使用函数参数的内联类型注释，而且想知道如何在该符号中标记函数参数为可选项，则我发现只需为可选参数分配默认值即可。但是如果您希望使用默认值为undefined，则必须显式地设置它，否则即使它在已经标记为可选的参数之前，该参数也不会被标记为可选项：

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

如果你在IDE中悬停在demo上，你应该会看到optional1和optional2现在都被标记为可选项了。在VSCode中，这通过参数名后面跟着一个?符号（TypeScript注解）来表示。如果你从optional2中移除= undefined，你将只会看到optional1被标记为可选项，这当然是不合理的，所以这里的默认值必须像我在上面的段落中所提到的那样显式地指定。

- Tomáš Hübelbauer

Answer 5

最完整的答案将来自官方 TypeScript 文档。

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

- MetaSeth

Answer 6

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

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

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

因此，在TS中，你必须使用外部的@param注释块。

- phil294