Java 9 introduces javadoc html version choice
Description
Environment
Activity
Ian YoungJune 10, 2019 at 4:56 PM
Just for historical completeness, it looks like support for HTML 4 API documentation is removed in Java 13 under https://bugs.openjdk.java.net/browse/JDK-8215608
Ian YoungJanuary 25, 2019 at 2:49 PM
This is a fairly low-significance decision as my proposal is to "do nothing, be happy" and we can always revisit it later.
Resolving this as done for now; if people can't stand it once we have moved to Java 11, that would be a new ticket.
Scott CantorJanuary 24, 2019 at 6:51 PM
I loooove frames in my javadoc, but given how vocal I am about them everywhere, I guess I'm a hypocrite. I don't really care for any of the newer styles to begin with so I'll manage. I don't really use ours much anyway, I use other people's. My guess is they'll keep generating frames.
Ian YoungJanuary 24, 2019 at 6:47 PM
The transitional warning that was introduced in Java 10 has been removed in Java 11.
In Java 8, 9 and 10, generated Javadoc included the following:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">In Java 11, generated Javadoc includes this instead:
<!DOCTYPE HTML>This indicates HTML 5, according to this. So, although I do not remember seeing any advance indication of a change (and I can't find one now in retrospect) it does look like the default has changed in Java 11.
I don't see a ton of new warnings from the Javadoc processor on some selected projects, so it looks like the Javadoc we have is fairly close to being clean, probably partly due to the work done in JPAR-115. On the other hand, we still have "doclint" disabled so there may be some nits we won't find until we turn that off.
In Java 11, the javadoc command does still have an -html4 option, so we could skip this transition if we want to, for the life of Java 11. As we seem to have done what we need to do to transition, though, I'd prefer to just accept that HTML 5 is the way of the future and close this as done.
One wrinkle is that Java 11 also changed the default output generation such that frames are no longer generated (see JDK-8202961). Again, frames are something the Java developers say they will eliminate entirely in the longer term (you can search for things instead), but restoring (most of) the previous behaviour is still possible using the {{--frames}} option. It's not clear whether that gives you exactly what you had before, though, because HTML 5 supposedly has less support for the concept. In addition, invoking that behaviour in Java 11 results in the following warning:
javadoc: warning - You have specified to generate frames, by using the --frames option.
The default is currently to not generate frames and the support for
frames will be removed in a future release.
To suppress this warning, remove the --frames option and avoid the use of frames.That's not "suppressing the warning", fellows...
Although a new UI is always a bit of a wrench, my proposal again is to go with the flow here and just accept that our API documentation won't have frames for V4.
Thoughts, before I declare victory?
Ian YoungSeptember 17, 2018 at 2:59 PM
Not required to build under Java 7, so removing that "fix version".
Java 9 implements JEP 224 ("HTML5 Javadoc"). This introduces new
-html4and-html5options forjavadoc.In Java 10, a warning is introduced:
You have not specified the version of HTML to use. The default is currently HTML 4.01, but this will change to HTML5 in a future release. To suppress this warning, please specify the version of HTML used in your documentation comments and to be generated by this doclet, using the -html4 or -html5 options.We should determine which version of HTML we want to standardise on. Clearly the intention is to push us towards HTML5, which would have the advantages of not going against the grain as well as working with a better-defined specification.
The downside of going down the HTML5 path is that it may require us to make some additional changes to our existing document comments to make them valid HTML5 (in addition to any changes already required to make them valid HTML 4.01, which given that historically the javadoc parser has not flagged up most HTML issues may well be a non-empty set).
Once we have decided which way we want to go, we should set the appropriate option on the
maven-javadoc-pluginin Java 9 and later.There's no indication yet of which Java version will change the default to HTML5. In particular, we don't know whether it will be done in Java 11 as the EAs have just started coming out.