javadoc-style-guide

Javadoc Style Guide

When to Use

• Writing new public/protected classes, methods, or fields
• Reviewing Javadoc compliance
• Fixing Checkstyle Javadoc violations

Coverage Requirements (BLOCKING)

Required Documentation

Javadoc is required for all protected and public members:

• Classes, interfaces, and enums
• Methods (including constructors)
• Fields

Exceptions (No Javadoc Required)

• Methods annotated with @Override (inherited documentation applies)
• Methods annotated with @Test (test method names should be self-documenting)
• Private and package-private members (encouraged if complex)
• Generated code (*.antlr packages)

Structure and Formatting

Class/Interface/Enum Documentation

/**
 * Brief summary sentence describing the type's purpose.
 * <p>
 * Additional paragraphs providing more detail as needed.
 *
 * @param <T>
 *          description of type parameter (indent 10 spaces from asterisk)
 */
public class Example<T> {

Method Documentation

/**
 * Brief summary sentence describing what the method does.
 * <p>
 * Additional detail about behavior, side effects, or usage notes.
 *
 * @param paramName
 *          description of the parameter (indent 10 spaces from asterisk)
 * @return description of return value
 * @throws ExceptionType
 *          when this exception is thrown (indent 10 spaces from asterisk)
 */
public String exampleMethod(String paramName) throws ExceptionType {

Tag Order (Enforced by Checkstyle)

Tags must appear in this order:

1. @param (all parameters, in declaration order)
2. @return
3. @throws / @exception
4. @deprecated

Multi-line Tag Indentation

Continuation lines must be indented 10 spaces from the asterisk:

/**
 * @param config
 *          the configuration object used to initialize the component
 *          and establish default settings
 */

Summary Sentence Rules

Forbidden Patterns (Checkstyle Enforced)

Do NOT start summaries with:

• @return the - e.g., "Returns the value" (redundant)
• This method returns - redundant phrasing
• A {@code ClassName} is a - weak opening