Javadoc @return tag comment duplication necessary?

With javadoc 16 you may make use of the new combo {@return ...} tag in order "to avoid duplication of return information in simple situations".

/**
 * {@return the name of the object}
 */
public String getName();

Is equivalent to the (still supported) style:

/**
 * Returns the name of the object.
 *
 * @return the name of the object
 */
public String getName();

Find more details at https://bugs.openjdk.java.net/browse/JDK-8075778


From Oracle's recommendation How to Write Doc Comments for Javadoc Tool:

@return (reference page)

Omit @return for methods that return void and for constructors; include it for all other methods, even if its content is entirely redundant with the method description. Having an explicit @return tag makes it easier for someone to find the return value quickly. Whenever possible, supply return values for special cases (such as specifying the value returned when an out-of-bounds argument is supplied).


If you (like me) really don't like to violate DRY, then this is one of the most important lines of the javadoc ref:

It is possible to have a comment with only a tag section and no main description.

(@see http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#tagsection)

So it is perfectly valid (and working) for simple methods to write your javadoc like:

/**
* @return the name of the object
*/
public String getName();

So you could even write something like this:

/**
* @return the n-th element of the object
*
* @param n index of element to get
*/
public String get( int n );

Which is (after a little getting to know each other) more readable in source and better maintainable as the longer form which violates DRY.

Tags:

Java

Javadoc