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