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

Add javadoc tag to avoid duplication of return information in simple situations.

    Details

      Description

      For a simple, getFoo method, the recommended correct javadoc is

      /**
       * Returns a Foo.
       * @return a Foo.
       */
      Foo getFoo()

      This pattern is quite redundant, tedious to maintain, and clumsy to read in the sources.

      It would be preferable if a single javadoc tag, say {@Return } could be used in these situations like

      /**
       * {@Returns} a Foo.
       */
      Foo getFoo()

      which would have the same effect as the method javadoc with a separate @return tag as above.

      The use of the {@Returns} tag would be intended for simple situation where there was a direct (near) repetition of the initial sentence and the @return tag. When such repetition was not present or desirable, the {@Returns} tag should not be used.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                jjg Jonathan Gibbons
                Reporter:
                darcy Joe Darcy
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: