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

[Joe Darcy]

On Wed, 2 Dec 2020 15:39:56 GMT, Roger Riggs <rriggs 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.

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.

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

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