eslint: require-jsdoc doesn't recognize comment blocks with newlines afterward
What version of ESLint are you using?
2.10.2
What parser (default, Babel-ESLint, etc.) are you using?
default
Please show your full configuration:
$ $(npm bin)/eslint --print-config index.js
{
"globals": {},
"env": {},
"rules": {
"require-jsdoc": "error"
},
"parserOptions": {}
}
What did you do? Please include the actual source code causing the issue.
/**
* Returns "yay!"
* @returns {String}
*/
function pleaseWork() {
return "yay!";
}
What did you expect to happen?
No errors. jsdoc allows whitespace between the comment block and the commented node.
What actually happened? Please include the actual, raw output from ESLint.
$ $(npm bin)/eslint index.js
/Users/ruppel/Documents/Scratch/jsdoc/index.js
6:1 error Missing JSDoc comment require-jsdoc
✖ 1 problem (1 error, 0 warnings)
About this issue
- Original URL
- State: closed
- Created 8 years ago
- Comments: 21 (18 by maintainers)
Commits related to this issue
- Allow whitespace after jsdoc comments. Fixes #6238 — committed to jeremyruppel/eslint by jeremyruppel 8 years ago
- Fix: Allow whitespace after jsdoc comments (fixes #6238) — committed to jeremyruppel/eslint by jeremyruppel 8 years ago
To add to this, I also would interested in exploring alternatives to Doctrine since very few of the maintainers have much knowledge about its internals at this point and it’s hard for us to make modifications.
I’m all for discussing how we handle JSDoc comments again.
I think there are two separate issues that have been discussed here (though there may be one solution that solves them both). One is re-evaluating the logic that locates JSDoc comments, and the second is seeing if we can move away from Doctrine to another implementation.
For the first, the logic we use to locate JSDoc comments could probably be refactored and simplified, now that I look at it. Though I’m still unsure of how we would handle the cases described above.
For the latter, JSCS uses the comment-parser and jsdoctypeparser packages to parse JSDocs. We could try to do something similar, though I don’t think it’s a trivial amount of work. Both packages have quite a few monthly downloads (though one hasn’t been updated in a year).
@kaicataldo I don’t have the knowledge to know if I can/should advocate for it. Seemed wiser to ask in case someone else knew and could either run with it or tell me why we shouldn’t. I can create a new issue if preferred.
@platinumazure If you’d like to advocate for this, can you make a new issue? Old, closed issues don’t get much visibility.
@eslint/eslint-team Should we revisit this? One of the earlier comments talked about how JSCS looked at comments at the token level instead of the AST. We have since made that change in our comment handling logic. Is there anything we could/should consider doing here to improve the JSDoc validation experience?
@kaicataldo I disagree. I think having jsdoc-related rules that don’t match the semantics of the actual jsdoc parser is a defect, not an “enhancement”, and this issue should be labeled as such.
I would say this is a relaxing option that detects doc-blocks as long as there is no other token between the docblock and the thing it’s describing. This seems like a totally legit ask IMO