@Deprecated(since) and Javadoc
stuart.marks at oracle.com
Thu Apr 21 21:54:43 UTC 2016
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
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.
More information about the core-libs-dev