A step remains before you can go public with your hot new class library or application: preparing the documentation for its classes. Fortunately, Java provides a tool called JavaDoc that can automatically create fancy HTML-based documentation based on comments in your source files.

All you have to do is add a comment for each public class, field, and method; then run the source files through the javadoc command; voilá! you have professional-looking, web-based documentation for your classes.

Adding JavaDoc comments

The basic rule for creating JavaDoc comments is that they begin with /** and end with */. You can place JavaDoc comments in any of three different locations in a source file:

• Immediately before the declaration of a public class

• Immediately before the declaration of a public field

• Immediately before the declaration of a public method or constructor

A JavaDoc comment can include text that describes the class, field, or method. Each subsequent line of a multiline JavaDoc comment usually begins with an asterisk. JavaDoc ignores this asterisk and any white space between it and the first word on the line.

The text in a JavaDoc comment can include HTML markup if you want to apply fancy formatting. You should avoid using heading tags (

and so on) because JavaDoc creates those, and your heading tags just confuse things. But you can use tags for boldface and italics ( and ) or to format code examples (use the

 tag).

In addition, you can include special doc tags that provide specific information used by JavaDoc to format the documentation pages.


Tag
Explanation


@author
Provides information about the author, typically the
author’s name, e-mail address, website information, and so
on.


@version
Indicates the version number.


@since
Used to indicate the version with which this class, field, or
method was added.


@param
Provides the name and description of a method or
constructor.


@return
Provides a description of a method’s return value.


@throws
Indicates exceptions that are thrown by a method or
constructor.


@deprecated
Indicates that the class, field, or method is deprecated and
shouldn’t be used.


To give you an idea of how JavaDoc comments are typically used, check out this code.
Note that for the Employee class to compile, you must also provide a class named Address, which represents a street address. The following simple class will suffice:
public class Address implements Cloneable
{
    public String street;
    public String city;
    public String state;
    public String zipCode;
}
This codes shows an employee class with JavaDoc comments.
package com.lowewriter.payroll;
/** Represents an employee.
 * @author Doug Lowe
 * @author www.LoweWriter.com
 * @version 1.5
 * @since 1.0
*/
public class Employee
{
 private String lastName;
 private String firstName;
 private Double salary;
/** Represents the employee’s address.
*/
 public Address address;
/** Creates an employee with the specified name.
 * @param lastName The employee’s last name.
 * @param firstName The employee’s first name.
*/
 public Employee(String lastName, String firstName)
 {
  this.lastName = lastName;
  this.firstName = firstName;
  this.address = new Address();
 }
/** Gets the employee’s last name.
 * @return A string representing the employee’s last
 *     name.
*/
 public String getLastName()
 {
  return this.lastName;
 }
/** Sets the employee’s last name.
 * @param lastName A String containing the employee’s
 *     last name.
*/
 public void setLastName(String lastName)
 {
  this.lastName = lastName;
 }
/** Gets the employee’s first name.
 * @return A string representing the employee’s first
 *     name.
*/
 public String getFirstName()
 {
  return this.firstName;
 }
/** Sets the employee’s first name.
 * @param firstName A String containing the
 *     employee’s first name.
*/
 public void setFirstName(String firstName)
 {
  this.firstName = firstName;
 }
/** Gets the employee’s salary.
 * @return A double representing the employee’s salary.
*/
 public double getSalary()
 {
  return this.salary;
 }
/** Sets the employee’s salary.
 * @param lastName A double containing the employee’s
 *     salary.
*/
 public void setSalary(double salary)
 {
  this.salary = salary;
 }
}
Using the javadoc command
The javadoc command has a few dozen options you can set, making it a complicated command to use. However, you can ignore all these options to create a basic set of documentation pages. Just specify the complete path to all the Java files you want to create documentation for, like this:
javadoc comlowewriterpayroll*.java
The javadoc command creates the documentation pages in the current directory, so you may want to switch to the directory where you want the pages to reside first.
For more complete information about using this command, refer to the javadoc documentation at the Sun website.
Viewing JavaDoc pages
After you run the javadoc command, you can access the documentation pages by starting with the index.html page. To quickly display this page, just type index.html at the command prompt after you run the javadoc command. Or you can start your browser, navigate to the directory where you created the documentation pages, and open the index.html page.

If you think this page looks familiar, that’s because the documentation for the Java API was created using JavaDocs. So you should already know how to find your way around these pages.
To look at the documentation for a class, click the class name’s link. A page with complete documentation for the class comes up. JavaDocs generated this page from the source file.