Josh On Design

One of the innovations in the JavaFX toolchain is our new javafxdoc tool. Rather than producing a set of html files like regular 'javadoc' does, we produce a single large XML file representing the entire codebase's API. This lets us easily add extra processing steps, such as producing semantic wellformed XHTML as you see today. It also lets us do a few other things. I think I've mentioned before the custom doclet tags for things like default value and read only attributes. Now we've added inline examples.

Before today if you wanted some example code with a screenshot in your docs you had to mark up the code manually (assuming you wanted any syntax highlighting), then copy the code into a separate project, compile it, run it, then save a screenshot of the running app. And finally you must copy the screenshot back into your docs. This system is really bad for several reasons:

• It's time consuming, so we do less of it.
• The repository becomes polluted with screenshots
• The sample code may not compile if the API changes before you release the SDK
• The screenshots can get quickly out of date
• The code snippets aren't syntax highlighted

Inline Examples

With our new inline examples system all of these are taken care of. Just use the @example doc tag and the rest is handled for you. The doc tool will compile and run your code into a buffered image. Then it will insert nicely syntax highlighted code back into the final page along with a link to the screenshot.

Here's an example:

@example
import javafx.scene.geometry.*;
import javafx.scene.paint.*;

ShapeSubtract {
    fill: Color.BLACK
    a: Rectangle { width: 100 height: 50 }
    b: Ellipse { centerX: 100 centerY: 25 radiusX: 50 radiusY: 25}
}

Will produce the page you see here:

Live page here

That's it. No muss! No fuss. Everything is taken care of for you.

So what doesn't work?

Well, there are a few rough edges still. Specifically:

• The syntax highlighting is very primitive. Essentially just a couple of quick regex's.
• The text the code: and produces: are generated, rather than being text the author specifies.
• There is no good way to know when the @example ends. For the time being I'm hacking it by marking the end with another doc tag @endexample.
• You can't have nicely formatted and highlighted code without also getting a screenshot.
• This won't work for non-graphics classes.
• This won't work for animation.

So there's still lots to do. In a future version I'd like to produce running applets rather than just screenshots, but I think that will have to wait until after the preview SDK. This is enough that we can get on with the task of writing great docs.

Stay tuned for more documentation improvements in the future.