On Jul 26, 2013, at 10:27 AM, Stephen Colebourne wrote: > On 26 July 2013 14:49, David M. Lloyd <david.ll...@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.
