RFR: JDK-8075778: Add javadoc tag to avoid duplication of return information in simple situations.
Joe Darcy
darcy at openjdk.java.net
Thu Dec 3 21:21:54 UTC 2020
On Fri, 27 Nov 2020 16:33:27 GMT, Roger Riggs <rriggs at openjdk.org> wrote:
>
>
> ```
> /**
> * {@return the result} Optional additional text.
> */
> ```
>
> The java source looks a bit odd/unusual because the "first sentence" does not appear to end with a period.
> Though it seems like a convenience to include the '.' in the expansion, the source might be clearer if it did not, as in:
>
> ```
> /**
> * {@return the result}. Optional additional text.
> */
> ```
>
> Similarly, prepending the "Returns", forces the verb, which is conventional but always the most appropriate word.
> Changing the expansion to be only the contents of @ return would allow more flexible use.
> It would put more responsibility on the developer to form the first sentence. (With "Returns"... and the "." outside the tag.
I've done a trial use of this feature in the java.compiler API. While initially I found the lack of a period after "{@return ...}" odd, I quickly adapted to this usage.
-------------
PR: https://git.openjdk.java.net/jdk/pull/1355
More information about the compiler-dev
mailing list