Java

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:

  1. 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.
  2. Compile your doclet. You can use the compiler in the Java Development Kit, javac.
  3. 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:

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.


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

Please send comments to: javadoc@sun.com
Sun
JavaSoft