Question

我正在为我的JS库寻找文档生成器。我发现JSDuck是最全面和最强大的。但我没有看到使用其语法为泛型类和函数定义类型变量的方法。快速浏览流行的JS文档生成器让我觉得他们都没有能力做到这一点。这是我正在寻找的一个伪示例：

/**
 * @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);

示例输出：

MYARRAY＆LT; T＆GT;
我完美的阵列课程。

BirdArray＆lt; T extends Bird＆gt;延伸MyArray＆lt; T＆gt;
请使用这个很棒的数组类来计算鸟类。

有没有办法在JSDuck中实现这一目标？如果没有，是否有一些JS文档生成器可以为我做到这一点？请假设它应该像JSDuck一样通用，以确保我能够使用任意类继承模式。

Answer 1

有趣的是，Google Closure Compiler有support for generic types，语法如下：

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

作为JSDuck already supports Closure Compiler样式类型注释，应该已经可以编写类似{MyClass.<T>}的类型。但是，JSDuck并没有将@template tag用于完全不同的目的，而是使用@typevar实现自己的自定义标记，或覆盖内置@template以使用{{3}进行出价}。

但由于JSDuck中没有实际的泛型类型支持，因此它不会检查您的泛型类型。相反，它可能会抱怨你引用了一个未知类型T和其他类型。但是使用--external=T使JSDuck忽略某些类型（或类型变量）很容易。

最后一点说明。 Closure Compiler不支持类型变量中的extends语法，我真的不明白你为什么要写T extends Bird然后{MyArray<T>}，而不只是写{MyArray<Bird>} }。

有没有办法在JS文档中定义泛型类型？

1 个答案: