Is @deprecated javadoc comment still useful?

[Weijun Wang]

Hi Stuart

>
> This issue may be moot since this example
> (sun.security.tools.policytool.PolicyTool) 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.

Thanks
Max