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

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

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


javascript jsdoc webstorm
person Sebastian    schedule 15.04.2013    source источник

Ответы (3)


arrow_upward
32
arrow_downward

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

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

person lena    schedule 15.04.2013
comment
Спасибо, я только что узнал об этом из этой проблемы YouTrack и этот набор изменений компилятора закрытия. Есть ли поддержка для этого на уровне класса? Мои тесты показывают, что это работает только для параметров локального типа функции. - person Sebastian; 15.04.2013

arrow_upward
27
arrow_downward

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

В основном это работает для классов ES6:

/** @template T */
class Foo {
  /** @return {T} */
  get() { ... };

  /** @param {T} t */
  set(t) { ... };
}

... и так для кода до ES6:

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

и

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

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

WebStorm 7.0 не поддерживал эту функцию на момент написания исходного ответа, но по состоянию на сегодня (2019 г.) все IDE JetBrains правильно понимают этот синтаксис.

person Sebastian    schedule 11.10.2013

arrow_upward
0
arrow_downward

Следующий код отлично работает для меня в 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(){}
...
person SM Adnan    schedule 16.09.2014
comment
В приведенном выше примере он также работал с объектами Event и Thought. - person SM Adnan; 16.09.2014
comment
Да, в то же время многое из этого было реализовано в WS8, но все еще есть открытые проблемы, которые будут исправлены только в WS9 — см. мой ответ и связанные проблемы. - person Sebastian; 16.09.2014