Most programming languages ship with a set of tools to help you build great software. Java has debuggers, compilers, syntax highlighting, and more bug reporting systems than you can shake a stick at. We even have great reference manuals. And yet the API documentation itself always gets the short end of the stick. JavaDoc was breathtaking in it's simplicity and elegance when first released in 1995. At the time HTML was new and the most advanced competing documentation was WinHelp. Today, however, well... let's just say you can have your breath back.

Java's API documentation hasn't changed much since the mid-90s and it's starting to show. There are a lot of good reasons for the slow pace of change, but it certainly gets annoying. When we started developing JavaFX we set out to make some serious changes to the platform, and API documentation was part of that. The JavaFX SDK ships with a new documentation tool creatively named javafxdoc. My initial suggestion was AwesomeDocs 5000, but sadly that was turned down by the trademark lawyers. Despite the pedestrian name, however, it remains awesome. Go check it out here.

javafxdoc: Awesome docs, but why?

So what makes it awesome? It could be all of the new GUI goodness we added like the accordion control and javascript animation, but those are secondary to the really cool thing: we built it to be future proof. Unlike javadoc, javafxdoc doesn't directly produce HTML at all. Instead it generates a large XML file which is fed into a second transformation step. This transformation currently produces the semantic & strict XHTML you see today, but in the future we could generate PDFs instead. Or a mobile phone version. Or push it into a database for searching and annotation. Or something else no one has thought of yet. No longer will we be locked into a single output format for all time. When the next great way to visualize API docs comes along we'll be ready.

Screenshot of new JavaFXDocs

A New Look and Feel

So with our new infrastructure in place, what can we do with it? Well, first we enlisted the help of a graphic designer to create a style that looks modern, clean, and easy to skim. Next, we took advantage of modern browser support for CSS and Javascript to change the navigation. We don't use frames anymore. Instead we have an accordion control on the far left, provided by the excellent open source Mootools project. HTML Frames are rife with problems, so we are happy to be rid of them. Finally you can bookmark the actual class you are on, not the frameset as a whole. And when the CSS and JavaScript is turned off (as it would be in a screen reader for the blind or a search engine), our new docs still make logical sense.

The class selection accordion

Inline Examples

Next we added support for inline examples. Code examples often get stale, meaning the code no longer compiles or references older versions of the API. Additionally, graphical APIs need lots of screenshots to explain their usage, but authors don't like to do screenshots. They take time and must be redone whenever the API changes. It's busy-work. To deal with this we added the @example doc tag. Now, rather than having the doc writer type some code into a <code> block, which will then quickly go out of date, the author can put the code after the @example tag. The doc tool itself will do syntax highlighting on the code (making the final documentation more readable), then compile the code and execute it, creating a final screenshot automatically. Less busy-work for the doc writers means better documentation.

Inline highlighted code and examples

Profiles

Finally, we wanted direct support for profiles. JavaFX has just one platform and one SDK for all devices, so why shouldn't there be one set of documentation as well. However, JavaFX also has profiles. Certain classes and functions are only available in certain environments & devices. We could add a note to each function letting you know which profile it is in, but wouldn't it be great to only show you the functions you are actually interested in? With just a bit of Javascript we can do that. There are buttons in the the upper right of every page which let you switch the current profile, automatically hiding the classes not in the profile. This means we can support any number of profiles in the future, but you still only have to download one set of docs. It's documentation that scales.

Profile Switcher

Since this is the first release of the SDK we still have bugs in our docs, both in the text and in the JavaScript & CSS formatting. As you find these bugs please report them. Our goal is for JavaFX to have world class documentation, both in content and presentation, and the only way to do that is with your help.

Thanks,
  Josh