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


Maven is not working in Java 8 when Javadoc tags are incomplete

由于我使用Maven，因此我能够在我的本地存储库项目中构建和安装具有不完整Javadoc标记的项目(例如，缺少参数)。

但是，由于我迁移到Java 8(1.8.0-ea-b90)，当我尝试构建或安装Javadoc不是Javadoc的项目时，Maven绝对严格缺少文档标记，并向我展示了许多与Javadoc问题相关的Javadoc错误"完善"。我试图在我的本地存储库中编译和安装的一些项目是我无法控制的第三方项目。因此，在我的场景中，仅修复所有这些项目中的所有Javadoc的解决方法似乎并不可行。

这是我在项目中执行mvn clean package install时看到的输出的一小部分：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[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] ^

Javadoc Maven插件在我的POM中配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

正如我之前所说，如果我回到Java 7，一切正常。
也许这是与Java 8中运行的Maven相关的错误？
我如何使用Java 8使其工作(即，能够构建项目的Javadoc并在我的本地存储库中安装其代码)？
我已经在OSX中使用Maven 3.0.3和3.0.5进行了测试。

更新：

如果我用false更改我的Javadoc插件配置(感谢Martin)：

1
2
3
4
5
6
7
8
9
10
11
12
13
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    maven-javadoc-plugin</artifactId>
    <version>2.9</version>
    <executions>
        <execution>
            <id>attach-javadocs</id>
            <goals>
                <goal>jar</goal>
            </goals>
        </execution>
    </executions>
</plugin>

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

我在控制台中看到的具有这种新配置的输出片段是：

[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

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

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)

有关如何构建源代码，安装项目以及在使用Java 7时一步生成Javadoc JAR的任何解决方法？

相关讨论

最好的解决方案是修复javadoc错误。如果由于某种原因不可能(即：自动生成的源代码)，则可以禁用此检查。

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之前运行大量检查。您需要按照此线程中的指定为Java 8关闭此功能。您必须将此添加到您的maven配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
<profiles>
  <profile>
    <id>java8-doclint-disabled</id>
   
      <jdk>[1.8,)</jdk>
    </activation>
    <properties>
      <javadoc.opts>-Xdoclint:none</javadoc.opts>
    </properties>
  </profile>
</profiles>
<build>
  <plugins>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        maven-javadoc-plugin</artifactId>
        <version>2.9</version>
        <executions>
            <execution>
                <id>attach-javadocs</id>
                <goals>
                    <goal>jar</goal>
                </goals>
                <configuration>
                    ${javadoc.opts}</additionalparam>
                </configuration>
            </execution>
        </executions>
    </plugin>
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        maven-site-plugin</artifactId>
        <version>3.3</version>
        <configuration>
          <reportPlugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              maven-javadoc-plugin</artifactId>
              <configuration>
                ${javadoc.opts}</additionalparam>
              </configuration>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
   </plugins>
</build>

对于maven-javadoc-plugin 3.0.x：
更换

1
-Xdoclint:none</additionalparam>

同

1
<doclint>none</doclint>
相关讨论

使用java 8和java 7的最简单方法是在构建中使用配置文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
<profiles>
  <profile>
    <id>doclint-java8-disable</id>
   
      <jdk>[1.8,)</jdk>
    </activation>

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

这是我所知道的最简洁的方法，无论使用的是哪个版本，都会忽略doclint警告。无需在略有修改的情况下在多个配置文件中复制插件配置。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
<profiles>
  <profile>
    <id>doclint-java8-disable</id>
   
      <jdk>[1.8,)</jdk>
    </activation>
    <properties>
      <javadoc.opts>-Xdoclint:none</javadoc.opts>
    </properties>
  </profile>
</profiles>

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      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>
            ${javadoc.opts}</additionalparam>
          </configuration>
        </execution>
      </executions>
    </plugin>
    ...
  </plugins>
</build>

在oracle / open jdk 6,7,8和11上测试过。

相关讨论

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

1
2
3
4
5
<project>
    ...
    <properties>
        -Xdoclint:none</additionalparam>
    </properties>

此处在其他答案中提供的常见解决方案(在插件部分中添加该属性)由于某种原因不起作用。只有通过全局设置我才能成功构建javadoc jar。

相关讨论

适用于任何Java版本的最短解决方案：

1
2
3
4
5
6
7
8
9
10
11
<profiles>
    <profile>
        <id>disable-java8-doclint</id>
       
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            -Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

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

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

对于maven-javadoc-plugin 3.0.0用户：

更换

-Xdoclint:none

通过

<5233>

相关讨论

仅覆盖maven-javadoc-plugin配置，不能解决mvn site的问题(例如在发布阶段使用)。这就是我必须做的事情：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<profile>
  <id>doclint-java8-disable</id>
 
    <jdk>[1.8,)</jdk>
  </activation>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        maven-javadoc-plugin</artifactId>
        <configuration>
          -Xdoclint:none</additionalparam>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        maven-site-plugin</artifactId>
        <version>3.3</version>
        <configuration>
          <reportPlugins>
            <plugin>
              <groupId>org.apache.maven.plugins</groupId>
              maven-javadoc-plugin</artifactId>
              <configuration>
                -Xdoclint:none</additionalparam>
              </configuration>
            </plugin>
          </reportPlugins>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>
相关讨论

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

以下是您可以注意的事项：

  • 格式错误的HTML(例如缺少结束标记，未转义的括号等)
  • 无效{@link } s。 (同样适用于类似的标签，如@see)
  • 无效的@author值。这曾经被接受：@author John 但由于未转义的括号而不再如此。
  • Javadoc中的HTML表现在需要摘要或标题。请参阅此问题以获得解释。

您只需修复源代码文件并继续构建Javadoc，直到它可以构建而不会出现故障。很麻烦是的，但我个人喜欢当我把我的项目提升到DocLint级别时，因为这意味着我可以更自信我生产的Javadoc实际上是我想要的。

当然，如果您在自己没有生成的某些源代码上生成Javadoc，例如因为它来自某些代码生成器，例如，的wsimport。奇怪的是，在实际发布JDK8之前，Oracle没有为JDK8合规性准备自己的工具。它似乎不会在Java 9之前修复。只有在这种特殊情况下，我建议关闭本页其他地方记录的DocLint。

相关讨论

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    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>

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

相关讨论

由于它取决于用于运行maven命令的JRE版本，因此您可能不希望在pom.xml中默认禁用DocLint

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

示例：mvn clean install -Dadditionalparam=-Xdoclint:none

相关讨论

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

因此不会起作用。所以我们必须修改如下。

1
2
3
4
5
6
7
8
   <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      maven-javadoc-plugin</artifactId>
      <version>3.0.0</version>
      <configuration>
         <doclint>none</doclint>
      </configuration>
  </plugin>
相关讨论

从maven-javadoc-plugin 3.0.0开始，您应该使用additionalJOption来设置其他Javadoc选项，因此如果您希望Javadoc禁用doclint，则应添加以下属性。

1
2
3
4
5
<properties>
    ...
    -Xdoclint:none</additionalJOption>
    ...
<properties>

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

1
2
3
4
5
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>    
</plugin>

我想补充一些其他答案的见解

就我而言

-Xdoclint:none

没工作。

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

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

1
2
3
4
5
6
7
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    maven-javadoc-plugin</artifactId>
    <configuration>
        <skip>true</skip>
    </configuration>
</plugin>

在下面添加

JAVA_TOOL_OPTIONS = -DadditionalJOption = -Xdoclint：无

进入詹金斯的工作
配置>构建环境>将环境变量注入构建过程>属性内容

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

相关讨论

所以，节省一些我没有的时间，如果它似乎不起作用，请尝试这个：

1
 -Xdoclint:none</additionalJOption>

标签已更改为较新版本。

相关讨论

我不确定这是否会有所帮助，但即使我最近也遇到了与oozie-4.2.0版本完全相同的问题。阅读完上述答案后，我刚刚通过命令行添加了maven选项，它对我有用。所以，只是在这里分享。

我正在使用java 1.8.0_77，还没试过java 1.7

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

要忽略缺少的@param和@return标记，只需禁用missing doclint组即可。这样，仍将检查javadoc是否存在更高级别和语法问题：

1
2
3
4
5
6
7
8
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        maven-javadoc-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
            <doclint>all,-missing</doclint>
        </configuration>
    </plugin>

请注意，这适用于3.0或更高版本的插件。

我参加派对有点晚了，但我也被迫寻找解决方法，最后来到这里，然后找到了。

这对我有用： -

1
export JAVA_TOOL_OPTIONS=-DadditionalJOption=-Xdoclint:none

然后开始你的Maven构建，任何Linux发行版构建等。它不需要Maven配置文件修改的好事 - 我不能这样做，因为我的目标是重建一堆Centos rpm包，所以不得不真的很深。

使用

1
2
3
/*
 * Comments
 */

代替

1
2
3
/**
 * Comments
 */