Eclipse IDE
Javadoc Configuration Tutorial

NOTE: Revised January 19 / 06

NOTE: These tutorial were done using Eclipse version 3.1

NOTE: In these tutorials we install Eclipse, workspaces and other files related to the tutorials in a directory called c:\eclipse31. If you are using another directory such as your home directory c:\Documents and Settings\username\eclipse31 you will need to replace c:\eclipse31 everywhere with your directory.

We assume that you have done the preceding Introductory Eclipse Tutorial and have created the two projects geoproject and geotesterproject.

Generating Java Documentation for a Project
Viewing Javadoc for the JDK API
Viewing Documentation in the Editor Window
Viewing Documentation from Source Code
Next Tutorial: Editor Configuration Tutorial


In this tutorial we show how to configure the javadoc program that comes with the Java Development Kit (JDK) so that you can create Java documentation for your own classes and projects We also show how to view the standard Java API documentation, within Eclipse, that you installed in the java installation notes.

Generating Java Documentation for a Project

To generate the Java documentation for a project you first need to tell Eclipse where to find the javadoc program and then tell it where the directory for the project documentation should be stored in your file system. In general the project documentation can be stored anywhere in your file system but to keep things simple we will generate it inside the project directory. One common convention is to store the documentation files in the project directory in a directory called docs or doc. We will follow this convention and use docs.

First let us generate Java documentation for project geoproject. If you closed these projects in the last tutorial please open them (right click on package name in the "Package Explorer" and select "Open Project").

Select project geoproject in the "Package Explorer" and from the "Project" menu select "Generate Javadoc..." to get the dialog box:

This dialog box shows the following changes.

If you are generating documentation for the first time it is necessary to specify the location of the javadoc command. If you installed the Java JDK in directory c:\Program Files\java then the full path to the javadoc command is

C:\Program Files\Java\jdk1.5.0_02\bin\javadoc.exe
If this is not shown in the "Javadoc command:" field you can enter it directly or click the "Configure..." button to obtain a dialog box in which you can navigate to javadoc.exe.

We have also selected project geoproject by placing a check mark in the box next to it if there isn't one already Finally, we have used the "Browse..." button to fill in the "Destination:" field. It shows

which specifies that the docs directory is inside our project directory (Note: the default directory is just doc and we have changed it to docs).

When your dialog box is as shown above click the "Finish" button

If the update box

appears click "Yes to All".

The documentation will now be generated. The progress and any errors is shown in the console window (sometimes errors can be fixed by generating the documentation again):

and the "Package Explorer" window now looks like

To obtain a more compact listing in the "Package Explorer" click the small white triangle at the right end of the "Package Explorer" toolbar, select "Layout" and select "Hierarchical"

This gives the more compact "package Explorer" view

showing the docs directory.

To view the documentation for project geoproject simply select the project in "Package Explorer" and from the "Navigate" menu select "Open External Javadoc" (or just select the project and press "Shift F2") and the browser will appear showing

Now Repeat the above steps for project geotesterproject to obtain the documentation for its class, CircleTester.

NOTE: Make sure the "Destination" field shows

The "Package Explorer" now looks like

Viewing Javadoc for the JDK API

To view the standard Java JDK API documentation for all the classes that come with Java open up the tree in the "Package Explorer" for the JRE System Library, select rt.jar (the runtime library)

From the "Navigate" menu select "Open External Javadoc" and you will see the Java API documentation. The default location of the documentation is Sun's website so the URL in the browser will be something like
We want to use our own local version of the documentation in
file:/C:/Program Files/Java/jdk1.5.0_04/docs/api/
so that we don't need to connect to the internet each time we want to view the documentation.

To make the change right click on the rt.jar entry in the "Package Explorer" and select "Properties" to get the dialog box

We need to change the URL in the "Javadoc location path". You can either type in the local value directly or use its browse button to navigate to

Click "OK" and you should have the dialog box

showing the local URL

file:/C:/Program Files/Java/jdk1.5.0_04/docs/api/

Click "Apply" and then "OK".

Now to see the API documentation select rt.jar and choose "Open External Javadoc" from the "Navigate" menu (shortcut is Shift F2). Your local URL will now be shown in the browser address bar.

Viewing Documentation in the Editor Window

It is possible to show Java documentation in the editor window. From the "Package Explorer" open the docs directory for project geoproject and double click the file index.html. The editor window will now show

Viewing Documentation From Source Code

Another way to view documentation for a particular class in your source code is to select the class name and the press "Shift F2". To try this load the file into the Editor. Select the word Point

Now press "Shift F2". The documentation for the Point class will now appear in a browser window.

In the same way you can also select a package name and the package documentation will appear.

Editor Configuration Tutorial

The next editor configuration tutorial shows how to configure the Eclipse Java editor and change some preferences.