CodeQL documentation

Javadoc has impossible ‘throws’ tag

ID: java/inconsistent-javadoc-throws
Kind: problem
Severity: recommendation
Precision: high
Tags:
   - maintainability
Query suites:
   - java-security-and-quality.qls

Click to see the query in the CodeQL repository

A Javadoc @throws or @exception tag that references an exception that cannot be thrown is misleading.

Recommendation

Ensure that you only include the @throws or @exception tags in Javadoc when an exception can be thrown.

Example

The following example shows a method with Javadoc that claims it can throw Exception. Since Exception is a checked exception and the method does not declare that it may throw an exception, the Javadoc is wrong and should be updated.

/**
 * Javadoc for method.
 *
 * @throws Exception if a problem occurs.
 */
public void noThrow() {
	System.out.println("This method does not throw.");
}

In the following example the Javadoc has been corrected by removing the @throws tag.

/**
 * Javadoc for method.
 */
public void noThrow() {
	System.out.println("This method does not throw.");
}

References