JSDoc中的文档集合（类型数组）返回值和参数

Question

当数组元素可以是以下任何一个时，如何在JSDoc中记录Array返回值（和参数）：

• 类型（例如String ， Array ）。
• 对象字面量。

Answer 1

如果您正在寻找如何记录数组中对象的类型，您需要这样的东西：

 /**
  * @param {String[]} aliases
  */

http://code.google.com/p/jsdoc-toolkit/wiki/TagParam#Parameter_Type_Information

Answer 2

给出screenings参数：

screenings = [
    {
        timestamp: 1440157537,
        url: 'https://stackoverflow.com/a/22787287/1269037',
    },
    {
        timestamp: ...,
        url: ...,
    },
];

您可以通过以下三种方式之一来记录它：

使用@typedef ：

/**
 * @typedef {Object} screening
 * @property {Number} timestamp - UNIX timestamp.
 * @property {String} url - Booking URL.
 */

/**
 * @param {screening[]}
 */
function positionTimes (screenings) {}

当有多个函数使用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) {}

记录数组中值的属性 ：

/**
 * @param {Object[]} screenings
 * @param {Number} screenings[].timestamp - Unix timestamp.
 * @param {String} screenings[].url - Booking URL.
 */
function positionTimes (screenings) {}

这不适用于描述@return ed类型，因为返回值不带名称。

使用集合定义：

/**
 * @param {Array.<{timestamp: Number, url: String}>} screenings
 */
function positionTimes (screenings) {}

这种方法的一个优点是它是单行的，所以你可以在@return声明中使用它，其中第二种方法不起作用。

集合定义方法的缺点是它不允许描述属性值。

Answer 3

虽然您可能会发现某些其他答案中给出的指导对您有用，但我更喜欢这种语法：

/**
 * @return {Array<String>} ...
 */

与其他人提供的指导相比，我认为这更符合您在问题中给出的示例的期望。

以下是有关JSDoc的最佳信息来源： https ：//wiki.servoy.com/display/public/DOCS/JSDoc+Annotations

Answer 4

按照doco @returns

/** 
 * @returns {Array} Lines from the file.
 */
function readLines(filepath) {
}

另见 。

Answer 5

在http://usejsdoc.org/上的JSDoc文档中，给出了一个具有MyClass类型成员的数组的示例。 有两种可能性。 一个看起来像这样：

@param{MyClass[]}

另一个是这样的：

@param{Array.<MyClass>}

注意这个. 在Array和<之间。