Invalid "self-closing element not allowed" JavaDoc error

David M. Lloyd david.lloyd at
Thu Jul 25 18:13:30 UTC 2013

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


More information about the core-libs-dev mailing list