Espresso: A Concentrated Introduction to Java

Documenting Your Program Code with Javadoc

Summary: We consider the various forms of documentation that programmers typically write and read and examine Javadoc, Java's tool for generating documentation for client programmers.

Contents:

• Forms of Documentation
• Documenting at Many Levels
• When To Document
• Documenting Methods
• Javadoc: Generating Documentation for Client Programmers
• Generating Javadoc

Forms of Documentation

Even though you are a comparatively novice programmer, you have likely learned the importance of documenting your work (or, as importantly, of others documenting their work). When you use a program, such as Emacs, it helps to have documentation that lets you quickly identify how to do particular activities. When you use a Java class that comes as part of the standard installation, such as java.io.PrintWriter, you hope to have clear instructions on how to build and use objects in that class. When you're writing a method, it helps to have a short note as to what you expect the method to do. It may also help to have some notes as to the steps in your algorithm. (As a professor, I find it much easier to help my students when they have documentation that explains what they intended the method to do and how the code they've written is supposed to accomplish this task.) Finally, when you modify the code of others (Or even your own code a few months later), it helps to have similar explanations: What were you trying to do and how were you trying to do it? You can probably suggest other ways that you document your code.

I find that it helps to classify this wide variety of kinds of documentation into three audiences:

• Users, who consult the documentation when attempting to use your program. Although in the real world, programmers are not necessarily expected to provide this kind of documentation, you will often have to provide it earlier in your programming career and it helps to remember that someone has to write such documentation.
• Client Programmers, who use the classes you design, often in new contexts.
• Colleagues, who must support and update your code.

In this document, we will focus primarily on the documentation you write for other programmers, both client programmers and colleagues.

Documenting at Many Levels

One of the first things you should observe as you write documentation for other programmers is that there are many levels of documentation you need to write, particularly if you're providing a host of classes for client or colleague (or yourself).

You should begin with a package-level overview of the various classes and objects and the relationships they play with each other. Such an overview helps guide your colleagues to the right place to find something and guides your clients as to what classes they need for different purposes and how they interact. As a client, you may have found such high-level overviews useful for figuring out how things go together. Experience suggests that hihg-level overviews are strengthened by sample code, but you often don't want to write that code until after you've written a few programs using your package or packages yourself.

Next, you should provide a class-level overview of each class or interface you write. Like the package-level overview, it guides your reader as to how things fit together and where things can be found. Such overviews might also include code.

Third, you should write method and field summaries that provide details about the individual fields, methods, and constructors of your classes. Typically, a field summary provides information about the intended use of the field and any special values it may take on. (For example, some programs use 0 or -1 to indicate a special siutation.) The summary for a method or constructor should provide coherent information about the purpose of the method. We revisit the form and content of this summary in a subsequent section.

Finally, within each method, you document the intended meaning of each step.

When To Document

Many programmers seem unsure of when they should write their documentation. The answer is easy: you should Document Early and Often. By early, I mean that you should write most of your documentation before you begin to code. You may have to go back and modify your comments later, perhaps as you realize that you can't meet your intent, but early documentation helps guide you when you've forgotten what you want to do (and helps others help you).

Let's consider an example: How might I document and then write a procedure for exponeniation? I begin with a full statement of what I expect the algorithm to compute.

/**
 * Given an integer, x, and an exponent, p, compute x^p.
 *
 * @param x
 *   an integer
 * @param p
 *   a whole number
 * @pre
 *   x must be non-negative.
 *   x^p must be smaller than the largest representable integer.
 * @post
 *   The result = x*x*x* ... *x (p times)
 */

Next, I write a short summary of the algorithm or any other issues of import.

/*
  Algorithm: We rely on the rules that
    x^0 = 1
    x^k+1 = x^k*x
    x^2k = (x^k)^2
 */

Finally, I write the body with short comments of what I intend to do.

public int exp(int x, int p)
{
  // Base case: When p = 0, result is 1
  // Recursive case: When p is odd, result is x*(x^(p-1))
  // Recursive case: When p is even, result is x^(p^2) squard
} // exp(int, int)

Only once that infrastructure is in place do I begin coding.

Documenting Methods

As you may have noted from the above, there are a variety of things one can mention when documenting a method (or constructor). I recommend that you think about what I call the Five P's.

• Purpose: Summarize what the method does in a sentence or two (or three or four).
• Parameters: Describe the name, type, and possibly role of the paramers.
• Produces: Describe the type of the result. It may also be helpful to name it.
• Preconditions: A formal (or somewhat formal) specification of what must hold in order for the method to work.
• Postconditions: A formal (or somewhat formal) specification of the results. You should think of the purpose as giving an informal specification and the postconditions as giving a more formal specification.

Javadoc: Generating Documentation for Client Programmers

Because the designers of Java considered client documentation so important, they designed some language features and corresponding tools that make it easier to generate documentation for clients. The tool (and the notation) is called Javadoc.

In essence, when you run Javadoc on a .java file, the program searches for all comments that begin with /** (that is, a slash and two stars) and end with */ (that is, a star and a slash) and copies those to a documentation file. Even if you don't write many of those comments, javadoc also puts a summary of the methods and fields in your class into the associated file.

I recommend that you use Javadoc-style documentation at the start of your class and before each field and method.

One odd aspect of Javadoc is that you indcate special aspects of your documentation with tags that begin with an at sign. In the sample above, you see @pre, @post, and @param. Other important tags include

• @author, which is used to indicate an author of the class. You should include this tag only in the Javadoc comment for the whole class.
• @version, which is used to indicate the version of the class. You should also include this tag only in the Javadoc comment for the whole class.
• @exception NameOfException, which indicates an exception the method throws and why.
• @return, which describes return values.

Generating Javadoc

So, how do you run Javadoc? In Eclipse, it's fairly easy, you simply select Generate Javadoc from the Project menu.

History

Thursday, 22 February 2005 [Samuel A. Rebelsky]

• Created.

Sunday, 19 February 2006 [Samuel A. Rebelsky]

• Minor edits.
• Updated for Eclipse.