Detect documented @throws for (checked) exceptions that are never thrown

[Luro02]

What it does

For example, one could have a javadoc like this one:

/**
 * Main entry point for the application.
 * 
 * @param args no arguments are expected
 * @throws InvalidArgumentException if something breaks
 */
public static void main(String[] args) {
    System.out.println("Hello World!");
}

where the mentioned InvalidArgumentException is a checked exception. Because it has a checked exception, it must be either caught in the method or the method must be annotated with an @throws.

The implementation for this should be easy:

1. Visit every CtMethod
2. Check if the method has a javadoc, if it does not, skip it.
3. Keep track of all exceptions thrown by the method
4. Parse the doc with the javadoc parser like here (create a utility method as well, so we don't have duplicate code)

   autograder/autograder-core/src/main/java/de/firemage/autograder/core/check/complexity/UnusedImport.java

   Lines 111 to 124 in 0a29b0e

   	try {
   	JavadocParser parser = new JavadocParser(ctJavaDoc.getRawContent(), ctJavaDoc.getParent());
   	return parser.parse()
   	.stream()
   	.flatMap(element -> element.accept(new ReferenceFinder()).stream())
   	.anyMatch(otherReference -> isReferencingTheSameElement(ctReference, otherReference));
   	} catch (AssertionError e) {
   	// the javadoc parser did throw an assertion error on javadoc that was not valid, but the code did compile,
   	// so this is caught here to prevent the whole thing from crashing;
   	//
   	// The javadoc in question was: "/**\n * @param length the {@param string} and {@param value}.\n */"
   	return false;
   	}

5. Then visit every @throws where one checks if it is a checked exception and if it is part of the throws for the method, if not, report a problem.

Lint Name

DOCUMENTED_EXCEPTION_NOT_THROWN

Category

comment

Example

See above.