Sencha Docs gives JavaDoc a Facelift
If you have worked with Java, you are undoubtedly familiar with the JavaDoc tool. JavaDoc is the de facto standard for creating API documentation based on comments in Java source code. Although JavaDoc documentation contains most of the information you are looking for, the way it presents that information leaves a lot to be desired. Most notably, JavaDoc creates static HTML files that are not easily customized or styled. And although it lets you customize the display of content in some ways, this is mostly limited to basic changes such as changing font type or color. We’re about to change all that.
For roughly the past 15 years, Java developers using API reference documentation produced by JavaDoc have seen something like this:
Current JavaDoc Limitations
As you can see, JavaDoc has some major limitations, particularly compared to modern rich internet applications:
- It generates a document set with a very dated look and feel because the user interface design has not been upgraded in quite some time.
- It uses HTML frames, which make it difficult to print, navigate or bookmark a particular page.
- Since the documentation set generated is static HTML, you can’t search or filter data. For example, you have to navigate a tree of all documented classes in order to get to the documentation for any particular class.
- It’s hard to modify the style of the generated HTML because the HTML templating code is actually embedded directly in the JavaDoc source code.
- The generated HTML doesn’t contain enough information to properly style the content using CSS. With JavaDoc, the only real way to have complete control over the output is to write a custom Doclet rather than customizing the default Doclet. Although this works, you have to duplicate the functionality provided by the default doclet.
To summarize: the user interface is dated and uses frames, which hinder deep-linking and printing. You can’t search or filter on content. And the output is very difficult to customize and style.
Introducing Sencha Docs for Ext GWT
Sencha Docs offers a fresh take on API documentation for Java. Rather than modifying or restyling JavaDoc, we decided to start from scratch and build a new user interface experience using the JavaDoc parser and Ext GWT. Since Ext GWT is designed to build rich internet applications, it was a great framework with which to build a modern user experience. This current version of Sencha Docs also uses an icon set from the Eclipse project.
What’s New About Sencha Docs?
- Tabbed interface with multiple pages to be displayed at once
- Doc pages can be bookmarked and deeplinked (no frames!)
- Print-friendly views
- Client side filtering of packages and classes
- Server-side searching of classes, fields, constructors, and methods
- Documentation hyperlinked directly into source code
We hope you’ll like the new capabilities. Sencha Docs displays a tabbed interface that allows multiple pages to be opened at the same time. And you can quickly toggle between all open pages. You can also easily get to the information that you want using both filters and search. Pages can be bookmarked for easy sharing and saving. And unlike JavaDoc, the source code is hyperlinked from the documentation pages. For example, just click on a class or method name and you see the source code for the members. The source code is also nicely formatted and can be printed.
When listing class members such as fields and methods, JavaDoc lists members separately for the current class and each of its super classes. But this makes it difficult to see all of the members of the current class because you must look at a different section for each supertype. Sencha Docs merges the current class members with the super class members. And you always have the option to hide the inherited members if you prefer.
For the Ext GWT documentation in particular, we’ve added some things. Ext GWT components fire a large number of events. With JavaDoc documentation, these events were listed in the class documentation. Although this worked, it was not ideal. With Sencha Docs, events are listed in the same way that fields, contructors, and methods are listed. This makes it very easy to quickly see events fired by a particular class. Another nice feature is that you can see events from super classes so you can see all events being fired, not just events from the current class.
You can find our new application here. The documentation is from our forthcoming 2.2.0 release of Ext GWT. Compare this to the standard documentation produced by JavaDoc. Take a look and let us know what you think.