valid-jsdoc rule doesn't work on @param {String} options.X-My-Header custom header

What version of ESLint are you using? v2.2.0

What parser (default, Babel-ESLint, etc.) are you using? default

Please show your full configuration:

Full config is at https://github.com/watson-developer-cloud/speech-javascript-sdk/blob/51dd4a041c8e74051ebb87b2630f040b6f0f19a9/.eslintrc.js#L205 but here’s the relevant bit.

        'valid-jsdoc': [1, {
          'requireReturn': false,
          'requireParamDescription': false,
          'requireReturnDescription': false
        }],

I also tested and confirmed that I get the same issue with just 'valid-jsdoc': 1.

What did you do? Please include the actual source code causing the issue.

This is one example of my (working) JSDoc that’s failing ESLint:

* @param {Number} [options.X-WDC-PL-OPT-OUT=0] set to 1 to opt-out of allowing Watson to use this request to improve it's services

You can see it in context at https://github.com/watson-developer-cloud/speech-javascript-sdk/blob/9b683539218a3f060116aa65cfa709380a3ae98c/text-to-speech/synthesize.js#L34

I also tried writing it as

* @param {Number} [options['X-WDC-PL-OPT-OUT']=0] set to 1 to opt-out of allowing Watson to use this request to improve it's services

That passes ESLint but causes JSDoc to explode. (I filed a bug about that at https://github.com/jsdoc3/jsdoc/issues/1178 - but I still think the first behavior is an ESLint bug: a rule named “valid-jsdoc” really shouldn’t enforce invalid JSDoc.)

What did you expect to happen?

I expect my working JSDoc to pass the valid-jsdoc rule, or for there to at least be some format that works for both ESLint and JSDoc

What actually happened? Please include the actual, raw output from ESLint.

That line gives me

26:1 warning Missing JSDoc parameter type for 'Number' valid-jsdoc

Here’s the full output:

~/watson-speech (master) $ npm run lint

> watson-speech@0.14.0 lint /Users/nfriedly/watson-speech
> eslint .


/Users/nfriedly/watson-speech/speech-to-text/format-stream.js
  113:7  warning  Unexpected 'todo' comment  no-warning-comments

/Users/nfriedly/watson-speech/speech-to-text/media-element-audio-stream.js
  68:7  warning  Unexpected 'todo' comment  no-warning-comments

/Users/nfriedly/watson-speech/speech-to-text/recognize-stream.js
   34:1   warning  Missing JSDoc parameter type for 'String'  valid-jsdoc
   34:1   warning  Missing JSDoc parameter type for 'Number'  valid-jsdoc
  146:13  warning  Unexpected 'todo' comment                  no-warning-comments
  149:9   warning  Unexpected 'todo' comment                  no-warning-comments
  165:3   warning  Unexpected 'todo' comment                  no-warning-comments
  379:1   warning  Unexpected 'todo' comment                  no-warning-comments

/Users/nfriedly/watson-speech/speech-to-text/timing-stream.js
  37:32  warning  Unexpected 'todo' comment  no-warning-comments

/Users/nfriedly/watson-speech/text-to-speech/synthesize.js
  26:1  warning  Missing JSDoc parameter type for 'Number'  valid-jsdoc

✖ 10 problems (0 errors, 10 warnings)

(Ignore the todo’s - I want those to nag me until they’re fixed.)

[kaicataldo]

Opened a PR to doctrine to attempt to fix this. I’ve already tested that branch of doctrine with ESLint locally and can open a PR with tests covering this and bumping the doctrine version if that gets merged.

[kaicataldo]

@nfriedly Thanks for the kind words 😄