Creating API Documentation – Intermediate Programming

When writing code we can use package declarations and access modifiers to make some of the classes, fields, and methods that we write accessible to others. The classes, fields and methods that are accessible to others are referred to as the Application Programming Interface or API of the library or program we are writing. It is good form to provide documentation for the APIs that we write as a resource for our API users.

The Java programming environment provides a utility named javadoc that creates HTML documentation for our API using certain formatted comments written in source code files and other files within our packages. Although, the Javadoc tool can generate documentation from various types of files, we’re going to focus on creating documentation from comments in .java files. A tutorial on using javadoc can be found here.

Documentation comments (or doc comments) specified in source code are placed before a class, field, constructor or method declaration and placed between /** and */ delimiters. A doc comment consists of two parts: a description followed by a list of tags.

Consider the following example.

/**
   Returns the value of the argument that is larger.   
    
   @param a any integer
   @param b any integer
   @return  the larger of the values in a and b
*/
public int min(int a, int b) {
    return a >= b? a : b;
}

The result of using the javadoc tool on the above set of comments would be HTML code that appears in a browser like the following:

public static int min(int a, int b)

Returns the value of the argument that is larger.

Parameters:

a - any integer

b - any integer

Returns:

the larger of the values in a and b

Conventions

The description is a short summary of the element written in HTML.
If more than one paragraph is needed for the description, use <p> tags to separate them.
The description must precede the list of @tags and a blank line should separate the two.
Use <code> … </code> tags for keywords, identifiers, and code examples.
If referring to multiple methods with the same name, do not include parenthesis. If referring to a specific method that is overloaded, include parenthesis and the type of the parameters.
Method descriptions should begin with a verb. Eg. Returns the value of the argument that is larger.
Use the word this when referring to the instance on which an member is invoked.

Required Tags

An @param tag is required for each parameter in a constructor or method.
The @return tag is required for each method that has a non void return type.
The @throws tag must be included for any method that throws an exception.

Running Javadoc

There are many options for the javadoc tool and all of the various options can be found here.

The javadoc tool creates a set of documentation files, all in HTML format. These include a summary list file, an overview file, a deprecated list file, and files for each of the public classes in the packages.

Since we’re developing a set of packages in a repository we can create documentation for all of our packages at once by

Changing our current working directory to the directory that holds our repository root directory and
Running the following command while replacing repo-name with the name of our repository. Replace repo-name with the name of your respository.

javadoc repo-name -subpackages * -d ./repo-name/docs

The option -subpackages * tells javadoc to create documentation for all subpackages. The -d flag specifies where the documentation files will be stored. By including -d ./repo-name/docs, javadoc will put the files in a subdirectory in our repository named docs.