Java Documentation

Java - Documentation Comments (Javadoc)

Writing clear documentation is crucial for maintainable and understandable code. Java provides a standard way to embed documentation directly within source code using special comments, which can then be processed by the javadoc tool to generate professional API documentation (typically in HTML format).

Types of Comments in Java:

Type	Syntax	Description
Single-line	// text	The compiler ignores everything from // to the end of the line. Used for short explanations or temporarily disabling code.
Multi-line	/* text */	The compiler ignores everything from /* to */. Used for longer comments spanning multiple lines.
Documentation	/** documentation */	Special comment format recognized by the javadoc tool. Must immediately precede a class, interface, method, constructor, or field declaration.

What is Javadoc?

Javadoc is a command-line tool included with the Java Development Kit (JDK). It parses documentation comments (/** ... */) in Java source files and generates API documentation.

Structure of a Documentation Comment:

A Javadoc comment consists of:

1. Main Description: The first sentence should be a concise summary of the element being documented (class, method, etc.). This sentence ends at the first period followed by a space or tab, or at the first block tag. It’s used in summary tables.
2. Detailed Description: Additional paragraphs providing more detail. You can use HTML tags (like <p>, <ul>, <li>, ```, **, <i>) for formatting within the description.
3. Block Tags: Special tags starting with @ (e.g., @param, @return, @throws, @see, @since, @author, @version, {@code}, {@link}) provide specific metadata about the documented element.

Example Documentation Comment:

/**
 * Represents a simple calculator capable of basic arithmetic.
 * <p>
 * This class provides methods for addition, subtraction, etc.
 * It demonstrates the use of Javadoc comments.
 * </p>
 *
 * @author  Your Name
 * @version 1.1
 * @since   1.0
 */
public class SimpleCalculator {

    /**
     * Adds two integer numbers.
     * <p>
     * This is the primary addition method. Ensure inputs are valid integers.
     * For floating-point addition, use {@code add(double, double)}.
     * </p>
     *
     * @param numA The first integer operand.
     * @param numB The second integer operand.
     * @return int The sum of numA and numB.
     * @see #subtract(int, int)
     * @see <a href="https://www.example.com/math_principles">Math Principles</a>
     */
    public int add(int numA, int numB) {
        return numA + numB;
    }

    /**
     * Subtracts the second integer from the first.
     *
     * @param numA The integer to subtract from.
     * @param numB The integer to subtract.
     * @return The result of the subtraction.
     * @throws IllegalArgumentException if numB is larger than numA (example condition).
     */
    public int subtract(int numA, int numB) {
        if (numB > numA) {
             // Example of documenting an exception
             throw new IllegalArgumentException("numB cannot be larger than numA for this operation");
        }
        return numA - numB;
    }

    // Other methods would follow...
}

Common Javadoc Tags:

Here are some of the most frequently used block tags:

Tag	Description
@param parameter-name description	Describes a method or constructor parameter. Must be followed by the parameter name and then the description.
@return description	Describes the value returned by a method (omit for void methods).
@throws exception-class description or @exception exception-class description	Documents an exception that the method might throw. Include the fully qualified class name of the exception.
@see reference	Adds a “See Also” entry. Can reference other classes/methods (package.Class#member), link to external URLs (<a href=... >...</a>), or provide plain text.
@since version-text	Indicates the version of the software when this feature was introduced (e.g., @since 1.2).
@author author-name	Specifies the author(s) of the class or interface.
@version version-text	Specifies the version of the class or interface (often related to SCM version). Requires the -version option when running javadoc.
@deprecated description	Marks the element as deprecated, advising against its use. Explain why and suggest alternatives.
{@code text}	Renders text in code font without interpreting HTML. Useful for code snippets or identifiers within descriptions.
{@link package.Class#member label}	Inserts an inline link to another Javadoc element, displayed using the label (or the element name if label is omitted). Rendered in code font.
{@linkplain ...}	Same as {@link} but the label is rendered in plain font.
{@value package.Class#field}	Displays the value of a static final field (constant) directly in the documentation.

Generating Javadoc Documentation:

You can generate the documentation using the javadoc command from your terminal or command prompt.

Basic Usage:

# Generate docs for specific Java files
javadoc MyClass1.java MyClass2.java

# Generate docs for all Java files in a directory (and subdirectories)
javadoc -d output_directory -sourcepath src_directory -subpackages com.mypackage

# Common options:
# -d <directory> : Specify the output directory for generated HTML files.
# -sourcepath <pathlist> : Specify where to find source files.
# -classpath <pathlist> : Specify where to find referenced class files.
# -subpackages <packagename>[:<packagename>...] : Process subpackages recursively.
# -author : Include @author tags (excluded by default).
# -version : Include @version tags (excluded by default).
# -private : Include private members (default is protected/public).

Example Command:

Assuming SimpleCalculator.java is in a src directory under com/example/util:

javadoc -d docs -sourcepath src -subpackages com.example.util -author -version

This command would generate HTML documentation in a docs subdirectory, processing com.example.util and its subpackages found within the src directory, including author and version information.

Best Practices:

• Document all public classes, interfaces, methods, and constants.
• Write clear and concise summary sentences.
• Provide detailed explanations where necessary, including usage examples if helpful ({@code ...} is great for this).
• Document all parameters (@param), return values (@return), and exceptions (@throws).
• Use @see, {@link}, and {@linkplain} to cross-reference related elements.
• Keep documentation up-to-date with code changes.
• Use HTML tags sparingly and correctly for formatting.
• Configure your IDE to help generate Javadoc stubs.

Consult the official Oracle Javadoc documentation for a complete list of tags and options.