Document collection (array of type) return value and parameter in JSDoc

Question

How to document Array return value (and parameters) in JSDoc when array elements can be either of the following:

• A type (e.g. String,

Answer 1

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.