jdk1.7 error after upgrading to jdk1.8: [ERROR] javadoc:warning-multiple sources of package comments found

from:http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html[ERROR] javadoc:warning-multiple sources of package comments found for package

Turning off Doclint in JDK 8 Javadoc

JDK 8 includes many updates, but one was I suspect going to cause quite a few complaints-doclint for Javadoc.

Javadoc Doclint

Documentation is isn't something most developers like writing. With Java, we were fortunate to has the Javadoc toolset built in and easy-to-access from day one. As such, writing Javadoc is a standard part of the most developers life.

The Javadoc comments in source code use a mixture of tags, starting with @, and HTML to allow the developer to express the IR comment and format it nicely.

Up-to-JDK 7, the Javadoc tool was pretty lenient. As a developer, you could write anything that vaguely resembled HTML and the tool would rarely complain beyond warnings. Thus you could has @link references that were inaccurate (such as due to refactoring) and the tool would simply provide a Warning.

With JDK 8, a new part had been added to Javadoc called Doclint and it changes that friendly behaviour. In particular, the tool aim to get conforming website HTML 4.01 HTML (despite the fact that humans is very bad at matching co Nformance wrt HTML).

With JDK 8, your is unable to get Javadoc unless your tool meets the standards of Doclint. Some of its rules is:

• No self-closed HTML tags, such as <br/> or <a id= "x"/>
• No unclosed HTML tags, such as <ul> without matching </ul>
• No invalid HTML end tags, such as </br>
• No invalid HTML attributes, based on Doclint ' s interpretation of the HTML 4.01
• No duplicate HTML id attribute
• No empty HTML href attribute
• No incorrectly nested headers, such as class documentation must has <H3>, not
• No invalid HTML tags, such as list<string> (where you forgot to escape using &lt;)
• No broken @link references
• No broken @param references, they must match the actual parameter name
• No broken @throws references, the first word must be a class name

Note that these is errors, not warnings. Break the rules and you get no Javadoc output.

In my opinion, this is the by-too strict to be the default. I has no problem with such a tool existing in Javadoc, but given the history of Javadoc, errors like this should be opt-i N, not opt-out. Its far better to get slightly broken Javadoc than no Javadoc.

I also haven ' t been able to find a list of the rules, which makes life hard. At least we can see the source code to reverse engineer them.

Turning off Doclint

The Magic incantation need is -Xdoclint:none . This goes the command line invoking Javadoc.

If you is running from MAVEN, you need to use additionalparam the setting, as per the manual. Either add it as a global property:

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

or add it to the Maven-javadoc-plugin:

  <plugins>    <plugin>      <groupId>org.apache.maven.plugins</groupId>      < artifactid>maven-javadoc-plugin</artifactid>      <configuration>        <additionalparam >-Xdoclint:none</additionalparam>      </configuration>    </plugin>  </ Plugins>

Ant also uses additionalparam -Xdoclint:none to pass in, see the manual.

Gradle does not expose but additionalparam Tim Yates and Cedric Champeau advise of this solution:

  if (Javaversion.current (). Isjava8compatible ()) {    allprojects {      Tasks.withtype (Javadoc) {        Options.addstringoption (' Xdoclint:none ', '-quiet ')}}  

See also the Gradle manual.

Summary

I don ' t mind doclint existing, but the there is no-the-it should be-turned on-to-error mode by default. Getting some Javadoc produced without hassle is far more important than pandering to the Doclint style checks. In addition, it's very heavy handed with what it defines to being errors, rejecting plenty of HTML that works perfectly fine In a browser.

I ' ve asked the MAVEN team to disable Doclint by default, and I ' d suggest the same to Ant and Gradle. Unfortunately, the Oracle team seem convinced that they ' ve made the right choice with errors by default and their use of s Trict HTML.

Comments Welcome, but please note this non-specific "it didn ' t work for me" Comments should is at Stack Overflow or Java R Anch, not here!

jdk1.7 error after upgrading to jdk1.8: [ERROR] javadoc:warning-multiple sources of package comments found