当Javadoc标记不完整时，Maven不在Java 8中工作

Since I use Maven I have been able to build and install in my local repository projects that have incomplete Javadoc tags (for example, a missing parameter).

由于使用了Maven，我可以在本地存储库项目中构建和安装不完整的Javadoc标记(例如，缺少一个参数)。

However, since I migrated to Java 8 (1.8.0-ea-b90) Maven is absolutely strict about missing documentation tags and show me lots of Javadoc errors related to Javadoc problems when I try to build or install a project where the Javadoc is not "perfect". Some of the projects I am trying to compile and install in my local repository are third party projects from which I do not have control. So the workaround of just fixing all the Javadocs in all these projects does not seem to be feasable in my scenario.

然而，自从我迁移到Java 8 (1.8.0-ea-b90)时，Maven对于丢失文档标记绝对是严格的，并且在我尝试构建或安装一个Javadoc不是“完美”的项目时，给我展示了很多与Javadoc问题相关的Javadoc错误。我试图在本地存储库中编译和安装的一些项目是第三方项目，我无法控制这些项目。因此，在我的场景中，仅仅修复所有这些项目中的所有Javadocs似乎是不可能的。

This is a small part of the output I see when I execute mvn clean package install in my project:

这是我在项目中执行mvn clean包安装时看到的输出的一小部分:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.026s
[INFO] Finished at: Mon Apr 08 21:06:17 CEST 2013
[INFO] Final Memory: 27M/437M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.9:jar (attach-javadocs) on project jpc: MavenReportException: Error while creating archive:
[ERROR] Exit code: 1 - /Users/sergioc/Documents/workspaces/heal/jpc/src/main/java/org/jpc/engine/prolog/PrologDatabase.java:10: error: @param name not found
[ERROR] * @param terms the terms to assert
[ERROR] ^
[ERROR] /Users/sergioc/Documents/workspaces/heal/jpc/src/main/java/org/jpc/engine/prolog/PrologDatabase.java:11: warning: no description for @return
[ERROR] * @return
[ERROR] ^

The Javadoc Maven plugin is configured like this in my POM:

Javadoc Maven插件在我的POM中是这样配置的:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

As I said before, everything is working fine if I go back to Java 7. Maybe is this a bug related to Maven running in Java 8? How could I make it work (i.e., being able to build the Javadoc of the project and install its code in my local repository) with Java 8? I have tested with both Maven 3.0.3 and 3.0.5 in OSX.

正如我之前所说的，如果回到Java 7，一切都运行良好。也许这是一个与在Java 8中运行的Maven相关的bug ?我怎样才能使它工作呢?，能够使用Java 8构建项目的Javadoc并将其代码安装到本地存储库中吗?我在OSX中测试过Maven 3.0.3和3.0.5。

UPDATE:

更新:

If I change my Javadoc plugin configuration with <failOnError>false</failOnError> (thanks Martin):

如果我用 false 修改Javadoc插件配置(谢谢Martin):

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Then the project is installed in my local repository. However, the Javadoc JAR is still not generated.

然后该项目被安装在我的本地存储库中。然而，Javadoc JAR仍然没有生成。

A fragment of the output I see in the console with this new configuration is:

我在这个新配置的控制台中看到的输出片段是:

[ERROR] MavenReportException: Error while creating archive: Exit code: 1 - /Users/....java:18: warning: no @param ... Command line was: /Library/Java/Home/bin/javadoc @options @packages

【错误】MavenReportException:当创建档案时发生错误:退出代码:1 - /用户/ ....java:18:警告:没有@param…命令行是:/Library/Java/Home/bin/javadoc @options @packages

Refer to the generated Javadoc files in '/Users/sergioc/Documents/workspaces/heal/minitoolbox/target/apidocs' dir.

参考生成的Javadoc文件/用户/sergioc/文档/工作空间/修复/ minitolbox /target/apidocs的目录。

at org.apache.maven.plugin.javadoc.AbstractJavadocMojo.executeJavadocCommandLine(AbstractJavadocMojo.java:5043) at org.apache.maven.plugin.javadoc.AbstractJavadocMojo.executeReport(AbstractJavadocMojo.java:1990) at org.apache.maven.plugin.javadoc.JavadocJar.execute(JavadocJar.java:181) at org.apache.maven.plugin.DefaultBuildPluginManager.executeMojo(DefaultBuildPluginManager.java:101) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:209) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:153) at org.apache.maven.lifecycle.internal.MojoExecutor.execute(MojoExecutor.java:145) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:84) at org.apache.maven.lifecycle.internal.LifecycleModuleBuilder.buildProject(LifecycleModuleBuilder.java:59) at org.apache.maven.lifecycle.internal.LifecycleStarter.singleThreadedBuild(LifecycleStarter.java:183) at org.apache.maven.lifecycle.internal.LifecycleStarter.execute(LifecycleStarter.java:161) at org.apache.maven.DefaultMaven.doExecute(DefaultMaven.java:320) at org.apache.maven.DefaultMaven.execute(DefaultMaven.java:156) at org.apache.maven.cli.MavenCli.execute(MavenCli.java:537) at org.apache.maven.cli.MavenCli.doMain(MavenCli.java:196) at org.apache.maven.cli.MavenCli.main(MavenCli.java:141) at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) at java.lang.reflect.Method.invoke(Method.java:491) at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:290) at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:230) at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:409) at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:352)

在org.apache.m .plugin.javadoc. executejavadoc . executejavadoc.javadoc.javadoc.javadoc.javadoc.javadoc.javadoc.javadoc . executereport (AbstractJavadocMojo.java:1990) at org. apache.maven.javadoc.javadoc.javadoc.javadoc.javadoc.javadocjar .execute(JavadocJar.java:181)在org.apache.m .plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin. plugin.javadoc.javadocjar . javadoc.javadocjar . javadoc.javadocjar . javadoc.javadocjar . javadoc.javadoc.javadoc.javadoc.javadoc.javadoc.javadoc.javadoc.htmlcom . org.apache. mavene .生命周期。内部。mojoexecutorl .execute(mojoexecutorl .java .java生命周期。生命周期。执行(生命周期。java:161)。在org.apache.m . doexecute (DefaultMaven.java:320)在org.apache.m .execute(defaultmaven.java:156)。在sun.reflec . nativemethodorimpl .invoke(nativemethodaccessor .invoke) (nativemethodaccess .java . laun.57)在sun. reflec.reflec . delegate . methodaccessor .invoke .invoke .invoke(delegatingmethodaccessor .java: 143)在chera.com/chera.com/chera.worldchere.com/200.org/2012/2012-2012-2012-2016-2-2016-2-2012-2016-2-2016-2-2016-2-02-02-02-02-2-2-06-2-06-2-06-2-06-2-13。org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:352)

Any workaround about how to build the sources, install the project and generate the Javadoc JAR in one step as it was working with Java 7?

关于如何构建源、安装项目和在使用Java 7时一步生成Javadoc JAR的解决方案?

16 个解决方案

#1

The best solution would be to fix the javadoc errors. If for some reason that is not possible (ie: auto generated source code) then you can disable this check.

最好的解决方案是修复javadoc错误。如果由于某种原因，这是不可能的(例如:自动生成源代码)，那么您可以禁用这个检查。

DocLint is a new feature in Java 8, which is summarized as:

DocLint是Java 8中的一个新特性，总结为:

Provide a means to detect errors in Javadoc comments early in the development cycle and in a way that is easily linked back to the source code.

提供一种方法，在开发周期的早期检测Javadoc注释中的错误，并以一种容易链接回源代码的方式。

This is enabled by default, and will run a whole lot of checks before generating Javadocs. You need to turn this off for Java 8 as specified in this thread. You'll have to add this to your maven configuration:

这是默认启用的，在生成Javadocs之前将运行大量的检查。您需要在这个线程中指定Java 8。您必须将此添加到maven配置中:

<profiles>
  <profile>
    <id>java8-doclint-disabled</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>
    <properties>
      <javadoc.opts>-Xdoclint:none</javadoc.opts>
    </properties>
  </profile>
</profiles>
<build>
  <plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <version>2.9</version>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
                <configuration>
                    <additionalparam>${javadoc.opts}</additionalparam>
                </configuration>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.3</version>
        <configuration>
          <reportPlugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <configuration>
                <additionalparam>${javadoc.opts}</additionalparam>
              </configuration>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
   </plugins>
</build>

#2

The easiest approach to get things working with both java 8 and java 7 is to use a profile in the build:

要使java 8和java 7同时工作，最简单的方法是在构建中使用概要文件:

<profiles>
  <profile>
    <id>doclint-java8-disable</id>
    <activation>
      <jdk>[1.8,)</jdk>
    </activation>

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

#3

Here is the most concise way I am aware of to ignore doclint warnings regardless of java version used. There is no need to duplicate plugin configuration in multiple profiles with slight modifications.

这里是我知道的最简洁的方法，不管使用的是java版本，都可以忽略doclint警告。无需在多个概要文件中复制插件配置，只需稍加修改。

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

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-javadoc-plugin</artifactId>
      <version>2.9.1</version>
      <executions>
        <execution>
          <id>attach-javadocs</id> <!-- The actual id should be apparent from maven output -->
          <configuration>
            <additionalparam>${javadoc.opts}</additionalparam>
          </configuration>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
</build>

Tested on oracle/open jdk 6, 7 and 8.

在oracle/open jdk 6、7和8上进行测试。

#4

Add into the global properties section in the pom file:

添加到pom文件的全局属性部分:

<project>
    ...
    <properties>
        <additionalparam>-Xdoclint:none</additionalparam>
    </properties>

The common solution provided here in the other answers (adding that property in the plugins section) did not work for some reason. Only by setting it globally I could build the javadoc jar successfully.

在其他答案中提供的公共解决方案(在plugins部分中添加该属性)由于某些原因无法工作。只有全局地设置它，我才能成功地构建javadoc jar。

#5

Overriding maven-javadoc-plugin configuration only, does not fix the problem with mvn site (used e.g during the release stage). Here's what I had to do:

仅覆盖maven-javadoc-plugin配置，不能解决mvn站点的问题(使用e。g在发布阶段)。下面是我要做的:

<profile>
  <id>doclint-java8-disable</id>
  <activation>
    <jdk>[1.8,)</jdk>
  </activation>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-javadoc-plugin</artifactId>
        <configuration>
          <additionalparam>-Xdoclint:none</additionalparam>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-site-plugin</artifactId>
        <version>3.3</version>
        <configuration>
          <reportPlugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-javadoc-plugin</artifactId>
              <configuration>
                <additionalparam>-Xdoclint:none</additionalparam>
              </configuration>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>

#6

I don't think just turning off DocLint is a good solution, at least not long term. It is good that Javadoc has become a bit more strict so the right way to fix the build problem is to fix the underlying problem. Yes, you'll ultimately need to fix those source code files.

我不认为仅仅关闭DocLint是一个好的解决方案，至少不是长期的。Javadoc变得更严格了一点，因此解决构建问题的正确方法是修复底层问题。是的，您最终需要修复这些源代码文件。

Here are the things to look out for that you could previously get away with:

以下是一些你以前可以避免的事情:

• Malformed HTML (for example a missing end-tag, un-escaped brackets, etc)
• 格式错误的HTML(例如缺少结束标记、未转义括号等)
• Invalid {@link }s. (same goes for similar tags such as @see)
• 无效的{ @link }。(类似标签如@see也是如此)
• Invalid @author values. This used to be accepted : @author John <[e-mail]> but not so anymore because of the un-escaped brackets.
• 无效的@author值。这在以前是可以接受的:@author John ，但由于没有转义括号，现在已经不是这样了。 @mine.com>
• HTML tables in Javadoc now require a summary or caption. See this question for explanation.
• 现在，Javadoc中的HTML表需要一个摘要或说明。请解释这个问题。

You'll simply have to fix your source code files and keep building your Javadoc until it can build without a failure. Cumbersome yes, but personally I like when I have brought my projects up to DocLint level because it means I can be more confident that the Javadoc I produce is actually what I intend.

您只需要修复源代码文件并继续构建Javadoc，直到它能够在没有失败的情况下构建。是的，但是我个人喜欢当我把我的项目提升到DocLint的水平，因为这意味着我可以更有信心，我生产的Javadoc实际上是我想要的。

There's of course the problem if you are generating Javadoc on some source code you've not produced yourself, for example because it comes from some code generator, e.g. wsimport. Strange that Oracle didn't prepare their own tools for JDK8 compliance before actually releasing JDK8. It seems it won't be fixed until Java 9. Only in this particular case I suggest to turn off DocLint as documented elsewhere on this page.

当然，如果您在一些您没有自己生成的源代码上生成Javadoc，比如它来自一些代码生成器，例如wsimport，那么就会出现问题。奇怪的是，在实际发布JDK8之前，Oracle并没有为JDK8的遵从性准备自己的工具。看起来要到Java 9才能修复。只有在这个特殊的情况下，我建议关闭DocLint，在这个页面的其他地方。

#7

The shortest solution that will work with any Java version:

<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上，你就可以走了。

This is basically @ankon's answer plus @zapp's answer.

这基本上是@ankon的答案加上@zapp的答案。

---

For maven-javadoc-plugin 3.0.0 users:

Replace

取代

<additionalparam>-Xdoclint:none</additionalparam>

< additionalparam > -Xdoclint:没有< / additionalparam >

by

通过

<doclint>none</doclint>

< doclint > < / doclint >没有

#8

Since it depends on the version of your JRE which is used to run the maven command you propably dont want to disable DocLint per default in your pom.xml

由于它取决于用于运行maven命令的JRE版本，所以您可能不希望在您的poml .xml中每次默认禁用DocLint

Hence, from command line you can use the switch -Dadditionalparam=-Xdoclint:none.

因此，从命令行可以使用-Dadditionalparam=-Xdoclint:none。

Example: mvn clean install -Dadditionalparam=-Xdoclint:none

示例:mvn clean安装-Dadditionalparam=-Xdoclint:none

#9

You could try setting the failOnError property (see plugin documentation) to false:

您可以尝试将failOnError属性(参见插件文档)设置为false:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
              <failOnError>false</failOnError>
            </configuration>
        </execution>
    </executions>
</plugin>

As you can see from the docs, the default value is true.

从文档中可以看到，默认值为true。

#10

The configuration property name has been changed in the latest version of maven-javadoc-plugin which is 3.0.0.

在最新版本的maven-javadoc-plugin中，配置属性名称被更改为3.0.0。

Hence the <additionalparam> will not work. So we have to modify it as below.

因此， 不能使用。所以我们必须修改如下。

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

#11

I'm not sure if this is going to help, but even i faced the exact same problem very recently with oozie-4.2.0 version. After reading through the above answers i have just added the maven option through command line and it worked for me. So, just sharing here.

我不确定这是否会有帮助，但是最近我在oozi -4.2.0版本中也遇到了同样的问题。读完上面的答案后，我刚刚通过命令行添加了maven选项，它对我很有用。因此,在这里分享。

I'm using java 1.8.0_77, haven't tried with java 1.7

我使用的是java 1.8.0_77，还没有尝试过java 1.7

bin/mkdistro.sh -DskipTests -Dmaven.javadoc.opts='-Xdoclint:-html'

bin / mkdistro。sh -DskipTests -Dmaven.javadoc.opts = ' -Xdoclint:html '

#12

As of maven-javadoc-plugin 3.0.0 you should have been using additionalJOption to set an additional Javadoc option, so if you would like Javadoc to disable doclint, you should add the following property.

对于maven-javadoc-plugin 3.0.0，您应该使用additionalJOption来设置一个附加的Javadoc选项，所以如果您希望Javadoc禁用doclint，您应该添加以下属性。

<properties>
    ...
    <additionalJOption>-Xdoclint:none</additionalJOption>
    ...
<properties>

You should also mention the version of maven-javadoc-plugin as 3.0.0 or higher.

您还应该提到maven-javadoc-plugin的版本为3.0.0或更高版本。

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

#13

I'm a bit late to the party, but I was forced to search for workaround too, ended up here, and then found it.

我参加聚会有点晚了，但我也*寻找解决办法，最后来到这里，然后找到了它。

Here's what works for me:-

以下是对我有用的:

export JAVA_TOOL_OPTIONS=-DadditionalJOption=-Xdoclint:none

And then start your Maven build, any Linux distribution build etc. Nice thing about it that it doesn't require Maven config files modification - I couldn't do that as my objective was to rebuild a bunch of Centos rpm packages, so had to go really deep.

然后开始你的Maven构建，任何Linux发行版构建等等。它的好处是不需要Maven配置文件修改——我不能这样做，因为我的目标是重新构建大量Centos rpm包，所以必须深入。

#14

Added below

添加以下

JAVA_TOOL_OPTIONS=-DadditionalJOption=-Xdoclint:none

JAVA_TOOL_OPTIONS = -DadditionalJOption = -Xdoclint:没有

into Jenkins job configuration > Build Environment > Inject environment variables to the build process > Properties Content

在Jenkins作业配置>中，构建环境>将环境变量注入构建过程>属性内容

Solved my problem of code building through Jenkins Maven :-)

通过Jenkins Maven解决我的代码构建问题:-)

#15

To ignore missing @param and @return tags, it's enough to disable the missing doclint group. This way, the javadoc will still be checked for higher level and syntax issues:

要忽略缺失的@param和@return标记，只需禁用缺失的doclint组。这样，javadoc仍然会被检查，以获得更高的级别和语法问题:

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

Note that this is for plugin version 3.0 or newer.

注意，这是针对3.0或更新的插件。

#16

I would like to add some insight into other answers

我想在其他答案中加入一些见解

In my case

在我的例子中

-Xdoclint:none

-Xdoclint:没有

Didn't work.

没有工作。

Let start with that, in my project, I didn't really need javadoc at all. Only some necessary plugins had got a build time dependency on it.

首先，在我的项目中，我根本不需要javadoc。只有一些必需的插件在构建时依赖于它。

So, the most simple way solve my problem was:

所以，解决我的问题最简单的方法是:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
        <skip>true</skip>
    </configuration>
</plugin>