On Fri, 20 Nov 2020 17:15:22 GMT, Jonathan Gibbons <j...@openjdk.org> wrote:
> This change extends the functionality of the `@return` tag so that it can
> also be used as an inline tag in the first sentence of a description.
>
> The goal is to be able to simplify the following common pattern:
>
> /**
> * Returns the result. Optional additional text.
> * @return the result
> */
> int method() {
>
> by
>
> /**
> * {@return the result} Optional additional text.
> */
> int method() {
>
> Note:
>
> * The inline tag may only be used at the beginning of the description. A
> warning will be given if it is used elsewhere.
> * The expansion of the inline tag is `Returns " _content_ `.` where
> _content_ is the content of the tag.
> * If there is no block `@return` tag, the standard doclet will look for an
> inline tag at the beginning of the description
> * The inline tag can be inherited into overriding methods as if it was
> provided as a block tag.
/**
* {@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.
-------------
PR: https://git.openjdk.java.net/jdk/pull/1355
