Is @deprecated javadoc comment still useful?

Remi Forax forax at
Wed Mar 8 10:10:29 UTC 2017

---- Mail original -----
> De: "Weijun Wang" < at>
> À: "Stuart Marks" <stuart.marks at>
> Cc: "Java Core Libs" <core-libs-dev at>
> 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


More information about the core-libs-dev mailing list