commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Thomas Neidhart <thomas.neidh...@gmail.com>
Subject Re: [Math] Javadoc with Java 8 (Was: svn commit: r1591664 [2/2] - ...)
Date Thu, 01 May 2014 20:49:58 GMT
On 05/01/2014 10:31 PM, Gilles wrote:
> Hi.
> 
> 
> I don't like most of the changes performed on the Javadoc; most of them
> are going in the wrong direction IMHO, the most severe being the use of
> HTML "entities" rather than using MathJax.[1]

well, this does not really come as a surprise.

But seriously, about which changes are you talking?
There are 5 groups of changes which have been performed so far:

 * replace <br/> with <p> tags
 * escape angle brackets (<, >) with the corresponding HTML entities
 * remove unneeded </p> tags where java 8 javadoc complained
 * add <code> tags within <pre> blocks as <sub> was not allowed
   otherwise
 * fix wrong/missing closing of tags (mostly ol, ul, code, li)

The only change being potentially controversial wrt readability are the
angle brackets, but there are already many cases where the entities are
used and this is only good practice and making it consistent in the
whole codebase.

> Last time I checked W3C was trying to make HTML a valid XML language;
> now from what I read in this commit, Java 8 insists on being invalid
> XML...
> Since when was it decided to comply with Java 8 despite that it does not
> seem to be an obvious move?

Feel free to revert my change, I was only determined to avoid potential
problems with the 3.3 vote as some people build with Java 8 and report
errors with it.

As the build with Java 8 is broken anyway (due to findbugs), it was a
wasted effort for now, thus I stopped in the middle of it.

> Until there is agreement on a way out, I think that we should have
> followed the route proposed here:
>   http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html
> (i.e. disable the enforcement of the new rules).

Well, I tried that, but the setting did not seem to work with java 7,
thus I had to remove it again.

Thomas

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org


Mime
View raw message