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.
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.
- PackageWriter - This generates the package-summary.html
files that list the interfaces and classes for a given package. For an
example of this type of page, see the
package-summary.html
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:
The source files are located in the directory
src/share/classes/com/sun/tools/doclets.
