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

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

XMLWordPrintable

      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.

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

              Created:
              Updated:
              Resolved: