Somewhere in my travels on the interwebs, I came to realize that OpenJDK version 10 was already at “end of life” because version 11 had come out and was deemed the LTS version (long term support). This meant that version 10, while obviously still functional, wasn’t a great choice. It also meant version 11 could be the version I settle down on for a long time to come (several years at least it sounds like). Related to this was the additional good news that there were no changes to the code required to keep the project compiling properly.
Then came the issue of the Java documentation. Since the last time I talked about Java, the “no longer free” thing Oracle was doing to the licence for Java has come to pass. This came with some baggage I wasn’t fully prepared for. I’d already dealt with switching to OpenJDK, I’d already made sure I had OpenJFX available, but I’d simply assumed that the online Java API documentation would still be available for download. This was a requirement due to my desire to be able to work on the project fully offline if I had to.
This is where it gets kind of weird. OpenJDK doesn’t include or produce the JavaDocs for the API. I didn’t think this would be a problem because they should still be available from Oracle and those should be close enough to accurate to cover any needs I was likely to have. I headed over to Oracle’s site, clicked the “I accept” radio button for the documentation license like I had a hundred times before, clicked the download link, and was taken to an Oracle single sign on page.
Ok, no problem, I can apparently just make an Oracle account. I don’t particularly want to do so, but at least I seem to have a path forward. I start filling in the form to create an account and realize that they are asking me required questions about my work phone number, company, and job title. At this point I have become suspicious that I’m not really supposed to be signing up for an account as a person, so I pull the rip cord and start trying to come up with another way to get the docs. This is pretty frustrating because they won’t let me download the documentation that they clearly provide on their live site for free.
It stands to reason, at least in my head, that I should be able to generate the JavaDocs for the API on my own if I can locate the source code for the JDK. As it turns out this is a very simple thing to do. It’s available as a separate download on the OpenJDK site (assuming you live in a country where downloading it is allowed). That meant I just needed to unzip it and try to figure out how to configure the javadoc tool to build the API docs I want.
Due to Java modules, this actually proved to be a bit more complex than I thought it would. I’m an old hand at Java and I like and use packages all the time, but modules never seemed to really offer much value to me so I never spent any time learning how they work. New information to me was that when they are in use (as they are for the OpenJDK project) they pretty considerably change the way JavaDocs are generated.
After quite a bit of reading the documentation for how to make JavaDocs on code with modules, I finally managed to come up with this:
> cd src // the place I extracted the source code to
> ..\bin\javadoc -d ..\docs --module-source-path=. --module-path=. --module=java.base -html5I ran it and in about a minute I had an epic pile of documentation sitting in my docs directory and I was officially ready to go. Hopefully this helps someone else too, or perhaps it will just help me again later, which is also great.