Recipe 23.2 Documenting Classes with Javadoc

Problem

You have heard about this thing called "code reuse" and would like to promote it by allowing other developers to use your classes.

Solution

Use Javadoc.

Discussion

Javadoc is one of the great inventions of the early Java years. Like so many good things, it was not wholly invented by the Java folk; earlier projects such as Knuth's Literate Programming had combined source code and documentation in a single source file. But the Java folk did a good job on it and came along at the right time. Javadoc is to Java classes what "manpages" are to Unix or Windows Help is to Windows applications: it is a standard format that everybody expects to find and knows how to use. Learn it. Use it. Write it. Live long and prosper (well, perhaps not). But all that HTML documentation that you refer to when writing Java code, the complete reference for the JDK did you think they hired dozens of tech writers to produce it? Nay, that's not the Java way. Java's developers wrote the documentation comments as they went along, and when the release was made, they ran Javadoc on all the zillions of public classes and generated the documentation bundle at the same time as the JDK. You can, should, and really must do the same when you are preparing classes for other developers to use.

All you have to do to use Javadoc is to put special " doc comments" into your Java source files. These begin with a slash and two stars ( /**) and must appear immediately before the definition of the class, method, or field that they document. Doc comments placed elsewhere are ignored.

A series of keywords, prefixed by the at sign ( @), can appear inside doc comments in certain contexts. These are listed in Table 23-2.

Table 23-2. Javadoc keywords

Keyword	Use
@author	Author name(s)
@version	Version identifier
@param	Argument name and meaning (methods only)
@since	JDK version in which introduced (primarily for Sun use)
@return	Return value
@throws	Exception class and conditions under which thrown
@deprecated	Causes deprecation warning
@see	Cross-reference

Example 23-1 is a somewhat contrived example that shows almost every usage of a javadoc keyword. The output of running this through Javadoc is shown in a browser in Figure 23-1.

Example 23-1. JavadocDemo.java

import java.applet.*; import java.awt.*; import java.awt.event.*; /**  * JavadocDemo - a simple applet to show JavaDoc comments.  * <P>Note: this is just a commented version of HelloApplet.  * @author Ian F. Darwin, http://www.darwinsys.com/  * @version $Id: ch23.xml,v 1.5 2004/05/04 20:13:53 ian Exp $  * @see java.applet.Applet  * @see javax.swing.JApplet  */ public class JavadocDemo extends Applet {     /** init( ) is an Applet method called by the browser to initialize.      * Init normally sets up the GUI, and this version is no exception.      */     public void init( ) {         // We create and add a pushbutton here,          // but it doesn't do anything yet.         Button b;         b = new Button("Hello");         add(b);                        // connect Button into Applet     }     /** paint( ) is an AWT Component method, called when the       *  component needs to be painted. This one just draws colored      * boxes in the Applet's window.      *      * @param g A java.awt.Graphics that we use for all our      * drawing methods.      */     public void paint(Graphics g) {         int w = getSize( ).width, h=getSize( ).height;         g.setColor(Color.YELLOW);         g.fillRect(0, 0, w/2, h);         g.setColor(Color.GREEN);         g.fillRect(w/2, 0, w, h);         g.setColor(Color.BLACK);         g.drawString("Welcome to Java", 50, 50);     }     /** Show makes a component visible; this method became deprecated      * in the Great Renaming of JDK1.1.      * @since 1.0      * @deprecated Use setvisible(true) instead.      */     public void show( ) {         setVisible(true);     }     /** An Applet must have a public no-argument constructor.      * @throws java.lang.IllegalArgumentException if the current day of the week is  Sunday.      */     public JavadocDemo( ) {         if (new java.util.Date( ).getDay( ) == 0) {             throw new IllegalArgumentException("Never On A Sunday");         }     } }

The Javadoc tool works fine for one class but really comes into its own when dealing with a package or collection of packages. It generates thoroughly interlinked and crosslinked documentation, just like that which accompanies the standard JDK. There are several command-line options; I normally use -author and -version to get it to include these items, and often -link to tell it where to find the standard JDK to link to. Run javadoc -help for a complete list of options. Figure 23-1 shows one view of the documentation that the previous class generates when run as :

$ javadoc -author -version JavadocDemo.java

Figure 23-1. Javadoc in action

Be aware that one of the (many) generated files have the same name as the class, with the extension .html . If you write an applet and a sample HTML file to invoke it, the .html file is silently overwritten with the Javadoc output. For this reason, I recommend using a different filename or the filename extension .htm for the HTML page that invokes the applet. Alternately, use the -d directory option to tell Javadoc where to put the generated files if you don't want them in the same directory.

See Also

Javadoc has numerous other command-line arguments. If documentation is for your own use only and will not be distributed, you can use the -link option to tell it where your standard JDK documentation is installed so that links can be generated to standard Java classes (like String, Object, and so on). If documentation is to be distributed, you can omit -link or use -link with a URL to the appropriate J2SE API page on Sun's web site. See the online tools documentation for all the command-line options.

The output that Javadoc generates is fine for most purposes. It is possible to write your own Doclet class to make the Javadoc program into a class documentation verifier, a Java-to-MIF or Java-to-RTF documentation generator, or whatever you like. Those are actual examples; see the Javadoc tools documentation that comes with the JDK for documents and examples, or go to http://java.sun.com/j2se/javadoc/.

Visit http://www.doclet.com/ for a fabulous collection of other Javadoc-based tools.

Javadoc is for programmers using your classes; for a GUI application, end users will probably appreciate standard online help. This is the role of the Java Help API, which is not covered in this book but is fully explained in the O'Reilly book Creating Effective JavaHelp, which every GUI application developer should read.