Support for destructuring in function parameters #178

Closed
nodaguti opened this Issue Nov 23, 2015 · 5 comments

Comments

Projects
None yet
2 participants
@nodaguti

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.

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 {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?

@nodaguti

This comment has been minimized.

Show comment
Hide comment
@nodaguti

nodaguti Nov 23, 2015

Sorry, ESDoc already supports object destructuring ...

Sorry, ESDoc already supports object destructuring ...

@nodaguti nodaguti closed this Nov 23, 2015

@nodaguti

This comment has been minimized.

Show comment
Hide comment
@nodaguti

nodaguti Nov 23, 2015

Array destructuring in function parameters is somewhat broken?

warning: signature mismatch: Foo#foo src/test.js#2
1| /**
2|  * @param {Array<number>} coord hoge
3|  * @param {{x: {y: number}}} opts fuga
4|  * @return {number} desc.
5|  */
6| foo([a, b], {x: {y: c}}) {

Array destructuring in function parameters is somewhat broken?

warning: signature mismatch: Foo#foo src/test.js#2
1| /**
2|  * @param {Array<number>} coord hoge
3|  * @param {{x: {y: number}}} opts fuga
4|  * @return {number} desc.
5|  */
6| foo([a, b], {x: {y: c}}) {

@nodaguti nodaguti reopened this Nov 23, 2015

@robcolburn robcolburn referenced this issue in jsdoc3/jsdoc Jan 21, 2016

Closed

JSDoc for destructurings #987

h13i32maru added a commit that referenced this issue Feb 11, 2016

@h13i32maru

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Feb 11, 2016

Member

@nodaguti Hi! Thanks for reporting this issue!
I fixed #178 (comment) on master.

Member

h13i32maru commented Feb 11, 2016

@nodaguti Hi! Thanks for reporting this issue!
I fixed #178 (comment) on master.

@h13i32maru

This comment has been minimized.

Show comment
Hide comment
@h13i32maru

h13i32maru Feb 14, 2016

Member

I released v0.4.5 that fixed this issue.

Member

h13i32maru commented Feb 14, 2016

I released v0.4.5 that fixed this issue.

@h13i32maru h13i32maru closed this Feb 14, 2016

@nodaguti

This comment has been minimized.

Show comment
Hide comment
@nodaguti

nodaguti Feb 14, 2016

@h13i32maru Great job! Thanks!! 🍻

@h13i32maru Great job! Thanks!! 🍻

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment