The Standard Doclet

Javadoc 1.4

Contents

• What the Standard Doclet Is
• Classes in the Standard Doclet
• Running the Standard Doclet from the Command Line
• Running the Standard Doclet Programmatically
• The Source for the Standard Doclet

What the Standard Doclet Is

The standard doclet is the doclet provided by Sun that produces Javadoc's default HTML-formatted API output. The API documentation for the Java platform in this SDK documentation is an example of the standard doclet's output. Javadoc uses the standard doclet if no other doclet is specified using Javadoc's -doclet option on the command line.

One reason to look at the standard doclet is that it serves as a good example of the use of much of the doclet API. A second reason is that by seeing how the standard doclet produces the default HTML output, it will be easier for you to modify the standard doclet to make your own doclet for generating custom API documentation.

Classes in the Standard Doclet

The standard doclet is composed of the classes in the com.sun.tools.doclets, com.sun.tools.doclets.standard and com.sun.tools.doclets.standard.tags packages. Classes in the standard doclet that play key roles in generating the default HTML output are summarized here:

com.sun.tools.doclets

• HtmlWriter - This class contains APIs for writing the various HTML tags needed for generating any output in HTML form.
• HtmlDocWriter - This class extends HtmlWriter, and contains additional HTML-related APIs for producing the specialized hyperlinks used in the default HTML output, including links in the headers and footers of the HTML pages.
• Taglet - An interface that represents a class used to format the ouput of a tag. You can develop a Taglet to format the output of your custom tags. For more information about Taglets, please see the taglet overview.
• TagletManager - This class manages the Taglets being used by the doclet. It has methods for registering Taglets, retrieving Taglets and checking whether or not a tag is known by the TagletManager (used for error checking). The TagletManager also checks for tags that are used in the wrong places. For example, a warning message is printed if a @param tag is used in class documentation because that tag should only be used in constructor and method documentation.

com.sun.tools.doclets.standard

• Standard - This class contains the start method and hence serves as the entry point for the standard doclet. It orchestrates the generation of the HTML API files for the packages and classes upon which javadoc is operating.
• PackageIndexWriter - This class generates the overview-summary.html file that lists all packages specified on the javadoc command line. As an example, see the overview-summary.html file in the API documentation for this Java Development Kit.
• PackageIndexFrameWriter - This generates the overview-frame.html file used for displaying the list of package links in the upper-left frame in the frame-formatted default output. See the overview-frame.html file in the API documentation of this release of the SDK documentation.
• PackageFrameWriter - This generates the package-frame.html file that lists the interfaces and classes in a given package for displaying in the lower-left frame of the frame-formatted default output. As an example of this type of page, see the package-frame.html file for java.awt in the API documentation of this release of the platform API documentation.
• FrameOutputWriter - This generates the index.html file used for presenting the frame-formated "cover page" of the API documentation. See the index.html file from the platform API documentation as an example. files that list the interfaces and classes for a given package. For an example of this type of page, see the page for java.lang in the API documentation of this release.
• ClassWriter - This generates the HTML API documentation for each individual interface and class. For an example from the Java 2 Platform API documentation, see Font.html.
• SingleIndexWriter - This generates the single index file of class members that the standard doclet produces when the -splitindex option is not used.
• SplitIndexWriter - This generates the mutliple index files for the class members that is generated when the Javadoc runs the standard doclet with the -splitindex command-line option. The files are numbered such as index-1.html.
• TreeWriter - This class generates the overview-tree.html file that lists the Class Hierarchy for the classes upon which the standard doclet operates. For an example from the Java 2 Platform API documentation, see overview-tree.html.
• DeprecatedListWriter - This generates the file deprecatedlist.html which lists deprecated APIs. As an example, see the deprecated-list.html file from the API documentation in this release.
• ClassUseMapper, ClassUseWriter, and PackageUseWriter - These classes generate the "Use" files for classes and packages. Click the "Use" link in the navigation bar to go to a class or package "use" page. Examples of such pages are those for class Character and package java.lang.
• PackageListWriter - generates the package-list text file that gets placed in the top-level directory of the API documetation. This file is required for use with standard doclet's -link command-line option. Standard doclet class Extern also plays a role in making the -link option work. See the Javadoc reference pages ([Windows] [Solaris]) for details about this option.
• Group - This class handles the grouping of packages in one or more tables on the overview-summary.html page. It supports the standard doclet's -group command-line option. See the Javadoc reference pages ([Windows] [Solaris]) for details about this option.

com.sun.tools.doclets.standard.tags

• AbstractExecutableMemberTaglet - This is an abstract Taglet that formats the output for a tag used in documentation for executable members.
• AbstractInlineTaglet - This is an abstract Taglet that formats the output for an inline tag. You should subclass this abstract class if you would like to create your own custom inline tag.
• DocRootTaglet - A taglet that formats the output for {@docRoot}.
• InheritDocTaglet - A taglet that formats the output for {@inheritDoc}.
• ParamTaglet - A taglet that formats the output for @param.
• ReturnTaglet - A taglet that formats the output for @return.
• SeeTaglet - A taglet that formats the output for @see.
• SimpleTaglet - A taglet that formats the output for single argument tags such as @author and @version.
• ThrowsTaglet - A taglet that formats the output for @throws.
• ValueTaglet - A taglet that formats the output for {@value}.

For more information about Taglets, please see the taglet overview.

Running the Standard Doclet from the Command Line

The standard doclet is invoked by default when no other doclet is specified with the -doclet tag on the command line. For example, running

% javadoc myPackage

will use the standard doclet to produce the default-style HTML API documentation for myPackage. Running javadoc without the -doclet option is equivalent to running javadoc using the -doclet option to invoke the standard doclet. That is, the above command is equivalent to

% javadoc -docletpath /home/user/j2sdk1.4.0/lib/tools.jar \
  -doclet com.sun.tools.doclets.standard.Standard \
  myPackage

Running the Standard Doclet Programmatically

The Javadoc tool has a programmatic interface with public methods for invoking the Javadoc tool from another program written in the Java language. These methods are located in class com.sun.tools.javadoc.Main in lib/tools.jar. An example is given below.

The disadvantages of calling main are: (1) It can only be called once per run -- for 1.2.x or 1.3.x, use java.lang.Runtime.exec("javadoc ...") if more than one call is needed, (2) it exits using Systme.exit(), which exits the entire program, and (3) an exit code is not returned.

public static void main(java.lang.String[] args)

Command line interface.

Parameters:

args - The command line parameters.

The execute method overcomes all the disadvantages of main.

public static int execute(java.lang.String[] args)

Programmatic interface.

Parameters:

args - The command line parameters.

Returns:

The return code.

public static int execute(java.lang.String programName,
                          java.lang.String[] args)

Programmatic interface.

Parameters:

programName - Name of the program (for error messages).

args - The command line parameters.

Returns:

The return code.

public static int execute(java.lang.String programName,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)

Programmatic interface.

Parameters:

programName - Name of the program (for error messages).

defaultDocletClassName - Fully qualified class name.

args - The command line parameters.

Returns:

The return code.

public static int execute(java.lang.String programName,
                          java.io.PrintWriter errWriter,
                          java.io.PrintWriter warnWriter,
                          java.io.PrintWriter noticeWriter,
                          java.lang.String defaultDocletClassName,
                          java.lang.String[] args)

Programmatic interface.

Parameters:

programName - Name of the program (for error messages).

errWriter - PrintWriter to receive error messages.

warnWriter - PrintWriter to receive error messages.

noticeWriter - PrintWriter to receive error messages.

defaultDocletClassName - Fully qualified class name.

args - The command line parameters.

Returns:

The return code.

Example

With classpath set to lib/tools.jar in the Java 2 SDK, pass in each option and argument as a separate string:

com.sun.tools.javadoc.Main.execute(new String[] {"-d", "docs", "-sourcepath", "/home/usr/src", "p1", "p2"});

The Source for the Standard Doclet

You can download the source code for the standard doclet as part of the Java 2 SDK at:

• Java 2 SDK v1.4 Source Code Release
  (Note: There is a delay between when the J2SE SDK is available and the source code release is available.)

The source files are located in the directory src/share/classes/com/sun/tools/doclets.