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 22:02:46 GMT
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 
mistake, and transitional syntax was intended to make future versions 
(X)HTML be strictly XML-compliant (a.o. to simplify processing and 
the chance of "predictable results").
 From the partial information gotten here due to the issue with the 
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 
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):

If that means that Javadoc will become tied to legacy HTML, it's a 
for not using it more than necessary; in particular using entities 
be avoided wherever possible.

IMO, it makes little sense that Oracle now _requires_ than developers 
less legible documentation. This is turning back the clock...


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

View raw message