@Deprecated(since) and Javadoc

[Stuart Marks]

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.

s'marks