Invalid "self-closing element not allowed" JavaDoc error

[Stephen Colebourne]

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.

Stephen