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

【问题标题】：JSDoc: combining (optional) @param and @type for getter/setter function-propertiesJSDoc：将（可选）@param 和 @type 组合为 getter/setter 函数属性
【发布时间】：2016-02-01 23:30:04
【问题描述】：

如何使用@param 来提示作为属性的function 的可选参数（this.selectedPage()）以及使用@type提示它的返回类型？

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

/**
 * @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 在尝试传递参数时抱怨，但现在它在 not 传递参数时抱怨。

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

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

【问题讨论】：

您是否有理由不使用@returns 作为返回类型？
因为它是一个属性，所以它不起作用。 IE。 @return 适用于 function(){}，但不适用于 this.func = func();。除非它应该并且是 IDE 的问题。

标签： javascript documentation jsdoc docblocks

【解决方案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() 的返回值以及 this.pages() 发出的任何项目实际上都是 Page 类型，它们本身具有所有它们的属性被识别（因为Page 类型也以这种方式记录）。

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

【讨论】：