|
Doclet Overview
|
Contents
The Basics
A Simple Example
The Standard Doclet
Customizing Javadoc's Output
The Basics
Doclets are programs written in the JavaTM
programming language that use
the Doclet
API to specify the content and format of the output of the javadoc tool.
By default, the javadoc tool uses the
"standard" doclet provided by
JavaSoftTM
to generate HTML output with the traditional look and feel. However, you can
provide your own doclets to customize the output of Javadoc as you like.
You can write the doclets from scratch using the Doclet API, or you can
start with the standard doclet provided by JavaSoft and modify it to suit your
needs.
Here are the basic steps you need to follow to create and use your own doclet:
- Write the Java program that constitutes your doclet. Your program
should import sun.tools.javadoc in order to use the Doclet API. The entry
point of your program is a class with a public static boolean start
method that takes a Root
object as a parameter.
- Compile your doclet. You can use the compiler in the Java Development
Kit, javac.
- Run the javadoc tool using the -doclet <YourDoclet>
option to produce the output specified by your doclet.
If you run javadoc without the -doclet command-line option,
javadoc will default to the standard doclet to produce HTML-format API
documentation.
A Simple Example
You can get a feeling for the way doclets work by looking at this
simple example doclet that consists of one short class:
import sun.tools.javadoc.*;
public class ListClass {
public static boolean start(Root root) {
ClassDoc[] classes = root.classes();
for (int i = 0; i < classes.length; ++i) {
System.out.println(classes[i]);
}
return true;
}
}
As you might be able to guess by looking at the code, this doclet
takes the classes upon which javadoc is operating and prints out their
names. The doclet doesn't generate API documentation for the classes.
To run this doclet, you first have to compile it. You can compile it
with the JDK javac compiler:
% javac ListClass.java
To run the ListClass doclet, you point to the compiled doclet with javadoc's
-doclet tag. For example, to run the doclet on a file called
MyClass.java, you could use this command:
% javadoc -doclet ListClass MyClass.java
The output will be the string "MyClass".
Let's take a closer look at the doclet.
This first thing to notice is that the doclet imports
the sun.tools.javadoc package in order to use the Doclet APIs. As with
all doclets, the entry point is the public static boolean start
method. The start method takes as a parameter an instance of
class Root. This parameter carries information about
any options specified on the command line when javadoc is run, and also
about the classes and packages upon which javadoc is operating.
The class Root has a classes method that retrieves
an instance of ClassDoc for each class that javadoc parses.
The for loop then prints out the names of each class in the
array. (Passing a ClassDoc instance to println results in
the printing of the name of the class represented by the ClassDoc
instance.)
To generate API documentation, a doclet will have to be considerably
more complex than this simple example. If you want to customize the format of
the API documentation generated by javadoc, you may want to start with
the default standard doclet and modify it as necessary, rather than
write your own doclet from scratch.
The Standard Doclet
One reason to look at the standard doclet is
that it serves as a good example of much of the sun.tools.javadoc API.
A second reason is that by seeing how the standard doclet produces
the default HTML output, it will be easier for you to customize or
subclass the standard doclet to make your own doclet for generating
API documentation.
Classes in the standard doclet
The standard doclet is comprised of the classes in the
sun.tools.javadoc.doclets
package. This package is 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 packages.html
file that lists all packages specified on the javadoc command line. As an
example, see the packages.html
file for the API in this version of the Java Development Kit.
- PackageIndexFrameWrite - This generates the packages-frame.html
file used for diplaying the list of package links in the upper-left frame
in the frame-formatted default output.
- PackageFrameWriter - This generates the
package-frame-<package-name>.html file that lists classes in a
package in the lower-left frame of the frame-formatted default output.
- FrameOutputWriter - This generates the frame.html file used
for presenting the API documentation in HTML-frame format. See the
frame.html file from the JDK documentation
as an example.
- PackageWriter - This generates the pages that list the interfaces
and classes
in each package specified on the javadoc command line. For an example of this
type of page, see the package-java.lang.html
page in the JDK API documentation..
- ClassWriter - This generates the HTML API documentation for
each individual interface and class. For an example from the JDK
API documentation, see java.awt.Font.html.
- SingleIndexWriter - This generates the single index file of
class members that javadoc produces when the -breakindex option
is not used.
- SplitIndexWriter - This generates the mutliple index files for the
class members that is generated when javadoc is used with the
-breakindex option. For an example from the JDK API documentation,
see 1-index.html.
- TreeWriter - This class generates the HTML page that lists
the Class Hierarchy for the classes upon which the standard doclet
operates. For an example from the JDK API documentation,
see tree.html.
- DeprecatedListWriter - This generates the file
deprecatedlist.html which lists deprecated APIs. As an example,
see the deprecatedlist.html
file from the JDK documentation.
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:
% javadoc MyClass.java
is equivalent to
% javadoc -doclet sun.tools.javadoc.doclets.Standard MyClass.java
The source for the standard doclet
You can browse the source for the standard doclet from the
Javadoc Doclets page. If you download and
install the JDK documentation bundle, you will find the source files
for the standard doclet in the directory docs/tooldocs/javadoc/source.
Customizing Javadoc's Output
To customize the output of the javadoc tool, you need to write
your own doclet that specifies the content and format of the output
that you desire. If you want HTML output with roughly the same format
as the default output, you can use the standard doclet as a
starting point for creating your doclet. You can subclass
appropriate classes in the standard doclet and then add or
override methods as necessary to produce the output you want. Or
you can copy the whole standard doclet and modify it. If you use
a copy of the standard doclet as your starting point, you may want
to remove the package statements at the beginning of
each source file and replace is with the name of your own, new
package.
As a trivial example, suppose you wanted to customize the HTML
output generated by javadoc so that the horizontal rules were
bolder and thicker than the default horizonal rules in the
standard output.
How would you go about modifying the APIs in the standard doclet to
produce these to changes? Because the customization in question
involves a change in the HTML formatting, the API
summary of the standard doclet above will indicate to you that
you might need to modify the APIs in class HtmlWriter.
If you look at the source for
the HtmlWriter class, you will find methods for writing the HTML
tags used in generating the default HTML documentation. Among these,
there is a method for writing the HTML tag for horizonal rules:
public void hr() {
println("<hr>");
}
You'll also notice that the HtmlWriter class doesn't provide a
way to produce the custom horizontal rules that you want. You can
therefore either subclass or copy HtmlWriter, and add a method
to print the custom tag that you want. For example, you might
add this method:
public void hrCustom() {
println("<hr size=3 noshade>");
}
and call it instead of the hr method when you want to
your output to use the thicker horizontal rules.
Of course you can create doclets that generate API documentation that is
radically different from the default. You can also write doclets that
perform functions unrelated to API documentation. In such cases, you
may want to consider writing your doclet from scratch rather than
try to bend the standard doclet into the shape that you desire.