Support for destructuring in function parameters #178

When using destructuring in function parameters, the current spec of @PARAM is not enough.
For example, it's difficult to write a doc for the following function due to the mismatch between parameters and arguments.

function foo ([a, b], {x: {y: c}}) {
   return a + b + c;
}

foo([1, 2], {x: {y: 3}});  // => 6

This function requires an array as the first argument and an object as the second argument, and defines parameters a, b and c as number.

Here is a quick try to write a doc for the above function with the current spec.

/**
 * @param {Array<number>} array desc.
 * @param {Object} obj
 * @param {Object} obj.x
 * @param {number} obj.x.y desc.
 * @return {number} desc.
 */

But this docs has some problems such as:

• The parameters a, b, c are not described.
• Using dummy parameter names, array and obj, which are required due to the spec. (it says there must be the name of the documented parameter.)
• This doesn't provide information about the fact that the only top 2 elements of an array will be used.

For this kind of ES6-specific problems, it seems that JSDoc has no plan to deal with (providing an workaround or building a new syntax) currently.

• JSDoc for destructurings · Issue #987 · jsdoc3/jsdoc

So, I suggest introducing a few breaking changes into @arg and @PARAM:

• @arg: Stop treating it as an alias of @PARAM and let @arg describe arguments.

@arg {type} reference_name description.

• @PARAM: When using @PARAM along with @arg, @PARAM will indicate parameters referring @arg tags.

@param {type} parameter_name reference_expression description

As an example, the doc for the above function will be:

/**
 * @arg {Array<number>} ref1 desc.
 * @arg {{x: {y: number}}} ref2 desc.
 * @param {number} a ref1[0] desc.
 * @param {number} b ref1[1] desc.
 * @param {number} c ref2.x.y desc.
 * @return {number} desc.
 */

What do you think?