On Tue, 1 Dec 2020 17:09:25 GMT, Pavel Rappo <pra...@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
