eslint: Make valid-jsdoc @returns requirement configurable.
Firstly thanks for the great work on ESLint, very nice project.
I’ve enabled valid-jsdoc for my code but I’m finding that it’s sometimes overly strict.
Specifically the requirement to have an @returns specified seems to only make sense when there is a return statement in the documented function.
Yet to pass the rule you need to add
@returns {undefined}
to many of your JSDoc comments.
Making this explict doesn’t seem like a great win for developers or for tools which process the JSDoc. The implicit return value being undefined anyway.
I’d like to add another configuration value, returnRequiredIfReturnUndefined, to the valid-jsdoc rule.
"valid-jsdoc": [2, {
"returnRequiredIfReturnUndefined": false
}]
This is how, ideally, it would work.
If there is no return of if the return returns undefined then do not require the developer to fill in a @return tag.
Does this seem a sensible change? I can start working on a PR if so.
I have a vague memory of the SpiderMonkey AST having a ReturnNode or something of the type which I could use to achieve this.
I will follow the contributing guidelines.
About this issue
- Original URL
- State: closed
- Created 10 years ago
- Comments: 19 (18 by maintainers)
Commits related to this issue
- Fixes #673 allow configuration of @return errors via requireReturnIfReturnUndefined — committed to briandipalma/eslint by briandipalma 10 years ago
- Fixes #673 allow configuration of @return errors via requireReturn — committed to briandipalma/eslint by briandipalma 10 years ago
- Fixes #673 allow configuration of @return errors via requireReturn - (fixes #673) — committed to briandipalma/eslint by briandipalma 10 years ago
- Merge pull request #683 from briandipalma/issue673-2 Fixes #673 allow configuration of @return errors via requireReturn — committed to eslint/eslint by nzakas 10 years ago
I’m not convinced that’s a good idea. I’ve always enforced at work that JSDoc comments must include @returns at all times. When it’s missing, I don’t know if it’s because the method doesn’t return anything or if the developer just forgot to include it. By requiring it to always be there, you know for sure that if it’s missing, it was a developer mistake. In practice, I’ve found this to be extremely useful in avoiding inconsistencies between the documentation comment and the code. Thus
@returns {void}as the shortest possible way to say that a function doesn’t return anything.So, I’m really not in favor of allowing this to be turned off, as I see it as a best practice.
However, I always leave myself open to being convinced by others. The work of tracking down
returnstatements in a function body is non-trivial, so even if you could convince me that@returnsisn’t always necessary, I’m not sure I’d want to go the route of inspecting the function body to figure out if it’s necessary or not.I’d like to not have any
@returnsif there is no need though.You can do
@returns {void}and it will not require a description.