NEW PAGE

Javadoc Notes

literate programming, web idea by Knuth. very useful , but we ar e missing some crucial pieces. incremental up-date of single packages does not work.

Including the source code

Joel hacked together a system to include a link to the source code in a javadoc page. It uses the cgi script "incsource.cgi" in /sepwww/our/cgi-bin. To include the source code link in your javadoc, simply put the following line in your javadoc comment:

<!--#include file="./source.inc"-->

The inclusion seems to be broken currently.

Limitations/Warnings:

The script incsource.cgi figures out the name of the source code file from the name of the javadoc .html file. Thus, only classes which have the same name as their source-file can be used this way, i.e. this only works for one class per source file.
To view the javadoc pages with the source link in tact, you must use since the include directive doesn't seem to work with file.
It is important that the file source.inc be in the same directory as the javadoc files, and that it include the "java root directory" as the argument "javaroot" to the script incsource.cgi.

The system can be understood by looking at the files: incsource.cgi and source.inc. incsource.cgi should be in /sepwww/our/cgi-bin/ and source.inc should be in a jdocs/api directory.

Javadoc invocation

My standard invocation for javadoc is

 
javadoc -classpath  /usr/java/classes:/homes/sep/matt/jest 
        -sourcepath /usr/java/src:/homes/sep/matt/jest 
	-d          /homes/sep/matt/jest/jdocs/api 
	java.io java.lang ... rsf.vector rsf.util

The last list states all the packages for which I want to create a javadoc page. The classpath and the sourcepath let javadoc know where to look for these packages. The "-d" argument states where to put the generated html files.

I believe the class files have to be unzipped and the java source files have to available. To create javadoc pages for the official java API you need to get the java source code, unzip the class files, and include them in the javadoc invocation as shown above. I would like to know how to use zipped classes and to be independent of the source code.

The directory where I install the html pages needs some special care. I need to include the source.inc file for the source inclusion and I need to make a link to the images files for the various gifs that adorn the pages.

I use a combination of a makerule and a simple perl script to remake all javadoc documents from scratch. Given the class- and source path the script figures out all the packages that are included. Currently, the script searches for class files (suffix: .class) but I wonder if I should look for java source files (suffix: .java) instead. A simple make rule,

make javadocGlobal

, generates the list of all packages within subdirectories of the original path directory and creates javadoc html pages for all of them. It would be nice if we could keep the javadoc pages separate by package group (api, jag, book, etc) like we keep the corresponding java and class files.

Some errors remain

Currently, I use javadoc on our SGI, since its class and java files are easily accessible. My scripts require perl 5.000 or higher, which is not yet available on all our machines. In its own cryptic way, javadoc admits to 42 errors out of 2557 items. I am not sure if these are real errors.

Maintenance of the javadoc pages

I do not yet understand exactly when javadoc replaces the existing overview html pages, such as

packages.html

, when invoked. It would be nice to have new packages intelligently added to these overview documents without overwriting the already javadoc html. It seems that the lass hierarchy file is correctly updated rather than replaced.

It is difficult to remove javadoc generated html files when the underlying software becomes obsolete. I plan to remove all javadoc files from time to time.Afterwards I will reinstall the javadoc files from scratch. It would be nice to surgically remove, enhance, or replace individual packages.

What's wrong with javadoc

Javadoc in SGI JDK1.0.2 SGI's javadoc works pretty well. Unfortunately, it seems to mess up with the AllPackages file and the AllNames file. With these files, javadoc replaces instead of adds the information from a package. Thus, instead of giving information on all packages, these files only contain information on the latest package documented with javadoc. Ironically, the class hierarchy file is correctly updated rather than replaced.

Removing outdated .html files is difficult. Another problem with javadoc in general is removing documentation for a package. If you remove some classes from a package, and then redocument it with javadoc, I don't think that it removes the vestigial .html files, and I wonder if it removes the class from the class hierarchy.

Javadoc requires that we mix our javadoc files with the official API javadoc files so that they can crossreference. According to our Guru book, we need to have the API javadoc files mixed with our own javadoc files. You can either put everything all together or have many copies of the API files. (maybe we could do some fancy linking).

Local javadoc creation

I use make javadocLocal to temporarily create a javadoc representation of a package. In contrast to javadocGlobal, javadocLocal is restricted to a single package and does not change the overview packages, such as packages.html and tree.html.

Email from Joel

Since javadoc (as far as I can tell) currently screws up the all packages file by overwriting it with the latest javadoc-ed package instead of appending it, I wrote a simple perl script to generate the appropriate web page. It's also in makefile.inc, so packages.html is updated whenever we do make javadoc in a package directory (the main function of the javadoc target is, of course, to create docs for all the classes in the package).

Anyhoo, it's much better to have a central packages.html file instead of having to remember the name of the package you're looking for and typing it in.

The page isn't perfect, but click on Java in the lower left on your web page. Then click on Jag underneath Class Documentation near the bottom.

matt@hessen