commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Phil Steitz <phil.ste...@gmail.com>
Subject Re: [Math] Javadoc with Java 8 (Was: svn commit: r1591664 [2/2] - ...)
Date Fri, 02 May 2014 08:48:28 GMT
On 5/1/14, 7:20 PM, Paul Benedict wrote:
> Phil, I don't know who was telling people Javadoc is XML. I never heard of
> that. 

Well, could be just be personal ignorance, but the practice of
closing tags in commons javadoc goes back to at least 2002.  You can
see it in the [lang] Developer Guide (closing <p/>'s are referenced
there) and throughout Commons components.  I could not find much in
the archives actually discussing it.  I vaguely recall some argument
that valid XML would be easier to process with tools other than the
javadoc tool itself.  Personally, I find it a little more readable. 
I honestly don't care, but do find it irritating that we are being
forced to fiddle with this stuff to keep the tool happy / producing
"good" warnings.

I agree with Gilles though that entities damage readability and
using *more* of them is a step in the wrong direction.  I will -1
commits that rip out MathJax or mangle the embedded TeX (unless and
until someone explains for legitimate reasons why MathJax itself is
a bad idea).

 
Phil


> AFAIK, it has always been HTML but the Javadoc parser didn't care to
> enforce it. Now it's enforcing it so the only "good" Javadoc is HTML as it
> always was. If anyone wants to show me Sun saying Javadoc was XML, I'll
> gladly eat my words and enjoy learning something new. But why fight the
> technology? Javadoc isn't ever going to be XML so why continue going down
> that path?
>
>
> On Thu, May 1, 2014 at 9:15 PM, Phil Steitz <phil.steitz@gmail.com> wrote:
>
>> On 5/1/14, 2:31 PM, 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.
>>>
>>> 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
>>
>> Thanks for sharing.  Basically, I would say "what Stephen said"
>> which is that the J8 ridiculouslness should be roundly ignored.
>>
>> it is truly comical that roughly 10 years ago, we started
>> assiduously adding </p>'s so we would have "valid XML."  Now the
>> "best minds" are telling us that we need to rip all of that out.  I
>> am calling ########.  Lets focus on getting good, complete Javadoc.
>> Turn off whatever warning crap is being emitted.  I agree with
>> Gilles on this.
>>
>> Phil
>>> Paul
>>>
>>>
>>>
>>> On Thu, May 1, 2014 at 4:22 PM, Gilles <gilles@harfang.homelinux.org>
>> wrote:
>>>> On Thu, 01 May 2014 22:49:58 +0200, Thomas Neidhart wrote:
>>>>
>>>>> 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
>>>>>
>>>> Trigerring an error on self-closing (and valid XML) tags seems
>>>> utterly stupid. [There might be some deeper reasons which I'm not
>>>> aware of at this point, since those "nice" Java 8 features are
>>>> totally new to me.]
>>>>
>>>>   * escape angle brackets (<, >) with the corresponding HTML entities
>>>> Does Java 8 refuse angle brackets enclosed in {@code ...} tags?
>>>>
>>>>   * remove unneeded </p> tags where java 8 javadoc complained
>>>> In XML, closing tags are never unneeded, they are required; so it
>>>> looks like Java 8 decided to be XML non-compliant.
>>>> If this is so, my opinion is to not use <p> anymore!
>>>>
>>>>   * 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.
>>>>>
>>>> I don't agree that reducing legibility is good practise.
>>>>
>>>>
>>>>>  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.
>>>>>
>>>> Then, as I indicated in the [vote] post, we should just not support
>>>> Java 8 for the time being, and ask people to open appropriate issues
>>>> for the things they wish to be fixed.
>>>>
>>>> Why should we jump because Oracle made Java 8 non compatible with
>>>> Java 7?
>>>>
>>>>
>>>> Gilles
>>>>
>>>>
>>>> ---------------------------------------------------------------------
>>>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>>>> For additional commands, e-mail: dev-help@commons.apache.org
>>>>
>>>>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
>> For additional commands, e-mail: dev-help@commons.apache.org
>>
>>
>


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


Mime
View raw message