Spec-Zone .ru
спецификации, руководства, описания, API
Java

The Standard Doclet

Javadoc 1.4

Contents

What the Standard Doclet Is

The standard doclet is the doclet provided by SunTM that produces Javadoc's default HTML-formatted API output. The API documentation for the JavaTM 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.

The classes listed below are part of the internal implementation of the standard doclet, subject to change without notice from version to version -- they are not an API. These classes are published here as a good example of the use of much of the doclet API. Also, 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.

The next version of the standard doclet will be written to a Doclet Toolkit API that we will support.

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:

Important - These classes are part of the internal implementation of the standard doclet, and are subject to change without notice from version to version -- they are not an API. Use them at your own risk.
com.sun.tools.doclets com.sun.tools.doclets.standard com.sun.tools.doclets.standard.tags 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 System.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: The source files are located in the directory src/share/classes/com/sun/tools/doclets.


Copyright © 1995-98 Sun Microsystems, Inc. All Rights Reserved.

Please send comments to: javadoc-tool@sun.com
Sun