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

[Joe Darcy]

FYI, I had a good experience taking a trial run of this patch to update 
the java.compiler APIs to use the new feature. I didn't find any issues; 
a specdiff comparing with and without use of the new tag didn't have any 
unexpected diffs. (There were cases where small wording differences 
existed and were regularized in the patch.)

After this goes back, looking forward to pushing a fix for JDK-8256917: 
Use combo @returns tag in java.compiler javadoc.

Cheers,

-Joe

On 11/20/2020 4:34 PM, Jonathan Gibbons 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 incrementally with one additional commit since the last revision:
>
>    Update DocCommentParser to permit nested inline tags in specified cases: @return
>
> -------------
>
> Changes:
>    - all: https://git.openjdk.java.net/jdk/pull/1355/files
>    - new: https://git.openjdk.java.net/jdk/pull/1355/files/89846ff1..87edfb0c
>
> Webrevs:
>   - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=1355&range=02
>   - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=1355&range=01-02
>
>    Stats: 88 lines in 3 files changed: 82 ins; 3 del; 3 mod
>    Patch: https://git.openjdk.java.net/jdk/pull/1355.diff
>    Fetch: git fetch https://git.openjdk.java.net/jdk pull/1355/head:pull/1355
>
> PR: https://git.openjdk.java.net/jdk/pull/1355