checkRedundantParams: Jsdoc and destructuring

[blazkovicz]

I use jscs 2.1.0 with {"esnext": true, "jsDoc": {"checkRedundantParams": true}} in WebStorm for inline linting. Jscs highlights param definitions for destructured params (except first) as redundant:

class ServerResponsePage {
  /**
   * Page to show server response.
   * @constructor
   * @param {string} action - response name.
   * @param {string} result - response result. <--- this description is highlighted as redundant
   */
  constructor({query: {action, result}}) {
    // ...
  }
}

[qfox]

Oh, <3 issues about esnext features! ;-)

But atm it doesn't supported. But anyway your jsdoc is wrong. Since your constructor has only one param {Object} with internal structure you should describe it correctly:

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

If you know how to do it correctly just tell me because I don't ;-( I don't see anything in jsdoc manuals.

[blazkovicz]

WebStorm generates my jsdoc with unstructured param names, I think it's corrent since I do not have access in constructor to "opt" or "opt.query" but only to "action" and "result".

[qfox]

http://usejsdoc.org/tags-param.html — nothing about it
https://github.com/senchalabs/jsduck/wiki/@param — still nothing

jsdoc/jsdoc#987 (comment) — gotcha!

[qfox]

I've left the comment in jsdoc repo.

I'm fine if we make this possible, but then it won't work in jsdoc tool. Guess it will hurt a lot of people ;-( Personally I don't like this noise but... dunno.

I'm open to suggestions. Perhaps community will join to the discuss.

[blazkovicz]

Thanks for the detailed answer. I'll try to stick with your suggestion for now, but hope jscs will allow brief param descriptoin for such cases in the future.

[blazkovicz]

Sorry, I was quick to decide on closing. Jsdoc may not support this feature as it is, but it allows to describe params as I suggested, so it's up to jcsc to support such syntax in linting.

[blazkovicz]

Also to the issue: jscs does not highlight param names as wrong, it just indicates mismatch of parameters count, so partial support for destructuring is provided already (by the parser, I assume).

[blazkovicz]

Checked your suggestion about fake param "opt". Jcsc highlights param name as not present in function arguments, so this solution is not appropriate.