Generic Document Type Options in JSDOC

Question

In JSDoc, it is possible to document the exact types of array contents as follows :

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

This makes code completion in the IDE, for example, WebStorm provides the correct type information after [0]. . This works well for the Array type, however I have my own collection types in which I would also like to use this function. The problem is that I cannot find the correct syntax (perhaps because it does not exist). I would really like to declare my class like this:

 /** * @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(){} 

This syntax or function does not work with my IDE and is not listed here , so I am wondering if the syntax for this use is -case, either for WebStorm, or for any other JS authoring tool.

Answer 1

In the meantime, support for this function has been completed and is now documented on the Closure compiler JSDOC page for generalizations .

This basically works like this for ES6 classes:

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

... and so for code before ES6:

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

and

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

WebStorm 7.0 did not support this feature at the time of writing the initial answer, but today (2019) all JetBrains IDEs correctly understand this syntax.

Answer 2

You can try using the @template tag (the undocumented tag used in the Google Closure library is an extremely limited form of generics). Something like:

 /** * 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 uses this tag for the hinting type - that is, if we pass an array of strings to goog.array.find in the example above, the IDE will know that the return type is a string, so options for ending the string, etc. will be suggested.

Not sure if this is what you are looking for ... A message that looks related is here .

Answer 3

The following code works fine for me in 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(){} ...