每当有特定注释时如何使 Checkstyle 忽略丢失的 JavaDoc

Question

我想自定义 Checkstyle JavadocVariable 规则，这样它就不会抱怨具有 @FindBy 注释的字段。

class Demo{

    @FindBy(id = "new-button")
    public WebElement createButton;  //<- no JavaDoc required because it is a field "injected" by selenium

    public String otherField;    //<- complain about missing Java doc
}

但我不知道如何在 checkstyle.xml 文件中指定它。有人有想法吗？

在此用例中不起作用的事情：

修改勾选class也是无解！
SuppressWithNearbyCommentFilter 不行，因为是注解不是注释

Answer 1

我知道几种解决方案，但所有这些都需要额外的工作。

实现自己的 JavadocVariableCheck 并可能在提供注释的情况下跳过检查。
实施 checkstyle 过滤器（类似于 SuppressWarningsHolder + SuppressWarningsFilter 但具有注释支持）
或者实现简单的过滤器扫描 @FindBy 并忽略它后面的两行。

我的解决方案（最简单的）：

package org.aap.checks;

import com.google.common.collect.Lists;
import com.puppycrawl.tools.checkstyle.api.AuditEvent;
import com.puppycrawl.tools.checkstyle.api.AutomaticBean;
import com.puppycrawl.tools.checkstyle.api.FileContents;
import com.puppycrawl.tools.checkstyle.api.Filter;
import com.puppycrawl.tools.checkstyle.checks.FileContentsHolder;

import java.lang.ref.WeakReference;
import java.util.Collections;
import java.util.Iterator;
import java.util.List;

public class SuppressWithAnnotationFilter
        extends AutomaticBean
        implements Filter {

    public class Tag implements Comparable<Tag> {
        private final int firstLine;
        private final int lastLine;

        public Tag(int firstLine, int lastLine) {
            this.firstLine = firstLine;
            this.lastLine = lastLine;
        }

        @Override
        public int compareTo(Tag other) {
            if (firstLine == other.firstLine) {
                return lastLine - other.lastLine;
            }
            return (firstLine - other.firstLine);
        }

        public boolean isMatch(AuditEvent event) {
            final int line = event.getLine();
            return line >= firstLine && line <= lastLine;
        }

        @Override
        public final String toString() {
            return "Tag[lines=" + firstLine + " to " + lastLine + "]";
        }
    }

    private final List<Tag> tags = Lists.newArrayList();
    private WeakReference<FileContents> fileContentsReference =
            new WeakReference<FileContents>(null);

    public FileContents getFileContents() {
        return fileContentsReference.get();
    }

    public void setFileContents(FileContents fileContents) {
        fileContentsReference = new WeakReference<FileContents>(fileContents);
    }

    @Override
    public boolean accept(AuditEvent event) {
        if (event.getLocalizedMessage() == null) {
            return true;        // A special event.
        }

        final FileContents currentContents = FileContentsHolder.getContents();
        if (currentContents == null) {
            return true;
        }
        if (getFileContents() != currentContents) {
            setFileContents(currentContents);
            tagSuppressions();
        }
        for (final Iterator<Tag> iter = tags.iterator(); iter.hasNext(); ) {
            final Tag tag = iter.next();
            if (tag.isMatch(event)) {
                return false;
            }
        }
        return true;
    }

    private void tagSuppressions() {
        tags.clear();
        final FileContents contents = getFileContents();

        String[] contentsLines = contents.getLines();
        for (int i = 0; i < contentsLines.length; i++) {
            if (contentsLines[i].contains("@FindBy")) {
                tags.add(new Tag(i+1, i+2));
            }
        }

        Collections.sort(tags);
    }
}

将生成的 class 添加到检查样式任务的 class 路径中，然后在 checkstyle.xml 中指定过滤器：

<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
    "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
    "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">
<module name="Checker">
  <module name="TreeWalker">
    ....
    <!-- your Check goes here -->
    <module name="org.aap.checks.SuppressWithAnnotationFilter"/>
    ....
  </module>
</module>

每当有特定注释时如何使 Checkstyle 忽略丢失的 JavaDoc

How to make Checkstyle ignore missing JavaDoc whenever there is a specific annotation

java

checkstyle