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

Question

如何使用 @param 来提示 可选 参数 function 即 属性 (this.selectedPage() ) 以及使用@type来提示它的return类型？

以此为例（this.selectedPage()传一个参数可以接收一个页面，none传一个参数return一个）：

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

type-typehint 被 IDE 很好地拾取并允许自动完成 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 - 那么如何告诉文档块 @param 是可选的？

Answer 1

是的，在阅读了各种网站上的 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() 的 return 值和 this.pages() 发出的任何项目实际上都是类型 Page 其自身的所有属性都已被识别（因为 Page 类型也以这种方式记录）。

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