Using dulcet

Using dulcet to generate Java API documentation is simple. All you need to do is add command line arguments to your JavaDoc invocation to tell JavaDoc to use dulcet instead of the standard doclet.

For example, if you installed the dulcet.jar file in /usr/local/java, you would add these arguments to the JavaDoc command line:

-docletpath /usr/local/java/dulcet.jar -doclet dulcet.formats.html.HtmlDoclet

If you invoke JavaDoc using the Ant javadoc task, the doclet element can be used to provide the required information:

<doclet path="/usr/local/java/dulcet.jar" name="dulcet.formats.html.HtmlDoclet"/>

Member categories

Splitting lists of members into multiple categories requires identifying the category for each member and providing a title and optional description of the category.

A class member is assigned to a category using a new JavaDoc tag @category in the JavaDoc comment for the member. For example, the following is taken from java.awt.Container.getComponentCount(), as modified for the sample API document:

     * Gets the number of components in this panel.
     * @return    the number of components in this panel.
     * @see       #getComponent
     * @since     JDK1.1
     * @category hierarchy

The category title and description are defined using two new JavaDoc tags, @categoryTitle and @categoryDescription. These tags should be used in the JavaDoc comment for the class containing the categorized members, or a superclass or implemented interface. Each tag takes the category name as the first parameter, followed by the text of the title or description.

For example, the following category titles are taken from the JavaDoc comment for java.awt.Component, as modified for the sample API document:

     * @categoryTitle basicAttributes Basic Attribute Methods
     * @categoryTitle graphics Graphics Methods
     * @categoryTitle layout Layout Methods
     * @categoryTitle image Image Methods
     * @categoryTitle hierarchy Hierarchy Methods
     * @categoryTitle events Event Registration Methods
     * @categoryTitle focus Keyboard Focus Methods
     * @categoryTitle eventSupport Event Support Methods
     * @categoryTitle painting Painting Methods
     * @categoryTitle printing Printing Methods