Improve JSDoc support for destructured parameters

[shicks]

Currently it is very cumbersome to use destructuring for function parameters with more than a couple properties, particular if many are optional:

@param {{a: (number|undefined), b: (number|undefined), c: (number|undefined)}} param1

Note that the number= syntax does not work, and in fact leads to #1762.

Ideally we could write

/**
@param {number=} a
@param {number=} b
@param {number=} c
*/
function({a = 1, b = 2, c = 3} = {}) {}

[Dominator008]

@shicks That looks ambiguous, I guess? What's the difference between

/**
@param {number=} a
@param {number=} b
@param {number=} c
*/
function({a = 1, b = 2, c = 3} = {}) {}

and

/**
@param {number=} a
@param {number=} b
@param {number=} c
*/
function(a, b, c) {}

?

[MatrixFrog]

I agree. I'd like to see the = be supported someday, but I don't mind the verbosity other than that because it keeps things clear IMO.

[MatrixFrog]

The @param {{a: (number|undefined), b: (number|undefined), c: (number|undefined)}} param1 syntax is supported. Note that what Closure Compiler supports is pretty different from usejsdoc.org in general. From our official docs:

The Closure Compiler's type language derives from the annotations used by the JSDoc document-generation tool, though it has since diverged. It now includes several annotations that JSDoc does not support, and vice versa.

https://developers.google.com/closure/compiler/docs/js-for-compiler

[MatrixFrog]

Our "JSDoc" parser requires every param to have a name, so for destructuring params, we allow any name that's a valid JS identifier, even though that name won't appear in the (non-comment) JS code.

[peteblois]

I agree with the original syntax request- converting to destructured parameters is a common refactoring operation when the number of optional parameters grows but the loss of per-parameter documentation is a clear regression.

[teppeis]

FYI JSDoc 3 provides following syntax:

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

ref: #2584

[WillsB3]

I think I'm having the same problem here…

I'm converting a projects build chain to use Closure Compiler, and one of the sources in our application contains the following code which appears to be trying to use the official JSDoc syntax:

/**
 * Represents a dialog 
 * @constructor
 * @description Thin wrapper around material design components dialog.
 *
 * @param {Object} options
 *        Config object.
 * @param {HTMLElement} options.el
 *        Root element of dialog DOM
 * @param {NodeList=} option.triggers
 *        Trigger elements that can open the dialog.
 */
export default function Dialog(options) {
    …implementation…
}

I tried converting this to the Closure doc syntax as mentioned above:

/**
 * Represents a dialog
 * @constructor
 * @description Thin wrapper around material design components dialog.
 * @param {{el: (HTMLElement), triggers: (NodeList=)}} options
 */

However when compiling this I get the following warning:

WARNING - Bad type annotation. type not recognized due to syntax error. See https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler for more information.
 * @param {{el: (HTMLElement), triggers: (NodeList=)}} options

This appears to be down the the inclusion of the = after NodeList, which in my case is intended to represent that the triggers parameter is optional. If I remove the = the warning goes away... is that expected?

Is there an alternative way to document this, preferably so that I can keep the description of each parameter in the options object?