一个函数的参数是对象的数组的JSDoc3文档？ [英] JSDoc3 documentation of a function's argument being an array of objects?

问题描述

UseJSDoc.org对 @type 页面说明如何记录数组和对象，而不是数组的对象的。我的函数接受对象具有属性的特定列表的数组，它的这些特性，我想记录。

UseJSDoc.org's page on @type explains how to document arrays and objects, but not arrays of objects. My function accepts an array of objects with a specific list of properties and it's these properties that I'd like to document.

该功能可能看起来像函数foo（人）和人阵列可能被呼叫者创建功能为

The function might look like function foo(people) and the people array might have been created by the caller of the function as

arr = [];
arr.push({name: "Alfred", profession: "Butler", hitpoints: 2});
arr.push({name: "Batman", profession: "Vigilante", hitpoints: 42});
// ...
foo(arr)

我想使用 {{名称：字符串，职业：字符串，生命值：数}}人语法来记录对象，但还包括一个概念，他们必须是在数组中。

I'd like to use the {{name: string, profession: string, hitpoints: number}} Person syntax to document the objects but also include a notion that they've got to be in an array.

请注意，底层的对象（我称之为人上面，虽然code将不参考任何作为）是不是一个合适的类，ISN 'T甚至任何地方命名。也不是一个单一的人中定义的任何地方，我使用的 @property 标记。

Note that the underlying object (what I call Person above, though the code will not refer to anything as that) isn't a proper class, isn't even named anywhere. Nor is a single "Person" defined anywhere for me to use the @property tag.

这困难记录这种code与JSDoc3的可能建议组织不力，我会高兴地考虑如何重新安排短暂的对象就是这样，主要用作哈希表（关联数组）的建议。

This difficulty in documenting this kind of code with JSDoc3 might suggest poor organization, and I'd happily consider advice on how to reorganize ephemeral objects like this, used mainly as hash tables (associative arrays).

推荐答案

下面两种方法可以做到这一点：

Here are two ways to do it:

/**
 * @param {Array.<{name: string, profession: string, hitpoints: number}>} people The people.
 */
function foo(people) {
}

/**
 * @typedef Person
 * @property {string} name
 * @property {string} profession
 * @property {number} hitpoints
 */

/**
 * @param {Array.<Person>} people The people.
 */
function foo2(people) {
}

请注意，你可以告诉jsdoc的事情实际上并不存在于你的code。 @typedef 是一个最好的例子。我还用 @class 记录了 @typedef 无法处理抽象的数据结构。我已经在文档中指出，这些都没有在JavaScript中code任何相应的类伪类。

Note that you can tell jsdoc about things that don't actually exist in your code. @typedef is a prime example. I've also used @class to document abstract data structures that @typedef cannot handle. I've noted in the documentation that these are pseudo-classes that do not have any corresponding "class" in the JavaScript code.

这篇关于一个函数的参数是对象的数组的JSDoc3文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！