@returns v.s @return - ambiguity causes inconsistency

[fab1o]

This is a question/issue/feature request.

In the documentation, https://esdoc.org/manual/tags.html, there is no reference to @returns. I couldn't find it anywhere. I could only find @return as the correct tag.

However, when @returns is used in the code, the docs are still generated correctly, as if we used @return.

This ambiguity causes inconsistency in codebases if different team members use different tags.

To fix this issue, team members have to be aware of this and stop using one or the other.

Preferably stop using @returns, but if a project grows so much to the point that @returns is in 95% of the code base, then it makes it difficult to argue in favor of @return.

A better fix would be if ESDocs sticked with its Documentation and supported @return only.

Another fix would be if ESDocs supported @returns only and updated its Documentation accordingly.

But not both.

Insights?

[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 🙂