Javadoc @return tag comment duplication necessary?

Question

For functions that don't change the state of an instance, the javadoc comment for the method is often the same or very similar as the one for the @return-tag in the Java-API.

boolean Collection.isEmpty()

• Returns true if this collection contains no elements.
• Returns: true if this collection contains no elements

Now I am writing javadoc for many simple methods like getExpression() where I have the same problem. Should I do it like in the API or leave it out?

Answer 1

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.

Answer 2

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

Answer 3

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

Answer 4

Since Java 16 the recommended solution is to use the newly introduced inline {@return description} tag of the Standard Doclet:

/**
 * {@return the name} {@code null} if unknown.
 */
public String getName() {
    ...
}

This will generate a "Returns description." summary, followed by whatever you write behind it, and additionally uses the description for the description of the return value:

Note that the "Returns ..." sentence already ends with a period; you should not add an explicit one behind {@return }.