Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8229111

Allow omitting method summary when @return is present

    Details

    • Type: Enhancement
    • Status: New
    • Priority: P4
    • Resolution: Unresolved
    • Affects Version/s: 14
    • Fix Version/s: None
    • Component/s: tools

      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


        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              webbuggrp Webbug Group
            • Votes:
              0 Vote for this issue
              Watchers:
              2 Start watching this issue

              Dates

              • Created:
                Updated: