21. Javadoc

Literate Programming

As mentioned in the previous lecture, when we break a program into multiple source files, there is more need for documentation than there was when the file was small enough to be just one source file. Javadoc is a tool that was developed in parallel with Java to help improve the documentation of large programs.

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 ScanSupport {
    public static class NotFound extends Exception {}

    private static final Pattern name = Pattern.compile( "[a-zA-Z0-9_]*" );

    public static interface Message {
	public String myString();
    }

    public static String nextName( Scanner sc, Message m ) throws NotFound {
	sc.skip( whitespace );
	sc.skip( name );
	String s = sc.match().group();
	if ("".equals( s )) {
	    Errors.warn( "name expected: " + m.myString() );
	    sc.nextLine();
	    throw new NotFound();
	}
	return s;
    }
}

The only comment above is the one identifying the file name. There are numerous places in this code where we can put Javadoc comments

/** Support methods for scanning
 *  <p>
 *  Methods in this class scan for the desired target text and convert it as
 *  necessary before returning its value.
 *  <p>
 *  If the desired target is not found, class {@link Errors} is used to
 *  output warning messages and then a {@link NotFound} exception is thrown.
 */
class ScanSupport {
    /** Exception thrown to report that the desired target has not been found.
     *  <p>
     *  This should not be thrown by code outside this class.
     */
    public static class NotFound extends Exception {}

    private static final Pattern name = Pattern.compile( "[a-zA-Z0-9_]*" );

    /** Interface used for passing error messages.
     *  <p>
     *  Error message text will frequently be composed using large numbers
     *  of concatenations, so it does not make sense to do these concatenations
     *  in the normal error-free case.
     *  <p>
     *  This functional interface allows error messages to be passed using
     *  string-valued parameterless lambda expressions.
     */
    public static interface Message {
	public String myString();
    }

    /** Scan for the next name in the input file
     *  <p>
     *  Names are defined as sequences of letters, digits and underscores
     *  without intervening white space.  Typicall calls look like this:
     *  <pre>
     *  s = ScanSupport.nextName( sc, ()->"Context " + more + " stuff" );
     *  </pre>
     *  <p>
     *  In the event of an error, the resulting error message passed to
     *  {@link Errors.warning} will be something like this:
     *  <pre>
     *  name expected: Context more stuff
     *  </pre>
     *  @param sc The scanner from which the input is taken.
     *  @param m  The error message, typically a lambda expression.
     */
    public static String nextName( Scanner sc, Message m ) throws NotFound {
	sc.skip( whitespace );
	sc.skip( name );
	String s = sc.match().group();
	if ("".equals( s )) {
	    Errors.warn( "name expected: " + m.myString() );
	    sc.nextLine();
	    throw new NotFound();
	}
	return s;
    }
}

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.