Introducing doclauncher

5 March 2016 Author: Erik Lievaart In this article I will quickly introduce a simple tool I built and use to access javadoc quickly.

Programmers all have their quirks. We tend to be quirky people :)
One of my quirks is that I like to work offline. Network connections fail more often than we'd like. Even when we have internet, the site we are trying to reach may be unavailable. Both at home and at work I have been in numerous situations where there was no internet connection available. I always want to have an offline version of javadoc, reference documentation and jar files available. Files stored locally are opened faster and always available.

I have written a simple command line tool for openening javadoc. If I need to open the javadoc of for example java.util.HashMap al I have to do is open a command line and type: 

doc java8 HashMap
I find that this works a lot faster than opening a browser and googling it. It also reduces the load of context switching and ensures you always have the right version of the library.

Installing Doclauncher

Doclauncher requires Java8 to work. Grab the binary here: Download doclauncher.jar
We can invoke doclauncher as follows: 
java -jar doclauncher.jar [DOC_REPO] [LIBRARY] [CLASS]?
Now, specifying the doc repo every time takes away the effort saved by using this tool. So I use a bash or batch script to invoke it. doc.bat 
c:
cd /bin/appz/doclauncher
java -jar doclauncher.jar "C:/data/resources/api" %1 %2
doc.sh 
cd ~/bin/apps/doclauncher
java -jar doclauncher.jar "/links/api" $1 $2
You might need to modify and or rename the scripts for it to work on your OS. As you can see both scripts supply the DOC_REPO and pass the LIBRARY and CLASS on to doclauncher. Place the script somewhere on your path and invoking these scripts can be done like so: 
doc java8 HashMap
The CLASS argument is not case sensitive. Doclauncher does not deal with name collisions (e.g. java.awt.List & java.util.List). Whichever page gets opened is arbitrary. Name collisions within a library should be the exeption in well designed libraries. Note that the CLASS argument is optional. 
doc java8
Would simply open the index (with frames) of Java8. Doclauncher will also open the index if the class could not be resolved, as happens for example with typos. If even the LIBRARY cannot be found, then doclauncher will show a popup with all available libraries.

Creating the DOC_REPO is simply a matter of creating a directory on the filesystem and unpacking the javadoc there: The directories obviously contain more files than shown in the picture. Directories can be nested, doclauncher scans directories recursively until it finds a marker file (allclasses-frame.html). The allclasses file is parsed to determine the classes in the library. The name of the library is derived from the name of the folder containing the marker file.

Javadoc generated with the javadoc tool will contain this marker file, but not all libraries pack it. Some libraries mess with the javadoc and remove the allclasses file. You can add an empty marker file manually, but then you will only be able to open the index file. Be sure to use a dedicated DOC_REPO folder, or scanning the directories can take a long time.

Alternatives

It is possible to attach javadoc to jar files in Eclipse
(right mouse button on jar > properties > Javadoc Location). Viewing the javadoc is a simple matter of selecting a classname in code and pressing SHIFT + F2. When I found out about this feature originally, I loved it and used it extensively. The problem with this approach is that you have to configure eclipse manually (for every jar in every project in every workspace on every computer you develop on). A solution to this problem could be to scan the metadata files of eclipse and augment them.

Of course, this exactly how the maven eclipse plugin works. Maven is capable of adding javadoc to the generated eclipse workspace. Unfortunately the maven repositories rarely contain the javadoc for libraries. Making this solution work requires maintaining your own maven repository with javadocs in it. Maven repositories are not as easy to navigate as my DOC_REPO, though.