On 3/8/17 2:38 AM, Weijun Wang wrote:
The class page has:
*Deprecated, for removal: This API element is subject to removal in a future
version.*
The policytool tool has been deprecated and is planned to be removed in a future
release.
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.
But here I have nothing to say.
So, can I just write a bare @deprecated?
Clearly, it's not useful to have text after @deprecated that duplicates the
boilerplate that javadoc adds. That boilerplate was added fairly recently, so
that may be why nobody noticed it before.
The text for the @javadoc tag doesn't need to say that the API is deprecated,
nor should it say (if forRemoval=true) that it's subject to removal, since these
are both already covered by the javadoc boilerplate text.
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.
(By the way, you should add since="9" to the @Deprecated annotations here.)
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.
s'marks
