@Deprecated(since) and Javadoc

[Paul Benedict]

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.
On Apr 21, 2016 4:54 PM, "Stuart Marks" <stuart.marks at oracle.com> wrote:

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