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}}); // => 6This 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.
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?
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.
This function requires an array as the first argument and an object as the second argument, and defines parameters
a,bandcas number.Here is a quick try to write a doc for the above function with the current spec.
But this docs has some problems such as:
a,b,care not described.arrayandobj, which are required due to the spec. (it says there must be the name of the documented parameter.)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.
So, I suggest introducing a few breaking changes into @arg and @param:
As an example, the doc for the above function will be:
What do you think?