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 JDKTM 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 API documentation produced by the standard doclet has a different
format than that produced by the Javadoc tool in the JDK 1.1 software.
The output of the standard doclet has also changed during the beta cycle
of the JDK 1.2 software. See Changes to Standard
Doclet for a summary of these changes and for new requirements
for writing documentation comments in source code.
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 comprised of the classes in the com.sun.tools.doclets
and com.sun.tools.doclets.standard packages. These packages are
not a part of the core API of the Java platform. Classes in the standard
doclet that play key roles in generating the default HTML output are summarized
here:
-
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.
-
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.
-
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 JDK 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 JDK 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 JDK 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 JDK 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 -breakindex
command-line option. The files are named 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 JDK 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.
Running the Standard Doclet
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,
% javadoc MyClass.java
is equivalent to
% javadoc -doclet com.sun.tools.doclets.standard.Standard MyClass.java
The Source for the Standard Doclet
If you download and install the JDK documentation bundle, you will find
the source files for the standard doclet in the directories docs/tooldocs/javadoc/source
and docs/tooldocs/javadoc/scoure/standard. You can browse the
source code here: