Generating HTML Documentation for Classes

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:

  1. Select the class, package, or project.
  2. Select Document, Generate Javadoc from the element's pop-up menu.
  3. In the Directory for Javadoc output field, specify directory for the generated HTML files, if you do not want to use the default provided.
  4. By default, Javadoc generates an .html file that lists links to the documentation for all types, methods, and fields. Clear the Generate package index check box if you do not want this file to be generated.
  5. By default, it also generates a file that shows the class hierarchy for the classes in the generated documentation, with links to each class. Clear the Generate type hierarchy check box if you do not want this file to be generated.
  6. Select which methods you want to generate documentation for, based on access level. Choose one of the following options:
  7. Click OK. The HTML files are generated in the specified directory.

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:

  1. Create a directory called "images" in the directory you specified for the HTML files.
  2. If you installed VisualAge for Java in C:\IBMVJava (the default location), go to C:\IBMVJava\ide\javadoc\images
  3. Copy the files from this location to the new images directory.

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.