Moar updates to JEP 277 - Enhanced Deprecation - warnings policy

[Stuart Marks]

Hi all,

I've updated the JEP 277 text once again, this time focused on the policy for 
issuing deprecation warnings. See the revised JEP text in the bug report:

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

Specifically the following sections have been rewritten:

  - Deprecation vs. Introduction of Warning Messages
  - Impact of forRemoval on Warning Messages Policy
  - Suppression of Deprecation Warnings

The material in these sections is not actually new; the previous version talked 
about these issues, but it was so terse as to be unintelligible.

TL;DR: If code uses an API deprecated with forRemoval=true, the resulting 
warnings are not suppressed with the currently defined

    @SuppressWarnings("deprecation")

annotation. Instead, these warnings can be suppressed with a different annotation,

     @SuppressWarnings("removal")

The reason is that, if a deprecation warning is already suppressed with 
@SW("deprecation"), and the API is then "upgraded" to have forRemoval=true, this 
change will go unnoticed at use sites. This could lead to errors.

See the JEP text for further details.

s'marks