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.)
|
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:
- If you are attributing your code and using the XML file output by dbl2xml to populate the SMC, include the comment text for methods, return values, and parameters in your Synergy source files. See Documentation comments.
- If you are using the MDU to populate the SMC, include the comment text in the description fields in the MDU as you define your methods. There are fields for specifying method description, return value description, and parameter description. (See Creating new methods and Defining parameters for instructions on entering data in these fields.)
- Edit the generated source files (.java files) to add Javadoc comments or to add additional formatting tags to create the desired output. This method is not recommended, because any changes you make to the .java files will be lost if you regenerate class wrappers. See To manually add Javadoc comments for instructions.
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). |
