Is @deprecated javadoc comment still useful?

[Stuart Marks]

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