RFR: 8145461 changes to @Deprecated annotation

[Stuart Marks]

On 3/29/16 4:51 PM, Alex Buckley wrote:
> 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 ...".

Well, the tools are ones I intend to integrate later in JDK 9, but points taken.

Plus, we mustn't talk about the future. :-)

> - 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.

I'll add API notes about this.

> - "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.

Yes, "annotated." Thanks, this will improve that sentence.

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

ok

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

ok

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

ok

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

ok

> Alex

Thanks for the comments.

s'marks

>
> 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
>>