JDK-8229111 : Allow omitting method summary when @return is present
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 14
  • Priority: P4
  • Status: Closed
  • Resolution: Duplicate
  • CPU: x86_64
  • Submitted: 2019-08-02
  • Updated: 2020-10-07
  • Resolved: 2020-10-07
Related Reports
Duplicate :  
Description
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