doclint in jdk8-白红宇

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

Javadoc doclint

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

The Javadoc comments in source code use a mixture of tags, starting with @, and HTML to allow the developer to express their 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 have @link references that were inaccurate (such as due to refactoring) and the tool would simply provide a warning.

With JDK 8, a new part has been added to Javadoc called doclint and it changes that friendly behaviour. In particular, the tool aim to get conforming W3C HTML 4.01 HTML (despite the fact that humans are very bad at matching conformance wrt HTML).

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

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 W3C HTML 4.01

no duplicate HTML id attribute

no empty HTML href attribute

no incorrectly nested headers, such as class documentation must have <h3>, not <h4>

no invalid HTML tags, such as List<String> (where you forgot to escape using <)

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 are errors, not warnings. Break the rules and you get no Javadoc output.

In my opinion, this is way too strict to be the default. I have no problem with such a tool existing in Javadoc, but given the history of Javadoc, errors like this should be opt-in, 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 to reverse engineer them.

Turning off doclint

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

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


         
      
       -Xdoclint:none

or add it to the maven-javadoc-plugin:


         
            
       
        org.apache.maven.plugins
             
       
        maven-javadoc-plugin
             
               
        
         -Xdoclint:none

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

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

if (JavaVersion.current().isJava8Compatible()) {    allprojects {      tasks.withType(Javadoc) {        options.addStringOption('Xdoclint:none', '-quiet')      }    }  }

Summary

I don't mind doclint existing, but there is no way that 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 is very heavy handed with what it defines to be errors, rejecting plenty of HTML that works perfectly fine in a browser.

I've asked the maven team to doclint by default, and I'd suggest the same to Ant and Gradle. Unfortunately, the Oracle team seem that they've made the right choice with errors by default and their use of strict HTML.

Comments welcome, but please note that non-specific "it didn't work for me" comments should be at Stack Overflow or Java Ranch, not here!

Turning off doclint in JDK 8 Javadoc

Javadoc doclint

Turning off doclint

Summary

26 comments: