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.