Chapter 16

Using JavaDoc to Document Your Program

CONTENTS

• Overview
• Running JavaDoc
• Adding JavaDoc Comments
  • Documenting Classes
  • Documenting Methods
• Enhancing Your Documentation with HTML
• An Example
• Summary

One of the problems that has faced maintenance programmers through the years has been the horrible documentation left behind by the original programmers. Usually the original programmers included comments in the source code but probably didn't comment as thoroughly as they should have. Then an ambitious project manager recognized the inadequacy of the inline comments and forced the programmers to write a lengthy document about the software. This document was handed over to the maintenance programmers who used it to continue supporting and enhancing the software. Of course, even if the maintenance programmers kept the inline comments current, the other documentation fell out of date because it was just too hard to maintain. And, besides, the maintenance programmers ask, "Why should we keep the document up-to-date if we're also documenting the code?"

This is, of course, a very good question and one the Java developers must have asked themselves. Imagine yourself on the Java team. You've been working long hours writing the hundreds of classes that comprise Java and then you wake up one morning, hands still trembling from the previous night's caffeine excesses, and realize, "Darn! Now we've got to document all that code." The solution the Java developers came up with actually made it possible for them not to write a separate document describing each class, interface, and method. Instead, they wrote a program that would extract specially formatted source code comments and create class documentation from the embedded comments. The tool they developed to do this is called JavaDoc and is included in the Java Developer's Kit.

Overview

JavaDoc reads a .java file and creates a set of HTML files that can be read by a Web browser. As an example, consider the documentation for the Employee class that is shown in Figure 16.1. At the top of the documentation shown in this figure is an inheritance tree showing that Employee is a subclass of Person, which is a subclass of java.lang.Object.

Figure 16.1 : A sample documentation page generated by JavaDoc.

In addition to the class's inheritance tree, Figure 16.1 shows that an overall class description can be provided as well as a constructor index. Figure 16.1 shows only one screen of the documentation that will be created for the Employee class in this chapter. There are many more areas and types of documentation that can be generated and are described in this chapter.

Running JavaDoc

JavaDoc is a command-line program that is supplied with the Java Developer's Kit. It can be invoked in the following manner:

javadoc [options] PackageName | FileName.java

For example, to use JavaDoc to create documentation on a class named Employee, you would do the following:

javadoc employee.java

Command-Line Arguments and Environment Variables

The [options] parameter shown as part of the JavaDoc command line can be included if desired. It can be used to specify which directories should be searched for input files, the directory in which to put the generated HTML files, and whether JavaDoc should run in a special verbose mode. These are summarized in Table 16.1.

The only environment variable used by JavaDoc is CLASSPATH. This variable, if set in your environment, informs JavaDoc of the directories in which it should search for .java files. For example, to search the current directory, C:\CAFE\JAVA\SOURCE, and C:\MYJAVA\SOURCE, you would set CLASSPATH to the following:

.;C:\cafe\java\source;C:\myjava\source

Adding JavaDoc Comments

Unfortunately, JavaDoc is only as smart as the information you give it. It gets its information by parsing source code files and looking for comments enclosed within the /** and */ delimiters. JavaDoc comments are placed immediately above the class or member that they are meant to describe. For example, consider the following class definition and associated comment:

/** This is a comment that describes MyClass in general. */
public class MyClass {
    /** The DoSomething method is used to do something. */
    public int DoSomething() {
        // method source goes here
    }
    // remaining class source code
}

In this example, a JavaDoc comment has been placed above the class and above the DoSomething member method.

Documenting Classes

When documenting a class (in the comment immediately preceding the class definition), you can add class documentation tags to enhance the usability of the documentation. Class documentation tags each begin with an @ symbol to distinguish them. The following class documentation tags are available:

@author author-name
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
@version version-text

As an example of how these tags work, consider the following definitions of an Employee class and a Contractor class:

/**
  * The Employee class is used to represent employees
  * of our company. It augments the Person class with
  * information about an employee's salary and job
  * title.
  * @author Mike Cohn
  * @version 1.0.0
  * @see Contractor
*/
public class Employee extends Person {
    // class body
}

/**
  * The Contractor class is used to represent
  * contract employees. Contract employees are
  * paid by the hour.
  * @author Mike Cohn
  * @version 1.0.0
  */
class Contractor extends Employee {
    // class body
}

The comment preceding the Employee class describes the class and then shows the use of three of the class documentation tags. The author and version do not get included in the generated documentation but are useful to include. The @see Contractor line in the Employee comment will inform readers that they may want to see a related class. Because the @see tag is used, JavaDoc will generate a link to the Contractor class documentation. This can be seen in Figure 16.2.

Figure 16.2 : Class documentation for Employee.

As you can see in Figure 16.2, a link is provided for all superclasses of Employee (java.lang.Object and Person) and the @see tag has created a link to Contractor in a See Also section. Following this link will jump directly to the Contractor documentation, as shown in Figure 16.3. The Contractor documentation does not need a @see tag back to Employee because Employee is a superclass of Contractor and already appears as a link in the inheritance hierarchy.

Figure 16.3 : Class documentation for Contractor.

The link from Employee to Contractor positions your Web browser at the top of the documentation for the Contractor class. Sometimes you would prefer to have a link jump to a specific place within the target class. You can link directly to a method by specifying the name of the method after the target class. For example, the following tag would jump directly to the GetHourlyRate method in the Contractor class:

@see Contractor#GetHourlyRate

Documenting Methods

Like its class documentation tags, JavaDoc also supports method documentation tags. Method documentation tags are optional and can be placed in a JavaDoc comment directly above a method. Like class documentation tags, method tags begin with the @ symbol. The following method documentation tags are available:

@param parameter-name description
@return description
@exception fully-qualified-class-name description

To see how these tags can be used, consider the following definition of the Contractor class:

class Contractor extends Employee {
    public Contractor(float sal, String fName, String lName) {
        super(sal, fName, lName);
    }
    private float hourlyRate;
  /**
    * This method can be used to retrieve the hourly rate
    * paid to the contractor.
    * @return The contractor's hourly rate, excluding
    *         exceptional circumstances such as holidays
    *         and overtime.
    */
    public float GetHourlyRate() {
        return hourlyRate;
    }
  /**
    * This method calculates how much is due to
    * a contractor based on how much he's worked
    * and his hourly rate.
    * @param hours The number of hours worked by the
    *        contractor during this pay period.
    * @return The amount of money due the contractor.
    */
    public float CalculatePayCheck(int hours) {
        return hours * hourlyRate;
    }
}

The Contractor class includes two non-constructor methods-GetHourlyRate and CalculatePayCheck. Each of these uses the @return tag to describe its return value. Additionally, GetHourlyRate uses @param to describe its input parameters. The results of this documentation can be seen in Figure 16.4.

Figure 16.4 : Using @param and @return to document Contractor.

As you can see from Figure 16.4, the @return and @param tags nicely format the descriptions entered in the JavaDoc comments. If a method receives more than one parameter, the @param tag can be repeated as often as necessary. Although the @exception tag is not shown in this example, it behaves identically to @return and @param.

Enhancing Your Documentation with HTML

By using the class and method documentation tags that you can embed within JavaDoc comments, you can take huge strides toward improving the way you document your code. However, because JavaDoc produces HTML (HyperText Markup Language) files, you can go much further. By embedding HTML commands within your JavaDoc comments, you have almost infinite control over how your documentation will appear when viewed in a browser.

By using HTML tags, you can enhance your documentation by drawing attention to bold or italicized text, including numbered and bulleted lists, images, preformatted text, or even links to other documentation files or Web-based resources.

Table 16.2 shows the HTML tags that you probably find most useful in documenting your Java code. Additionally, you also may want to refer to Chapter 12, "HTML for Java Programmers."

An Example

This section demonstrates the use of JavaDoc, including class documentation tags, method documentation tags, and embedded HTML tags. Assume you have the following class definition that you need to document:

public class Employee extends Person {
    private float salary;
    private String job;
    public Employee(float sal, String fName, String lName) {
        super(fName, lName);
        salary = sal;
    }
    public void AssignJob(String newJob) {
        job = newJob;
    }
    public String GetJobTitle() {
        return job;
    }
    public static int GetMaxWorkingAge() {
        return 64;
    }
    private float GetMaxSalary() {
        return 200000f;
    }
    public boolean ChangeSalary(float newSalary) {
        if (newSalary < salary)
            return false;
        if (newSalary > GetMaxSalary())
            return false;
        salary = newSalary;
        return true;
    }
}

First, you need to document the class itself. You do this with the following comment:

/**
  * The <tt>Employee</tt> class is used to represent
  * employees of our company. It augments the <tt>Person</tt>
  * class with information about an employee's salary and
  * job title.<p>
  * This class was written by:
  * <blockquote>
  * <img src=logo.gif width=300 height=100>
  * </blockquote>
  * @author Mike Cohn
  * @version 1.0.0
  * @see Contractor
*/
public class Employee extends Person {

This will create the documentation screen shown in Figure 16.5. You can see that the <tt>…</tt> tags were used to set the names of other classes in a distinctive typewriter-style font. The <p> tag is used to indicate the end of a paragraph. If this tag had not been used, the text on the following line would have merged with the text prior to the tag. The <blockquote> and <img> tags were used to include a graphics image indicating the author of the class.

Figure 16.5 : Class documentation for Employee, including embedded graphic.

Next, you need to document the constructor. This is done with the following comment, which will produce the documentation shown in Figure 16.6:

Figure 16.6 : Documentation for the Employee constructor.

/** This constructor is used to create a new employee and
  * assign him an initial salary. <EM>It does not verify that
  * salary is less than the company's maximum salary.</EM>
  * You could use this method as follows:
  * <CODE><PRE>
  * Employee Emp = new Employee(35000f,"Mike","Cohn");
  * </PRE></CODE>
  * @param sal The starting salary of the new employee.
  * @param fName The employee's first name.
  * @param lName The employee's last name.
  */
public Employee(float sal, String fName, String lName) {

In this case the <CODE>…</CODE> and <PRE>…</PRE> tags were used to indicate a preformatted block of source code. Also, the <EM>…</EM> tags were used to apply emphasis to the statement that the employee's salary must be less than a company maximum. Finally, because this constructor is passed three parameters, each parameter is documented with the @param method tag.

In addition to the full documentation shown in Figure 16.6, JavaDoc creates a list of constructors for the class. This appears as a separate section in the HTML document, as shown in Figure 16.7.

Figure 16.7 : The constructor index for the Employee class.

The AssignJob method is documented by adding the following comment:

/**
  * This method assigns the employee to the
  * specified job. This method does not verify the
  * <i>job title</i> against the list of <i>approved
  * job titles</i> created by <b>Human Resources</b>.
  * Likely job titles you may want to pass include:
  * <ul>
  * <li>Programmer
  * <li>Analyst
  * <li>QA
  * <li>Tech Writer
  * <li>Project Manager
  * <li>Database Administrator
  * <li>Database Engineer
  * </ul>
  * Reminder: All positions must be approved by the
  * <b>Manager of Human Resources</b> according to
  * the company's <CITE>Employee Hiring Guidelines.
  * </CITE>
  * @param newJob This is the new job title.
  * @see #GetJobTitle
  */
  public void AssignJob(String newJob) {

The result of this documentation can be seen in Figure 16.8. This example demonstrates the use of <B>…</B> and <I>…</I> to bold and italicize text. Additionally, the use of an unordered (bulleted) list is demonstrated. The <UL>…</UL> tags indicate the start and end of the list and the <LI> tags indicate each of the list items. This example also demonstrates the use of <CITE>…</CITE> to indicate a citation. Finally, the @see method tag is used. In this example, no class name appears to the left of the #. This will create a link to a method within the current class.

Figure 16.8 : Documentation for the AssignJob.method.

Just as JavaDoc created a constructor index that listed each of a class's constructors, it also creates a method index that will list each of a class's non-private methods. The method index for Employee is shown in Figure 16.9.

Figure 16.9 : The method index for the Employee.class

Next, the following comment is written for GetJobTitle to produce the documentation shown in Figure 16.10:

Figure 16.10 : Documentation for the GetJobTitle method.

/**
  * This function returns the job title of the employee.
  * @return A string representing the job title (for
  * example, "programmer").
  * @see #AssignJob
  */
  public String GetJobTitle() {

The method GetMaxWorkingAge is defined as static, meaning that it is associated with the class itself, rather than with instances of the class. However, because it is a public method, it can be documented as shown in the following comment:

/**
  * This method returns the highest age at which
  * an employee can remain at work. <STRONG>
  * After this age, an employee must retire and
  * move to Florida.</STRONG>
  * @return The last allowable working year before
  * mandatory retirement.
  */
  public static int GetMaxWorkingAge() {

As you can see in Figure 16.11, the use of the <STRONG>…</STRONG> tag places heavy emphasis on the need for retirees to move to Florida.

Figure 16.11 : Documentation for the GetMaxWorkingAge method.

Next, the method GetMaxSalary is documented, as follows:

/**
  * This comment will not show up in JavaDoc because
  * it is private.
  */
private float GetMaxSalary() {

However, GetMaxSalary is declared as private, so it will not be documented by JavaDoc. Because private functions are not usable outside the class in which they are declared, there is no need to document them for use by others in the same way that exists for externally visible methods.

At this point, the only method left to document is ChangeSalary, which is documented as follows:

/**
  * This function changes the employee's salary.
  * A salary change can occur only after the two following
  * tests have been applied:
  * <ol>
  * <li>The new salary is higher than the current salary.
  * <li>The new salary is less than the maximum salary.
  * </ol>
  * @return <B>true</B> if the salary change is approved,
  *         <B>false</B> otherwise.
  * @param newSalary The proposed new salary.
  */
  public boolean ChangeSalary(float newSalary) {

The documentation for ChangeSalary will appear as shown in Figure 16.12. This example demonstrates the use of <OL>…</OL> and <LI> to introduce an ordered list and its items. Ordered lists are like unordered lists except that instead of bullets, they have numbers to the left of each item. Additionally, this example shows that some HTML tags can be embedded with class or method documentation tags. In this case, <B>…</B> is embedded within the @return tag.

Figure 16.12 : Documentation for the ChangeSalary method.

Summary

In this chapter, you learned how JavaDoc can simplify the job of documenting your classes. You saw how class documentation tags can be used to link classes by providing jumps between related classes. You also learned how to use method documentation tags to document the parameters, return values, and exceptions of each method. Even with this much power and flexibility, it only scratched the surface of what can be done. By embedding HTML commands directly into your comments, you learned how to enhance your documentation by using formatted text, numbered and bulleted lists, and embedded images. Finally, you saw an extensive example that put all of these pieces together to document a single class.