Answer by Gajus for Document collection (array of type) return value and parameter in JSDoc

Given a screenings parameter:

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

You can document it one of the three ways:

Using @typedef:

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

When there are multiple functions that use a variation of the screening object, you can use a function namespace, e.g.

/** * @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) {}

Documenting the 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) {}

This won't work for describing @returned types because the return value doesn't take a name.

Using a collection definition:

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

An advantage of this approach is that it's a one-liner so you can use it in @return declarations, where the second method won't work.

The disadvantage of the collection definition approach is that it doesn't allow describing property values.