"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. Cheers, Paul On Thu, May 1, 2014 at 5:02 PM, Gilles <gil...@harfang.homelinux.org> wrote: > On Thu, 1 May 2014 16:31:13 -0500, Paul Benedict wrote: > >> Gilles, >> >> Javadoc is not XHTML but HTML... and not just HTML, but an HTML fragment. >> Documentation writers need to remember that their content is being placed >> within a bigger document so correct tag usage is important to get >> predictable results. >> > > The issue here is: what is correct tag usage? > IIRC, some years ago, W3C indicated that lenient HTML syntax was a design > mistake, and transitional syntax was intended to make future versions of > (X)HTML be strictly XML-compliant (a.o. to simplify processing and enhance > the chance of "predictable results"). > From the partial information gotten here due to the issue with the release > of CM, I get the impression that for some obscure reason, Java tries to > distance itself from the path set by the W3C. > > Until we know all the consequences of upgrading to Java8, I think that we > should not rush to make unnecessary changes. > > > >> I think all Math committers will find this thread about the Javadoc >> changes >> for Java 8 to be informative (switching to thread view can help): >> >> http://mail.openjdk.java.net/pipermail/core-libs-dev/2013- >> July/019269.html >> > > If that means that Javadoc will become tied to legacy HTML, it's a reason > for not using it more than necessary; in particular using entities should > be avoided wherever possible. > > IMO, it makes little sense that Oracle now _requires_ than developers write > less legible documentation. This is turning back the clock... > > > > Gilles > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > -- Cheers, Paul
