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

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

    XMLWordPrintable

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

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

              Dates

                Created:
                Updated:
                Resolved: