Javadoc @link bugs

I think the sad reality is that the vast majority of Java programmers don't
bother to write JavaDocs at all. Or if they do, it's just enough to satisfy
some sort of automated checking tool like CheckStyle, without any meaningful
content. That's why so few people run into this issue. Before I descend into
a rant, there are two ways I've worked around this:
1) keep the entire @link on one line. If you've imported a class you can use
the unqualified class name instead of the fully qualified one, which helps
to keep it from getting too long to fit on a line.
2) put references in @see tags instead, and leave what was in the @link tag
as plain text. If you mentioned a class name in the text of the old @link,
make sure you allow IDEA to search through comments and strings when
refactoring - that should pick it up.

Hope that helps,
Vil.

Keith Lea wrote:

The IDEA tracker has two bugs related to multiline @link tags:

http://www.intellij.net/tracker/idea/viewSCR?publicId=4800
http://www.intellij.net/tracker/idea/viewSCR?publicId=9802

One is marked fixed and the other was filed for build 690 and is still in Submitted state. I've always had problems with multiline {@link tags, like:

  * [...]
>  * also the only known way to retrieve a buddy's {@linkplain 
>  * net.kano.joscar.snaccmd.InfoData#getCertificateInfo() security information}.
>  */]]>

In that piece of code, IDEA does not recognize that either InfoData or getCertificateInfo are symbols (I cannot ctrl-click them, etc.). Javadoc itself recognizes that as a valid {@linkplain} tag - why doesn't IDEA?

This has always been a real annoyance for me (renaming a method does not rename references in multiline link tags, etc.) but I never bothered to file an SCR. But judging from the state those two SCR's, maybe I'm the only one having these problems?

Does this happen to anyone else? Am I doing something wrong?

--
Vilya Harvey
vilya.harvey@digitalsteps.com / digital steps /
(W) +44 (0)1483 469 480
(M) +44 (0)7816 678 457 http://www.digitalsteps.com/

Disclaimer

This e-mail and any attachments may be confidential and/or legally
privileged. If you have received this email and you are not a named
addressee, please inform the sender at Digital Steps Ltd by phone on
+44 (0)1483 469 480 or by reply email and then delete the email from
your system. If you are not a named addressee you must not use,
disclose, distribute, copy, print or rely on this email. Although
Digital Steps Ltd routinely screens for viruses, addressees should
check this email and any attachments for viruses. Digital Steps Ltd
makes no representation or warranty as to the absence of viruses in this
email or any attachments.

Vilya Harvey wrote:

1) keep the entire @link on one line. If you've imported a class you can
use the unqualified class name instead of the fully qualified one, which
helps to keep it from getting too long to fit on a line.

Not an option if you want to rewrap comments automatically (using the
javadoc formatter plugin, for example)...

2) put references in @see tags instead, and leave what was in the @link
tag as plain text. If you mentioned a class name in the text of the old
@link, make sure you allow IDEA to search through comments and strings
when refactoring - that should pick it up.

I guess this could work, if you always make sure to update the @see
references so they are in sync with the main text, and if you are
willing to search through comments/strings and then manually remove all
the instances that should not be changed so IDEA doesn't alter them.

I'm not really complaining about the workarounds -- they're just about
the best thing you can do given the way IDEA works right now. I'm just
saying this is a silly bug which ought to be trivial to fix in order to
save us all a lot of extra work. At the very least it ought to be
planned for Aurora.

+1

No argument here.

Vil.


Jonas Kvarnström wrote:

I'm not really complaining about the workarounds -- they're just about
the best thing you can do given the way IDEA works right now. I'm just
saying this is a silly bug which ought to be trivial to fix in order to
save us all a lot of extra work. At the very least it ought to be
planned for Aurora.

--
Vilya Harvey
vilya.harvey@digitalsteps.com / digital steps /
(W) +44 (0)1483 469 480
(M) +44 (0)7816 678 457 http://www.digitalsteps.com/

Disclaimer

This e-mail and any attachments may be confidential and/or legally
privileged. If you have received this email and you are not a named
addressee, please inform the sender at Digital Steps Ltd by phone on
+44 (0)1483 469 480 or by reply email and then delete the email from
your system. If you are not a named addressee you must not use,
disclose, distribute, copy, print or rely on this email. Although
Digital Steps Ltd routinely screens for viruses, addressees should
check this email and any attachments for viruses. Digital Steps Ltd
makes no representation or warranty as to the absence of viruses in this
email or any attachments.

In article <bl0u95$e03$1@is.intellij.net>,
Vilya Harvey <vilya.harvey@digitalsteps.com> wrote:

I think the sad reality is that the vast majority of Java programmers don't
bother to write JavaDocs at all.

One problem with JavaDocs (and all other comments) is that they can get
out of date easily. A wise man once said: "Comments lie. Code doesn't."

IMHO, many methods don't require JavaDoc comments because they are
private and are implemented in a clear fashion, or because they are
getters/setters. But there are public methods that one sometimes wants
to explain, so sometimes JavaDoc comments are indeed necessary.


I've just thought of a way IDEA can help with this: when you modify a
method body, the JavaDoc comments could be marked as a warning (yellow
underline or whatever, plus a yellow mark to the right of the
scrollbar).

The warning message would be something like: "Method body changed;
please inspect JavaDoc comment." The intention lightbulb menu would
contain an item for "Inspect JavaDoc comment" which would open a diff
window with the previous version of the method (with JavaDoc comment) in
the left pane; and an editable pane on the right with the new code and
JavaDoc comment, with the text cursor blinking in the JavaDoc comment
area so you know you can edit it. You read the comment, maybe change it,
and then press the "OK" button on the diff window and the warning goes
away.

This proposed feature would be a pain in the butt, but I think it would
improve the chances of having correct JavaDoc comments. Does anyone else
think it's a good enough idea to submit to the tracker? Or do you think
you'd get so tired of the warnings that you'd turn the feature off?


Erik

It would make a good plugin....


Erik Hanson wrote:

In article <bl0u95$e03$1@is.intellij.net>,
Vilya Harvey <vilya.harvey@digitalsteps.com> wrote:

>>I think the sad reality is that the vast majority of Java programmers don't
>>bother to write JavaDocs at all.

One problem with JavaDocs (and all other comments) is that they can get
out of date easily. A wise man once said: "Comments lie. Code doesn't."

IMHO, many methods don't require JavaDoc comments because they are
private and are implemented in a clear fashion, or because they are
getters/setters. But there are public methods that one sometimes wants
to explain, so sometimes JavaDoc comments are indeed necessary.


I've just thought of a way IDEA can help with this: when you modify a
method body, the JavaDoc comments could be marked as a warning (yellow
underline or whatever, plus a yellow mark to the right of the
scrollbar).

The warning message would be something like: "Method body changed;
please inspect JavaDoc comment." The intention lightbulb menu would
contain an item for "Inspect JavaDoc comment" which would open a diff
window with the previous version of the method (with JavaDoc comment) in
the left pane; and an editable pane on the right with the new code and
JavaDoc comment, with the text cursor blinking in the JavaDoc comment
area so you know you can edit it. You read the comment, maybe change it,
and then press the "OK" button on the diff window and the warning goes
away.

This proposed feature would be a pain in the butt, but I think it would
improve the chances of having correct JavaDoc comments. Does anyone else
think it's a good enough idea to submit to the tracker? Or do you think
you'd get so tired of the warnings that you'd turn the feature off?


Erik

Erik Hanson wrote:

In article <bl0u95$e03$1@is.intellij.net>,
Vilya Harvey <vilya.harvey@digitalsteps.com> wrote:

>>I think the sad reality is that the vast majority of Java programmers don't
>>bother to write JavaDocs at all.

One problem with JavaDocs (and all other comments) is that they can get
out of date easily. A wise man once said: "Comments lie. Code doesn't."

I've heard the same said before and it's not true. Code can lie. It can
have bugs, or it can just be non-obvious what the code does. Or the code
might appear to perform correctly, but fail on border cases. It's definitely
true that JavaDoc can get out of date with what the code is supposed to be
doing; but the same can be said of the code. Not all code does what it's
supposed to do. Unfortunately. :)

I advocate the use of JavaDoc as a plain-text specification of what a method
is supposed to do. It shouldn't have any details about how the method
actually does it. I've found that in most cases, JavaDoc of that kind
requires fewer changes than you might think to keep it current. That's
purely subjective though - my own opinion, based on my own experience.

IMHO, many methods don't require JavaDoc comments because they are
private and are implemented in a clear fashion, or because they are
getters/setters. But there are public methods that one sometimes wants
to explain, so sometimes JavaDoc comments are indeed necessary.

I agree, in part. Many getters and setters are so trivial that there's no
real benefit to documenting them. I personally think JavaDoc should be used
for more than just public methods though: protected, package and private
methods can need it just as much IMO. One place which is very important is
methods which are designed to be overridden. But I do agree that not all
methods need it.

I've just thought of a way IDEA can help with this: when you modify a
method body, the JavaDoc comments could be marked as a warning (yellow
underline or whatever, plus a yellow mark to the right of the
scrollbar).

The warning message would be something like: "Method body changed;
please inspect JavaDoc comment." The intention lightbulb menu would
contain an item for "Inspect JavaDoc comment" which would open a diff
window with the previous version of the method (with JavaDoc comment) in
the left pane; and an editable pane on the right with the new code and
JavaDoc comment, with the text cursor blinking in the JavaDoc comment
area so you know you can edit it. You read the comment, maybe change it,
and then press the "OK" button on the diff window and the warning goes
away.

This proposed feature would be a pain in the butt, but I think it would
improve the chances of having correct JavaDoc comments. Does anyone else
think it's a good enough idea to submit to the tracker? Or do you think
you'd get so tired of the warnings that you'd turn the feature off?

Interesting idea! I'd like to try it out and see how well it works. I think
there probably would be a lot of people that just switched it off
immediately and others would just click through it by rote each time. For
the rest though, it might be a useful reminder.

I don't think it would be possible to implement as a plugin just yet: I
don't think the necessary LVCS hooks are part of the OpenAPI & I'm not sure
whether the diff window hooks are there either. (I don't know the OpenAPI
very well yet, so I'd love to be corrected on that). I couldn't see this
functionality being very high on JetBrains' list of priorities, so it
probably would be best done as plugin.

Vil.
--
Vilya Harvey
vilya.harvey@digitalsteps.com / digital steps /
(W) +44 (0)1483 469 480
(M) +44 (0)7816 678 457 http://www.digitalsteps.com/

Disclaimer

This e-mail and any attachments may be confidential and/or legally
privileged. If you have received this email and you are not a named
addressee, please inform the sender at Digital Steps Ltd by phone on
+44 (0)1483 469 480 or by reply email and then delete the email from
your system. If you are not a named addressee you must not use,
disclose, distribute, copy, print or rely on this email. Although
Digital Steps Ltd routinely screens for viruses, addressees should
check this email and any attachments for viruses. Digital Steps Ltd
makes no representation or warranty as to the absence of viruses in this
email or any attachments.