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