Missing Javadoc

ID

java.missing_javadoc

Severity

low

Remediation Complexity

trivial

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.

"Public" means the visibility keyword, not "everything that is not private". A package-private member is an implementation detail of its package and is not checked by default; a member of an interface or annotation type is public even though no keyword says so, and is.

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

checkPackageClasses

false

Require Javadoc on package-private types

checkPrivateClasses

false

Require Javadoc on private types

checkPublicMethods

true

Require Javadoc on public methods and constructors

checkProtectedMethods

false

Require Javadoc on protected methods

checkPackageMethods

false

Require Javadoc on package-private methods

checkPrivateMethods

false

Require Javadoc on private methods

checkPublicFields

false

Require Javadoc on public fields

checkProtectedFields

false

Require Javadoc on protected fields

checkPackageFields

false

Require Javadoc on package-private fields

checkPrivateFields

false

Require Javadoc on private fields

Exempt members

Four kinds of member carry no information a Javadoc comment could add. Each is exempt by default; set its property to true to require documentation anyway.

Property Default Description

checkAccessors

false

Accessors and mutators. Recognised by the body — a method that does nothing but read or write one field — so fluent setters and builder methods count too

checkOverrides

false

Methods annotated @Override, documented by the member they override

checkEmptyConstructors

false

Constructors with an empty body

checkConstants

false

static final fields, which say what they are in their name and initializer

Tag requirements

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

Property Default Description

requireParam

false

Require @param for each parameter

requireReturn

false

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

© 2026 Xygeni. All rights reserved