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>}"
forbidden)?
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org
For additional commands, e-mail: dev-h...@commons.apache.org
