Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8065614 JEP 277: Enhanced Deprecation
  3. JDK-8162674

change javadoc output text and style emitted by for-removal deprecations

    Details

    • Type: Sub-task
    • Status: Closed
    • Priority: P3
    • Resolution: Fixed
    • Affects Version/s: 9
    • Fix Version/s: 9
    • Component/s: tools
    • Labels:
    • Subcomponent:
    • Resolved In Build:
      b150
    • Verification:
      Verified

      Description

      If an API element is deprecated, javadoc's out as of Java 8 is as follows:

       * In the method (field) summary, the first sentence is replaced with the word "Deprecated"
          in boldface, followed by the text from the @deprecated javadoc tag.

       * In the method (field) detail, "Deprecated" is emitted in boldface, followed by the @deprecated
          javadoc text in italics, followed by the ordinary method or field documentation.

      In Java 9, there is now an additional kind of deprecation declaration, one that has forRemoval=true. Javadoc's current treatment of "ordinary" (forRemoval=false) depecation, as described above, is fine. Javadoc should emit different output if the deprecation is "terminal," that is, if forRemoval=true.

      Currently (JDK 9 build 134) the @Deprecated annotation elements (e.g., since="1.2", forRemoval=true) are simply listed at the class declaration, or at the location of the method or field signature declaration in the corresponding detail section.

      It would be nice if terminal deprecations caused additional changes in javadoc output to occur, making such deprecations more prominent and easier to find. Discussion of ideas for what to do are listed in comments.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                bpatel Bhavesh Patel (Inactive)
                Reporter:
                smarks Stuart Marks
              • Votes:
                0 Vote for this issue
                Watchers:
                5 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved: