Fwd: Invalid "self-closing element not allowed" JavaDoc error

Thu Jul 25 18:59:47 UTC 2013

The message about "self-closing element not allowed" is because 
self-closing elements are not allowed in HTML 4. The message is 
generated by the new "doclint" feature available in javac and javadoc, 
which is specifically intended to detect issues in javadoc comments.  If 
you do not wish to use the new doclint feature, you can disable it with 
-Xdoclint:none.

As confirmation that this is not legal HTML, try typing a code fragment 
such as the following into the W3c validator at 
http://validator.w3.org/check

> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 
> "http://www.w3.org/TR/html4/loose.dtd">
> <head>
> <title>test</title>
> </head>
> <body>
> <br/>
> </body>
> </html>

You will get the following warning:

>  1. /Line 6 <http://validator.w3.org/check#line-6>, Column 4/:
>     NET-enabling start-tag requires SHORTTAG YES
>     |<br*/*>|
>
>     For the current document, the validator interprets strings like
>     |<FOO />| according to legacy rules that break the expectations of
>     most authors and thus cause confusing warnings and error messages
>     from the validator. This interpretation is triggered by HTML 4
>     documents or other SGML-based HTML documents. To avoid the
>     messages, simply remove the "/" character in such contexts. NB: If
>     you expect |<FOO />| to be interpreted as an XML-compatible
>     "self-closing" tag, then you need to use XHTML or HTML5.
>
>     This warning and related errors may also be caused by an unquoted
>     attribute value containing one or more "/". Example: |<a
>     href=http://w3c.org>W3C</a>|. In such cases, the solution is to
>     put quotation marks around the value.
>

-- Jon

On 07/25/2013 11:14 AM, Alan Bateman wrote:
> Re: Invalid "self-closing element not allowed" JavaDoc error.eml
>
> Subject:
> Re: Invalid "self-closing element not allowed" JavaDoc error
> From:
> "David M. Lloyd" <david.lloyd at redhat.com>
> Date:
> 07/25/2013 10:41 AM
>
> To:
> core-libs-dev at openjdk.java.net
>
>
> 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 http://www.w3.org/TR/html401/struct/text.html#edef-BR for more info.
>
> So I'm curious when you say "using self-closing tags is /preferred/", 
> do you have any sources to cite?
> -- 
> - DML
>
> Re: Invalid "self-closing element not allowed" JavaDoc error.eml
>
> Subject:
> Re: Invalid "self-closing element not allowed" JavaDoc error
> From:
> Stephen Colebourne <scolebourne at joda.org>
> Date:
> 07/25/2013 10:59 AM
>
> To:
> core-libs-dev at openjdk.java.net
>
>
> Its complicated, see for example:
> http://stackoverflow.com/questions/3558119/are-self-closing-tags-valid-in-html5
>
> 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 redhat.com>  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).
>> >
>> >Seehttp://www.w3.org/TR/html401/struct/text.html#edef-BR  for more info.
>> >
>> >So I'm curious when you say "using self-closing tags is/preferred/", do you
>> >have any sources to cite?
>> >--
>> >- DML