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

【问题标题】：Document collection (array of type) return value and parameter in JSDocJSDoc中的文档集合（类型数组）返回值和参数
【发布时间】：2012-01-19 21:39:40
【问题描述】：

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

A 类型（例如String、Array）。
一个对象字面量。

【问题讨论】：

标签： javascript jsdoc

【解决方案1】：

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

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

花括号内的String[] 是参数类型：将String 键入为数组[]。

另见 jsdoc-toolkit，关于 @Param tag, Parameter Type Information 的存档 wiki 页面：

参数类型信息

在参数的预期类型周围使用花括号来记录此信息。

/** * @param {String} userName */ function logIn(userName) { // ... }

使用管道符号说明允许使用多种类型。

/** * @param {String|Number} product */

在类型后使用 [] 表示法来指示这些类型的数组。

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

【讨论】：

【解决方案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) {}

记录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) {}

这不适用于描述 @returned 类型，因为返回值没有名称。

使用集合定义：

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

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

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

【讨论】：

这正是我正在寻找的。非常感谢你帮我节省了很多时间。

【解决方案3】：

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

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

与其他人提供的指导相比，根据您在问题中提供的示例，我认为这更接近您的期望。

这里是 JSDoc 信息的重要来源： https://wiki.servoy.com/display/DOCS/JSDoc+Annotations

编辑：固定移动链接 - 感谢@hc_dev 的注意

【讨论】：

IntelliJ 语法高亮对此很满意 :)
但 Netbeans 不是，在荧光笔中给出“Array.,”。报告了一个错误。
arrays of objects with keys 呢？
您指向 Servoy 的 JSDoc 文章的链接已损坏：从他们的 Confluence 返回“404 Page Not Found”。

【解决方案4】：

根据 doco @returns

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

Also see.

【讨论】：

呵呵，没想到使用代码搜索。不幸的是它将关闭...谢谢！
我不知道他们为什么要删除它:(
此答案中的“另见”链接已失效。
@JonathanChan：这个答案真的很老，而且非常不完整。请选择another one。

【解决方案5】：

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

@param{MyClass[]}

另一个是这样的：

@param{Array.<MyClass>}

注意Array 和< 之间的.。

【讨论】：

使用@typedef:

记录properties of the values in an array:

使用集合定义：

使用`@typedef`: