60

What are the best workarounds when running javadoc using JDK 8 and one receives this error.

It seems that for JDK 8 it has been decided that tags like <br /> and <p /> should generate errors, because they are invalid (strict) HTML 4. see discussion JDK mailing list here

I wonder, because I just wanted to compile some java project using maven and tripped over this issue. Of course, I can file a ticket with the project (and I guess I will), but it would be great if there is a way how to disable this behaviour (for a machine). Otherwise, I expect that a lot of projects need to be fixed before they can be built on JDK 8 without issues.

JE42
  • 4,881
  • 6
  • 41
  • 51
  • 5
    Does -Xdoclint:none work? – Ajay George Sep 25 '14 at 22:50
  • 2
    Googling for this option yielded a very nice link: http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html – JE42 Sep 25 '14 at 23:09
  • 2
    possible duplicate of [JDK8 and Javadoc has become very strict](http://stackoverflow.com/questions/22528767/jdk8-and-javadoc-has-become-very-strict) – Joe Dec 17 '14 at 13:27
  • The causes in the linked article are different ones than the cause that triggered this questions. – JE42 Dec 17 '14 at 16:09
  • Related. Getting the same error types from maven: http://stackoverflow.com/questions/15886209/maven-is-not-working-in-java-8-when-javadoc-tags-are-incomplete – AlikElzin-kilaka Sep 20 '15 at 06:24
  • Note that, at least for one project I'm compiling, the following works: `mvn clean package -Dadditionalparam=-Xdoclint:none` – Erhannis Nov 16 '16 at 15:58
  • yes. however this requires JDK8. If you need to make this work for both you need to detect the JDK version first. – JE42 Nov 17 '16 at 11:55

4 Answers4

29

For those two particular cases, I think the recommended action is to substitute them with <p>. This is the link to the Oracle documentation.

Tavo
  • 3,087
  • 5
  • 29
  • 44
  • Best recommendation is from @JE42 to set `-Xdoclint:none.` using this http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html – Abhijeet Jun 30 '16 at 03:56
23

To remove the errors in the javaDocs just replace:

  • <p/> with just <p>
  • <br/> with just <br>

Everything works fine after the correction in a excepted way.

friederbluemle
  • 33,549
  • 14
  • 108
  • 109
Xelian
  • 16,680
  • 25
  • 99
  • 152
  • 1
    Simple replacement of

    with

    will lead to a number of empty p tag warnings. Up-voted because this was better than the other answers, but I still added a more complete solution as an answer.

     – Ralph Ritoch Jun 05 '18 at 10:32
13

Taken from "What's New in JDK 8" from oracle.com:

The javac tool now has support for checking the content of javadoc comments for issues that could lead to various problems, such as invalid HTML or accessibility issues, in the files that are generated when javadoc is run. The feature is enabled by the new -Xdoclint option. For more details, see the output from running "javac -X". This feature is also available in the javadoc tool, and is enabled there by default.

Now I did what it told me to do. On JDK 7, the output of "javac -X" does not mention the -Xdoclint option. However, on JDK 8, it gives:

 -Xdoclint:(all|none|[-]<group>)[/<access>]
    Enable or disable specific checks for problems in javadoc comments,
    where <group> is one of accessibility, html, missing, reference, or syntax,
    and <access> is one of public, protected, package, or private.

So, run the Javadoc utility as follows:

javadoc.exe -Xdoclint:none <other options...>

In my script, the error you mentioned disappeared by using this option.

Timmos
  • 3,215
  • 2
  • 32
  • 40
  • 1
    Yes, that's correct. However, javdoc of JDK 7 will fail with this option, that means you have to detect support for the new option. In the end, I ended up fixing the html. – JE42 Jan 21 '15 at 15:33
  • 1
    If the project is using maven you can use profiles that activate only for jdk8. It's probably better to just fix the HTML if you can and file a bug with the project. – Adam Gent Feb 18 '15 at 16:21
7

While it is possible to disable error checking with the -Xdoclint option it doesn't repair the problem, it just hides the problem. To make valid HTML4 documents the following substitutions are correct.

  • Replace self closing br tags with regular br tags (<br /> with <br>)
  • Replace empty p tags with br tags (<p /> with <br>)
  • Ensure all p tags have content and are closed (<p>... with <p> ...</p>)
Ralph Ritoch
  • 3,260
  • 27
  • 37