Bug ID: JDK-8162674 change javadoc output text and style emitted by for-removal deprecations

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

JDK 9
9 b150Fixed

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.

Good catch: +1 on matching the wording in the spec for java.lang.Deprecated.
03-11-2016
Slight update to Jon's proposal for the presentation of an element that is deprecated for removal: <b>Deprecated, for removal:</b> This (item) is subject to removal in a future version. <p> body of @deprecated tag Basically, use "version" instead of "release" in order to match the wording used in the java.lang.Deprecated specification for the forRemoval element. Also, as Jon mentioned to me, the text should NOT include "Java SE" as I had suggested earlier, since javadoc is used for processing specifications other than Java SE.
03-11-2016
With respect to Stuart's first point above: Currently, the presentation for deprecated items is <b>Deprecated:</b> body of @deprecated tag When an item has been deprecated for removal, the default presentation could be something like: <b>Deprecated, for removal:</b> This (item) is subject to removal in a future release. <p> body of @deprecated tag
14-09-2016
Changes for terminal deprecation could be as follows: * Instead of just adding "Deprecated" in bold, additional boilerplate text could be added, e.g., "Deprecated. This method is subject to removal in a future release of Java SE." (Instead of "method" the appropriate noun would be inserted, such as class, interface, field, etc., or something more generic such as "API element".) Presumably there would need to be a way to customize javadoc's boilerplate text here, since javadoc serves platforms other than Java SE. * In the deprecated API index, the terminal deprecations could be gathered into their own section(s) at the top of the page. This would make it convenient for users to see at a glance all of the APIs that are on the chopping block. * The presentation style for displaying the @deprecated javadoc text could differ between ordinary and terminal deprecation. It might be displayed against a colored background, or perhaps an attention-attracting icon could be added.
07-09-2016