valid-jsdoc fails on functions that use ES6 destructuring assignment in signature

Given the following code:

/**
 * @param {object} options
 * @return {number}
 */
const test = function({ a, b, c }) {
  return a + b + c;
};
module.exports = test;

The valid-jsdoc rule fails with the following message:

Expected JSDoc for ‘undefined’ but found ‘options’. (valid-jsdoc)

Changing the variable name in the @param tag to “undefined” doesn’t work either.

ESLint 0.17.0

<bountysource-plugin>

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource. </bountysource-plugin>

[aaronroberson]

It seems like this is a good behavior. Using destructuring in a method or function signature seems like a poor contract to make.

I would suggest that it is a good practice to have all required items listed separately in the method signature and use a single parameter for a config object.

Within the function body, it makes sense to use destructuring to pull out distinct properties from the provided config/options object. And it would make sense to use destructing when calling the method. But I don’t think destructing belongs in the method signature itself.

[robcolburn]

@nzakas, The fix in a1da3b4 sort of dodges the issue a bit, and doesn’t quite do what we’d hope it could…

It turns out JSDoc does support destructing via making up a placeholder name. It is lacking in official documentation. https://github.com/jsdoc3/jsdoc/issues/987

/**
 * @param {object} param
 * @param {number} param.a - First value
 * @param {object} param.b - Wrapper
 * @param {number} param.b.c - Second value
 * @return {number} sum a and b
 */
letters = ({a, b: {c}}) => a + c;

Perhaps, we can support this kind of grammar?