JSDoc: объединение (факультативно) @param и @type для геттера/инкубационных функциональных свойств

Question

-

Как можно использовать @param намек на дополнительных параметров для function, что является свойством (this.selectedPage()) , а также использование@type намекнуть на его тип возврата?

Возьмите это, например (this.selectedPage() может получить страницу, передавая параметр и вернуть один за другим не проходит ни один):

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

Тип-typehint красиво снимаемого с помощью интегрированной среды разработки и позволяет авто- завершение того факта, что this.selectedPage() дает Page.

Однако, пожалуйста, обратите внимание, что this.selectedPage() принимает параметр - а именно страницу. В противном случае IDE жалуется, что функция позволяет использовать 0 параметров при попытке передать один.

Так что я соединил два:

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

Это, кажется, остановить IDE от жалуясь при попытке передать параметр, но теперь он жалуется, когда не проходя один.

Я пробовал @type {function(undefined|Page): Page} безрезультатно.

Функция геттер/сеттер - так как можно сообщить докблоку, что @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(); 

Это именно то, что я хочу, чтобы: документация генераторов и Иды признают, что возвращаемое значение this.selectedPage() и любые предметы, выпущенные this.pages(), являются, по сути, типом Page, которые сами по себе обладают всеми признанными свойствами (начиная с Page тип тоже зарегистрирован таким образом).

Аналогичным образом, я считаю, что это обозначение также должно правильно документировать (необязательные) типы, которые могут передаваться как параметры.