@Deprecated(since) and Javadoc

[joe darcy]

On 4/21/2016 7:02 PM, Stuart Marks wrote:
> On 4/21/16 4:51 PM, Paul Benedict wrote:
>> Well, my point was that it becomes redundant coding to specify both 
>> the annotation and the Javadoc tag. It would just seem better, in my 
>> opinion, if doing a @j.l.Deprecated(since="9") triggered whatever 
>> output is necessary during doc generation. It doesn't make sense to 
>> me to require both. The language annotation, with the new attribute, 
>> is now expressive enough for generation needs. Asking the developer 
>> to do both is wasteful effort, I think.
> If you want to deprecate something and not provide any documentation 
> about why it was deprecated or what it should be replaced with, then 
> the @Deprecated annotation will be sufficient. Javadoc will place a 
> boldface heading
>
> *Deprecated.*
>
> into the javadoc output. (This has been true in JDK 8 and earlier, and 
> it has nothing to do with the new "since" element in the @Deprecated 
> annotation.)
>
> If you want documentation about the deprecation (rationale and 
> replacement) then you do need to add a @deprecated javadoc tag, as 
> redundant as that may seem. There's no place to put such documentation 
> in the @Deprecated annotation.
>

The distinct java.lang.Deprecated annotation type separate from the 
@deprecated javadoc tag was a deliberate design decision made back in 
JDK 5. Just as @throws tags and the method throws clauses are 
complementary, so are the annotation and javadoc tag associated with 
deprecation. It would be awkward to perform javadoc processing on a 
string in an annotation.

Cheers,

-Joe