JSDoc:组合(可选)@param和@type用于getter / setter函数属性

时间:2016-02-01 23:30:04

标签: javascript documentation jsdoc docblocks

如何使用@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是可选的呢?

1 个答案:

答案 0 :(得分:0)

是的,在阅读了各种网站上的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类型也是这样记录的。)

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