7

I'm looking for documentation generator for my JS library. I find JSDuck the most comprehensive and powerful one. But I don't see a way to define type variables for generic classes and functions using its syntax. Quick look at popular JS documentation generators makes me feel that neither of them has a capability of doing that. 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);

Sample output:

MyArray<T>
My perfect array class.

BirdArray<T extends Bird> extends MyArray<T>
Please count birds using this awesome array class.

Is there a way of achieving that in JSDuck? If not, is there some JS documentation generator which can do that for me? Please assume that it should be as versatile as JSDuck, to make sure that I'll be able to use arbitrary class inheritance pattern.

Egor Nepomnyaschih
  • 932
  • 1
  • 8
  • 13

1 Answers1

5

Interestingly, Google Closure Compiler has support for generic types, with a 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());

As JSDuck already supports Closure Compiler style type annotations, it should be already possible to write types like {MyClass.<T>}. JSDuck doesn't however uses a @template tag for a different purpose altogether, but one implement its own custom tag like @typevar or override the builtin @template to do your bidding using the custom tags system.

But as there is no actual generic types support in JSDuck, it won't check your generic types. On the contrary, it will probably complain, that you're referencing an unknown type T and others. But it's easy to make JSDuck ignore certain types (or type variables) by using --external=T.

One final note. The Closure Compiler doesn't support your extends syntax in type variables, and I don't really see why would you write T extends Bird and then {MyArray<T>}, instead of just writing {MyArray<Bird>}.

Rene Saarsoo
  • 13,580
  • 8
  • 57
  • 85
  • Thank you for information. I won't go with custom tags, because generic types logic is pretty complicated in all programming languages. It can be a big project. Your suggestion about `--external=T` is very useful. – Egor Nepomnyaschih Sep 12 '13 at 12:13
  • 1
    The reason to write `BirdArray` is that you can define explicit `BirdArray` in this implementation instead of just abstract `BirdArray`. – Egor Nepomnyaschih Sep 12 '13 at 12:14