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

Allow omitting method summary when @return is present

    XMLWordPrintable

Details

    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

        Issue Links

          Activity

            People

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

              Dates

                Created:
                Updated:
                Resolved: