了解 CheckStyle 检查“JavadocMethod”，属性“logLoadErrors”答案

【问题标题】：Understanding CheckStyle Check "JavadocMethod", property "logLoadErrors"了解 CheckStyle 检查“JavadocMethod”，属性“logLoadErrors”
【发布时间】：2017-01-23 05:04:54
【问题描述】：

阅读检查JavadocMethod的CheckStyle文档我不了解logLoadErrors的属性。

我们被告知

这个检查可能需要加载@throws标签中提到的异常类来检查它们是否是RuntimeExceptions。如果加载类失败，此属性允许控制 checkstyle 的错误处理。如果设置为 false，则假定存在类路径配置问题，并且 TreeWalker 将完全停止对该类的操作。如果设置为 true（默认值），则 checkstyle 假定 javadoc 中存在拼写错误或重构问题，并将问题记录在正常的 checkstyle 报告中（可能掩盖配置错误）。

另外属性suppressLoadErrors描述如下：

当 logLoadErrors 设置为 true 时，TreeWalker 会完全处理一个类并将加载异常的任何问题显示为 checkstyle 违规。当此属性设置为 true 时，在 logLoadErrors 设置为 true 时生成的违规将被禁止在 checkstyle 报告中报告为违规。

我的第一个想法是，在标准配置中，logLoadErrors = true, suppressLoadErrors = false CheckStyle 如果未找到@throws 标签中提到的异常类，则会发出警告。我试过这个例子：

 /**
  * 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;
}

我以为我会在运行 CheckStyle 时收到警告，因为 MyException 类不存在。但我没有得到任何警告。有人可以提供另一个例子吗？

【问题讨论】：

标签： java javadoc checkstyle

【解决方案1】：

此属性已被删除，因此从 v8.28 开始不可用。

您可以找到更多信息here。

【讨论】：

【解决方案2】：

这是一个非常好的问题，它与 Checkstyle 工具的一个阴影区域有关。其实在JavadocMethodCheck的父类AbstractTypeAwareCheck的源码中是这样写的：

Checkstyle 不是类型感知工具，并且从此类派生的所有检查都可能不稳定。

在我看来，这有点悲观，因为如果配置正确，它的逻辑应该可以正常工作，但当然它取决于运行时的实际类路径配置。

在Checkstyle code 中，您询问的选项是这样的（此处简化为伪代码）：

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

因此，每当 Checkstyle 尝试加载类（在您的情况下为 MyException）时，失败，它将评估这些标志以确定要做什么。

如果您信任您的类路径（我们现在通常这样做），您希望突出显示 Javadoc 中的错误，因此您可以将 suppressLoadErrors 设置为 false。如果您不信任您的类路径，您可以将suppressLoadErrors 设置为true。您永远不会将 logLoadErrors 更改为默认值 true 以外的其他值，因为这会阻止 Checkstyle 做其他有意义的事情。

如果我从 throws 子句中删除不存在的异常，您的示例实际上会为我生成警告：

/**
 * 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;
}

无法编译的代码通常不会发送到代码质量工具（或仅在以前的本地版本中），因此这可能是您的 IDE 的特殊性。

此答案基于 Checkstyle 7.1.1。希望能给大家带来启示！

【讨论】：