[icedtea-web] RFC: More javadoc fixes for Java 8

[Jacob Wisor]

On 05/13/2014 07:51 PM Omair Majid wrote:
> * Jacob Wisor <gitne at gmx.de> [2014-05-12 10:04]:
>> Please read my message <5370C9E4.7000607 at gmx.de> for this. Standards
>> compliance is my main motivation.
>
> But we know that Javadoc is not valid xhtml. It is a mix of html and
> it's own formatting system. And it's processed by only one tool:
> javadoc.
>
>> I was hoping javadoc would have finally moved to XHTML since OpenJDK 8, but
>> unfortunately progress has been a bit of a pain for Java during the last few
>> years. :-\
>
> No, this is still not the case. The official documentation on javadoc
> contradicts this and then goes on to suggest non-valid html as the
> default:
> http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#format

I know ;-) which is insane. This may have been okay 1994 or until 2000, but we 
have moved far beyond that.

>> As I mentioned earlier, your patch is not wrong but it fixes problems that
>> will or might become a problem themselves when javadoc finally transitions
>> to XHTML.
>
> I doubt it. For starters, that means every comment must also begin with
> valid markup. I don't see us changing
>
>      /** Foo the bar
>
> to
>
>      /** <p>Foo the bar
>
> everywhere.

No. XHTML specifically allows for content in the body element. Since javadoc 
comments do not constitute HTML documents by definition but only body content, 
it would not be required for an XHTML honoring javadoc to place comment content 
into any specific elements. Anyway, the comment can be enclosed by any means a 
reading or extracting tool chooses to already but using non-conforming XML 
elements inside comments will presumably cause problems for comment reading or 
displaying tools, even for those with the most tolerant parsers. This is why it 
makes a lot of sense to resort to purely XML conforming elements in comments. 
This is also the main reason why XML has been standardized in the first place - 
and of course because SGML is too complex to be fully implemented for most 
products and platforms.

>> I think, I do not need to elaborate on the human *and* machine
>> readability benefits of XML here, so this is mainly why I would like every
>> javadoc source code out there to be prepared for that transition.
>
> While I don't personally care about this, many people disagree with the
> premise [1][2].
>
>> If self-enclosing elements are stopping OpenJDK 8 javadoc from digesting
>> that Java source code documentation then I would rather assume javadoc needs
>> to be fixed.
>
> I don't think upstream is budging on this. I, for one, will be really
> happy if they fixed javadoc to be more lenient by default. But they
> aren't. And they are aware of this issue:
> http://thread.gmane.org/gmane.comp.java.openjdk.core-libs.devel/19308

Making a lint feature more lenient on the input it checks is definitely the 
wrong way to go. This is an absurd approach. lint tools' sole purpose is to 
check for more and better structure than promoting more ambiguity.

>> And evidently, the time has come to give back javadoc the
>> attention it requires, since it has been neglected for so many years.
>
> This doclint effort (which is what breaks javadoc-ing of code) is the
> attention upstream gave them. I am hoping they don't give it much more
> attention.
>
> To summarize, I hope you are okay with me pushing the patch. I will be
> happy to hold it back if you think an alternate solution (either
> upstream or in icedtea-web) is possible.

No offense, but obviously either because I am chanting into the wrong direction 
or I am ignored, I am giving up on this here.

> [1] http://blog.codinghorror.com/xml-the-angle-bracket-tax/

Well, this guy seems to miss the point. Not the XML standard is a problem, bad 
design is. XML does not prevent anybody from creating bad designs or bad XML 
document generators. Yes, there is a lot of crap software in this world which 
even drives mission critical stuff and communicates in XML, but this is no 
reason or excuse to blame their existence on XML. Besides, XML was designed for 
/documents/ not /data/ in general.

> [2] http://www.ibm.com/developerworks/xml/library/x-sbxml/index.html

Actually, for javadoc comments all questions presented here can be answered with 
NO. Javadoc comments are structured indeed and although individually they do not 
constitute or form a document, they are supposed to be pulled together into one 
document, at least when displayed to a user. So again, while marking-up content 
you create structure, thus making XML a natural choice for this. ;-)

Jacob