Is @deprecated javadoc comment still useful?

[Remi Forax]

---- Mail original -----
> De: "Weijun Wang" <weijun.wang at oracle.com>
> À: "Stuart Marks" <stuart.marks at oracle.com>
> Cc: "Java Core Libs" <core-libs-dev at openjdk.java.net>
> Envoyé: Mercredi 8 Mars 2017 01:15:10
> Objet: Is @deprecated javadoc comment still useful?

> Hi, Mr Deprecator

I'm not Dr Deprecator :)

> 
> I'm adding @Deprecated annotations with arguments to a module and a
> class, and at the same time I add @deprecated javadoc comments. The
> resulting javadoc pages are attached.

attachments are skipped by the mailer daemon :(

> 
> As you can see, the bold sentence (I assume it's generated from the
> annotation) and the line below contain the exact same information.
> However, they do not use the exact same words: subject vs planned,
> version vs release. This makes me uncomfortable.
> 
> I've tried to remove the content of the javadoc comment and only keep
> the @deprecated tag, the result looks better.
> 
> Is that the right way?
> 

Usually, the annotation @Deprecated says that the class/member/etc is deprecated, and the javadoc @deprecated indicates how to fix the issue by by example providing a replacement.

> Thanks
> Max

cheers,
Rémi