javascript JSDoc中的文档集合（类型数组）返回值和参数
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/8498975/
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 collection (array of type) return value and parameter in JSDoc
提问by Jonathan Chan
How to document Arrayreturn value (and parameters) in JSDoc when array elements can be either of the following:
Array当数组元素可以是以下之一时，如何在 JSDoc 中记录返回值（和参数）：
- A type (e.g.
String,Array). - An object literal.
- 一种类型（例如
String，Array）。 - 对象字面量。
回答by dmertl
If you're looking for how to document the type of objects in an array, you want something like this:
如果您正在寻找如何记录数组中对象的类型，您需要这样的东西：
/**
* @param {String[]} aliases
*/
http://code.google.com/p/jsdoc-toolkit/wiki/TagParam#Parameter_Type_Information
http://code.google.com/p/jsdoc-toolkit/wiki/TagParam#Parameter_Type_Information
回答by Gajus
Given a screeningsparameter:
给定一个screenings参数：
screenings = [
{
timestamp: 1440157537,
url: 'https://stackoverflow.com/a/22787287/1269037',
},
{
timestamp: ...,
url: ...,
},
];
You can document it one of the three ways:
您可以通过以下三种方式之一对其进行记录：
Using @typedef:
使用@typedef：
/**
* @typedef {Object} screening
* @property {Number} timestamp - UNIX timestamp.
* @property {String} url - Booking URL.
*/
/**
* @param {screening[]}
*/
function positionTimes (screenings) {}
When there are multiple functions that use a variation of the screeningobject, you can use a function namespace, e.g.
当有多个函数使用screening对象的变体时，您可以使用函数命名空间，例如
/**
* @typedef {Object} positionTimes~screening
* @property {Number} timestamp - UNIX timestamp.
* @property {String} url - Booking URL.
*/
/**
* @param {positionTimes~screening[]}
*/
function positionTimes (screenings) {}
/**
* @typedef {Object} filterTimes~screening
* @property {Number} timestamp - UNIX timestamp.
* @property {String} url - Booking URL.
*/
/**
* @param {filterTimes~screening[]}
*/
function filterTimes (screenings) {}
Documenting the properties of the values in an array:
记录数组中值的属性：
/**
* @param {Object[]} screenings
* @param {Number} screenings[].timestamp - Unix timestamp.
* @param {String} screenings[].url - Booking URL.
*/
function positionTimes (screenings) {}
This won't work for describing @returned types because the return value doesn't take a name.
这不适用于描述@returned 类型，因为返回值没有名称。
Using a collection definition:
使用集合定义：
/**
* @param {Array.<{timestamp: Number, url: String}>} screenings
*/
function positionTimes (screenings) {}
An advantage of this approach is that it's a one-liner so you can use it in @returndeclarations, where the second method won't work.
这种方法的一个优点是它是单行的，因此您可以在@return声明中使用它，而第二种方法不起作用。
The disadvantage of the collection definition approach is that it doesn't allow describing property values.
集合定义方法的缺点是它不允许描述属性值。
回答by SirLenz0rlot
Although you may find that the guidance given in some of the other answers works for you, I prefer this syntax:
尽管您可能会发现其他一些答案中给出的指导对您有用，但我更喜欢以下语法：
/**
* @return {Array<String>} ...
*/
And in comparison to the guidance others have offered, I think this is closer to your expectation based on the example you give in your question.
与其他人提供的指导相比，我认为根据您在问题中给出的示例，这更接近您的期望。
Here's great source for information on JSDoc: https://wiki.servoy.com/display/public/DOCS/JSDoc+Annotations
这是有关 JSDoc 的重要信息来源：https://wiki.servoy.com/display/public/DOCS/JSDoc+Annotations
回答by Seyeong Jeong
回答by Wilt
In the documentation for JSDocon http://usejsdoc.org/there is an example given for an array with members of type MyClass. There are two possibilities. One looks like this:
在该文档JSDoc上http://usejsdoc.org/有用于与类型的成员的阵列给出的例子MyClass。有两种可能。一个看起来像这样：
@param{MyClass[]}
The other one like this:
另一种是这样的：
@param{Array.<MyClass>}
Be aware of the .between Arrayand <.
须注意的.之间Array和<。
