Since its beginning, Javadoc output has been largely static HTML with navigation links and simple stylesheet styling of its appearance. Java SE 7 saw the first significant change in Javadoc output default appearance in a long time and now it looks like JDK 8 will introduce a new twist on generated Javadoc output. In this post, I look briefly at the more dynamic filtering of methods in Javadoc output by type of method that appears to be available with JDK 8's javadoc tool.
The following two screen snapshots compare the JDK 7 and JDK 8 versions of default Javadoc output for the Calendar class (chosen for its variety of method types).
Although the Javadoc output for JDK 8 has the same overall styles (including orange "tabs" for "Constructors", "Fields", "Methods" and so forth) as Java 7 Javadoc documentation, the methods in the JDK 8 generated documentation have multiple orange tabs above the listing of methods that allow the reader to click on the appropriate tab to see the appropriate subset of methods. The names of the tabs are about as self-explanatory as you could want with names like "All Methods" (all methods on the class), "Static Methods" (class-level methods), "Instance Methods" (object-level methods), "Abstract Methods" (methods without implementation), and "Concrete Methods" (implemented methods).
The next series of screen snapshots demonstrate how clicking on any of these tabs invokes embedded JavaScript code that calls appropriate functions in the script.js file that exists at the root level of the generated Javadoc directory structure.
This is a minor, but still somewhat handy, feature of Javadoc in JDK 8. I have often looked through methods of Javadoc for a class with mixed method types for methods that fit one particular type. Now, rather than needing to scan for keywords such as "static" or "abstract" or for the absence of those same words, I can simply use these "tabs" to filter the types of methods I want to see for a given class.
2 comments:
It'd be nice if the JavaDocs had a feature that provided an aggregated view of the inherited methods, too.
I often find myself scouring the dense list of inherited methods at the bottom of the Method Summary section. How am I supposed to know what type the method is defined on exactly?
True that JDK8 javadoc has the new method filtering feature. That's about the only good thing.
The really bad things about JDK8 javadoc:
1. JDK8 javadoc breaks backwards compatibility with the new doclint feature which is engaged by default. In particular if you use CI tools and Maven you'll experience that your builds will fail with JDK8 whereas they worked with JDK7. What is worse is the tools bundled with JDK8 that produce source code (e.g. wsimport) are actually incompatible with the JDK8 javadoc, meaning such source will not compile with JDK8 javadoc. So, one part of JDK8 is incompatible with another part of JDK8. See Steven Colebourne's excellent blog on the topic.
2. The look-and-feel. In JDK8 the descriptive text for parameters and exceptions are now printed in mono spaced font and they are no longer indented. This is just plain ugly if you ask me as mono spaced font should never be used for anything but names of identifiers, source code snippets, etc. But visual appearance aside the worst part of it is that here too the backwards compatibility is broken since things you put into {@code xxxxx} tags will no longer render any differently than the text around it.
Example: If you are describing a parameter with text like this:
@param myParam the name of the entity, use {@code null} to get the default entity
which I would say is quite common for developers to do, you can now forget all about that. It won't render.
For a side-by-side comparison of JDK7 javadoc and JDK8 javadoc I've found this. I think it is difficult to argue - objectively - that JDK8 javadocs have become easier to read than their JDK7 counterpart. Whether or not they have become visually more appealing is of course a matter of taste (I have my opinion on that too), but my point is about eligibility which has diminished.
I'm trying not to sound like a conservative grumpy old guy who's just opposed to any kind of change, but I really do think JDK8 javadoc is a major step back. The new method filtering feature doesn't make up for it. :-(
Post a Comment