Is @deprecated javadoc comment still useful?

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Is @deprecated javadoc comment still useful?

Weijun Wang
Hi, Mr Deprecator

I'm adding @Deprecated annotations with arguments to a module and a
class, and at the same time I add @deprecated javadoc comments. The
resulting javadoc pages are attached.

As you can see, the bold sentence (I assume it's generated from the
annotation) and the line below contain the exact same information.
However, they do not use the exact same words: subject vs planned,
version vs release. This makes me uncomfortable.

I've tried to remove the content of the javadoc comment and only keep
the @deprecated tag, the result looks better.

Is that the right way?

Thanks
Max

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Is @deprecated javadoc comment still useful?

Remi Forax
---- Mail original -----
> De: "Weijun Wang" <[hidden email]>
> À: "Stuart Marks" <[hidden email]>
> Cc: "Java Core Libs" <[hidden email]>
> Envoyé: Mercredi 8 Mars 2017 01:15:10
> Objet: Is @deprecated javadoc comment still useful?

> Hi, Mr Deprecator

I'm not Dr Deprecator :)

>
> I'm adding @Deprecated annotations with arguments to a module and a
> class, and at the same time I add @deprecated javadoc comments. The
> resulting javadoc pages are attached.

attachments are skipped by the mailer daemon :(

>
> As you can see, the bold sentence (I assume it's generated from the
> annotation) and the line below contain the exact same information.
> However, they do not use the exact same words: subject vs planned,
> version vs release. This makes me uncomfortable.
>
> I've tried to remove the content of the javadoc comment and only keep
> the @deprecated tag, the result looks better.
>
> Is that the right way?
>

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.

> Thanks
> Max

cheers,
Rémi

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Is @deprecated javadoc comment still useful?

Weijun Wang
Hi Remi

On 03/08/2017 06:10 PM, Remi Forax wrote:
>
> attachments are skipped by the mailer daemon :(

That's bad.

The module 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.

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.

The first lines are *bold*.

>
> 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?

Thanks
Max
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: 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
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Is @deprecated javadoc comment still useful?

Weijun Wang
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 | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Is @deprecated javadoc comment still useful?

Stuart Marks


On 3/8/17 4:12 PM, Weijun Wang wrote:
> 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?

Hm, it looks like somebody is running javadoc over these packages, otherwise I
doubt it would have been noticed.

>>  * @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.

Great, glad to help!

s'marks

Loading...