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.
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:
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 (
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 CloneableThis 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; >>
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.
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.
