使用Maven时如何解决更严格的Java 8 Javadoc问题 [英] How to work around the stricter Java 8 Javadoc when using Maven

问题描述

当谈到Javadoc时，你会很快发现JDK8更严格（默认情况下）。 （链接 - 请参阅最后一点）

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

如果你从来没有生成任何Javadoc那么你当然不会遇到任何问题，但Maven发布过程和可能你的CI构建之类的东西会在他们工作的地方突然失败JDK7很好。任何检查Javadoc工具退出值的东西现在都会失败。与JDK7相比，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 warnings compared to JDK7 but that's not the scope here. We are talking about 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.

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

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

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

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

/**
 * My very best class
 * @author John <[e-mail]> 
 */

现在由于<字符。严格来说这是合理的，但不是很宽容。

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

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

HTML Tables in your Javadoc? Consider this valid 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:

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

但为什么这必须是来自Javadoc的世界各地的错误工具打败了我？

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

1. 链接无效，例如 {@ link notexist}


2. 格式错误的HTML，例如： 始终返回< code> true< code> if ...

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

UPDATE

链接：

UPDATE

Links:

优秀 Stephen Colebourne .htmlrel =noreferrer>有关主题的博客。

Excellent blog on the subject by Stephen Colebourne.

推荐答案

现在，我知道在使用Maven时使用更严格的Java 8 Javadoc的最简单方法正在停用它。

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

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

Since the parameter -Xdoclint:none only 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.

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

只需将其添加到您的POM中就可以了。

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

替换

< additionalparam> -Xdoclint：none< / additionalparam>

by

< doclint> none< / doclint>

谢谢@banterCZ！

Thanks @banterCZ!

这篇关于使用Maven时如何解决更严格的Java 8 Javadoc问题的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！