java - 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?

question from:https://stackoverflow.com/questions/10088311/javadoc-return-tag-comment-duplication-necessary

Answer 1

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