[news.eclipse.tools] Re: JavaDoc niggles

["Carolyn MacLeod" <Carolyn_MacLeod@xxxxxxx>]

I do not have any info on point #1 - hopefully someone else can say why we
don't ship the IBM JRE source - I personally would like to see it ship.  :)
I am looking at #2 to try to reproduce the problem.
For #3, I don't think having multiple Javadoc comments for a class is legal
Javadoc, but I don't see anything that explicitly says that on Sun's
"Writing Javadoc Comments" web page:
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
I have opened a PR for your point #4:
    1GIV7MH: ITPJUI:ALL - EC DCR: Javadoc hoverhelp could be prettier
Carolyn

"Jon Skeet" <skeet@xxxxxxxxx> wrote in message
news:MPG.15ec41817ff98224989697@xxxxxxxxxxxxxxxxxxx
> I really like having the JavaDoc come up on hover, but there are a few
> problems (some of which may be entirely user-error):
>
> 1) I can't find a way to link to JRE JavaDocs. I presume I could set the
> source of the JRE, but I only have the source to the Sun 1.3 JRE, and
> without changing to use that for Eclipse itself (or the launcher), I'd
> rather not link the wrong source in place. I dare say I could find the
> IBM 1.3 JRE source somewhere, but it would be nice to be able to just
> say where JRE documentation is. I realise this may well be out of the
> scope of whatever keeps track of JavaDoc comments.
>
> 2) Sometimes the help just doesn't come up - I can hover over a method
> name and nothing happens. Move the mouse cursor off and on again and it
> shows up...
>
> 3) The wrong documentation is picked if there are two bits available.
> For instance:
>
> public class Test
> {
>     /** This isn't really documentation */
>
>     /**
>      * This is a method
>      *
>      * @param x This is a parameter
>      */
>     public void method (int x)
>     {
>     }
>
>     public static void main (String [] args)
>     {
>     new Test().method(5);
>     }
> }
>
> Hovering over the method call, you see "This isn't really
> documentation" instead of the "This is a method" bit. Sure, it's nasty
> code, but it's worth getting right :)
>
> 4) The way of displaying the documentation itself is a bit ugly - I see
> that *some* HTML is noticed (eg <br>) but other stuff isn't (eg <i>). I
> realise this may be due to this nature of whatever's displaying the
> docs. Also, just displaying the @param etc tags isn't nearly as nice as
> laying out the parameters properly, as I believe some other IDEs do. My
> guess is that this bit is still a work in progress, but I thought I'd
> raise it anyway :)
>
> --
> Jon Skeet - <skeet@xxxxxxxxx>
> http://www.pobox.com/~skeet/
> If replying to the group, please do not mail me too