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

问题:

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.} 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} ...  */ 

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.} 

Be aware of the . between Array and .

文章来源: Document collection (array of type) return value and parameter in JSDoc