30. Abuse of Class Hierarchy

Javadoc

When everything was in one source file, you could just do a text search to find something. Internal comments were useful, but we primarily used Javadoc comments as if they were internal, without fully exploiting them.

When your program gets big, Javadoc becomes far more useful. If you've used Javadoc comments in your code, you can run Javadoc over the program with one of the following shell commands -- the shell parameters should be the same ones you use with the Java compiler when you compile your code:

javadoc Classname.java
javadoc *.java
javadoc @classes

This will create a web site of documentation for your program, one web page per class. If you open a web browser on the index.html page this creates in your directory, you can dive into this web site and explore the kind of documentation Javadoc creates from the Javadoc comments in your code.

Very likely, what you'll find is that your Javadoc comments weren't very good. Once you start using Javadoc, you really should wander the web site it generates and do a critical reading of the content of that web site. One thing you'll notice immediately is that almost all of the huge web site documenting the Java library was generated using Javadoc. That is, the library documentation was all derived from extensive comments in the actual Java source code for that library.

Literate Programming

Javadoc, or rather, the style of commenting that Javadoc uses, is an example of a broad class of techniques described as literate programming. The old, low-tech approach to programming is to develop code and documentation as entirely separate documents. You write the program here, and you create a web page or other document describing the program there, using unrelated tools and unrelated languages. Perhaps you write the program in C++ and then write the manual using Microsoft Word.

In 1984, Donal Knuth published a book, Literate Programming, that encourages a different approach. In Knuth's model, the programmer creates a single document that incorporates program fragments woven into the documentation for that program. Knuth provided two tools for processing this document. One tool traverses the document, weaving together the program fragments into a program in the target programming language, while the other tool traverses the document, typesetting human readable text to document that program.

Knuth's tools for supporting literate programming were Web (for Pascal programs) and later Cweb (for C programs). Noweb was derived from this as a language-independent literate programming environment, and many others have followed in this direction.

Javadoc is not quite the same as Knuth's idea, but it is in the same broad category. Unlike Knuth's idea, Javadoc does not allow the order or structure of the Java program to be assembled "out of order" or rather, in the order that makes sense to the programmer, as opposed to the language. It does, however, support the idea of creating a single document from which documentation and code can be derived.

A Javadoc Example

Let's look at a simplified small example class from our highway network simulator:

class MyRandom extends Random {
    private MyRandom() {
        // uncomment exactly one of the following!
        super();                // let Java pick a random seed
        // super( 3004 );       // set seed so we can debug
    }

    static final MyRandom stream = new MyRandom();

    public static MyRandom stream() {
        return stream;
    }

    public double nextExponential( double mean ) {
        return -Math.log( nextDouble() ) * mean;
    }
}

The above code is from the version of the road-network simulator from before it was broken into multiple source files and with most of the old comments stripped out. There are numerous places in this code where we can put Javadoc comments as we prepare it to be a stannd-alone source file as part of a multi-file project:

The documentation output of Javadoc will use this text to build the global structure of the document, but each public component of the class should also be documented. Note that all kinds of HTML may be included in Javadoc comments. The <p> tags used above are paragraph dividers, while the <pre> and </pre> tags are used to set out pre-formatted segments of code.

Using Javadoc

Once you have a file that contains Javadoc comments, you can comple it with the Java compiler using the javac command, and you can create an HTML (world wide web) document describing the contents of that file using the javadoc command. For example, you could type:

[HawkId ~]$ javadoc ScanSupport.java

If you do this, it will output any error messages resulting from misformed Javadoc comments, and then it will create a flood of interlinked .html files, as well as a javascript file (.js suffix) and a style sheet (.css suffix).

You can do this one file at a time when you are developing your code, but the real power of Javadoc comes to the fore when you use Javadoc on the main class of your project or on the set of all .java files that make up your project. When you do that, the set of files generated by Javadoc becomes a complete web site describing your project.

In fact, if you use a web browser to view the output of Javadoc, what you will see is documentation that, at least in style, resembles the on-line documentation provided by Oracle for the Java libraries. That is because Oracle uses Javadoc to prepare this documentation as they maintain their libraries.