Sencha Inc. | HTML5 Apps

Blog

Sencha Docs gives JavaDoc a Facelift

July 15, 2010 | Darrell Meyer

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:

JavaDocs uses HTML frames and looks very dated.

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.

Searching

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.

Merging

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.

Events

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.

There are 38 responses. Add yours.

Justin Akehurst

4 years ago

Will there be a similar tool to document JavaScript, in a nice to display fashion?

Andrew

4 years ago

Looks great! Is it possible create the same theme for jsdoc-toolkit?

knalli

4 years ago

It looks beautiful. smile

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?

Paulo Ferreira

4 years ago

Is it going to be publicly available?

+1 on the jsdoc suggestion smile

makana

4 years ago

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!

Harry

4 years ago

This is so amazing!!  I can’t wait to see what is next!

Travis Tilley

4 years ago

Hell… I’d pay for the tool to generate those docs.

johanes

4 years ago

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

Thomas Fritz

4 years ago

I hope we will get that for jsdoc and so the ExtJS API Docs!? Any chance?

Great work!

Nick Donald

4 years ago

Nice, very easy on the eye and the mind.

Looking forward to using them soon on my next Ext adventure.

Great work.

Robert

4 years ago

“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

Francis C

4 years ago

Jaw dropped as soon as I used it.  Wow!!!  Sencha FTW!!

Animal

4 years ago

Majorly cool!

I use Java API docs a lot, and Extifying^H^H^H^H^H^H^H^H^HSenchifying them is absolutely necessary!

Animal

4 years ago

With Ext.History too.

Will the ExtJS 3.3 API docs be served through this app?

Rafael Chaves

4 years ago

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.

Mohammed Imran Khan

4 years ago

Very nice to see this.

Frank

4 years ago

Really nice!

f.sauter

4 years ago

It’s pretty cool!!!!!

??

4 years ago

beautiful….........!

Peter

4 years ago

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.

Shane

4 years ago

Justin, check out http://dojodocs.uxebu.com for a great UI on top of a JavaScript documentation framework

Gorka

4 years ago

A port to PHPDoc, which uses JavaDoc like tags, would be great.

Shiv

4 years ago

Fabulous, you guys are awesome.

ibnesayeed

4 years ago

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.

Neil Bartlett

4 years ago

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?

Michael Mullany

4 years ago

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!

uiap2031

4 years ago

well done!

Edwin Commandeur

4 years ago

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.

Ali

4 years ago

Great great! good job guys

handy.wang

4 years ago

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.

sunny

4 years ago

Very nice job!! thank you for your sharing!!!
So cool!!

David Easley

4 years ago

Drool!

Releasing this app as open source would be great publicity for Sencha and Ext GWT.

Behrang

4 years ago

Is there a way to view the official Java 1.6 docs using this tool?

blop

4 years ago

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.

Bhavesh

4 years ago

Guys,
    The scope of Javadoc tool is to help generate developers their own API documentation. You can have Javadoc for JDK on the web and get it generated dynamically but what about the the people who wnat to run Javadoc on their code? That is the reason why Javadoc generated static pages (offline users). Besides, Oracle already have a much better application for Java API documentation.
    Please check out DocWeb @ http://doc.java.sun.com/DocWeb/ The D.ocWeb is not only a dynamic Javadoc generation application but it also allows users to add comments, code samples and bug references. It also provides facility to translate API docs and comments to different languages. Besides, it also provides a search functionality for users to search for a package, a class, a field or a method. It have all these and much more. Please check it out and see if you can contribute as developer, writer etc. It is an open-source project.

Regards,
Bhavesh.

Arno Nyhm

4 years ago

is this sencha styled JavaDocLet available to download(and to use in my other java projects?)

Marlien

4 years ago

Now we know who the sebnsile one is here. Great post!

Comments are Gravatar enabled. Your email address will not be shown.

Commenting is not available in this channel entry.