Missing Javadoc

ID

java.missing_javadoc

Severity

low

Remediation Complexity

auto_fix

Remediation Risk

low

Remediation Effort

low

Resource

Documentation

Language

Java

Tags

best-practice, documentation

Description

Reports declarations that lack a Javadoc comment or whose Javadoc is missing required tags.

Public APIs should be documented with Javadoc so that consumers can understand the contract without reading the implementation. Missing @param, @return, or @throws tags force readers to guess parameter semantics, return values, and error conditions.

This rule does not apply to files under paths configured in applicativeCode.excludedPathPatterns (typically /test/, generated sources, fixtures). Test code is conventionally not documented, so missing Javadoc there would produce only noise. Matching uses the project-relative path — configure additional exclusions in depsdoctor.yml.

Rationale

  • Maintainability – Undocumented public APIs slow down onboarding and increase the chance of misuse.

  • Tooling – IDEs and documentation generators rely on Javadoc to provide inline help and API reference pages.

Configuration

The rule is fully configurable. Properties control which declarations require Javadoc and which tags must be present.

Declaration checks

Property Default Description

checkPublicClasses

true

Require Javadoc on public classes, interfaces, enums, records

checkProtectedClasses

false

Require Javadoc on protected types

checkPrivateClasses

false

Require Javadoc on private types

checkPublicMethods

true

Require Javadoc on public methods and constructors

checkProtectedMethods

false

Require Javadoc on protected methods

checkPrivateMethods

false

Require Javadoc on private methods

checkPublicFields

false

Require Javadoc on public fields

checkProtectedFields

false

Require Javadoc on protected fields

checkPrivateFields

false

Require Javadoc on private fields

Tag requirements

When a method or constructor has Javadoc, these properties control which tags must be present.

Property Default Description

requireParam

true

Require @param for each parameter

requireReturn

true

Require @return on non-void methods

requireThrows

false

Require @throws when exceptions are declared

requireAuthor

false

Require @author tag

requireVersion

false

Require @version tag

requireSince

false

Require @since tag

requireSee

false

Require @see tag

Remediation

Non-compliant code

public class Calculator {
    // Missing Javadoc on public method
    public int add(int a, int b) {
        return a + b;
    }

    /**
     * Multiplies two numbers.
     * Missing @param and @return tags.
     */
    public int multiply(int a, int b) {
        return a * b;
    }
}

Compliant code

/**
 * Basic arithmetic operations.
 */
public class Calculator {
    /**
     * Adds two integers.
     * @param a the first operand
     * @param b the second operand
     * @return the sum
     */
    public int add(int a, int b) {
        return a + b;
    }
}

References