April 2004 Technical Tip Javadoc

Javadoc is a tool provided by Sun for creating HTML files that document Java code. It is not automatic documentation! You still have to comment your code! But having done so, Javadoc formats your comments in the same format as the standard API documentation.

Javadoc comments begin with /** and end with */. By convention, use asterisks on each line within the comments block to align the comments. Javadoc will ignore all whitespace up to the first non-whitespace character in each line. If the first non-whitespace character is an asterisk, it is also ignored.

You can use special tags such as @param and @return as shown in the example. You can also add other HTML tags (such as <I> and </I>) within the documentation. All of this can be found in the setAmount method shown here:

/** The setCurrency method allows the user to change
  * the dollar and cents amounts. <I>If the given cents
  * is over 99, dollars and cents will be adjusted
  * accordingly, thereby ensuring a consistent state.</I>
  * @param d - dollars
  * @param c - cents
  * @return a reference to the current MyCurrency object
  */

public MyCurrency setAmount( int d, int c )
{
   dollars = d;
   cents = c;
   adjust();
   return( this );
}

The complete source can be found at http://www.caliberdt.com/tips/MyCurrency.java. For completeness, I have also created a test application for this class, which can be found at http://www.caliberdt.com/tips/MyCurrencyTest.java.

To create the documentation, use the javadoc command as shown in the following screen capture:

C:\Java\MyJava>javadoc MyCurrency.java
Loading source file MyCurrency.java...
Constructing Javadoc information...
Standard Doclet version 1.4.1
 
Generating constant-values.html...
Building tree for all the packages and classes...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating packages.html...
Generating MyCurrency.html...
Generating package-list...
Generating help-doc.html...
Generating stylesheet.css...
 
C:\Java\MyJava>

The Javadoc output for the setAmount method is shown here. The complete Javadoc output can be found at http://www.caliberdt.com/tips/MyCurrency/index.html.

Go to the articles index. Written by Bill Qualls. Copyright © 2004 by Caliber Data Training 800.938.1222