Document collection (array of type) return value a

问题:

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.

回答1:

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

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

http://code.google.com/p/jsdoc-toolkit/wiki/TagParam#Parameter_Type_Information

回答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.

回答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/public/DOCS/JSDoc+Annotations

回答4:

As per doco @returns

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

Also see.

回答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 <.