Invalid "self-closing element not allowed" JavaDoc error

Fri Jul 26 16:50:46 UTC 2013

Most elements MUST NOT be self closed; it'll screw up document tree.
Try this piece of html in your browser

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/strict.dtd">
<div style="color:red;" /> text outside div

However <br/> etc seems to be fine; they are elements with EMPTY
content model, or "VOID element" in html 5 jargon. There are exactly
10 such elements in html 4

    area base br col hr img input link meta param

I agree with Nick that a mere warning is appropriate for these elements.

Zhong Yu

On Fri, Jul 26, 2013 at 10:46 AM, Nick Williams
<nicholas+openjdk at nicholaswilliams.net> wrote:
>
> On Jul 26, 2013, at 10:27 AM, Stephen Colebourne wrote:
>
>> On 26 July 2013 14:49, David M. Lloyd <david.lloyd at redhat.com> wrote:
>>> You took one step outside of logic, in my opinion.  Yes, the spec is a
>>> guide, in practice.  But to use that to justify not even trying to conform
>>> or not encouraging people to conform is crazy.  Without the spec, the HTML
>>> world would be even more insane than it is now, by orders of magnitude.
>>>
>>> It is very likely that browsers will accept spec-compliant HTML.  It is also
>>> very *unlikely* that your average user will be arsed to test their HTML on
>>> every browser on the planet before they publish their JavaDoc. It is also
>>> unlikely for your average Java developer to know or understand *any* of
>>> these issues; you're giving them way too much credit IMO by assuming that
>>> they're simply imposing some kind of rational style, rather than simply not
>>> knowing how HTML works.
>>>
>>> In the end I think it does far less harm to bark at people who are not
>>> writing spec-compliant HTML than it does to assume they know what they're
>>> doing and what the implications are.  If doclint doesn't enforce this kind
>>> of strictness, then what will?
>>
>> Frankly, getting developers to write any Javadoc is a huge problem.
>> Getting them to correctly use the basic tags is another huge step
>> (generally enforced today via checkstyle). Asking them to write
>> well-formed HTML seems unrealistic and likely to have the negative
>> effect of causing less documentation, not more.
>>
>> In addition, Javadoc is frequently read as source code in IDEs (F3
>> through to the class and read the source code Javadoc, not the HTML
>> Javadoc). In fact, I read source code Javadoc at least ten times more
>> often than HTML Javadoc. Given that strict HTML tends to simply get in
>> the way visually of reading the source code Javadoc, it becomes yet
>> another negative of strictness.
>>
>> The original issue in the thread is whether <br /> should be valid. I
>> think it should because its hugely widely used and accepted by
>> browsers, and forcing developers to change to <br> is net negative.
>>
>> Note that if doclint was off by default in the Javadoc tool, I
>> probably wouldn't care.
>
> I would even say note that if <br /> wasn't a process-stopping ERROR I probably wouldn't care. That's the biggest pain in the @$$ to me. That having <br /> in a JavaDoc makes in impossible for me to generate JavaDoc. Sure, I can disable doclint, but THEN I miss out on all the other useful messages it provides. Just make <br /> a warning (or all self-closing void tags in general) and I'm satisfied.