Understanding CheckStyle Check "JavadocMethod", property "logLoadErrors"

Question

Reading the CheckStyle documentation for the Check JavadocMethod I do not understand the property logLoadErrors.

There we are told

This check may need to load exception classes mentioned in the @throws tag to check whether they are RuntimeExceptions. If loading the class fails, this property allows to control checkstyle's error handling. If set to false a classpath configuration problem is assumed and the TreeWalker stops operating on the class completely. If set to true (the default) , checkstyle assumes a typo or refactoring problem in the javadoc and logs the problem in the normal checkstyle report (potentially masking a configuration error).

Furthermore the property suppressLoadErrors is described as follows:

When logLoadErrors is set to true, the TreeWalker completely processes a class and displays any problems with loading exceptions as checkstyle violations. When this property is set to true, the violations generated when logLoadErrors is set true are suppressed from being reported as violations in the checkstyle report.

My first thought was that on standard configuration logLoadErrors = true, suppressLoadErrors = false CheckStyle gives a warning if an Exception class mentioned in the @throws tag is not found. I tried this example:

 /**
  * Returns if the first of two given numbers is smaller than the other one.
  * @param a Description param a
  * @param b Description param b
  * @throws Exception bla
  * @throws MyException foo
  */
public boolean javadocMethod(int a, int b) throws Exception, MyException {
    return a < b;
}

I thought I would get a warning on running CheckStyle because the class MyException does not exist. But I don't get any warning. Can some provide another example?

zappee · Accepted Answer · 2020-05-13 11:30:27Z

1

This property was removed, so it is not available from v8.28.

You can find more info here.

answered May 13, 2020 at 11:30

zappee

23.2k15 gold badges97 silver badges157 bronze badges

Sign up to request clarification or add additional context in comments.

Comments

barfuin · Accepted Answer · 2016-09-21 19:03:01Z

This is a very good question, and it pertains to one of the shadier areas of the Checkstyle tool. In fact, in the source code of JavadocMethodCheck's parent class, AbstractTypeAwareCheck, it says:

Checkstyle is not type aware tool and all Checks derived from this class are potentially unstable.

This is a slight bit pessimistic, in my opinion, because if configured correctly, its logic should work quite okay, but of course it depends on the actual classpath configuration at runtime.

In the Checkstyle code, the option you ask about works like this (simplified here to pseudocode):

protected void logLoadErrorImpl(int lineNo, int columnNo, ...) {
    if (!logLoadErrors) {
        // throw an exception
    }
    if (!suppressLoadErrors) {
        // report a Checkstyle violation
    }
}

So, whenever Checkstyle tries to load a class (in your case, MyException), and this fails, it will evaluate these flags to determine what to do.

If you trust your classpath (which we normally do these days), you want to highlight errors in the Javadoc, so you would set suppressLoadErrors to false. If you don't trust your classpath, you would set suppressLoadErrors to true. You would never change logLoadErrors to something other than its default of true, because that would stop Checkstyle from doing other meaningful stuff.

Your example actually produces the warning for me if I remove the non-existent exception from the throws clause:

/**
 * Returns if the first of two given numbers is smaller than the other one.
 * @param a Description param a
 * @param b Description param b
 * @throws Exception bla
 * @throws MyException foo
 */
public boolean javadocMethod(int a, int b) throws Exception {
    return a < b;
}

Code which does not compile is often not sent to the code quality tools (or only in a previous local version), so this might be a particularity of your IDE.

This answer was based on Checkstyle 7.1.1. Hope it sheds some light!

Collectives™ on Stack Overflow

Understanding CheckStyle Check "JavadocMethod", property "logLoadErrors"

2 Answers 2

Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related