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.
Summary
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.
Will there be a similar tool to document JavaScript, in a nice to display fashion?
Looks great! Is it possible create the same theme for jsdoc-toolkit?
It looks beautiful. :)
What means that in detail? Are you generating based on source code files a whole “docs web application” including static files, links and so on.. or parsing, analyzing it live but with cache? What about using this wonderful output for other (java) projects? Useable for Ant or Maven?
Is it going to be publicly available?
+1 on the jsdoc suggestion :)
Something like this is very very overdue for a long time! Missing searching/filter functionality is what makes me hate this javadoc pages. Tabbed interface is definitely a plus, too! Great work!
This is so amazing!! I can’t wait to see what is next!
Hell… I’d pay for the tool to generate those docs.
quite interesting, normally when i open javadoc i use a lot of tabs in my browser, so tab feature is definitely going to help a lot. The methods and events structuring is not that new since Actionscript doc has been doing it for a while. I am looking forward to be able to see the source file for the doc. It will definitely be a killer feature if you often extend other classes
I hope we will get that for jsdoc and so the ExtJS API Docs!? Any chance?
Great work!
Nice, very easy on the eye and the mind.
Looking forward to using them soon on my next Ext adventure.
Great work.
“JavaDoc is the de facto standard” IMHO that fact that javadoc is developed by Oracle and included in Oracle’s jdk make it the “standard” standard, not the de facto one
Jaw dropped as soon as I used it. Wow!!! Sencha FTW!!
Majorly cool!
I use Java API docs a lot, and Extifying^H^H^H^H^H^H^H^H^HSenchifying them is absolutely necessary!
With Ext.History too.
Will the ExtJS 3.3 API docs be served through this app?
There is nothing wrong with Javadoc, which is the standard for documenting Java code, it is just the standard doclet that is very primitive. I bet Sun never meant for to be so popular anyway.
Regardless, your design looks refreshing.
Very nice to see this.
Really nice!
It’s pretty cool!!!!!
beautiful…………!
Doxygen is (since 5 or more years) already providing an updated look for javadoc, more so with optional inheritance graphs, latex/xml/rtf/chm output, embedded foldable source code, etc. It can also create documentation for several other programming languages.
It would be nice, if this flashy javascript-based interface would be integrated with doxygen.
Another useful feature would be graceful degradation: The current interface does not work at all if there is no javascript.
Justin, check out http://dojodocs.uxebu.com for a great UI on top of a JavaScript documentation framework
A port to PHPDoc, which uses JavaDoc like tags, would be great.
Fabulous, you guys are awesome.
It’s been a couple of years, I was thinking the same for Ruby documentation in place of RDoc. I wish I could do that.
It looks very nice, but those icons are clearly “borrowed” from Eclipse. Nothing wrong with that except they are licensed under the EPL which I believe is incompatible with the GPL… assuming that’s the licence you intend to release this under?
Neil, yes the current icon set is from Eclipse, and if we ever decide to release docs as a product, we’d replace the icon set with a set that is compatible with GPL. But now that you point it out, we should have mentioned where the icons come from in the blog post. I’ll add that now. Thanks!
well done!
http://twitter.com/freeurl/status/6735118808
Very smooth, and well-done API docs! Sure hope that docs will be available to the public to spice up our API docs and making them a pleasure to use.
Would be a pity if the icon set cannot be re-used, because it is really insightful to have the same icons in Eclipse and in the API docs.
Great great! good job guys
Hi Darrell Meyer,
Recently, I relized that ExtJS was renamed to Sencha heared from my colleagues, then downloaded it. However, I didn’t find the first snapshot graphics of this post in the directory(sencha-touch-beta-0.91/docs/index.html) of downloaded package. So, I am so comfused and was crazy to find that package explorer because the explorer is cool for me.
So, can you or some guyes do me a favor?
Thanks.
Very nice job!! thank you for your sharing!!!
So cool!!
Drool!
Releasing this app as open source would be great publicity for Sencha and Ext GWT.
Is there a way to view the official Java 1.6 docs using this tool?
Have a look at jdocs.com – thats what javadocs could be.
Senchadocs is nice except it tries to retain too much of the javadoc format.