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

[Omair Majid]

* 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

> 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.

> 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

> 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.

Thanks,
Omair

[1] http://blog.codinghorror.com/xml-the-angle-bracket-tax/
[2] http://www.ibm.com/developerworks/xml/library/x-sbxml/index.html

-- 
PGP Key: 66484681 (http://pgp.mit.edu/)
Fingerprint = F072 555B 0A17 3957 4E95  0056 F286 F14F 6648 4681