How to document array destructured parameter in JSDoc

Question

Given the following code, how do I properly document that using the latest JSDoc?

function docMe([foo, bar = null, baz = 1]) { 
  /* */ 
}

I have tried this:

/**
 * @param {Array} options Array containing the options.
 * @param {HTMLElement} options[0].foo An HTML element.
 * @param {Object} [options[1].bar] An object.
 * @param {Number} [options[2].baz] A number.
 */

Obviously this didn't work, and all that the JSDoc documentation mentions is how to document a destructured object parameter, not a destructured array parameter.

Stephanystephen

Answer 1

As of this writing, there is an open issue for this in the Closure Compiler.

That thread produces 3 imperfect solutions:

1: @param for JSDocs3:

/**
 * Assign the project to an employee.
 * @param {Array} param1
 * @param {string} param1.foo
 * @param {*?} param1.bar
 * @param {number} param1.baz
 */
function docMe([foo, bar = null, baz = 1]) {
    // ...
};

2: Reported working in VSCode (I'm not a user so I couldn't confirm)

/**
 * @param {[foo, bar, baz]: [string, *, Number]} param1
 */
function docMe([foo, bar = null, baz = 1]) {
  // ...
}

3: For Closure compiler: Wait for the issue to be resolved and use that format. It is apparently pending a fix, and unblocked, so hopefully it's resolved soon.

Bessette