Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for destructuring in function parameters #178

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

Support for destructuring in function parameters #178

nodaguti opened this issue Nov 23, 2015 · 5 comments

Comments

@nodaguti
Copy link

@nodaguti nodaguti commented Nov 23, 2015

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
Copy link
Author

@nodaguti nodaguti commented Nov 23, 2015

Sorry, ESDoc already supports object destructuring ...

@nodaguti nodaguti closed this Nov 23, 2015
@nodaguti
Copy link
Author

@nodaguti nodaguti commented 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}}) {
@nodaguti nodaguti reopened this Nov 23, 2015
h13i32maru added a commit that referenced this issue Feb 11, 2016
@h13i32maru
Copy link
Member

@h13i32maru h13i32maru commented Feb 11, 2016

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

@h13i32maru
Copy link
Member

@h13i32maru h13i32maru commented Feb 14, 2016

I released v0.4.5 that fixed this issue.

@h13i32maru h13i32maru closed this Feb 14, 2016
@nodaguti
Copy link
Author

@nodaguti nodaguti commented Feb 14, 2016

@h13i32maru Great job! Thanks!! 🍻

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
2 participants
You can’t perform that action at this time.