Документация JSDoc3 аргумента функции, являющейся массивом объектов?

Question

Страница UseJSDoc.org на @type объясняет, как документировать массивы и объекты, но не массивы объектов. Моя функция принимает массив объектов с определенным списком свойств, и именно эти свойства я хотел бы задокументировать.

Функция может выглядеть так function foo(people) и people массив мог быть создан вызывающей функцией как

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

Я хотел бы использовать {{name: string, profession: string, hitpoints: number}} Person синтаксис для документирования объектов, но также включает понятие, что они должны быть в массиве.

Обратите внимание, что базовый объект (что я называю Person выше, хотя код не будет ссылаться ни на что как таковое) не является правильным классом, даже нигде не назван. Ни один "Personmsgstr "где-то для меня определено использовать тег @property.

Эта трудность при документировании такого рода кода с помощью JSDoc3 может указывать на плохую организацию, и я с удовольствием рассмотрю совет о том, как реорганизовать эфемерные объекты, подобные этому, используемые в основном в качестве хеш-таблиц (ассоциативных массивов).

Answer 1

Вот два способа сделать это:

/**
 * @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 о вещах, которые на самом деле не существуют в вашем коде. @typedef это яркий пример. Я также использовал @class документировать абстрактные структуры данных, которые @typedef не выдерживаю. Я отметил в документации, что это псевдоклассы, которые не имеют соответствующего "класса" в коде JavaScript.