@Deprecated(since) and Javadoc

[Stuart Marks]

On 4/21/16 9:51 AM, Paul Benedict wrote:
> Is there a requirement that the new "since" attribute on @j.l.Deprecated
> lead to an automatic JavaDoc @deprecated in the doc generation? It's a bona
> fide replacement, right?
>
> I'm just curious because I think, if that's true, @j.l.Deprecated should
> mention this tool coordination in its own JavaDoc header.

I'm not sure what you mean by "since" in the annotation leading to an 
"automatic" javadoc tag.

But to clarify, the @Deprecated annotation and the @deprecated javadoc tag are 
complementary; neither is a replacement for the other. The annotation contains 
"since" and "forRemoval" information and ends up in memory at runtime, since it 
has runtime retention. The javadoc tag should have descriptive text that 
explains the rationale for deprecation, risks of using, preferred alternatives, etc.

It should be considered an error to have the annotation without the javadoc tag 
and vice-versa. Javac does some checking in this regard, but it only does the 
check in one direction! The tools should check both. See

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

Aside from that, if you think something needs to be clarified in the doc for the 
@Deprecated annotation, please suggest it. Now's the time.

s'marks