[news.eclipse.tools] Re: JavaDoc niggles

[erich_gamma@xxxxxxx (erich gamma)]

Regarding 1)
The JavaDoc hover for the JRE class is currently extracted 
from the source attachment. If the Eclipse Java runtime comes
with source, then the JDT will set-up everything
for you automatically. However, Eclipse ships with the 
IBM 1.3 JRE and in contrast to the JDK the JRE doesn\'t
come with the src.jar. It is not allowed change 
this, i.e., shipping the src.jar with a JRE. 
To reconfigure this yourself you can define a 
new VM Install with Sun\'s JRE and make this 
install the default JRE. This JRE will then
be used for building and launching your projects. 
Eclipse itself can still run on the IBM JRE. To do so:
1) Windows>Preferences>Java>Installed JREs
2) Add...
3) in the JRE Add dialog enter a name for the install 
   e.g. \"SUN JDK 1.3\" and enter the JRE home directory
4) back in the preference dialog change the default 
   JRE to the new install.

Once you have done that you can browse the source 
of the JRE and you get the Java Doc help hovers.

The alternative is to just add a 1.3 src.jar  
as the src for the IBM JRE install. Since the API 
and doc is the same no harm is done.
 
--erich

Jon Skeet wrote:

> 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