updates to JEP 277 - Enhanced Deprecation

[Stuart Marks]

Hi all,

I've done a major update to the text of JEP 277.[1] Most of this is to reflect 
the reality of what's happening in JDK 9, and some of it is tying off of loose ends.

The most significant change is around the treatment of warning messages mandated 
by the JLS (9.6.4.6). Currently, deprecation warnings can be suppressed with 
@SuppressWarnings("deprecation"). Currently, this suppresses warnings even if 
the API is deprecated with forRemoval=true. This is a problem, since the removal 
warning might be missed, leading to unexpected compile-time or run-time errors 
when the API is actually removed.

The proposal is to have uses of APIs deprecated for removal generate warnings 
anyway, even within code that as @SuppressWarnings("deprecation").

These new "deprecation for removal" warnings can in turn be suppressed using a 
different warnings suppression string,

     @SuppressWarnings("dep-removal")

The idea is that you get a warning for use of a for-removal deprecated API, even 
if you've previously suppressed the warning. Essentially you have to suppress it 
again if you want to continue using the API warning-free. This is somewhat 
intrusive, but I think it's warranted, given the gravity of the for-removal 
deprecation.

Highlights of other changes to the JEP include:

* update terminology from "condemned" to "forRemoval"

* new material on policy for usage of @Deprecated in Java SE, particularly with 
regarding to forRemoval=true

* updated list of deprecation candidates, with specific references to APIs being 
deprecated in Java SE 9

* removal of dynamic deprecation detection usage tool from JDK 9, for lack of 
time :-(

* new material describing issues with warning messages

s'marks


[1] https://bugs.openjdk.java.net/browse/JDK-8065614