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).
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.
This is a small part of the output I see when I execute mvn clean package install
in my project:
[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:
<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.
UPDATE:
If I change my Javadoc plugin configuration with <failOnError>false</failOnError>
(thanks 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.
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
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)
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?
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:
<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.
The easiest approach to get things working with both java 8 and java 7 is to use a profile in the build:
<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>
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:
<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>
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.
Here are the things to look out for that you could previously get away with:
{@link }
s. (same goes for similar tags such as @see
)@author
values. This used to be accepted : @author John <[email protected]>
but not so anymore because of the un-escaped brackets.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.
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.
Added below
JAVA_TOOL_OPTIONS=-DadditionalJOption=-Xdoclint:none
Into Jenkins job :
Configuration > Build Environment > Inject environment variables to the build process > Properties Content
Solved my problem of code building through Jenkins Maven :-)
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.
I'm using java 1.8.0_77, haven't tried with java 1.7
bin/mkdistro.sh -DskipTests -Dmaven.javadoc.opts='-Xdoclint:-html'
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.
<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, 8 and 11.
In my case I was using a parent pom (not sure it was the real cause since I was running against the clock), maven 2.x and java 1.6 were used, for some reason above solutions didn't work, so I added the following profile and managed it to make it run:
<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>
You could try setting the failOnError
property (see plugin documentation) to 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
.
I would like to add some insight into other answers
In my case
-Xdoclint:none
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.
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>
So, save yourself some hours that I didn't and try this if it seems not to work:
<additionalJOption>-Xdoclint:none</additionalJOption>
The tag is changed for newer versions.
<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.
This is basically @ankon's answer plus @zapp's answer.
Replace
<additionalparam>-Xdoclint:none</additionalparam>
by
<doclint>none</doclint>
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
Hence, from command line you can use the switch -Dadditionalparam=-Xdoclint:none
.
Example: mvn clean install -Dadditionalparam=-Xdoclint:none
The configuration property name has been changed in the latest version of maven-javadoc-plugin which is 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>
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.
<properties>
...
<additionalJOption>-Xdoclint:none</additionalJOption>
...
<properties>
You should also mention the version of maven-javadoc-plugin as 3.0.0 or higher.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.0</version>
</plugin>
Add into the global properties section in the pom file:
<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.
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.
Source: Stackoverflow.com