Javadoc has impossible ‘throws’ tag¶

ID: java/inconsistent-javadoc-throws
Kind: problem
Security severity: 
Severity: recommendation
Precision: high
Tags:
   - quality
   - maintainability
   - readability
Query suites:
   - java-code-quality.qls
   - 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¶

Java SE Documentation: How to Write Doc Comments for the Javadoc Tool,

GeezerVison

Javadoc has impossible ‘throws’ tag¶

Recommendation¶

Example¶

References¶