javascript 有没有办法在 JS 文档中定义泛型类型？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/18738023/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Is there a way to define generic types in JS documentation?
提问by Egor Nepomnyaschih
I'm looking for documentation generator for my JS library. I find JSDuckthe 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:
我正在为我的 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);
Sample output:
示例输出：
MyArray<T>
My perfect array class.
MyArray<T>
我完美的数组类。
BirdArray<T extends Bird> extends MyArray<T>
Please count birds using this awesome array class.
BirdArray<T extends Bird> extends MyArray<T>
请使用这个很棒的数组类来计算鸟类。
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.
有没有办法在 JSDuck 中实现这一点？如果没有，是否有一些 JS 文档生成器可以为我做到这一点？请假设它应该像 JSDuck 一样通用，以确保我能够使用任意类继承模式。
回答by Rene Saarsoo
Interestingly, Google Closure Compiler has support for generic types, with a syntax like this:
有趣的是，Google Closure Compiler支持泛型类型，语法如下：
/**
* @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 supportsClosure Compiler style type annotations, it should be already possible to write types like {MyClass.<T>}. JSDuck doesn't however uses a @template tagfor a different purpose altogether, but one implement its own custom tag like @typevaror override the builtin @templateto do your bidding using the custom tags system.
由于 JSDuck已经支持Closure Compiler 风格的类型注解，应该已经可以编写像{MyClass.<T>}. 然而，JSDuck 并没有将@template 标签用于完全不同的目的，而是实现自己的自定义标签，例如@typevar或覆盖内置标签@template以使用自定义标签系统进行出价。
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 Tand others. But it's easy to make JSDuck ignore certain types (or type variables) by using --external=T.
但是由于 JSDuck 中没有实际的泛型支持，它不会检查您的泛型类型。相反，它可能会抱怨您引用了未知类型T和其他类型。但是很容易通过使用 .jsduck 来让 JSDuck 忽略某些类型（或类型变量）--external=T。
One final note. The Closure Compiler doesn't support your extendssyntax in type variables, and I don't really see why would you write T extends Birdand then {MyArray<T>}, instead of just writing {MyArray<Bird>}.
最后一点。Closure Compiler 不支持您extends在类型变量中的语法，而且我真的不明白您为什么要编写T extends Birdand then {MyArray<T>}，而不是只编写{MyArray<Bird>}.
