документа в JSDoc

Question

В JSDoc существует возможность документировать точные типы содержимого массива like this:

/** @param {Array.<MyClass>} myClasses An array of MyClass objects. */ 
TestClass.protoype.someMethod = function(myClasses){ 
    myClasses[0].aMethodOnMyClass(); 
} 

Это делает код завершение в Иде как WebStorm фактически предоставляет информацию правильного типа после [0].. Это хорошо работает для типа Array, однако у меня есть свои собственные типы коллекций, в которых я также хотел бы использовать эту функцию. Проблема в том, что я не могу найти правильный синтаксис (возможно, потому что его нет). Я хотел бы, чтобы иметь возможность объявить свой класс как-то вроде этого:

/** 
* @typeparam {T} the type parameter 
* @constructor {Test2.<T>} 
* */ 
Test2 = function(){}; 

/** 
* @returns {T} a value of type T, where T is the generic type parameter of Test2 
*/ 
Test2.prototype.getGenericValue = function(){} 

Этот синтаксис или функция не работает с моей IDE и не указано here, поэтому мне интересно, есть ли синтаксис этой полезности либо для WebStorm, либо для любого другого инструмента создания JS.

Answer 1

Тем временем поддержка этой функции была завершена и теперь задокументирована на the Closure Compiler JSDOC page.

В основном это так:

/** 
* @constructor 
* @template T 
*/ 
Foo = function() { ... }; 

и

/** @return {T} */ 
Foo.prototype.get = function() { ... }; 

/** @param {T} t */ 
Foo.prototype.set = function(t) { ... }; 

К сожалению, на момент написания, WebStorm 7.0 does not support this feature (Vote for it!), пока.

Answer 2

Вы можете попробовать использовать тег @template (недокументированный тег, используемый в библиотеке Google Closure - крайне ограниченная форма дженериков). Что-то вроде:

/** 
* Search an array for the first element that satisfies a given condition and 
* return that element. 
* @param {Array.<T>|goog.array.ArrayLike} arr Array or array 
*  like object over which to iterate. 
* @param {?function(this:S, T, number, ?) : boolean} f The function to call 
*  for every element. This function takes 3 arguments (the element, the 
*  index and the array) and should return a boolean. 
* @param {S=} opt_obj An optional "this" context for the function. 
* @return {T} The first array element that passes the test, or null if no 
*  element is found. 
* @template T,S 
*/ 
goog.array.find = function(arr, f, opt_obj) {  
    var i = goog.array.findIndex(arr, f, opt_obj);  
    return i < 0 ? null : goog.isString(arr) ? arr.charAt(i) : arr[i]; 
}; 

WebStorm использует этот тег для типа намекая, - то есть, если мы передаем массив строк в goog.array.find в приведенном выше примере, IDE будет знать, что тип возвращаемого значения строки, поэтому варианты завершения строки будет и т.д.

Не уверен, что это то, что вы ищете ... Сообщение, которое выглядит связанным, это here.

Answer 3

Следующий код работает отлично для меня в WebStorm 8.

/** @type {Array.<MyPair.<Event, Array.<Thought>>>} */ 
scope.pairs = []; 

/** 
* @template TFirst, TSecond 
*/ 
function MyPair(first, second){ 
    this.first = first; 
    this.second = second; 
} 
/** @type {TFirst} */ 
MyPair.prototype.first = null; 
/** @type {TSecond} */ 
MyPair.prototype.second = null; 

... 
function Event(){} 
... 
... 
function Thought(){} 
...