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

时间:2013-04-08 18:23:37

标签: java maven migration java-8 javadoc

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

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

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

[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中配置如下:

<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>

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

更新

如果我用<failOnError>false</failOnError>更改我的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>

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

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

  

[ERROR] MavenReportException:创建存档时出错:退出   代码:1 - /Users/....java:18:警告:没有@param ...命令行   是:/ Library / Java / Home / bin / javadoc @options @packages

     

请参阅中生成的Javadoc文件   '/用户/ sergioc /文档/工作区/愈合/ minitoolbox /目标/ apidocs'   DIR。

     

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

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

19 个答案:

答案 0 :(得分:364)

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

DocLint is a new feature in Java 8,摘要如下:

  

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

默认情况下启用此选项,并在生成Javadoc之前运行大量检查。您需要按照指定的in this thread为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>

对于maven-javadoc-plugin 3.0.x: 取代

<additionalparam>-Xdoclint:none</additionalparam>

<doclint>none</doclint>

答案 1 :(得分:94)

使用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>

答案 2 :(得分:60)

这是我所知道的最简洁的方法,无论使用的是哪个版本,都会忽略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>

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

答案 3 :(得分:38)

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

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

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

答案 4 :(得分:35)

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

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

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

这基本上是@ankon's answer@zapp's answer

对于maven-javadoc-plugin 3.0.0用户:

替换

<additionalparam>-Xdoclint:none</additionalparam>

通过

<doclint>none</doclint>

答案 5 :(得分:30)

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

<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 :(得分:28)

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

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

  • 格式错误的HTML(例如缺少结束标记,未转义的括号等)
  • {@link }无效。 (同样适用于类似的标签,例如@see
  • 无效的@author值。这曾经被接受:@author John <john.doe@mine.com>但由于未转义的括号而不再如此。
  • Javadoc中的HTML表现在需要摘要或标题。有关解释,请参阅this question

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

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

答案 7 :(得分:19)

您可以尝试将failOnError属性(请参阅plugin documentation)设置为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>

正如您从文档中看到的那样,默认值为true

答案 8 :(得分:17)

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

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

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

答案 9 :(得分:9)

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

因此&lt; additionalparam&gt;不管用。所以我们必须修改如下。

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

答案 10 :(得分:3)

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

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

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

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

答案 11 :(得分:2)

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

我正在使用java 1.8.0_77 ,还没有尝试过使用java 1.7

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

答案 12 :(得分:2)

我想对其他答案添加一些见解

就我而言

  

-Xdoclint:无

没用。

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

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

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

答案 13 :(得分:2)

在下面添加

JAVA_TOOL_OPTIONS = -DadditionalJOption = -Xdoclint:无

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

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

答案 14 :(得分:2)

因此,为自己节省一些我没有花的时间,如果看来行不通,请尝试以下操作:

 <additionalJOption>-Xdoclint:none</additionalJOption>

标记已更改为较新的版本。

答案 15 :(得分:1)

要忽略遗失的@param@return标记,只需停用missing doclint group即可。这样,仍然会检查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>

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

答案 16 :(得分:0)

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

这对我有用: -

export JAVA_TOOL_OPTIONS=-DadditionalJOption=-Xdoclint:none

然后启动你的Maven构建,任何Linux发行版构建等等。它不需要Maven config 文件修改 - 我无法做到这一点,因为我的目标是重建一堆 Centos rpm包,所以必须非常深入。

答案 17 :(得分:0)

在我的情况下,我使用的是父pom(由于是我按时运行,所以不确定是真正的原因),使用了maven 2.x和java 1.6,由于某种原因上述解决方案无法正常工作,因此我添加了以下配置文件并对其进行管理以使其运行:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mycompany</groupId>
    <artifactId>myapp</artifactId>
    <packaging>war</packaging>
    <name>myapp</name>
    <version>0.0.1-SNAPSHOT</version>
    <description>My App</description>
    <parent>
        <groupId>com.mycompany</groupId>
        <artifactId>parent-artifact</artifactId>
        <version>0.0.1</version>
    </parent>

    <profiles>
        <profile>
            <id>doclint-java6-disable</id>
            <activation>
                <jdk>[1.6,)</jdk>
            </activation>
            <properties>
                <additionalparam>--allow-script-in-comments</additionalparam>
            </properties>
        </profile>
    </profiles>
</project>

答案 18 :(得分:-1)

使用

/*
 * Comments
 */

代替

/**
 * Comments
 */