Package satin.tools.doclets.satinapi

This is the standard Satin doclet for generating the official API documentation in HTML form for interactive browsing.

See:
Description

Class Summary

Standard

The class with "start" method, calls individual Writers.

Package satin.tools.doclets.satinapi Description

This is the standard Satin doclet for generating the official API documentation in HTML form for interactive browsing. It is based on Sun's standard doclet, and extends or modifies its functionality in the following ways:

• Supports the @history tag for producing Revision Histories.
• Puts static final class variables in a separate "Constants" section.
• Generates file version information, optionally taken from ClearCase.
• Generates a list of sub-packages in each package overview page.
• Assorted minor cosmetic improvements in the generated documentation.

Source File Tags

This doclet recognizes the following special source file tags, in addition to the ones recognized by the standard doclet:

@history date name [changeRecordID] - comment

You should place these tags somewhere in the JavaDoc comment for a class. (They are not recognized in comments for fields or methods.) They are gathered up in the order they are encountered, and placed in at the bottom of the generated document under the heading "Revision History". The change record ID should be a decimal number prefixed with the number sign "#". For example:

@history 7/24/01 Ed Stauff #987 - rewrote everything in Python.
@history 1/1/01 Ed Stauff - file created.

History tags should be ordered with the most recent one first, the oldest one last.
Note: the date, name and changeRecordID fields are currently not enforced, but you should observe the proper formatting for future compatability.

Command Line Options

This doclet recognizes the following special command line options, in addition to the ones recognized by the standard doclet:

-clearcase

If this option is given, then for each class, the doclet will attempt to locate the source file in which the class was defined, and execute the command "cleartool describe" on the file. The information obtained from this command will be used to generate version number information at the very bottom of the documentation file. This information will look something like this:

Generated on 15/5/2001 18:10 from MyClass.java version main/4 15-5-01.03.16.45

In order for this to work, the source files must be in a "live" ClearCase view. If this option is not given, then version information is still generated, but noted with "(PRIVATE SOURCES)". For example:

Generated on 15/5/2001 18:10 from MyClass.java (PRIVATE SOURCES)

Source files are located according to the usual JavaDoc rules:

1. If the "-sourcepath" option is given, then that path is used.
2. Otherwise, if the "-classpath option is given, then that path is used.
3. Otherwise, the CLASSPATH environment variable is used.

Note: this option should always be used when generating "official" documentation for publishing on the Satin web site.

A Useful Shell Script

In the source directory for this doclet you will find a Korn Shell script called "generate.ksh". It invokes JavaDoc with all the proper options for generating official public documentation. It takes two arguments: the directory containing the "satin" source directory, and a directory in which the generated documentation will be placed. Note that this script deletes the entire contents of the destination directory before running JavaDoc!

Revision History

6/15/01 Ed Stauff - file created.