Documenting Code in WSAD Using Javadoc

Bibhas Bhattacharya, Web Age Solutions Inc.

Javadoc

Javadoc is a tool shipped with JDK that generates HTML documentation from the comments in the class source files. Insufficient documentation has been a consistent problem in the software industry. With the aid of Javadoc you can simplify documentation of your code and make it a regular habit.

Javadoc Comment Convention

All documentation is written as Java comments. The comment block must start with "/**" and end with "*/". For example:

/**
* @author Bibhas Bhattacharya
*/

Special keywords are entered after the @ sign to supply specific information. For example, @author as shown above.

Your are allowed to have HTML tags in the code. For example:

/**
* @author Bibhas Bhattacharya<BR>
* (C) <a href="http://www.webagesolutions.com">Web Age Solutions Inc.</a>
*/

Documenting the Class

Detail class information (including the author's name as seen above) goes above the class declaration. Here is a complete example.

/**
* Here is a detail description of the class. You can use HTML tags. The
* paragraph and listing tags come handy.
*
* @author Bibhas Bhattacharya<BR>
* (C) <a href="http://www.webagesolutions.com">Web Age Solutions Inc.</a>
*/

public class MyClass {
}

Documenting Member Variables

Add a short and long description of the variable separated by an empty line as shown below.

/**
* A short description.
*
* A long description. This is displayed only in the field detail section.
*/
public String firstName;

Documenting Methods

The long description of a method must be entered within an HTML paragraph tag. Input parameter information is eneterd after a @param Javadoc tag. Here is an example.

/**
* Short description of the method.
*<p>
* More detailed description of the method here.
*</p>
* @param param1 Description of parameter 1.
* @param param2 Description of parameter 2.
* @return Description of the returned object.
* The calculated area.
*/
public double area(double param1, double param2) {
//...
}

Tip: WSAD can automatically generate portion of the method Javadoc for you. You can save time by not having to manually enter the @param or @return tags. Above the method in question, type in /** and then hit enter. WSAD will generate the Javadoc comment. All you have to do is fill in the detail description.

Setup Javadoc in WSAD

Open the preferences window (Window->Preferences). Then select the Java->Javadoc node. Enter the location of the javadoc.exe executable. For example, if you have WebSphere installed, it will be <WAS>\AppServer\java\bin\javadoc.exe.

Generate Javadoc

Right click on a project and select Export. You can also select File->Export from the menubar. Select the Javadoc export type and click on Next. Enter the output directory.

Then click on Finish. It is not entirely a bad idea to export the Javadoc within a docs folder of the project and keep the documentation under version control.

WSAD makes the Javadoc generation easy and reliable by saving the export directory as a part of the project definition. You can view and change it from the project properties.

Conclusion

Writing documentation should be a standard part of software development. Java makes the process more appealing through the Javadoc tool.

Feedback