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.
Objective
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.
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:
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.exeIf 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
c:\eclipse31\e-workspaces\workspace\geoproject\docswhich 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
c:\eclipse31\e-workspaces\workspace\geotesterproject\docsThe "Package Explorer" now looks like
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
http://java.sun.com/j2se/1.5.0/docs/api/index.htmlWe 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.
docs directory
for project geoproject and double click the file
index.html. The editor window will now show
Circle.java into the
Editor. Select the word Point
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.
The next editor configuration tutorial shows how to configure the Eclipse Java editor and change some preferences.