Doclet Overview (original) (raw)

Java The Standard Doclet Javadoc Contents

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 JDK 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.

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/jdk1.5.0/lib/tools.jar
-doclet com.sun.tools.doclets.standard.Standard
myPackage

or

% javadoc -docletpath /home/user/jdk1.5.0/lib/tools.jar
-doclet com.sun.tools.doclets.formats.html.HtmlDoclet
myPackage

Both of these approaches are equivalent.

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 J2SE, 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 J2SE at:

Copyright © 2004, 2010Oracle and/or its affiliates. All rights reserved. Please send comments to: javadoctool @ sun.com Sun