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

[Roger Riggs]

On Tue, 1 Dec 2020 17:09:25 GMT, Pavel Rappo <prappo 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.
>
> @RogerRiggs ,
> 
> 1. I agree on that the lack of `.` after `}` looks unnatural:
> 
> /**
>  * {@return the result} Optional additional text.
>  */
> int method() { 
> 
> 2. I disagree on allowing a flexible expansion. This enhancement aims to support a very particular case of redundancy in doc comments. I believe that the proportion of redundant doc comments that use some other verb (instead of "Return(s)") is smaller than it needs to be to support the increase in tag's complexity.

There is lots of other duplication/repetition in most javadoc. I'd rather see some kind of text macro that would allow a single definition of a string that can be repeated.  The source would be a bit less readable, but it would be lower maintenance when the same phrase or sentence is repeated to make the javadoc more locally complete and easier to read in isolation. Now many times do you have to say "throws NullPointerException when the reference is null" or similar assertion.

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

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