[javadoc] How to download Javadoc to read offline?

update 2019-09-29: Java version 11

The technique below does not now work with Java 11, and probably higher versions: there is no way of ignoring multiple "broken links" (i.e. to other classes, other APIs). Solution: keep your javadoc executable file (or javadoc.exe) from Java version 8


There are good reasons for making your own local javadocs, and it's not particularly difficult!

First you need the source. At the time of writing the Java 8 JDK comes with a zip file called src.zip. Sometimes, for unexplained reasons, Oracle don't always include the source. So for some older versions (and who knows about the future) you have to get hold of the Java source in another way. It's worth also being aware that, in the past, Oracle have sometimes included the source with the Linux version of the JDK, but not with the Windows one.

I just unzipped this file... the top directories are "com", "java", "javax", "launcher" and "org". Directory launcher contains no files to document.

You can generate the javadocs very very simply from any or all of these by CD'ing at the command prompt/terminal to the directory ...\src. Then go

javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath . -subpackages java:javax:org:com

NB note that there is a "." after -sourcepath

Simple as that. Generating your own javadocs also has 2 huge advantages

  1. you know they are precisely the right javadocs for the JDK (or any exernal jar file) you are using on your system
  2. once you get into the habit, reconstituting your Javadocs is not a tiresome challenge (i.e. where to go looking for them). For example I just unzipped a couple of source jars whose packages are closely coupled, so their sources were in effect "merged" & then made a single Javadoc from them...

NB Swing is semi-officially DEAD. We should all be switching to JavaFX, which is helpfully bundled with Java 8 JDK, but in its own source file, javafx-src.zip.

Unzipped, this reveals 3 "root" packages: com, javafx and netscape (wha'?). These should be manually moved over the to appropriate places under the unzipped src directory (including the JavaFX com.sun packages under the Java com.sun strcture). Compiling all these Javadoc files took my machine a non-negligible time. I'd expect to see all the JavaFX source classes in with all the other source classes some time soon.


BTW, the same thinking applies to documenting any and all Java jars (with source) which you use. However, all versions of most jars will be found with their documentation available for download at Maven Central http://search.maven.org...

PS afterthought:
using Eclipse and the "Gradle STS" plugin: the "New Gradle STS Project" wizard will create a gradle.build file containing the line

include plugin: 'eclipse'

This magically downloads the source jar with the executable jar (under GRADLE_HOME) when you go

./gradlew build

[addendum 2020-01-13: if you have chosen not to include the Eclipse plugin in your build.gradle, it would appear that you can go (with the selection on your project in the Project Explorer) Right-click Gradle --> Refresh Gradle Project to get Eclipse to download the source files.]

... giving you an extra degree of certainty that you have got the right src and therefore the right javadoc for the dependency in question.