Where is/how to setup SWT and JFace JavaDoc for eclipse 3.1?

[Slot Head]

Select a classname made by Sun and press F1 and we see a list of options including Show JavaDoc for classname. We've always gotten this with no effort in eclipse. Sadly, the same is not true with SWT and JFace.

With eclipse 3.0.x I found myself hunting down the javadoc for SWT buried deep in a plug-ins folder with a name that didn't make a lot of sense, but at least I could find it. I would then right click on the swt jar in my project, select Properties, navigate to the Javadoc. Then I had to do that for JFace too.

And, we had to do that for each and every project. Could the eclipse people make this a bigger PITB? Are they trying to emulate Microsoft and the way they butchered on line help with MSDN? I must be doing something wrong.

Now, with eclipse 3.1, I haven't been able to get this going again. Here's the issues I have:

1. Created a new SWT/JFace project. Jface.jar is visible, but where's SWT?

2. Where is the Javadoc for either of these in the 3.1 distribution? I am using the Javadoc we found in the 3.0.2 release, which we put in a separate folder so that we can delete the eclipse folder and cleanly reinstall eclipse and swt-designer from time to time.

I would really like to hear how fellow users of swt-designer manage to see JavaDoc for SWT and JFace classes. Eclipse and SWT-designer are brilliant products, so I can't believe something this utterly fundamental to developers s/b difficult to setup. I use Windows XP and 2000, but responses from Mac and Unix developers will be appreciated too.

So what does everybody do? Never need Javadoc? Another download from eclipse? Do you unzip anything? Do you put it in its own folder? Do you deploy files in a network share for your group of developers to use?

Thank you.

[Eric Clayberg]

This sort of question would be better addressed to the Eclipse SWT newsgroup.

1. Created a new SWT/JFace project. Jface.jar is visible, but where's SWT?

The org.eclipse.swt.win32.win32.x86_3.1.0.jar file should be in your Eclipse plugins directory.

2. Where is the Javadoc for either of these in the 3.1 distribution?

The SWT source (and Javadoc) is in the plugins\org.eclipse.rcp.source.win32.win32.x86_3.1.0\src\org.eclipse.swt.win32.win32.x86_3.1.0\src.zip directory.

The JFace source is in the plugins\org.eclipse.rcp.source_3.1.0\src\org.eclipse.jface_3.1.0\src.zip directory.

So what does everybody do? Never need Javadoc? Another download from eclipse?

I associate the above source files with the appropriate jars in the .classpath file. Like this...

<classpathentry sourcepath="ECLIPSE_HOME/plugins/org.eclipse.rcp.source.win32.win32.x86_3.1.0/src/org.eclipse.swt.win32.win32.x86_3.1.0/src.zip" kind="var" path="ECLIPSE_HOME/plugins/org.eclipse.swt.win32.win32.x86_3.1.0.jar"/>

[Slot Head]

Hi Eric, and thank you for the reply. I certainly agree that this question belongs on the Eclipse forums. I have tried it several times in several forms on their Newcomer, SWT and JDT forums. The answers were always very short and never worked. The eclipse people seem arrogant sometimes. The energy you put into your one reponse below blows away their total response effort to date.

Unfortunately, my problem has not been blown away.

1. You wrote: "The SWT source (and Javadoc) is in the plugins\org.eclipse.rcp.source.win32.win32.x86_3.1.0\src\org.eclipse.swt.win32.win32.x86_3.1.0\src.zip directory. "

I copied that file to another folder and unzipped it. I studied it. There is only one HTML file in it: about.html. I looked for other zip files buried in this. I tried right-clicking on the swt jar in my project, selecting Properties and then setting Javadoc location. No go. Are you sure the JavaDoc is in this file? What am I misunderstanding here?

2. You wrote:
"I associate the above source files with the appropriate jars in the .classpath file. Like this...

<classpathentry sourcepath="ECLIPSE_HOME/plugins/org.eclipse.rcp.source.win32.win32.x86_3.1.0/src/org.eclipse.swt.win32.win32.x86_3.1.0/src.zip" kind="var" path="ECLIPSE_HOME/plugins/org.eclipse.swt.win32.win32.x86_3.1.0.jar"/>"

Wow. Now this looks like a really valuable tip! I will certainly try this. Using the Navigator window, I looked at my .classpath file for a project. It begins with this text:

<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<classpathentry kind="src" path="src"/>
<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
<classpathentry kind="var" path="ECLIPSE_HOME/plugins/org.eclipse.osgi_3.1.0.jar"/>
<classpathentry kind="var" path="ECLIPSE_HOME/plugins/org.eclipse.ui.forms_3.1.0.jar"/>
<classpathentry kind="var" path="ECLIPSE_HOME/plugins/org.eclipse.core.runtime_3.1.0.jar"/>
<classpathentry kind="var" path="ECLIPSE_HOME/plugins/org.eclipse.swt.win32.win32.x86_3.1.0.jar"/>
<classpathentry kind="var" path="ECLIPSE_HOME/plugins/org.eclipse.jface_3.1.0.jar">
<attributes>
<attribute value="file:/C:/eclipse_doc/" name="javadoc_location"/>
</attributes>
</classpathentry>

That final attribute is how I used to hook up javadoc with 3.0.2.

My question about this is: can we simply add name="javadoc_location" and name="whereever the source is" attributes to this file to set things up? Can we do this when Eclipse is running?

My bigger question is, why does this, something completely fundamental to developing SWT/JFace with eclipse, have to be this mysterious and also have to be done for each and every project?

I would consider you and your crew at Instantiations true champions of the SWT world if you could automate this. If you can't do that, could you offer me some tips on automating this? I bought your book but haven't read it yet and know nothing about building plugins. I'm pretty familiar with JDOM, however, so writing a little app that parses and updates the classpath file might be doable for me.

Since this has to be done for each and every project, it would seem worth the effort, or am I missing something?

If we can't automate this, I plan on developing detailed instructions for exactly how to do it which I will give out to our group of developers so they can get back to doing what I pay them to do: develop. I would like to post drafts of these instructions here for review and community benefit.

Respectfully yours,
Bill Ewing

[Eric Clayberg]

I copied that file to another folder and unzipped it. I studied it. There is only one HTML file in it: about.html. I looked for other zip files buried in this. I tried right-clicking on the swt jar in my project, selecting Properties and then setting Javadoc location. No go. Are you sure the JavaDoc is in this file? What am I misunderstanding here?

Maybe I'm not sure what you are looking for. The Javadoc is just embedded in the source of the various SWT classes. If you want to know about a specific class like the SWT Button, you look at the Javadoc comments in the Button class. AFAIK, Eclipse just extracts that Javadoc info directly from the class source any time it needs to show you Javadoc for a class (either when you hover over a class name or have the Javadoc view open).

I don't know how hard or easy this would be to automate.

[Slot Head]

I figured it out. Incredibly, you cannot get this guidance from any of the eclipse forums.

All comments and corrections will be appreciated.

Here is an excerpt from a guidelines document I am distributing to my developers. Sorry, the images did not survive, but I think the text may be good enough.

I don't think anybody should have to spend the time I did figuring this out. I would like to suggest that Instantiations post something like this on its website, or better, automate this whenever File, New, SWT/JFace Project is invoked. That would add a lot of value and differentiate you from competitors. How hard would this be for you to do? Yes, Eclipse is general purpose and so is Designer, so the excuses for not doing this are well understood. But just look at how utterly essential and useful this is for anyone who has not memorized the entire SWT/JFace API (>95% percent of your users?), and also consider this would nned to be done for each and every project.

These instructions are narrowed to my company's specific environment in which we always install eclipse into c:\eclipse on windows PC's.

===========

1. Find the following file:
c:\eclipse\plugins\org.eclipse.platform.doc.isv_3.1.0\doc.zip

2. Create folder: c:\eclipse_doc. Making this independent from c:\eclipse avoids having to recreate it if eclipse is ever deleted. Unzip doc.zip into this folder.

3. In the Package Explorer window, find the SWT and JFace library jar files. Starting with Eclipse 3.1, swt.jar has been renamed to the file highlighted in the screenshot below. JFace, which is not machine dependent, is the file shown right below it.
(screenshot missing)

4. For each of the above jar files:
· Right click, select Properties.
· Select Java Build Path.
· Click on Browse.
· Navigate to C:/eclipse_doc/reference/api/
· Click on OK.

5. Click on Validate. Success looks like the following.
(screenshot missing)

6. Now do the real test. In the source editor, click on an SWT control class name such as Combo (you can simply declare one or make one visually using the designer). Press F1. A window should appear with Javadoc for 'org.eclipse.swt.widgets.Combo'

7. Don't forget to do the same for the JFace library as well. Test this with a JFace class such as ApplicationWindow.