Javadoc in JDK 8 : Invalid "self-closing element not allowed"

Question

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.

Solution 1

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

Solution 2

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.

Solution 3

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.

Solution 4

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

View more solutions