-
Notifications
You must be signed in to change notification settings - Fork 203
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
@returns v.s @return - ambiguity causes inconsistency #550
Comments
There's inconsistency even in ESDocs' own source code: https://github.com/esdoc/esdoc/blob/38ad523936d425278cc037c9c0e11338faa2709b/src/Parser/ParamParser.js Imagine a huge project with thousands of files. |
Given that it seems to there're more Documentation needs to be updated to support it. And It would be nice if it didn't support |
I strongly disagree that either One final point, |
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?
The text was updated successfully, but these errors were encountered: