如何在 JSDoc 中记录对象数组作为参数？答案

【问题标题】：How do you document an array of objects as a parameter in JSDoc?如何在 JSDoc 中记录对象数组作为参数？
【发布时间】：2020-10-10 02:27:26
【问题描述】：

我有一个如下所示的数组：

[{
    "name": "c917379",
    "email": "jim@bmw.de"

},
{
    "name": "c917389",
    "email": "jane@bmw.de"
}]

它是一个具有多个重复字段的任意长度数组（为了清楚起见，我将其简化为两个字段）。这被传递到 JavaScript 方法中。

/**
 * @param {?}  data
 */
update:  function(data) {...}

我想知道您将如何在 JSDoc 中记录这一点。 IE。您将如何记录问号所在的类型？

【问题讨论】：

JSON 是您将数据序列化为 JSON 文本时得到的结果。它只是 JavaScript 中的一个对象数组。
我知道。但我想知道您将如何在 JSDoc 中记录它。我知道 JSDoc 可以记录方法类型和匿名对象
我不明白你的编辑。 JSON 是数据结构的 javascript 表示。我认为您需要在问题中至少提及一次 JSON
您将 JSON 与对象文字混淆（一个常见错误）。 JSON 是一种类似于 XML 或 CSV 的数据格式。对象字面量是在 JavaScript 源代码中定义对象的特定语法结构。它们看起来相似，但完全不同。
Document collection (array of type) return value and parameter in JSDoc 的可能重复项

【解决方案1】：

在 JSDoc 中，给出了一个包含 MyClass 类型成员的数组的示例。它看起来像这样：

@param {Array.<MyClass>}

那么你也可以这样做：

@param {Array.<Object>}

然后这也是有道理的：

@param {Array.<{name:string, email:string}>}

【讨论】：

为什么这不是更高的投票？虽然尖括号有点怪，但感觉[]这个格式不太容易看出来。 尤其是当涉及到较长的情况时，例如{a: number, b: string, c}[]}。
@mliqu 尖括号代表一个泛型类型参数。这是一种非常常见的语法。 [] 已经由单词 Array 表示。您应该将 Array. 阅读为“SomeType 数组”，例如字符串数组，人员数组。
我同意@MichaelLiquori的观点，即这种语法比方括号@param {Array.<{name:string, email:string}>}的语法更容易阅读

【解决方案2】：

我刚刚找到了我的问题的答案：

看起来像这样：

/**
 *
 * @param {{name:string, email:string}[]}  
 *
 */

【讨论】：

【解决方案3】：

由于您的对象内容本质上没有什么“特殊”，我相信您只需将其声明为：

@param {Object[]} data

另一种方法是为您的“类”声明一个“适当的”构造函数，然后用该函数名替换Object。

这种封装也可能有助于代码的其他部分；-)

【讨论】：

这是一个 ajax 回调对象，所以即使我将它发送给构造函数，我也想记录我传入的类型。
啊，所以你没有机会先将“普通旧数据”中的对象按摩成更好的东西？
是的，我想先将它按摩到某个对象中，然后将其作为参数 {MYMassagedObjects[]}，但是重构 JS 是地狱，我认为他们不会让我做这样的改变.
@OliverWatkins 如果您碰巧使用 jQuery 和 .done 样式回调，那么 .then 方法是在将结果传递给原始回调之前预处理结果的便捷方法。
如果 PHPDoc 允许您记录这样的对象 @param {{a: number, b: string, c}} 而不是 @param {Object} 那么为什么不应该记录这样的数组：@param {{a: number, b: string, c}[]} 而不是 @param {Object[]}？

【解决方案4】：

由于这是出现在 Google 上的第一个问题，我认为这对展示如何记录二维数组很有用。

默认的sintax不起作用，它显示为'JsDoc sinxtax error'：

/**
 * @param {Object[][]} a two dimensional array of object
 * */

给二维数组发信号的正确方法是：

/**
 * @param {Array.<Array.<Object>>} a two dimensional array of object
 * */

【讨论】：