RFR: JDK-8075778: Add javadoc tag to avoid duplication of return information in simple situations.

[Jonathan Gibbons]

On Fri, 27 Nov 2020 16:33:27 GMT, Roger Riggs <rriggs at 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.

@RogerRiggs I think that having to write `Returns {@return the result}.` would look more weird than the current proposal to omit the `.`.  Note also that the proposed form matches the existing `{@summary ...}` tag which can be used to explicit define the "first sentence" that appears in summary tables.

-------------

PR: https://git.openjdk.java.net/jdk/pull/1355