JavaFX API Documentation Tool Now Supports In-line Examples
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:
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
