JSDoc for destructurings

[AlexanderZeilmann]

This is more a question/feature request than a bug report. In ES2015 it is possible to do destructurings directly in the arguments of a function. For example:

var fn = function ({prop1, prop2}) {
  // Do something with prop1 and prop2
}

// fn is called like this
fn({prop1: 1, prop2: 2});

How should the function fn be annotated with JSDoc comments?

I found the following on the documentation page for param tags:

The @param tag requires you to specify the name of the parameter you are documenting.

But I my case, the parameter has no name, so it is impossible for me to specify the parameter name...

[hegemonic]

You can just give the object a fake name and document its properties, like this:

/**
 * My cool function.
 *
 * @param {Object} obj - An object.
 * @param {string} obj.prop1 - Property 1.
 * @param {string} obj.prop2 - Property 2.
 */
var fn = function ({prop1, prop2}) {
  // Do something with prop1 and prop2
}

[AlexanderZeilmann]

@hegemonic thanks for the quick answer :-)

Hmm, the solution feels a little bit like a hack. But I agree, that is probably the best backwards compatible way to do this.

You might want add this case to the documentation.

[qfox]

Sorry for the posting to closed issue but just look:

class ServerResponsePage {
  /**
   * @param {string} action - response name.
   * @param {string} result - response result.
   */
  constructor({query: {action, result}}) {
    // ...
  }
}

If we go the usual way it will be:

/**
 * @param {Object} opts
 * @param {Object} opts.query
 * @param {string} opts.query.action - desc
 * @param {string} opts.query.result - desc
 */

And it's noisy as hell.

Would be great if we can rethink this.

/cc @blazkovicz

[robcolburn]

@hegemonic's #987 (comment) is consistent w/ esdoc esdoc/esdoc#178

As far as I can tell, it's not documented though. Perhaps, we can be more explicit / borrow from esdoc?

https://esdoc.org/tags.html#object

[lll000111]

Just for reference, the URL to esdoc documentation posted by @robcolburn just above seems to have changed:

https://esdoc.org/manual/tags.html#object

[hegemonic]

I filed jsdoc/jsdoc.github.io#159 to add an example of this to the docs.

[dandv]

For the record, this is now documented at http://usejsdoc.org/tags-param.html#parameters-with-properties