Generating Javadoc

Javadoc can be helpful for the Java developer who uses your JAR file. Javadoc is constructed from comments in the source files. To create Javadoc for your JAR file, you will need to do the following:

1. Add documentation comments for methods, return values, and parameters. See To add documentation comments to your source files and To manually add Javadoc comments.

We include comments for the xfNetLink Java utility methods in every class, but you must provide a description for each of your user-defined methods if you want to produce useful documentation.

2. Select the “Generate Javadoc” option in Workbench or use the genjava -j option when you generate classes.

The generated classes include the Javadoc tags (e.g., @param) regardless of whether you have specified that you want to produce Javadoc. When you select “Generate Javadoc” or use the genjava -j option, a command to create Javadoc is added to the batch file. (The batch file is run either manually or from Workbench to create the JAR file.)

Note

xfNetLink Java uses the standard Javadoc utility included in the Java Development Kit to produce basic documentation that includes all the public methods in the JAR file. Should you wish to produce more elaborate Javadoc, do not use the “Generate Javadoc” or genjava -j option. Instead, run the Javadoc utility separately. See the Javadoc section of the Oracle website for more information: www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.htm.

To add documentation comments to your source files

Do one of the following:

The descriptions in the SMC are included in the generated files as Javadoc comments when you generate class wrappers. If a method does not have a description in the SMC, a “To Do” comment is inserted in the generated file, as shown in To manually add Javadoc comments below. If a return value description is not provided in the SMC, the return data type is used as the Javadoc comment. If a parameter description is not provided in the SMC, the parameter name, Java data type, and direction passed are used as the Javadoc comment.

For structures passed as parameters, the field descriptions in the repository are used as the Javadoc comments for the set and get property methods in the generated classes. The description text from the repository is preceded with either “Sets” or “Gets”. If a field does not have a description in the repository, “Sets the property value” and “Gets the property value” are used as the Javadoc comments.

Several Javadoc HTML files will be produced when you build the JAR file. In the package directory, there will be an index file and three other “navigation” files. In a subdirectory within the package directory, there will be files for each of the classes. See Setting up your environment for development for information on making the Javadoc files available to your Java developers.

To manually add Javadoc comments

1. Open the .java file(s) and find the “To Do” comments. There is a “To Do” comment before every user-defined method for which there was no description text provided in the SMC.
2. Replace the line that reads “***To Do*** Add method description” with a description of the method. Edit the comments for the @param and @return tags if desired. In structure classes, edit the descriptions for the set and get methods if desired.
3. Save the .java file(s).