Mr N

While setting up the Documentation Repository to house Javadocs, I have been doing a lot of work with Javadoc to generate Java API documentation and thought I’d show you how it’s done. Sun has produced loads of documentation for Javadoc, but it didn’t seem as straight forward as I would have thought it would have been!

The first thing you need to know is that Javadocs works in packages and not source files. Once you have got this all the documentation is a little more understandable.

The Javadocs program comes with the Java Development Kit (JDK), so you must get a hold of that.

Next, set up the environment. The environment variable JAVA_HOME tells the Java programs where to find their libraries, and the PATH tells your command shell where to find the programs. Under Windows:

set JAVA_HOME=C:\Java\j2sdk1.4.2_07
set PATH=%JAVA_HOME%\bin;%PATH%

Or under Unix:

export JAVA_HOME=/usr/local/jdk1.6.0_07
export PATH=$JAVA_HOME:$PATH

Now we need to get packages. Under windows, we will need to issue the dir command with the following options:

dir /b/on/ad/s src > packages.txt

/b: Uses bare format (no heading information or summary)
/on: sorts by name
/ad: only list directories
/s: search sub directories
src: top level directory of source files

or if you love Unix:

find src -type d -print > packages.txt

Once you have your list of packages we can run the Javadoc program to generate the API documentation for each of the packages from the source. Below is the command to do this. The backslashes are Unix-speak for new line breaks:

javadoc \
-sourcepath src \
-d dest \
-windowtitle “JavaDoc Documentation Repository - JacORB 2.2.4″ \
@packages.txt

-sourcepath <dir>: top level directory of source files
-d <dir>: directory where to put the API documentation (the output)
-windowtitle <title>: what to put in the title of the each of the generated HTML pages
@<file>: name of the file where the package names are held.

And there you have it!