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


    • 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:
    • Verification:


      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.


          Issue Links



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


                • Created: