Java DocLint – Java DocLint

最后修改: 2021年 6月 22日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

There are so many reasons why using Javadoc is a good idea. For example, we can generate HTML from our Java code, traverse through their definitions, and discover various properties related to them.

使用Javadoc有很多理由。例如，我们可以从我们的Java代码中生成HTML，遍历它们的定义，并发现与它们相关的各种属性。

Moreover, it facilitates communication among developers and improves maintainability. Java DocLint is a tool to analyze our Javadoc. It throws warnings and errors whenever it finds bad syntax.

此外，它促进了开发人员之间的交流，提高了可维护性。Java DocLint是一个分析我们Javadoc的工具。每当它发现不好的语法时就会抛出警告和错误。

In this tutorial, we focus on how we can use it. Later, we’ll look at the problems it can create in certain situations, along with some guidelines on how we can avoid them.

在本教程中，我们重点讨论如何使用它。稍后，我们将看看它在某些情况下可能产生的问题，以及一些关于我们如何避免这些问题的指南。

2. How to Use DocLint

2.如何使用DocLint

Suppose we have a class file named Sample.java:

假设我们有一个名为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!");
    }
}

Purposefully, There is a mistype here, the @author parameter is written @autho. Let’s see what happens if we try to make Javadoc without DocLint:

故意的，这里有一个错误的类型，@author参数被写成@autho。让我们看看如果我们尝试在没有DocLint的情况下制作Javadoc会发生什么：。

As we can see from the console output, the Javadoc engine couldn’t figure out the mistake in our documentation and did not return any errors or warnings.

我们可以从控制台输出中看到，Javadoc引擎无法找出我们文档中的错误，没有返回任何错误或警告。

To make Java DocLint return this type of warning, we have to execute the javadoc command with the –Xdoclint option. (we’ll explain this in detail later):

为了使Java DocLint返回这种类型的警告，我们必须在执行javadoc命令时加入-Xdoclint选项。(我们将在后面详细解释这个问题)。

As we can see in the output, it directly mentions the error in line 5 of our Java file:

我们可以在输出中看到，它直接提到了我们的Java文件第5行中的错误。

Sample.java:5: error: unknown tag: autho
 * @autho  Baeldung
   ^

3. -Xdoclint

3. Xdoclint

The -Xdoclint parameter has three options for different purposes. We’ll take a quick look at each one.

Xdoclint参数有三个选项，用于不同的目的。我们将快速浏览一下每一个选项。

3.1. none

3.1. 无

The none option disables the -Xdoclint option:

none选项禁用了Xdoclint选项。

javadoc -Xdoclint:none Sample.java

3.2. group

3.2 小组

This option is useful when we want to apply certain checks related to certain groups, for example:

当我们想应用与某些组相关的某些检查时，这个选项很有用，比如说。

javadoc -Xdoclint:syntax Sample.java

There are several types of group variables:

有几种类型的群体变量。

  • accessibility – checks for the issues to be detected by an accessibility checker (for example, no caption or summary attributes specified in a table tag)
  • html – detects high-level HTML issues, like putting block elements inside inline elements or not closing elements that require an end tag
  • missing – checks for missing Javadoc comments or tags (for example, a missing comment or class, or a missing @return tag or similar tag on a method)
  • reference – checks for issues relating to the references to Java API elements from Javadoc tags (for example, item not found in @see, or a bad name after @param)
  • syntax – checks for low-level issues like unescaped angle brackets (< and >) and ampersands (&) and invalid Javadoc tags

It’s possible to apply multiple groups at once:

有可能同时应用多个组。

javadoc -Xdoclint:html,syntax,accessibility Sample.java

3.3. all

3.3.所有

This option enables all groups at once, but what if we want to exclude some of them?

这个选项可以同时启用所有的组，但如果我们想排除其中一些组怎么办？

We could use the -group syntax:

我们可以使用-group语法。

javadoc -Xdoclint:all,-missing

4. How to Disable DocLint

4.如何禁用DocLint

Since Java DocLint didn’t exist before Java 8, this can create unwanted headaches, especially in old third-party libraries.

由于Java DocLint 在Java 8之前并不存在，这可能会造成不必要的麻烦，特别是在旧的第三方库中。

We’ve already seen the none option with the javadoc command in a previous section In addition, there’s an option to disable DocLint from build systems like Maven, Gradle, Ant. We’ll see these in the next few subsections.

我们已经在上一节中看到了none选项和javadoc命令。此外，还有一个选项可以从构建系统中禁用DocLint，如Maven、Gradle、Ant。我们将在接下来的几个小节中看到这些。

4.1. Maven

4.1.Maven

With maven-javadoc-plugin, starting with version 3.0.0, a new doclint configuration has been added. Let’s see how to configure it to disable DocLint:

从3.0.0版本开始，maven-javadoc-plugin增加了一个新的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>

But generally, it’s not recommended to use the none option because it skips all types of checks. We should use <doclint>all,-missing</doclint> instead.

但是一般来说，不建议使用none选项，因为它跳过所有类型的检查。我们应该使用<doclint>all,-missing</doclint>代替。

When using earlier versions (before v3.0.0), we need to use a different setting:

当使用早期版本（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

4.2 Gradle

We can deactivate DocLint in Gradle projects with a simple script:

我们可以用一个简单的脚本在Gradle项目中停用DocLint。

if (JavaVersion.current().isJava8Compatible()) {
    allprojects {
        tasks.withType(Javadoc) {
            options.addStringOption('Xdoclint:none', '-quiet')
        }
    }
}

Unfortunately, Gradle doesn’t support additionalparam as Maven does in the example above, so we need to do it manually.

不幸的是，Gradle不像Maven那样支持additionalparam，所以我们需要手动操作。

4.3. Ant

4.3.蚂蚁

Ant uses additionalparam as Maven does, so we can set -Xdoclint:none as demonstrated above.

Ant和Maven一样使用additionalparam，所以我们可以按照上面的演示设置-Xdoclint:none。

5. Conclusion

5.总结

In this article, we looked at various ways of using Java DocLint. It can help us when we want to have a clean, error-prone Javadoc.

在这篇文章中，我们研究了使用Java DocLint的各种方法。当我们想拥有一个干净的、容易出错的Javadoc时，它可以帮助我们。

For additional in-depth information, it’s a good idea to have a look at the official documentation.

对于其他深入的信息，最好是看看官方的文件。