Search code examples
javajavadoc

Javadoc @return tag comment duplication necessary?

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?

Solution

  • 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