Using a Doclet with JavaFX

This article explains how to use a Javadoc doclet that was created specifically for use with JavaFX source code.

Introduction

The JavaFX Software Development Kit (SDK) libraries, which are now included in the JDK 7 installation, include a doclet that can be used with the Javadoc tool to generate HTML documentation for JavaFX source code. You can use this doclet to produce customized and nicely formatted documentation for the users of your JavaFX library. The doclet is included in the <path-to-sdk>/lib/javafx-doclet.jar.

The declarations and documentation comments that you include in your JavaFX library source files are parsed by the Javadoc tool. The doclet specifies the content and format used to generate the HTML pages. Figure 1 shows the API documentation for the JavaFX 2 that was generated using the doclet.


Note:

The behavior of the javadoc tool used with the JavaFX doclet differs depending on the version of the JDK you are using with the tool. For example, the JDK 7 javadoc tool can process the source code with undeclared non-standard annotations, but the JDK 6 javadoc tool can not handle that type of annotations.

Figure 1 JavaFX 2 API Documentation Generated by the Doclet (Click image to enlarge.)

Description of Figure 1 follows
Description of "Figure 1 JavaFX 2 API Documentation Generated by the Doclet"

The API documentation includes the Property Summary section, as shown in Figure 2. The Property Summary section is added to the Field, Method, and Constructor summary sections generated by the standard Java doclet. The properties listed are linked to the sections for the getter and setter methods of each property.

Figure 2 Property Summary Section in Generated Documentation (Click image to enlarge.)

Description of Figure 2 follows
Description of "Figure 2 Property Summary Section in Generated Documentation"

You can also place the property documentation comments before the private property field. These comments are then automatically copied to the generated documentation for the getter and setter methods if there are no documentation comments already written explicitly for those methods.

Using the Doclet

You can use the doclet either on the command line or with an Ant task by setting the javafx.javadoc variable to true. Example 1 demonstrates an example of how to use the doclet on the command line.

Example 1 Using the JavaFX Doclet on the Command Line

javadoc -docletpath <path-to-the sdk>/lib/javafx-doclet.jar -doclet 
com.javafx.tools.doclets.formats.html.HtmlDoclet -sourcepath src
-d docs -private -J-Djavafx.javadoc=true packageName

You can use the JavaFX doclet with an Ant task by using a command similar to that shown in Example 2.

Example 2 Using the JavaFX Doclet in an Ant Task

<javadoc  destdir="docs" sourcepath="src" packagenames="packageName"
     access="private" additionalparam="-J-Djavafx.javadoc=true">
    <doclet name="com.javafx.tools.doclets.formats.html.HtmlDoclet"
        path="<path to the sdk>/lib/javafx-doclet.jar">
    </doclet>
</javadoc>

For more information about the standard Java SE Javadoc technology on which this JavaFX doclet is based, go to the Java SE Javadoc Technology document.