Invalid "self-closing element not allowed" JavaDoc error

Nick Williams nicholas+openjdk at
Thu Jul 25 20:19:26 UTC 2013

Point of interest: JavaDoc uses the HTML 4 "Loose" specification, not the HTML 4 "Strict" specification. By using frames, JavaDoc is in violation of the HTML 4.01 Loose specification (see below).

There are void elements and there are empty elements.

Void elements are elements that ARE NOT ALLOWED to have content. They are: area, base, br, col, command, embed, hr, img, input, keygen, link, meta, param, source, track, wbr, and some foreign/extension elements.

Empty elements are elements that ARE ALLOWED to have content but don't, for whatever reason. This is any element not listed above.

In HTML (all versions), empty elements CANNOT be self-closing, they MUST have start and end tags (like <script scr="foo"></script>) because they MAY have content. Void elements MUST NOT have start and end tags because they MAY NOT have content. Browsers MAY permit self-closing void tags, and all browsers do. There is no syntax difference between Strict, Transitional (Loose), and Frameset. Strict prohibits frame sets, presentational elements (like <font>), and deprecated elements. Transitional (Loose) allows presentational elements and deprecated elements but prohibits frame sets. Frameset allows presentational elements, deprecated elements, and frame sets. /If/ the motivation behind "self-closing element not allowed" is abiding by the spec, then we should get rid of frames, too.

In XHTML (all versions), both empty elements and void elements MUST EITHER have a start and an end tag OR be self-closing ( Furthermore, the spec recommends for compatibility reasons that you always put a space before the forward slash in a self-closing element (

Special Note: In HTML5, the SVG and MathML elements MUST EITHER have a start and an end tag OR be self-closing.


On Jul 25, 2013, at 1:13 PM, David M. Lloyd wrote:

> It all hinges on whether the tool is generating HTML 4 or HTML 5.  If 4, then the output should be HTML 4 "strict" and this kind of input should either be translated or forced to be valid.
> If the output is going to be HTML 5 - which I suspect is going to be considered "premature" given the usual glacial pace of these kinds of changes - then perhaps it's time to revisit some other crustiness, like the use of frames.
> On 07/25/2013 12:59 PM, Stephen Colebourne wrote:
>> Its complicated, see for example:
>> The key point here is not whether its in the standard or not, but what
>> people actually *do*.
>> There is no doubt in my mind that <br /> br space slash is very common
>> indeed. Its certainly my default. The javadoc validator should be as
>> lenient as browsers are in this case.
>> Stephen
>> On 25 July 2013 18:41, David M. Lloyd <david.lloyd at> wrote:
>>> On 07/25/2013 12:27 PM, Nick Williams wrote:
>>>> My apologies if this is not the right place to address this. If so, please
>>>> forgive and direct me to the correct list.
>>>> There are a lot of people/projects complaining about Java 8's new
>>>> "self-closing element not allowed" error when compiling JavaDoc that has
>>>> legal <br /> tags in it (just google "self-closing element not allowed" in
>>>> quotes). Some (including myself) are asking, "Why should we fix this? The
>>>> problem is not in the JavaDoc, it's in the JavDoc compiler." However, I
>>>> haven't been able to find anyone who has actually broached the subject on
>>>> any mailing lists.
>>>> <br /> is completely legal. While it is not strictly required by the HTML
>>>> standard (unless you're using XHTML), using self-closing tags is /preferred/
>>>> because it's more obvious what the intention is. Perhaps most importantly,
>>>> <br /> is supported on 100% of browsers and is used throughout JavaDoc all
>>>> over the place. I have a feeling that once more projects start compiling on
>>>> a released Java 8, this is going to make a fair number of people angry that
>>>> hey have to "fix" (read: needlessly change) potentially thousands of
>>>> classes' worth of JavaDoc.
>>>> What was the motivation behind the new "self-closing element not allowed"
>>>> check and how can we make it go away?
>>> Not really having a stake in this, I just want to observe a couple things.
>>> First, from what I can see, the HTML 4.x specifications make no reference to
>>> self-closing elements or their syntactical realization.  As far as I can
>>> tell (not being any kind of SGML expert), self-closing elements are not
>>> valid or meaningful HTML according to its SGML definition.
>>> Finally, even if they were allowed, the BR tag is explicitly defined to
>>> forbid an end tag; self-closing elements imply an end tag (at least they do
>>> in XML, which appears to be the next-nearest concrete specification that has
>>> anything to say on the matter).
>>> See for more info.
>>> So I'm curious when you say "using self-closing tags is /preferred/", do you
>>> have any sources to cite?
>>> --
>>> - DML
> -- 
> - DML

More information about the core-libs-dev mailing list