Is @deprecated javadoc comment still useful?

Weijun Wang at
Thu Mar 9 00:12:03 UTC 2017

Hi Stuart

> This issue may be moot since this example
> ( is in a private package. I
> don't know if we deliver the javadoc output for this package. If not,
> then it doesn't really matter what you write for the @deprecated javadoc
> tag, or if you omit it entirely, though omitting it results in a doclint
> warning.

It does not show on the current javadoc page, but I am assigned the bug

   8175846: Provide javadoc descriptions for jdk.policytool and 
jdk.crypto.* modules

So maybe there will be a change?

> In general, though, I recommend that the text for the @deprecated
> javadoc tag have some background information and rationale about the
> deprecation. It's usually possible to come up with a simple statement or
> two; a big essay isn't required. For example, by reading the bug report
> for this deprecation (JDK-8147400), I was able to come up with the
> following:
>  * @deprecated PolicyTool has been deprecated for removal because it
>  * is rarely used, and it provides little value over editing policy
>  * files using a text editor.
> If this were a public API I'd definitely add something like this. It's
> up to you whether you think it's worth adding this to PolicyTool.

Good suggestion. I'll use it.


More information about the core-libs-dev mailing list