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.