-
Enhancement
-
Resolution: Duplicate
-
P4
-
None
-
14
-
x86_64
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
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
- duplicates
-
JDK-8075778 Add javadoc tag to avoid duplication of return information in simple situations.
- Resolved