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

Reply via email to