如何调整DocLint(-Xdoclint)以允许JavaDoc使用自定义标签？

你遇到的这个问题很常见——DocLint默认对JavaDoc标签的检查非常严格，遇到未内置的标签（比如@checkstyle）就会抛出unknown tag错误。不用完全禁用所有检查，有两种更精准的解决方式：

方式一：仅关闭「未知标签」检查 #

如果你不想逐个注册自定义标签，只想让DocLint忽略所有未知标签的报错，可以直接在编译参数中禁用unknown检查项，保留其他DocLint规则（比如缺失参数、HTML格式错误等）。

配置示例： #

• Javac命令行：

  javac -Xdoclint:-unknown YourClass.java
  

• Maven Compiler插件：在pom.xml中添加配置：

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <version>3.11.0</version>
        <configuration>
          <compilerArgs>
            <arg>-Xdoclint:-unknown</arg>
          </compilerArgs>
        </configuration>
      </plugin>
    </plugins>
  </build>
  

方式二：注册自定义标签（更严谨） #

如果希望只允许特定的自定义标签（比如仅@checkstyle），其他未知标签仍触发检查，可以通过JavaDoc的-tag参数注册标签，DocLint会自动识别已注册的标签。

配置示例： #

• Javac命令行：

  javac -tag checkstyle:a:"Checkstyle Rule:" YourClass.java
  

  这里的a表示标签可以有参数，后面的字符串是标签的描述文本（可选）。
• Maven Javadoc插件：在pom.xml中配置：

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>3.5.0</version>
        <configuration>
          <tags>
            <tag>
              <name>checkstyle</name>
              <placement>a</placement>
              <head>Checkstyle Rule:</head>
            </tag>
          </tags>
        </configuration>
      </plugin>
    </plugins>
  </build>
  

两种方式的对比 #

• 方式一操作简单，适合有大量自定义标签、不想逐个维护的场景；
• 方式二更严谨，能确保只有你认可的自定义标签可以出现在JavaDoc中，避免拼写错误或无关标签的混入。

内容的提问来源于stack exchange，提问作者Krzysztof Krasoń