Duplicate :
|
A DESCRIPTION OF THE PROBLEM : There are cases where the summary of a method would be exactly the same as the return value description (@return), e.g.: class Point { int x; int y; /** * Returns the x-coordinate. * * @return the x-coordinate */ public int getX() { return x; } /** * Returns the y-coordinate. * * @return the y-coordinate */ public int getY() { return y; } } Currently you have to write a method summary and a return value description, as described by https://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@return However, this violates the "Don't repeat yourself" principle and makes maintaining the javadoc and keeping it up to date more difficult. As shown in the Stack Overflow question https://stackoverflow.com/q/10088311 people have started working around this by: - Omitting the method summary: Leads to an empty summary in the "Method Summary" table of class - Omitting the @return tag (also recommended in Google's Java Style Guide [0]): Leads to warning when using `javadoc` command It would be useful if there was an official way to do this. Here are some suggestions to solve this, though they might have drawbacks: - When no method summary is present use the @return description, but only for "Method Summary" table and similar, do not show it under "Method Detail" -- javadoc should only allow this for methods which actually have a return type -- Would not work when overriding method since method summary is inherited if not present - Introduce {@return} or {@returnDesc} as inline tag which copies the @return description When the @return description is shown as summary it could possibly be preceded with "<i>Returns</i> ", though that requires that the @return description starts with a lowercase letter. [0] https://google.github.io/styleguide/javaguide.html#s7.2-summary-fragment