Javadoc Content

ID

java.javadoc_content

Severity

low

Remediation Complexity

auto_fix

Remediation Risk

low

Remediation Effort

low

Resource

Documentation

Language

Java

Tags

best-practice, documentation

Description

Reports quality issues in existing Javadoc comments. Unlike java.missing_javadoc which checks whether Javadoc is present, this rule checks whether existing Javadoc is correct.

Rationale

Misleading Javadoc is worse than no Javadoc: callers read a wrong contract, generated reference pages carry stale statements, and outdated TODO markers leak into the public API surface. Keeping Javadoc internally consistent with the declaration it documents preserves the value of the doc for tooling and for API consumers.

Checks

  • @return on void methods – A @return tag on a void method is misleading.

  • @exception instead of @throws – The @exception tag is a legacy synonym for @throws. Modern code should use @throws consistently.

  • @param tag order – When multiple @param tags are present, they should appear in the same order as the method parameters for readability.

  • TODO/FIXME in Javadoc – TODO and FIXME markers in Javadoc are visible to API consumers via generated documentation. They belong in implementation comments, not in the public API contract.

  • Misplaced comment – A non-Javadoc comment between a /** */ block and its declaration disconnects the Javadoc from the code it documents.

Configuration

Property Default Description

forbidReturnOnVoid

true

Flag @return on void methods

forbidExceptionTag

true

Flag @exception (prefer @throws)

checkParamOrder

true

Flag @param tags that don’t match parameter declaration order

forbidTodoInJavadoc

true

Flag TODO/FIXME markers in Javadoc blocks

checkJavadocLocation

true

Flag comments wedged between a Javadoc block and its declaration

Remediation

Non-compliant code

/**
 * Returns nothing.
 * @return nothing at all
 */
public void doWork() { } // @return on void

/**
 * Processes input.
 * @exception IOException if I/O fails
 */
public void process() throws IOException { } // @exception instead of @throws

/**
 * Adds numbers.
 * @param b the second
 * @param a the first
 * @return the sum
 */
public int add(int a, int b) { return a + b; } // wrong @param order

/**
 * TODO: finish this.
 */
public void incomplete() { } // TODO in Javadoc

Compliant code

/**
 * Processes input.
 * @throws IOException if I/O fails
 */
public void process() throws IOException { }

/**
 * Adds numbers.
 * @param a the first
 * @param b the second
 * @return the sum
 */
public int add(int a, int b) { return a + b; }

References