How to document array elements?

[brunano21]

Hi,
I have a function that takes an array of strings.
Something like:

function myFunc(args) {
    var a = args[0];
    var b = args[1];
}

But I want to specify what each element within the array represents.
How can I achieve that? I tried with something like:

/**
 * @param {String[]} args
 * @param {String}  args.0 - attribute name.
 * @param {String}  args.1 - value to set.
 */

But obviously this is wrong since they are interpreted as properties.
Of course, I also tried with args[0] but I get an error at jsdoc generation phase.
Finally, Google did not help this time. :/
Any suggestion?

[glumb]

Same question for me.

[IanVS]

I'm also wondering this. In my case, I have a typedef of an array, for which the first element has a particular significance and should always be a number. Any suggestions how to document this?

[ElfenLiedGH]

i'm using it

        /**
            @typedef AR_INNERJOIN
            @type {Set}
            @property {string} полеСвязи имя поля свзя, по которому осуществлять соединение, либо псевдоним при  отсутсвии поля связи в словаре
            @property {string} имяТаблицы имя таблицы, которую присоединяем ( при отсутсвии поля связи в словаре )
            @property {string} условие условие соединения, Пример t1.ROW_ID = t3.Счет
            @property {string} типСоединения по умолчанию LEFT JOIN, при необходимости можно указать просто JOIN, FULL JOIN  и т.д
            @property {string} неТребуетПолей если заполнено, то поля этого присоединения в SELECT не попадут
        */

        /**
         * набор внутренних присоединений к выборке
         * @type {AR_INNERJOIN}
         */
        this.внутренниеПрисоединения = new Set(); 

click AR_INNERJOIN

@typedef MyArray
@type {array}
@property {string} 0 - attribute name.
@property {string} 1 - value to set.

@param {MyArray}
function myFunc(args) {
    var a = args[0];
    var b = args[1];
}

[dandv]

/**
 * The `@returns` below was autogenerated by WebStorm:
 * @returns {Promise.<{f: [number,number], b: [string,string]}>}
 */
foo() {
  return Promise.resolve({
    f: [1, 2],
    b: ['bar', 'baz']
  })
}

Is this correct (but under-documented) JSDoc?

[hegemonic]

There's currently no way to document the expected type of individual array elements. The best you can do is the workarounds proposed by @brunano21 and @ElfenLiedGH. Or, of course, you can just use text:

/**
 * Foo function.
 *
 * @param {Array} bar - The bar array. The first element must be a number, and the
 * second element must be a string.
 */
function foo(bar) {}

I'm open to a pull request that supports something like the following example (inspired by WebStorm), but keep in mind that most of the work will involve modifying the Catharsis type-expression parser:

/**
 * Foo function.
 *
 * @param {[number, string]} bar - The bar array.
 */
function foo(bar) {}

[kenbellows]

Just wanted to probe this issue again. Has any progress been made on this issue?

For my two cents, the format generated (an presumably supported, though I haven't checked) by WebStorm makes a lot of sense to me, especially in return statements:

/**
 * Calculate the x and y coordinates of a point given a vector
 * @param {Vector} v
 * @returns [Number, Number]    x and y coords in pixels of the point indicated by the vector
 */
function getPointFromVector(v) {
    //...
}

[brettz9]

While it is not great DRY, one advantage of the @property {type} index - Description approach would be that a named label might be made allowable after the index to represent the item, e.g.:

/**
* @property {string} 0 type The type that...
* @property {string} 1 value The value which ...
*/

And if the list is long, the numeric indexes also do help one see at a glance what the number is without having to count commas....