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

[Jan Lahoda]

On Mon, 7 Dec 2020 18:37:37 GMT, Jonathan Gibbons <jjg 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.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - Update JShell to handle inline `{@return}`
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - fix test
>  - Update for new `@return` tag
>  - Merge remote-tracking branch 'upstream/master' into new-return
>  - Update DocCommentParser to permit nested inline tags in specified cases: @return
>  - Add default impl for new method
>  - Fix test failure
>  - Fix trailing whitespace in test
>  - ... and 2 more: https://git.openjdk.java.net/jdk/compare/d5251c03...a25dadca

The javac/jshell changes look sensible to me.

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

Marked as reviewed by jlahoda (Reviewer).

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