javascript - JSDoc：将（可选）@param 和 @type 组合为 getter/setter 函数属性

Question

如何使用@param来提示作为属性 ( )的可选参数以及用于提示其返回类型？functionthis.selectedPage()@type

以这个为例（this.selectedPage()可以通过传递参数接收页面并通过传递无返回）：

/**
 * @type {function(): Page}
 */
this.selectedPage = ko.observable(data.page);

type-typehint 很好地被 IDE 接收，并允许自动完成this.selectedPage()产生Page.

但是，还请注意，它this.selectedPage()需要一个参数——即一个页面。否则 IDE 会抱怨该函数在尝试传递 1 时允许 0 参数。

所以我将两者结合起来：

/**
 * @type {function(Page): Page}
 */
this.selectedPage = ko.observable(data.page);

这似乎阻止了 IDE 在尝试传递参数时抱怨，但现在它在不传递参数时抱怨。

我试过@type {function(undefined|Page): Page}无济于事。

该函数是一个 getter/setter - 那么如何告诉 docblock @param 是可选的呢？

score 1 · Accepted Answer

是的，在阅读了各个网站上的 JSDoc 规范之后，我现在遇到了 Google 的 Closure Compiler 语法，它实现了我一直在尝试做的事情——IntelliJ/PHPStorm 也正确地采用了这一点。

本质上，可选参数可以以为后缀=：

/**
 * @type {function(Page=): Page}
 */
this.selectedPage = ko.observable(data.page);

或者更复杂的例子：

/**
 * @type {function(Array.<Page>=): Array.<Page>}
 */
this.pages = ko.observableArray();

这正是我想要的：文档生成器和 IDE 识别出的返回值this.selectedPage()和发出的任何项目this.pages()实际上是Page其所有属性都被识别的类型（因为Page类型也被记录在案）这边走）。

同样，我相信，这种表示法也应该正确记录可以作为参数传递的（可选）类型。

1 回答 1