Pure Programmer
Blue Matrix

Cluster Map

Documentation

Every program describes how to accomplish some task in the language of mathematics and logic. While high level languages help us to express programming concepts easily and clearly, they are often not the best way to explain the abstract concepts involved. This is where programming documentation comes to the rescue. Documentation in the form of program comments interspersed in the source code are a means to explain in plain English the expected workings of a program and the high level concepts involved. They are a way to include information that is not obvious or clear in the programming statements themselves.

In this site we will use a standard block of comments at the beginning of each file to explain the purpose of the program in the file. We will include the program author, the date that the program was written and any updates that were made. This last use of comments to document the update history is one that should only be used for programs that are not under source code control. For complex multi-file programs a [[source code control system]] will be a necessity and will perform the task of managing the update history of files.

Basic comments take two forms: single-line and multiple-line. Single-line comments begin with a double slash (//) and continue to the end of the current line. They can start at the beginning of the line or anywhere in the middle of a line. Multi-line comments may begin anywhere using the comment start symbol (/*) and continue until the comment end symbol (*/). All characters in the comment are ignored and not considered to be executable program content.

A special type of multi-line comment is the JavaDoc comment. It is used for documentation that can be extracted and formatted into formal documentation for the file. JavaDoc comments begin with the symbol (/**) and end with the symbol (*/)

The following are examples of comments.

// This is a single line comment

/* This is an example
   of a multi-line comment */

/** documentation */

Each program file, class or function/method should have a comment preceding it that describes the purpose and typical usage of the item being documented. Comments should document the high-level behavior and not get involved in the specifics of the current implementation. Implementation details can change but the interface described by the comment should rarely change. It also helps to know how the program, class or function/method is intended to perform when the code itself is found to have a bug. The following is an example of what a program file comment might look like.

/*********************************************************************
 * This program computes ...
 *
 * Copyright © 2023 Richard Lesh.  All rights reserved.
 ********************************************************************/

Modern Java Documentation

Modern Java documentation has two layers:

  1. Human-facing guides: README, tutorials, architecture notes, examples
  2. API/reference docs: generated from source using Javadoc-style comments

What Should Be Documented

Modern Java documentation should describe:

This aligns better with how modern Java libraries are read and maintained. Java has a built-in documentation syntax for documenting APIs called Javadoc. Javadoc reads specially formatted comments in Java source code and can generate HTML API documentation automatically.

Javadoc Comments

Javadoc uses documentation comment blocks such as /** ... */. It supports summary and detailed descriptions, plus tags like @param, @return, @throws, and @author.

For example, a Javadoc comment for a method might look like this:

/**
 * Computes the area of a circle.
 *
 * Uses the standard formula pi * r^2.
 *
 * @param radius radius of the circle in meters; must be non-negative
 * @return area in square meters
 * @throws IllegalArgumentException if radius is negative
 */
public static double circleArea(double radius) {
    if (radius < 0) {
        throw new IllegalArgumentException("radius must be non-negative");
    }
    return Math.PI * radius * radius;
}

This is a typical Javadoc documentation block. The comment begins with /**. Unlike normal comments (// or /* */), this style signals to documentation tools that the text inside should be parsed and included in generated API documentation.

The comment is placed immediately before the method declaration, which tells Javadoc that the documentation applies to that method.

The first sentence provides a short summary of the method.

Most documentation systems display the summary description in:

The summary should explain what the method does, not how it works internally.

After the summary line, you can include additional explanatory text.

This section may describe:

Javadoc treats this as the detailed description of the method.

The @param tag documents each formal parameter of the method.

Good parameter documentation usually explains:

Each method parameter should normally have its own @param entry.

The @return tag explains what value the method returns.

It should describe:

Even if the return type is obvious from the code, describing the meaning of the result is helpful for readers.

The @throws tag documents exceptions that the method may throw.

It should include:

This helps programmers understand the error conditions that must be handled when calling the method.

Structured comments like this serve several purposes:

  1. Readable source code documentation
  2. Automatically generated API reference manuals
  3. Improved IDE tooltips and code navigation
  4. Clear documentation of interface contracts

Tools such as Javadoc can scan these comments and generate HTML documentation directly from the source code.

Classes, enumerations, interfaces, and generic types can also have Javadoc comments placed before them. For example:

Class Example

/**
 * Represents a bank account with a running balance.
 *
 * Instances of this class are not thread-safe.
 */
public class Account {
    private double balance;

    /**
     * Deposits money into the account.
     *
     * @param amount amount to deposit; must be positive
     */
    public void deposit(double amount) {
        balance += amount;
    }

    /**
     * Returns the current balance.
     *
     * @return current balance in dollars
     */
    public double getBalance() {
        return balance;
    }
}

Enumeration Example

/**
 * States a task can be in during execution.
 */
public enum TaskState {
    /** Task has not started yet. */
    PENDING,

    /** Task is currently executing. */
    RUNNING,

    /** Task finished successfully. */
    COMPLETE,

    /** Task ended with an error. */
    FAILED
}

Generic Type Example

/**
 * Returns the larger of two values.
 *
 * @param <T> a type that implements Comparable
 * @param a first value
 * @param b second value
 * @return the larger of a and b
 */
public static <T extends Comparable<T>> T maxValue(T a, T b) {
    return a.compareTo(b) >= 0 ? a : b;
}

Generic comments use the @param <T> form to document the type parameter(s) used by the generic method or class.

Javadoc also supports documenting packages and modules.

Package Example

/**
 * Utility classes for common mathematical operations.
 */
package org.pureprogrammer.math;

Interface Example

/**
 * Defines a simple shape with an area.
 */
public interface Shape {
    /**
     * Computes the area of the shape.
     *
     * @return area of the shape
     */
    double area();
}

Modern docs are much easier to learn from when each API item includes a short usage example.

/**
 * Converts a string to uppercase.
 *
 * <p>Example:</p>
 * <pre>{@code
 * String s = toUpper("Hello");
 * // s == "HELLO"
 * }</pre>
 *
 * @param text input text
 * @return uppercase copy of the input text
 */
public static String toUpper(String text) {
    return text.toUpperCase();
}

In Javadoc, {@code ...} is an inline tag that tells the documentation generator to display the enclosed text as code.

It has two main effects:

  1. Uses a monospace font
  2. Automatically escapes HTML characters such as <, >, and &

The <pre> HTML element is used to preserve the whitespace in your code example

Combined, these techniques make it safer and cleaner for showing program code in documentation.

Generating Documentation with Javadoc

Once your Java code contains Javadoc-style comments, you can automatically generate a browsable documentation website.

Run Javadoc

If the JDK is installed, the javadoc tool is usually included.

Linux and
Raspberry Pi

$ javadoc -d doc src/*.java

macOS

% javadoc -d doc src/*.java

Windows

> javadoc -d doc src\*.java

The -d option tells Javadoc where to place the generated HTML documentation.

Generate Documentation for Packages

In larger projects, it is more common to generate documentation for packages rather than individual files. For example:

$ javadoc -d doc -sourcepath src -subpackages org.pureprogrammer

This tells Javadoc to:

View the Generated Documentation

The generated documentation will appear in the output directory. Open the index.html file in a web browser to browse your project’s API documentation.

References