使用 Maven 时如何解决更严格的 Java 8 Javadoc

How to work around the stricter Java 8 Javadoc when using Maven

提问by peterh

You'll quickly realize that JDK8 is a lot more strict (by default) when it comes to Javadoc. (link- see last bullet point)

您很快就会意识到 JDK8 在 Javadoc 方面要严格得多（默认情况下）。（链接- 见最后一个要点）

If you never generate any Javadoc then of course you'll not experience any problems but things like Maven release process and possibly your CI builds will suddenly fail where they worked just fine with JDK7. Anything that checks the exit value of the Javadoc tool will now fail. JDK8 Javadoc is probably also more verbose in terms of warningscompared to JDK7 but that's not the scope here. We are talking about errors!

如果您从不生成任何 Javadoc，那么您当然不会遇到任何问题，但是诸如 Maven 发布过程和可能您的 CI 构建会突然失败，而它们与 JDK7 一起工作得很好。任何检查 Javadoc 工具退出值的操作现在都将失败。warnings与 JDK7 相比，JDK8 Javadoc 可能也更冗长，但这不是这里的范围。我们在谈论errors！

This question exist to collect proposals on what to do about it. What is the best approach ? Should these errors be fixed once and for all in the source code files? If you have a huge code base this might be a lot of work. What other options exist ?

这个问题的存在是为了收集关于如何处理它的建议。最好的方法是什么？这些错误是否应该在源代码文件中一劳永逸地修复？如果你有一个庞大的代码库，这可能需要大量的工作。还有哪些其他选择？

You are also welcome to comment with stories of what now fails that would previously pass.

也欢迎您对现在失败而以前通过的故事发表评论。

Horror stories of what now fails

现在失败的恐怖故事

wsimport tools

wsimport 工具

wsimporttool is a code generator for creating web service consumers. It is included in the JDK. Even if you use the wsimporttool from JDK8 it will nevertheless produce source code that cannot be compiled with the javadoc compiler from JDK8.

wsimport工具是用于创建 Web 服务消费者的代码生成器。它包含在 JDK 中。即使您使用wsimportJDK8 中的工具，它仍然会生成无法使用 JDK8 中的 javadoc 编译器编译的源代码。

@author tag

@作者标签

I'm opening up source code files 3-4 years old and see this:

我正在打开 3-4 岁的源代码文件，看到这个：

/**
 * My very best class
 * @author John <[email protected]> 
 */

This now fails because of the < character. Strictly speaking this is justified, but not very forgiving.

由于 < 字符，这现在失败了。严格来说，这是有道理的，但不是很宽容。

HTML tables

HTML表格

HTML Tables in your Javadoc? Consider this valid HTML:

Javadoc 中的 HTML 表格？考虑这个有效的 HTML：

/**
 *
 * <table>
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

This now fails with error message no summary or caption for table. One quick fix is to do like this:

现在失败并显示错误消息no summary or caption for table。一种快速解决方法是这样做：

/**
 *
 * <table summary="">
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

but why this has to be a stop-the-world error from Javadoc tool beats me??

但是为什么这必须是来自 Javadoc 工具的一个 stop-the-world 错误打败了我？？

Things that now fail for more obvious reasons

现在由于更明显的原因而失败的事情

1. Invalid links, e.g. {@link notexist}
2. Malformed HTML, e.g. always returns <code>true<code> if ...

1. 无效链接，例如 {@link notexist}
2. 格式错误的 HTML，例如 always returns <code>true<code> if ...

UPDATE

更新

Links:

链接：

Excellent blog on the subjectby Stephen Colebourne.

Stephen Colebourne关于这个主题的优秀博客。

采纳答案by Fred Porciúncula

For now, the easiest way I know to work around the stricter Java 8 Javadoc when using Mavenis deactivating it.

目前，我知道在使用 Maven 时解决更严格的 Java 8 Javadoc的最简单方法是停用它。

Since the parameter -Xdoclint:noneonly exists in Java 8, defining this parameter breaks the build for any other Java. To prevent this, we can create a profile that will be active only for Java 8, making sure our solution works regardless of the Java version.

由于该参数-Xdoclint:none仅存在于 Java 8 中，因此定义此参数会破坏任何其他 Java 的构建。为了防止这种情况，我们可以创建一个仅对 Java 8 有效的配置文件，确保我们的解决方案无论 Java 版本如何都有效。

<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

Just add that to your POM and you're good to go.

只需将其添加到您的 POM 中即可。

---

---

For maven-javadoc-plugin 3.0.0 users:

对于 maven-javadoc-plugin 3.0.0 用户：

Replace

代替

<additionalparam>-Xdoclint:none</additionalparam>

<additionalparam>-Xdoclint:none</additionalparam>

by

经过

<doclint>none</doclint>

<doclint>none</doclint>

Thanks @banterCZ!

谢谢@banterCZ！

回答by assylias

If you are using the maven javadoc plugin, you can use the failOnErroroption to prevent it from stopping if it finds any html errors:

如果您使用的是 maven javadoc 插件，您可以使用该failOnError选项防止它在发现任何 html 错误时停止：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>

Or you can deactivate the strict html options completely with:

或者您可以使用以下命令完全停用严格的 html 选项：

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

For more info.

欲了解更多信息。

回答by Gray

I like @ThiagoPorciúncula's solution but it didn't quite go far enough for me.

我喜欢@ThiagoPorciúncula 的解决方案，但对我来说还远远不够。

I typically already have javadoc plugin additionalparamset which were not being overridden by the profile. Because of this I had to:

我通常已经有 javadoc 插件additionalparam集，它没有被配置文件覆盖。因此，我不得不：

• Set a disableDoclintproperty to be empty by default.
• If in java >= 8, set the disableDoclintproperty to be -Xdoclint:none
• The use ${disableDoclint} in theadditionalparamsection of themaven-javadoc-plugin`.

• disableDoclint默认情况下将属性设置为空。
• 如果在 java >= 8 中，将disableDoclint属性设置为-Xdoclint:none
• 使用${disableDoclint} in theadditionalparam section of themaven-javadoc-plugin`。

This seems to work well albeit verbose.

尽管冗长，这似乎运作良好。

<properties>
    <!-- set empty property -->
    <disableDoclint></disableDoclint>
</properties>
<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <!-- set property if >= java 8 -->
            <disableDoclint>-Xdoclint:none</disableDoclint>
        </properties>
    </profile>
    ...
</profiles>

Then down below I could use the optional ${disableDoclint}variable in the additionalparamsection that I had already defined.

然后在下面我可以使用我已经定义${disableDoclint}的additionalparam部分中的可选变量。

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <showPackage>false</showPackage>
                <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <showPackage>false</showPackage>
        <bottom>This documentation content is licensed...</bottom>
        <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
    </configuration>
</plugin>

This works under java 8 but doesn't cause syntax errors under java 7. Woo hoo!

这在 java 8 下有效，但在 java 7 下不会导致语法错误。哇哦！

回答by Vlad Isajkin

Since version 3.0.0 of maven-javadoc-plugin the doclint is configured via the dedicated XML tag

由于 maven-javadoc-plugin 的 3.0.0 版，doclint 是通过专用的 XML 标记配置的

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>

回答by Jeronimo Backes

Note that for the error no summary or caption for table, using <table summary="">won't work anymore. If that's your situation, add a <caption>element to your table, like this:

请注意，对于 error no summary or caption for table， using<table summary="">将不再起作用。如果这是您的情况，<caption>请在表格中添加一个元素，如下所示：

<table>
    <caption>Examples</caption>
    ...
</table>

Hope this helps someone out there. It took me a while until I found this out.

希望这可以帮助那里的人。我花了一段时间才发现这一点。