Документирование параметров универсального типа в JSDOC

Question

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

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

Это делает завершение кода в IDE, таких как 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 и здесь не указан, поэтому мне интересно, есть ли синтаксис для этого варианта использования, либо для WebStorm, либо для любого другого инструмента разработки JS.

Answer 1

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

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

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

а также

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

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

К сожалению, на момент написания этой статьи WebStorm 7.0 пока не поддерживает эту функцию (проголосуйте за нее!).

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 будет знать, что возвращаемый тип является строкой, поэтому будут предложены варианты завершения строки и т. Д.

Не уверен, что это то, что вы ищете... Пост, который выглядит связанным, находится здесь.

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(){}
...