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, Array).
• An object literal.

Solution 1

If you're looking for how to document the type of objects in an array, you want something like this:

/**
 * @param {String[]} aliases
 */

Here inside curly-braces the String[] is the parameter type: type String as array [].

See also jsdoc-toolkit, archived wiki page about @Param tag, Parameter Type Information:

Parameter Type Information

Use curly-braces around the expected type of the parameter to document this information.

/** * @param {String} userName */ function logIn(userName) { // ... }

Use a pipe symbol to document that multiple types are permitted.

/** * @param {String|Number} product */

Use the [] notation after a type to indicate an array of those types.

/** * @param {String[]} aliases */

Solution 2

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.

Solution 3

Although you may find that the guidance given in some of the other answers works for you, I prefer this syntax:

/**
 * @return {Array<String>} ...
 */

And in comparison to the guidance others have offered, I think this is closer to your expectation based on the example you give in your question.

Here's great source for information on JSDoc: https://wiki.servoy.com/display/DOCS/JSDoc+Annotations

Edit: fixed moved link - thanks @hc_dev for noticing

Solution 4

As per doco @returns

/** 
 * @returns {Array} Lines from the file.
 */
function readLines(filepath) {
}

Also see.

Solution 5

In the documentation for JSDoc on http://usejsdoc.org/ there is an example given for an array with members of type MyClass. There are two possibilities. One looks like this:

@param{MyClass[]}

The other one like this:

@param{Array.<MyClass>}

Be aware of the . between Array and <.

View more solutions