Is @deprecated javadoc comment still useful?
weijun.wang at oracle.com
Thu Mar 9 00:12:03 UTC 2017
> 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
It does not show on the current javadoc page, but I am assigned the bug
8175846: Provide javadoc descriptions for jdk.policytool and
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
> * @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.
More information about the core-libs-dev