The Sun JDK includes a tool called Javadoc, which generates HTML files based on special comments in Java class files. VisualAge for Java uses the Javadoc tool to make it easy for you to generate online documentation for classes that you create within the IDE.
Note: Documentation for the JDK, the JFC, and some IBM Java Classes is provided in the VisualAge for Java help web. Click on "Reference" in the help banner frame to find links to this documentation.
Adding Comments for Javadoc
When you create a program element in the IDE, a generic comment is generated automatically
for the element. You can customize the comment either in the SmartGuide while you are
creating the element, or by editing the comment in the Source pane for the element.
Javadoc picks up comments that start with /** and end with */, and that are placed immediately before a class, method, or field declaration. You can use Javadoc tags, which start with @, within these delimiters format the comment output. For example, the following code is a Javadoc-style comment and signature for a method, getNameOfEmployee:
/** This method returns the name of the employee for the given employee number. * @param employeeNumber an int indicating the employee number. * @return a String containing the employee's name. * @throws an exception if the employee number is out of range. */ public String getNameOfEmployee(int employeeNumber) throws Throwable { /* code omitted */ }
Add comments of this nature to your own classes, interfaces, and methods. Most Java language reference books, including the JDK documentation, contain detailed information on the tags available for documenting classes with Javadoc. Add regular HTML tags within the text of the comment to format the output text.
If the description of a class or its member changes, make the change in the source rather than in the generated HTML files. Any changes you make to the HTML files will be lost when you regenerate documentation.
Generating the HTML Files
To generate HTML documentation for any class, package, or project:
The generated HTML files link to graphics files in an images directory. If you accepted the default directory for the generated HTML files, then the images are in the right place. If you did not accept the default location, copy the images to the location you specified by doing the following steps:
You may find that some reference links between the HTML files are broken. Broken links occur if you do not generate documentation for a complete set of classes. Ensure the class path includes the path to the classes used by those for which you are generating documentation..
Viewing the Generated Documentation
Open the generated files in an HTML browser. The files tree.html, packages.html,
and AllNames.html, if you generated them, are useful indexes to the contents of the
generated class documentation files. Each class also has its own .html file containing the
formatted documentation for its methods and fields. This .html file is named after the
class and the package that contains the class, in the format package.class.html.
The output for the above example method and its Javadoc comment would appear in an HTML file for the class that contains getNameOfEmployee. A linked index at the top of the file lists all the members, followed by the documentation. The documentation for the method looks similar to the following example:
getNameOfEmployee
public String getNameOfEmployee(int employeeNumber) throws Throwable
This method returns the name of the employee for the given employee number.
- Parameters:
- employeeNumber - an int indicating the employee number.
- Returns:
- a String containing the employee's name.
- Throws:
- an exception if the employee number is out of range.