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

问题描述

您很快就会意识到 JDK8 在 Javadoc 方面要严格得多(默认情况下).(link - 见最后一个要点)

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 在 warnings 方面可能也更加冗长，但这不是这里的范围.我们正在谈论错误！

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 工具的 stop-the-world 错误打败了我??

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

1. 无效链接，例如{@link notexist}
2. 格式错误的 HTML，例如 总是返回 true如果 ...

更新

链接:

优秀的关于这个主题的博客 来自 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.

替换

-Xdoclint:none

由

无

谢谢@banterCZ！

Thanks @banterCZ!

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