Invalid "self-closing element not allowed" JavaDoc error

[Stephen Colebourne]

On 25 July 2013 21:46, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
> First, as was pointed out earlier[1] in the original thread, the HTML 4 spec
> does not mention the existence of self-closing elements, and in that
> message,
> David makes a good point that <br> is defined to not have an end tag,
> making the <br/> syntax doubly questionable.
>
> So what does "doclint" stand for?  Read it as "doc lint" meaning it is to
> javadoc comments what -Xlint is to javac and lint is to C code. In other
> words, it is intended to be used to point out questionable (or erroneous)
> input.   The ";" in "for (Item i: list);" is totally legal, the cast in
> "String s =
> (String) "abc"; are both legal, but we do not think it unreasonable to
> highlight them in code, along with all the other -X lint warnings.  So
> too with -Xdoclint messages regarding javadoc comments.
>
> Yes, you can say that all the browsers (now) accept this syntax -- but
> the design intent of -Xdoclint was to highlight issues that might cause
> a validator to give comments.  For far too long, the javadoc tool itself
> has generated bad code, and so the general goal in the ongoing javadoc
> TLC has been that given valid input, javadoc should generate valid output,
> where "valid" means "conforms to the published DOCTYPE" and accepted
> by a standard recognized validator, such as the one I cited at w3c.org.
>
> I would /strongly/ prefer that we not revert back to "is the output from
> javadoc
> accepted by all browsers?".

At a high level I've known about this doclint project, and thought it
seemed like a good idea, so I didn't investigate it much. Only now as
the implications become clearer do I start to care.

I'm afraid that it looks like the goal of the project has become to
"enforce the perfect" rather than "remove the imperfect". There is a
huge difference between the two,

It is widely accepted, including by Tim Berners Lee, that XHTML failed:
http://dig.csail.mit.edu/breadcrumbs/node/166
http://lemire.me/blog/archives/2006/10/30/reinventing-html-or-yes-we-admit-it-xhtml-failed/

The key point is that humans both hated and were bad at
writing/maintaining strict HTML. HTML is all about quick hacks. And
the entire HTML world is built on lenient input parsing. Strict input
parsing just isn't what HTML is about, hence the failure of XHTML and
validation exercises in general. Postels Law applies here.

Now, as programmers, we are used to having to get our syntax right so
that it passes the compiler. Its easy to make the analogy with HTML
and assume a need and desire for the same there. But that misses the
HTML culture, which is lenient, not strict.

The doclint tool should be focussed on the imperfect. Missing
@param/@return/@throws tags, Misues of end of sentence markers. HTML
structure that is known to fail on browsers would be fair game. The
general well-formedness of HTML is entirely different game - thats the
search for perfection.

In summary, developers should be able to put HTML in Javadoc that they
would use when building a typical HTML website. Its websites and
browsers that define what should be accepted as HTML, not standards.

Stephen