On Fri, 27 Nov 2020 16:33:27 GMT, Roger Riggs <rri...@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 ,
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.
-------------
PR: https://git.openjdk.java.net/jdk/pull/1355
