JSDoc：组合（可选）@param和@type用于getter / setter函数属性

Question

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

以此为例（this.selectedPage()可以通过传递参数来接收页面，并通过传递无法返回一个页面：

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

IDE可以很好地获取type-typehint，并允许自动完成this.selectedPage()产生Page的事实。

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

所以我将两者结合起来：

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

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

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

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

Answer 1

是的，在阅读了各种网站上的JSDoc规范之后，我现在遇到了Google的Closure Compiler语法，它实现了我一直在尝试做的事情 - 这也是IntelliJ / PHPStorm正确选择的。 / p>

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

/**
 * @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类型也是这样记录的。）

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