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.

[nzakas]

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 return statements in a function body is non-trivial, so even if you could convince me that @returns isn’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.

[briandipalma]

I’d like to not have any @returns if there is no need though.