Documenting an array of objects as a parameter of callback function in JSDoc

Question

callback.rows is array of arbitrary length with a number of repeating fields.

How can I document each field (type, property, description) in JSDoc?

Is there possible to apply this method?

Or may be this solution can be accepted:

/**
* Get list of all documents
* @param {Function} callback                      Standard callback function
* @param {Error}    callback.err                  Error object if any
* @param {Array}    callback.rows                 Rows list
* @param {String}   callback.rows[0].field1       field1
*/
var myFunc = function (callback) {
   // Function body
}

Answer 1

Try:

/**@param {string[]} callback.rows*/

Note that you can put any type there, not just string... Such as

/**@param {{field1: string}[]} callback.rows */

Answer 2

As I mentioned the best documentation for your code is unit tests.

In JSDoc should be only main parameters documented. I.e. callback is Function. The last 3 lines should be moved into your unit test.

This art of documentation is more maintainable and provable.

Extensive JSDocs are hard to read and maintain. Not all behavior can be documented.

Not all people can correct understand this documentation. Some people will try to change documentation on your own flavor.