RFR: 8145461 changes to @Deprecated annotation

[Alex Buckley]

Some editorial points:

- "Usage of a deprecated element may also be flagged by various analysis 
tools." -- recommend removing this sentence. (Vague info; passive voice; 
undue prominence.) If you really want to allude to third party tools, 
have a paragraph at the end "Analysis tools are encouraged to flag ...".

- Recommend that since() precedes condemned() everywhere. Anyone who 
writes @Deprecated knows what since is, even if they're too busy to 
think about tomorrow's build let alone a version next year. I think that 
condemned=true without a since is passive-aggressive behavior.

- "A value of {@code false} indicates that use of the annotated program 
element is discouraged but, at the time the annotated program element 
was specified, that there was no specific intent to remove it." -- by 
"specified", do you mean "declared" or "annotated" ? I have to think you 
mean "annotated", since hardly anyone declares an element and 
immediately writes @Deprecated.

- This annotation _type_ has a ... [two occurrences]

- This value indicates the version -> The value of this element 
indicates the version

- In the @apiNote, "that element's" and "This documentation" can just 
use "the".

- since() method decl suddenly mentions "API element" rather than 
"annotated element" (condemned() uses "annotated element").

Alex

On 3/29/2016 3:38 PM, Stuart Marks wrote:
> Hi all,
>
> Please review these changes to the @Deprecated annotation:
>
>      http://cr.openjdk.java.net/~smarks/reviews/8145461/webrev.0/
>
> This is the first of a set of changes for JEP 277, which I hope will
> become Targeted to JDK 9 late this week. Changes to the deprecation
> status of specific APIs will be in subsequent changesets, along with
> some deprecation tooling.
>
> Note that this is considerably simplified from previous drafts. In
> particular, there is no "reason" enum. See the JEP [1] for background
> and rationale.
>
> Thanks,
>
> s'marks
>
> [1] http://openjdk.java.net/jeps/277
>