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

[Jonathan Gibbons]

On Thu, 3 Dec 2020 21:19:38 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> 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.
>
>> 
>> 
>> 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.
> 
> IMO this is a case to avoid the perfect being the enemy of the good. There are many structural cases of repeated or nearly repeated return information in the first sentence and @return tag. Therefore, I think it is reasonable for don't-repeat-yourself purposes to have dedicated support for this usage pattern.
> 
> Separately, I agree it would be helpful to have a more general facility to allow structured placement of repeated text blocks.

Yes, there are two patterns being discussed here.

1. The pattern being directly addressed here, which is the local 
pairwise repetition of
      Returns the result.
      @return the result
     where the repetition is unlikely to occur elsewhere

2. "Disjoint repetition", such as repeated occurrences of
      @throws IOException if something occurrs
     which will be found at most once per method, but may appear on many 
methods

We can (separately) discuss #2, preferably in the context of a different 
JBS issue, and wearing sticky rubber shoes to avoid falling down the 
cliff of a general macro-substitution language.

-- Jon

On 12/3/20 1:19 PM, Joe Darcy wrote:
>
>     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.
>
> IMO this is a case to avoid the perfect being the enemy of the good. 
> There are many structural cases of repeated or nearly repeated return 
> information in the first sentence and @return 
> <https://urldefense.com/v3/__https://github.com/return__;!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDhTvrReYw$> 
> tag. Therefore, I think it is reasonable for don't-repeat-yourself 
> purposes to have dedicated support for this usage pattern.
>
> Separately, I agree it would be helpful to have a more general 
> facility to allow structured placement of repeated text blocks.
>
> —
> You are receiving this because you were mentioned.
> Reply to this email directly, view it on GitHub 
> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/1355*issuecomment-738325017__;Iw!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDh4e-tvuw$>, 
> or unsubscribe 
> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRT2VKB4GPG5D2FQJBDSS76HVANCNFSM4T5BHLXA__;!!GqivPVa7Brio!IUSEgZPlNh-w3R__hVpDuJiQuNZLQOKs4VXEe9tW9B3d2Aem9DM3WVH-17FJKDjzD260_w$>.
>

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

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