javascript 在 JSDOC 中记录泛型类型参数
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/16017627/
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
Document generic type parameters in JSDOC
提问by Sebastian
In JSDocthere 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:
这使得像 WebStorm 这样的 IDE 中的代码完成实际上在[0].. 这适用于 Array 类型，但是我有自己的集合类型，我也想在其中使用此功能。问题是我找不到正确的语法（可能是因为还没有）。我希望能够像这样以某种方式声明我的班级：
/**
* @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.
此语法或功能不适用于我的 IDE，也未在此处列出，因此我想知道是否有适用于 WebStorm 或任何其他 JS 创作工具的此用例的语法。
采纳答案by Sebastian
In the meantime, support for this feature has been finalized and is now documented on the Closure Compiler JSDOC page for generics.
与此同时，对这个特性的支持已经完成，现在记录在泛型的闭包编译器 JSDOC 页面上。
Basically it works like this for ES6 classes:
基本上它对于 ES6 类是这样工作的：
/** @template T */
class Foo {
/** @return {T} */
get() { ... };
/** @param {T} t */
set(t) { ... };
}
... and like this for pre-ES6 code:
...对于 ES6 之前的代码，就像这样：
/**
* @constructor
* @template T
*/
Foo = function() { ... };
and
和
/** @return {T} */
Foo.prototype.get = function() { ... };
/** @param {T} t */
Foo.prototype.set = function(t) { ... };
WebStorm 7.0 did notsupport this feature at the time the original answer was written, but as of today (2019) all JetBrains IDEs understand this syntax, properly.
在编写原始答案时，WebStorm 7.0不支持此功能，但截至今天（2019 年），所有 JetBrains IDE 都正确理解此语法。
回答by lena
You can try using @templatetag (undocumented tag used in Google Closure library - extremely limited form of generics). Something like:
您可以尝试使用@template标签（Google Closure 库中使用的未记录标签 - 泛型的极其有限的形式）。就像是：
/**
* 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.
WebStorm 使用此标记进行类型提示 - 即如果我们在上面的示例中将字符串数组传递给 goog.array.find，IDE 将知道返回类型是字符串，因此将建议字符串完成选项等。
Not sure if this is what you are looking for... The post that looks related is here.
不确定这是否是您要查找的内容...看起来相关的帖子在这里。
回答by SM Adnan
The following code works fine for me in WebStorm 8.
以下代码在 WebStorm 8 中对我来说很好用。
/** @type {Array.<MyPair.<Event, Array.<Thought>>>} */
scope.pairs = [];
/**
* @template TFirst, TSecond
*/
function MyPair(first, second){
this.first = first;
this.second = second;
}
/** @type {TFirst} */
MyPair.prototype.first = null;
/** @type {TSecond} */
MyPair.prototype.second = null;
...
function Event(){}
...
...
function Thought(){}
...
