1. 概述
使用Javadoc是个好主意的原因有很多。例如，我们可以从 Java 代码生成 HTML，遍历它们的定义，并发现与它们相关的各种属性。
而且， 方便了开发人员之间的沟通， 提高了可维护性 。 Java DocLint是一个分析 Javadoc 的工具。每当发现错误的语法时，它就会抛出警告和错误。
在本教程中，我们重点讨论如何使用它。稍后，我们将研究它在某些情况下可能产生的问题，以及有关如何避免这些问题的一些准则。
2. 如何使用DocLint
假设我们有一个名为 Sample.java 的 类文件：
/**
* This sample file creates a class that
* just displays sample string on standard output.
*
* @autho Baeldung
* @version 0.9
* @since 2020-06-13
*/
public class Sample {
public static void main(String[] args) {
// Prints Sample! on standard output.
System.out.println("Sample!");
}
}
故意，这里有一个错误， @author 参数写成 @autho 。让我们看看如果我们尝试在没有 DocLint 的情况下创建 Javadoc*:*
从控制台输出中我们可以看到，Javadoc 引擎无法找出文档中的错误，也没有返回任何错误或警告。
要使 Java DocLint 返回此类警告，我们必须使用 –Xdoclint 选项执行 javadoc 命令。 （我们稍后会详细解释）：
正如我们在输出中看到的，它直接提到了 Java 文件第 5 行中的错误：
Sample.java:5: error: unknown tag: autho
* @autho Baeldung
^
3. -Xdoclint
-Xdoclint 参数具有用于不同目的的三个选项。我们将快速浏览一下每一项。
3.1. 没有任何
none 选项禁用 -Xdoclint 选项：
javadoc -Xdoclint:none Sample.java
3.2. 团体
当我们想要应用与某些组相关的某些检查时，此选项非常有用，例如：
javadoc -Xdoclint:syntax Sample.java
组变量有多种类型：
- 可访问性 – 检查可访问性检查器要检测的问题（例如， 表格 标签中没有指定标题或摘要属性）
- html – 检测高级 HTML 问题，例如将块元素放入内联元素中或未关闭需要结束标记的元素
- Missing – 检查是否缺少 Javadoc 注释或标签（例如，缺少注释或类，或者方法上缺少 @return 标签或类似标签）
- 引用 – 检查与 Javadoc 标记中对 Java API 元素的引用相关的问题（例如，在 @see 中找不到项目，或者 @param 之后的错误名称）
- 语法 – 检查低级问题，例如未转义的尖括号（< 和 >）和与号（&）以及无效的 Javadoc 标记
可以一次应用多个组：
javadoc -Xdoclint:html,syntax,accessibility Sample.java
3.3. 全部
此选项同时启用所有组，但如果我们想排除其中一些组怎么办？
我们可以使用 -group 语法：
javadoc -Xdoclint:all,-missing
4. 如何禁用 DocLint
由于 Java DocLint 在 Java 8 之前并不存在 ，因此这可能会带来不必要的麻烦，尤其是在旧的第三方库中。
我们已经在上一节中看到了 javadoc 命令的 none 选项。此外，还有一个选项可以 从 Maven、Gradle、Ant 等构建系统中禁用 DocLint 。我们将在接下来的几小节中看到这些。
4.1.梅文
从 maven-javadoc-plugin 版本 3.0.0 开始，添加了新的doclint配置。让我们看看如何配置它来禁用 DocLint：
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.1.1</version>
<configuration>
<doclint>none</doclint> <!-- Turn off all checks -->
</configuration>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
但 一般情况下，不建议使用 none 选项， 因为它会跳过所有类型的检查。我们应该使用 全部，缺失 反而。
当使用早期版本（v3.0.0之前）时，我们需要使用不同的设置：
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<additionalparam>-Xdoclint:none</additionalparam>
</configuration>
</plugin>
</plugins>
4.2.摇篮
我们可以使用一个简单的脚本在 Gradle 项目中停用 DocLint：
if (JavaVersion.current().isJava8Compatible()) {
allprojects {
tasks.withType(Javadoc) {
options.addStringOption('Xdoclint:none', '-quiet')
}
}
}
不幸的是，Gradle 不像上面示例中的 Maven 那样支持 extraparam ，所以我们需要手动完成。
4.3.蚂蚁
Ant 像 Maven 一样使用 extraparam ，因此我们可以设置 -Xdoclint:none， 如上面演示的那样。
5. 结论
在本文中，我们研究了使用 Java DocLint 的各种方法。当我们想要一个干净的、容易出错的 Javadoc 时，它可以帮助我们。
如需更多深入信息，最好查看官方文档。