Jim has posted 66 posts at DZone. You can read more from them at their website. View Full User Profile

JavaFX API Documentation Tool Now Supports In-line Examples

07.04.2008
| 3477 views |
  • submit to reddit

The JavaFX API documentation tool (javafxdoc) now supports the effortless insertion of examples.  For instance, this screenshot shows a page of the JavaFX API in which an example is embedded along with its output image generated:

Examplesinjavafxdocs


An Explanation from the Author of this Feature

According to an explanation by Josh Marinacci of Sun, "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 well-formed XHTML as you see today.  It also lets us do a few other things. Last time I mentioned custom doclet tags for things like default value and read only.  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. Then you must finally 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.

With our new inline examples system all of these are taken care of. Just use the @example doc tag and the rest will be taken care of 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 in the screenshot above.

Tom Ball, a JavaFX development leader in Sun, added these comments in a reply: "It also lets *anyone* with basic XML transforming skills (lots of online tutorials) do things we never imagined.  One reason JavaDoc tends to look dated is that most developers have relied on whatever comes from Sun, instead of jumping in and raising the UI bar.  Now it is much more hackable...

This XML file is a database of a project's attributes, which can not only be data-mined to improve documentation, but to support many other tools.  For example, a cscope-like source navigator is more easily done than the original tool, as the XML model has more useful information about the source."

The ease of creating examples that are in-line with the documentation should encourage development of these examples, both in the JavaFX library API as well as in documentation that you and I as developers create for our projects.  Thanks Josh and the JavaFX development team for this facility!

Regards,
Jim Weaver
JavaFX Script: Dynamic Java Scripting for Rich Internet/Client-side Applications

Immediate eBook (PDF) download available at the book's Apress site

Published at DZone with permission of its author, Jim Weaver.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)

Comments

Kevin Daly replied on Fri, 2008/07/04 - 8:40am

Anyone know when the SDK will be made available? We're holding projects back until we see the sdk.

Jim Weaver replied on Fri, 2008/07/04 - 11:28am in response to: Kevin Daly

The Technology Preview Release of the Java SDK is being built out in the open, and the stated release goal (at JavaOne) is July 2008.  Instructions for downloading it, and running a simple application, may be found here.

Peter Arrenbrecht replied on Fri, 2008/07/11 - 10:46am

Cool, like doctest. But I'm missing some sort of verification of results. Is this planned?

For plain Java, which often has too much scaffolding around the interesting code, you might want to look at JCite which allows citing Java source from tests into documentation (JavaDoc and plain HTML). It also supports highlighting snippets.

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.