commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gilles <>
Subject Re: [Math] Javadoc with Java 8 (Was: svn commit: r1591664 [2/2] - ...)
Date Thu, 01 May 2014 23:12:31 GMT
On Thu, 1 May 2014 17:12:13 -0500, Paul Benedict wrote:
> "Correct tag usage" for JavaDoc is properly formed HTML. HTML does 
> not have
> self-closing tags -- XHTML does. So if you want to have a proper HTML
> document, you don't use self-closing tags.
> By the way, HTML isn't legacy. HTML continues to evolve but XHTML is 
> a
> whole different beast. XML (also XHTML) processing is unforgiving -- 
> your
> document is right or wrong (nothing in between). HTML processing is 
> lenient
> in error handling and allows predictable processing despite mistakes.
> Having a "properly formed XML document" inside of HTML, which is what
> JavaDoc generates, buys you nothing. What buys you something is 
> properly
> formatted HTML in an HTML document.

What I tried to convey is that the future seemed to be towards
XML-compliance (less forgiving but simpler). Here with Java 8
we seem to have non-forgiveness together with complexity. And
_preventing_ future compatibility with XML.

[HTML probably stays around for the same kind of reason that
M$-Windows had to be backward-compatible with M$-DOS.]

Maybe that it's useless to discuss "good" or "bad" if HTML it is,
and HTML it will be, forever...

Nevertheless, I'm asking whether it is possible to not decrease
the level of Javadoc legibility in our own project.

The recent commits were performed as if the answer is a definite
"no". E.g. can you confirm that there is absolutely no way to
write a verbatim "<" in Javadoc (i.e. is "{@code List<String>}"


To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message