JavaFX Documentation

If you’ve been browsing around the standard Javadocs for the Java API’s looking for JavaFX Javadocs, then you’re probably frustrated. Where are those JavaFX Javadocs? JavaFX like any Java API has its own set of Javadocs.

This is the location of the JavaFX 8 Javadocs. JavaFX 8 is large enough that it was deserving of its own Javadoc site.

https://docs.oracle.com/javase/8/javafx/api/index.html?overview-summary.html

JavaFX Javadocs
JavaFX is large and complex, so has its own Javadocs outside of standard Java’s Javadocs.

Some readers may be new to JavaFX and Java in general. For anyone that doesn’t know what a Javadoc is, keep reading.

Every public JavaFX class, method and variable should be given a Javadoc comment. This has already been done for the JavaFX 8 API, but you should be in the habit of adding Javadoc comments to your JavaFX code.

Javadocs are a collection of HTML files all linked together to provide easy browsing based off the class structure and Javadoc comments contained by Java code.

Browse around the official JavaFX 8 Javadocs link above to get a feel for what kind of information is placed into Javadocs. All of those Javadocs for the JavaFX 8 project were generated automatically based off Javadoc comments and source code in the JavaFX 8 project.

As you can imagine, keeping the documentation up-to-date for a project as huge as JavaFX 8 shouldn’t be done by hand. It really needs to be automated.

You should make sure that you take advantage of Javadoc comments in your own JavaFX projects. You’re first JavaFX projects won’t be that big or glamorous, but eventually they will be. Getting in the habit now of putting Javadoc comments all over your JavaFX code will save you all kinds of headaches in the future when you have an unwieldy JavaFx codebase that you can’t remember how it all worked without reading through your Javadocs for the project.

A Javadoc comment starts with /** and ends with */. Each line of the comment begins with a *. A standard Javadoc comment looks like this.

/**
 * I am a Javadoc comment.
 * I wish I were in some JavaFX code.
 */

When placed at the beginning of a class definition, a Javadoc comment might look like this.

package com.whatisjavafx;

import javafx.application.Application;
import javafx.stage.Stage;
import javafx.scene.Scene;
import javafx.scene.layout.BorderPane;

/**
 * This is the starting point 
 * of my JavaFX Application.
 * 
 * @author tdavis
 */
public class Main extends Application {
  
  @Override
  public void start(Stage primaryStage) {
    
    try {
      BorderPane root = new BorderPane();
      Scene scene = new Scene(root, 400, 400);
      scene
      .getStylesheets()
      .add(getClass()
          .getResource("application.css")
          .toExternalForm());
      primaryStage.setScene(scene);
      primaryStage.show();
    } catch (Exception e) {
      e.printStackTrace();
    }
    
  }

  public static void main(String[] args) {
    launch(args);
  }
}

 

This is your typical JavaFX project template for a Main class. Notice the @author tag above the JavaFX Application class implementation. The @author tag is commonly used to designate the righter of the class, and is required by many professors and employers. This tag gets carried over to your Javadoc when you generate it from your code.

A couple of other common tags are the @param and the @return tags. They are used for explaining the parameters and the returns from Java methods.

For example, see the following JavaFX Application start() method’s Javadoc.

  /**
   * This is the main method for the JavaFX app.
   * 
   * @param args Standard input arguments.
   * @return Nothing returned.
   */
  public static void main(String[] args) {
    launch(args);
  }

 

You may have already guessed, … Tags start with the @ symbol. You may not have guessed, tags typically require all of their associated information appear on the same line as the tag. Also, the @param tag requires the name of the parameter follow the tag, but come before the comment about the tag.

You can (and should) place the Javadoc comments above important variables, too.

  /**
   * States whether the app has
   * been registered yet.
   */
  public static boolean registered = false;

 

The only thing left to do is generate your Javadocs from your JavaFX code. Traditionally, the javadoc command is issued from the command line to create your Javadocs, but this is so 1900’s. These days, it is more common to set up a Maven task, or generate the Javadocs from your IDE.

In Eclipse, you can generate your Javadocs from a project by going to the File->Export… under the main Eclipse menu. You should get the Export dialog. Just select Generate Javadoc and click next.

Javadoc Export from Eclipse
You can export the Javadocs from your JavaFX applications by choosing Export under the File menu, and then choosing Generate Javadoc.

The actual dialog for exporting your Javadoc should look something like this.

Javadoc Command Needed
Configure your Javadoc export to use the javadoc command found in your Java installation’s bin directory.

If you get a warning stating that Javadoc command is needed, configure it to point at the javadoc command found in your Java installation’s bin directory.

Once you generate the Javadoc for your JavaFX application, you can browse it by double-clicking on the index.html file found in its root directory.

Don’t forget your comments!

Leave a Reply

Your email address will not be published. Required fields are marked *