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

Clean up java.lang.ref comments and documentation

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: Resolved
    • Priority: P4
    • Resolution: Fixed
    • Affects Version/s: 18
    • Fix Version/s: 18
    • Component/s: core-libs
    • Labels:
    • Resolved In Build:
      b16

      Description

      There's one typo in an inline comment and overlinking in a doc comment. See the linked PR for details.

      From "How to Write Doc Comments for the Javadoc Tool":
      """
      Use in-line links economically
      You are encouraged to add links for API names (listed immediately above) using the {@link} tag. It is not necessary to add links for all API names in a doc comment. Because links call attention to themselves (by their color and underline in HTML, and by their length in source code doc comments), it can make the comments more difficult to read if used profusely. We therefore recommend adding a link to an API name if:

      The user might actually want to click on it for more information (in your judgment), and
      Only for the first occurrence of each API name in the doc comment (don't bother repeating a link)
      Our audience is advanced (not novice) programmers, so it is generally not necessary to link to API in the java.lang package (such as String), or other API you feel would be well-known."""

        Attachments

          Issue Links

            Activity

              People

              Assignee:
              prappo Pavel Rappo
              Reporter:
              prappo Pavel Rappo
              Votes:
              0 Vote for this issue
              Watchers:
              3 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved: