Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Document generic type parameters in JSDOC

In JSDoc there exists the possibility to document the exact types of array contents like this:

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

This makes code completion in IDEs like WebStorm actually provide the right type information after the [0].. This works well for the Array type, however I have my own collection types where I would like to make use of this feature, too. The problem is I cannot find the right syntax (maybe because there is none, yet). I would love to be able to declare my class somehow 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 feature does not work with my IDE and is not listed here, so I am wondering whether there is a syntax for this use-case, either for WebStorm or any other JS authoring tool.

like image 479
Sebastian Avatar asked Apr 15 '13 14:04

Sebastian


People also ask

Can you use JSDoc with TypeScript?

You can use most JSDoc type syntax and any TypeScript syntax, from the most basic like string to the most advanced, like conditional types.

What is the JSDoc keyword to specify an argument to a function?

The @param tag provides the name, type, and description of a function parameter. The @param tag requires you to specify the name of the parameter you are documenting.

How do you write comments in JSDoc?

JSDoc comments should generally be placed immediately before the code being documented. Each comment must start with a /** sequence in order to be recognized by the JSDoc parser. Comments beginning with /* , /*** , or more than 3 stars will be ignored.

What is JSDoc used for?

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating.


2 Answers

You can try using @template tag (undocumented tag used in Google Closure library - 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 type hinting - i.e. if we pass array of strings to goog.array.find in the sample above , IDE will know that return type is string, so string completion options will be suggested etc.

Not sure if this is what you are looking for... The post that looks related is here.

like image 173
lena Avatar answered Oct 09 '22 05:10

lena


In the meantime, support for this feature has been finalized and is now documented on the Closure Compiler JSDOC page for generics.

Basically it works like this for ES6 classes:

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

... and like this for pre-ES6 code:

/**  * @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 the original answer was written, but as of today (2019) all JetBrains IDEs understand this syntax, properly.

like image 25
Sebastian Avatar answered Oct 09 '22 06:10

Sebastian