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

[Pavel Rappo]

On Wed, 2 Dec 2020 15:39:56 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> @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.

@RogerRiggs,

Here are some more thoughts on flexible expansion (i.e. not forcing a particular verb). To understand the nature and estimate the prevalence of cases where "Return(s)" was inappropriate as the first word of an internally repetitive doc comment, I conducted the following experiment in JDK.

I searched for doc comments whose first sentence was at least 90% similar to the contents of `@ return` tag. My program ignored differences in markup and compared contents as strings using normalized Levenshtein similarity; I got 3432 results. Then I modified the program to ignore those doc comments whose first sentence case-insensitively started with "return"; I got 194 results.

While more analysis might be required, I can preliminary see that we are talking about 5% of the cases. Which is not much, if you ask me. Here are a few findings made by the modified program:


/**
 * Cleaner for use within system modules.
 ...
 * @return a Cleaner for use within system modules
 */
public static Cleaner cleaner() {

/**
 * Get the localization resource bundle
 ...
 * @return the localization resource bundle
 */
public ResourceBundle getResourceBundle() {

/**
 * Obtains a line that is available for use and that matches the description
 * in the specified {@code Line.Info} object.
 ...
 * @return a line that is available for use and that matches the description
 *         in the specified {@code Line.Info} object
 ...
 */
Line getLine(Line.Info info) throws LineUnavailableException;

/**
 * The description of this filter. For example: "JPG and GIF Images."
 *
 * @return the description of this filter
 */
public String getDescription() {

/**
 * Fetch the object representing the layout state of
 * of the child at the given index.
 ...
 * @return the object representing the layout state of
 * of the child at the given index
 */
protected ChildState getChildState(int index) {

/**
 * Creates a new instance of the {@code DatatypeFactory} {@linkplain
 * #DATATYPEFACTORY_IMPLEMENTATION_CLASS builtin system-default
 * implementation}.
 *
 * @return A new instance of the {@code DatatypeFactory} builtin
 *         system-default implementation.
 ...
 */
public static DatatypeFactory newDefaultInstance() {

/**
 * True if this iterator has a reversed axis.
 *
 * @return <code>true</code> if this iterator is a reversed axis.
 */
public boolean isReverse() {

/**
 * Check if the annotation contains an array of annotation as a value. This
 * check is to verify if a repeatable type annotation is present or not.
 ...
 * @return true if the annotation contains an array of annotation as a value.
 */
private boolean isAnnotationArray(Map<? extends ExecutableElement, ? extends AnnotationValue> pairs) {

...

The most frequent first word in those 194 results was "Get(s)".

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

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