eJavaDoc: Documentation Enhancer for Java

Who is IBM Documentation Enhancer for Java intended for?

This application is intended for Java developers. It provides them with extended information about libraries and applications they obtain, but don't have the source code for.

The application can also be used by Java library developers who wish to provide their clients with a richer documentation of the APIs they develop.

Simply create a pruned version of your Javadoc documentation, which contains only the classes and packages you care about. Run the Documentation Enhancer with the pruned version as source, and use the result to overwrite a copy of the source.

The main causes of failures are erroneous Javadoc HTML files. Errors in the Javadoc HTML files result from the fact that programmers can add their own HTML tags to the Javadoc comments (which are used to generate the Javadoc files), and this is not always done correctly (consider, for example, the documentation of the method toString(double d) of class java.lang.Double in Sun's JDK 1.2.2). Besides that, incorrect parsing may result from version variations in Javadoc's output format, or simply (we hate to admit) from our bugs.

When the parsing of a Javadoc HTML file fails, the original (unenhanced) file is copied unchanged to the target location. The file errors.log in the destination folder contains the list of failed files.

However, when the error message in errors.log is 'No more DTM IDs are available', you probably do not have enough virtual memory. Try enhancing the allocated virtual memory by changing the -X Java parameters in enhance.bat.

The Documentation Enhancer requires the following files:

1. The analyzed component's Javadoc HTML files.
2. The JAR file containing the analyzed component.
3. The JAR and/or class files that are required by the analyzed component (e.g., files for classes that are superclasses of those in the analyzed component; files containing classes that are the types of fields in the analyzed component; and so forth).
4. The product's own libraries, including toad.jar and serveral other JAR files that are shipped with the Documentation Enhancer distribution.

The information added by the Documentation Enhancer includes references to methods that could be private, or with package-level access only. These methods are normally not included in the Javadoc documentation, but they do exist.

We have successfully run the Documentation Enhancer on the entire JDK 1.3 runtime library (over 5,000 classes and interfaces, about 1,800 of them public). However, the current version does not properly handle the entire JDK 1.4 runtime library (over 8,000 classes and interfaces, about 2,700 of them public). We plan to meet this challenge in a future release.

Realistically, this means that the product will correctly handle almost any existing Java class library.

Print this page