The Future of Javadoc


When I started to learn Java in 2001, I've spent hours and hours reading and crawling the Javadoc API back and forth. It's a great source of knowledge and Sun (now Oracle) did a great job in documenting all the core concepts of the Java API.

Unfortunately the usability of the Javadocs is extremely awkward. It's still based on HTML 4.01 with a clumsy frameset for navigation. You have to use the built-in browser search in order find anything. It's as mess and those issues haven't been addressed since the introduction of Javadoc in 1995.

Due to these flaws I changed my behaviour over time. I started to use the inline Javadocs from my IDE of choice (first Eclipse, now Intellij IDEA). Today I rarely use the original Javadoc HTML sites anymore, mainly because it's navigating through all the types is so inconvenient.

Oracle recently announced two Javadoc-related JEPs: JEP-224 (HTML5 Support) and JEP-225 (Searchability Improvements). In my opinion this is long overdue and a step in the right direction.

In the meantime I've wrote a tool called Javadoc Reloaded to address the searchability issue by my self. It's some kind of prototype (or proposal) for JEP-225. I've used the code base of my Java 8 API Explorer that I wrote earlier this year when Java 8 came out.

Javadoc Reloaded

Javadoc Reloaded reads a given Javadoc API folder and creates a modified site with an entirely new landing page as seen in the screenshot above. The new site gets rid of the original frameset. Instead you use the search input field at the top of the page to filter the classes shown in the sidebar.

The project supports various kinds of search queries. Here's a few examples:

  • action - Finds every class whose name contains action. This is a shortcut for name:action
  • version:1.8 - Finds every class since version 1.8 (alias: since).
  • extends:runnable - Finds every class which extends (or implements) runnable (alias: sub).
  • in:java.lang - Finds everything from package java.lang (alias: package, pkg, from).
  • is:interface - Finds every interface. Other accepted values are: class, enum, annotation, abstract, final, functional
  • stream in:util is:interface since:8 - A combined example query (should be self explanatory).

The source code is hosted on GitHub and published under the MIT license. Feel free to fork this project and send me pull requests. You can also send me your feedback, bugs reports or feature requests via Twitter or by opening an issue.

Hopefully a few of those search capabilities will be picked up for revised Javadocs targeted for JDK 9.

Benjamin is Software Engineer, Full Stack Developer at Pondus, an excited runner and table foosball player. Get in touch on Twitter, and GitHub.

Read More