@returns v.s @return - ambiguity causes inconsistency

[fab1o]

@returns v.s @return - ambiguity causes inconsistency

[fab1o]

There's inconsistency even in ESDocs' own source code: https://github.com/esdoc/esdoc/blob/38ad523936d425278cc037c9c0e11338faa2709b/src/Parser/ParamParser.js
https://github.com/esdoc/esdoc/blob/master/src/Parser/ParamParser.js

Imagine a huge project with thousands of files.

[fab1o]

Given that it seems to there're more @returns than @return in ESDocs own source code.

Documentation needs to be updated to support it. And It would be nice if it didn't support @return to avoid ambiguity and inconsistency.

[bbusschots-mu]

I strongly disagree that either @return or @returns should be removed. Instead, the docs should be updated to make it explicit that @return is an alias for @returns. This is how JSDoc handles this situation. It is similar to @param, @arguments & @arg.

One final point, @returns is more in keeping with @throws, so it is definitely the most consistent of the two options. Because @returns is not documented I use @return, and it drives me nuts that it's @return followed by @throws on the next line 🙂