classdoc - The reverse engineering Java API Documentation Generator

Generates HTML pages of API documentation from compiled .class or .jar files.

Copyright © Jens Gulden – mail@jensgulden.de
This software comes with absolutely NO WARRANTY. See file licence.txt for details.

CONTENTS

• Synopsis

• Description

  • Javadoc Doclets

  • Related Documentation

• Source Files

  • Package Directories

  • JAR Files

• Generated Files

• Example

• Limitations

• Environment

  • Java Virtual Machine

  • CLASSPATH

• See Also

SYNOPSIS

java -cp classdoc.jar;java_home/lib/tools.jar;dirs_or_jars classdoc -docpath dirs_or_jars ( -public | -protected | -packageprivate | -private ) (-1.1) (-doclet class) (-verbose) (-nofakepublic) [doclet-options]  |  -help

Options are:

-docpath dirs_or_jars

Directories and/or jar archive files containing the classes to be reverse-documented, separated by the system's path separator (i.e. ';' on Windows, ':' on UNIX etc.). All classes found in the specified directories or archives will be documented. Directories are searched recursively.
All directories and archives in the docpath must also be included in the classpath (see option '-cp'). See Example.

-public

Include only public classes and members in the documentation.

-protected (default)

Include all public and protected classes and members in the documentation.

-packageprivate

Include all non-private classes and members in the documentation.

-private

Include all classes and members in the documentation.

-doclet class

Specify a doclet class that generates the documentation output. By default, JDK1.3's Standard Doclet will be used. If you specify doclet, make sure it is accessible via the classpath.

-nofakepublic

The Standard Doclet refuses to include detailled member information in classes that are not considered public. To allow complete documentation, there is a workaround that makes any class that fits user's choice of -public/-protected/... to appear public to the doclet. This does, however, not affect the textual representation of the class's modifiers in the generated HTML. When using other doclets than the Standard Doclet, you may want to switch that workaround off by specifying the -nofakepublic option.

-1.1

Use JDK1.3's javadoc 1.1-style emulation doclet in place of the Standard Doclet.

-verbose

Output more detailled messages.

-help

Display help text.

The Standard Doclet's options are (options not named here are not recommended for use with classdoc):

-d output-directory

Destination directory for output files.

-splitindex

Generate multiple index files, one file per letter.

-windowtitle text

Title of browser window for the documentation.

-doctitle html-code

Title for the package.

-header html-code

Header text for each page.

-footer html-code

Footer text for each page.

-bottom html-code

Bottom text for each page.

-link url

Link to javadoc output at <url>.

-linkoffline url url2

Link to javadoc output at url using package list at url2.

-group name p1:p2..

Group packages together.

-notree

Do not generate class hierarchy tree.

-noindex

Do not generate index.

-nohelp

Do not generate link to help page.

-nonavbar

Do not generate navigation bar.

-charset charset

Charset for documentation.

-helpfile file

Use specified help file.

-stylesheetfile path

Style sheet file for generated documentation.

-docencoding name

Name of output encoding.

DESCRIPTION

classdoc parses compiled Java class files in directories or archive-files and produces a corresponding set of HTML pages describing classes, inner classes, interfaces, constructors, methods, and fields. By default, the public and protected fields and members are described. Classdoc does not need source codes to generate the documentation. You can reverse-engineer vitually any Java-written and compiled program.

An example is given at the end of this document.

As classdoc implements the Java Doclet API, it can incorporate any doclet to generate output in different formats. See See Javadoc Doclets.

When classdoc builds the documentation, it loads all classes referenced in the declarations of the classes in the docpath. This is the reason why classdoc must be able to load these classes from the classpath.

Javadoc Doclets

The content and format of classdoc's output can be customized by using doclets. By default, classdoc uses the Standard Doclet belonging to the javadoc-tool that ships with the Java Development Kit 1.3 to generate HTML-formatted API documentation. You can write your own doclet to generate whatever output format you'd like or you can download a third party doclet.

Related Documentation

• Javadoc Tool documenation for details about generating HTML-based API documentation and using doclets.

• Javadoc Enhancements for an overview on doclet technology.

• Doclet API for details on developing Doclets.

SOURCE FILES

Classdoc will generate output originating from compiled class files only. Source files neither have to nor even can be incorporated in generating classdoc's output.

Package Directories

Each directory that is contained in the docpath (see command line option -docpath) is recursively searched for class files. Any class that is found and that matches the desired access modifiers (-public/-protected/...) will be included in the documentation. Note that, as known from classpath settings, the structure of subdirectories in the specified directory must match the classes' package structure.

JAR Files

Each archive file that is contained in the docpath (see command line option -docpath) is searched for class files. Any class that is found and that matches the desired access modifiers (-public/-protected/...) will be included in the documentation.

Note: in order to make all classes in the docpath available to classdoc's class loader, any directory and archive included in the docpath must also be accessible in the classpath.

GENERATED FILES

By default, classdoc uses JDK 1.3's Standard Doclet to generate HTML-formatted documentation. This doclet generates two groups of files: those describing classes/interfaces (having the same name as the described item), and those that are internally generated parts of the HTML documenation. (E.g. package-summary.html). Internally generated files contain hyphens to prevent filenames to conflict with class / interface descriptions. Refer to the Generated Files section in the Javadoc Tool Documentation for more detailled information about files generated by the Standard Doclet.

EXAMPLE

The following example creates reverse engineered documentation of the classes in JDK's archive tools.jar, including all private classes and members. The HTML files are created in directory c:\tmp. Run this as a batch-file (.bat) on a Windows 9x system.

set CLASSDOC=d:\java\classdoc
set JAVA=d:\java\jdk1.3

set DOCPATH=%JAVA%\lib\tools.jar
set TARGET=c:\tmp

%JAVA%\bin\java -cp %JAVA%\lib\tools.jar;%CLASSDOC%\classdoc.jar;%DOCPATH% classdoc -docpath %DOCPATH% -private -d %TARGET% -windowtitle "tools.jar documentation - reverse engineered by classdoc" -header "Generated by <b>classdoc</b>" -verbose

(Note that here tools.jar appears twice in the classpath, because it is also the value of DOCPATH. This is to illustrate that both tools.jar and the classes to be documented must be part of the classpath. In this example, these are the same.)

LIMITATIONS

Some limitations and bugs apply to the current version:

• The generated HTML documentation does not contain hyperlinks (e.g. you cannot click on a method name to directly get to its documentation). This is considered a bug, as it affects the flexibility of navigation through the documentation. However, any information stays accessible through frame-based navigation.

• Inner class names are displayed with '$' as the delimiting character between the name of the corresponding outer class and the actual inner class's name. This matches the filename convention for class files. The actual Java language convention, however, uses a '.' like in 'outerClass.innerClass'.

• Names are sorted differetly than javadoc does. This way, in a sorted list classnames might appear in a different order than they would in a correspondig documentation generated by javadoc, if classnames starting with lower cases are involved. However, classes are usually not named in lowercase, so this is just an aesthetical question, no bug.

ENVIRONMENT

Java Virtual Machine

To run classdoc, use a Java Development Kit (JDK) 1.3 (or higher). A Java Runtime Environment (JRE) is not sufficient as it does not provide the classes of the Doclet API and the Standard Doclet.

CLASSPATH

The classpath should provide access to the following archives:

• <jdk1.3-installation-directory>/lib/tools.jar
  This archive contains the Doclet API interface classes and the Standard Doclet's classes.

• <classdoc-installation-directory>/classdoc.jar
  classdoc's classes.

• <directories-and-archives-from-docpath>
  All classes that are to be documented must both be present in the classpath and the docpath.

• Of course, the Java 2 API classes in archive rt.jar must also be part of the classpath. However, when using option -cp to specify additional classpath components, you do not need to take care about this.

SEE ALSO

Javadoc 1.3 Tool Documentation.

Please send comments to: classdoc@jensgulden.de