Is there a way to define generic types in the JS documentation?

Question

I am looking for a documentation generator for my JS library. I consider JSDuck the most complete and powerful. But I see no way to define type variables for common classes and functions using its syntax. A quick look at the popular JS documentation generators makes me feel like they have no way to do this. Here is a pseudo example of what I'm looking for:

/** * @class MyArray * My perfect array class. * @typevar T */ MyArray = function() ... /** * @class BirdArray * Please count birds using this awesome array class. * @typevar T extends {Bird} * @extends {MyArray<T>} */ BirdArray = function() ... extend(BirdArray, MyArray); 

Output Example:

MyArray <T>
My perfect array class.

BirdArray <T extends Bird > extends MyArray <T>

Please count the birds using this class of classroom class.

Is there any way to achieve this in JSDuck? If not, is there any JS documentation generator that can do this for me? Suppose it should be as universal as JSDuck to make sure that I can use an arbitrary inheritance class.

Answer 1

Interestingly, the Google Closure Compiler supports generic types with syntax like this:

 /** * @constructor * @template T */ Foo = function() { ... }; /** @return {T} */ Foo.prototype.get = function() { ... }; /** @param {T} t */ Foo.prototype.set = function(t) { ... }; /** @type {!Foo.<string>} */ var foo = new Foo(); var foo = /** @type {!Foo.<string>} */ (new Foo()); 

Because JSDuck already supports Annotations of the Closure Compiler type, you can now write types like {MyClass.<T>} . However, JSDuck does not use the @ tag for another purpose, but one implements its own tag as @typevar or overrides the built-in @template to fulfill your bids using a custom tag system .

But since there is no support for generic generic types in JSDuck, it will not check your generic types. On the contrary, he will probably complain that you are referring to an unknown type T and others. But it's easy to get JSDuck to ignore specific types (or type variables) with --external=T

Last remark. The Closure compiler does not support your extends syntax in type variables, and I really don’t understand why you write T extends Bird and then {MyArray<T>} instead of just writing {MyArray<Bird>} .