Invalid "self-closing element not allowed" JavaDoc error

[Nick Williams]

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.