Javadoc @return tag comment duplication necessary?

java, javadoc

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

Problem

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?

Original source