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

Use Javadoc.

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 MS-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.

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

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.

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.
 * @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.
     * @return None.
     */
    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 on Sundays.
     */
    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 inter-linked and cross-linked 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:

Figure 23-1. Javadoc in action

$ javadoc -author -version JavadocDemo.java

Be aware that one of the (many) generated files will 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 will be 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 it where to put the generated files if you don’t want them in the same directory.

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/. A tool for testing Java files to ensure that they have adequate Javadoc comments can be downloaded from http://www.znerd.demon.nl/doclint/. This tool is a Javadoc Doclet!

Javadoc is for programmers using your classes; for a GUI application, 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.