Training

WASKB009 - Documenting code in WebSphere Studio Application Developer Tutorial

Popular Courses

Browse Our Free Resources

  • whitepapers
  • whitepapers
  • webinars
  • blogs

Our Locations

Training Centres

Vancouver, BC
Calgary, AB
Edmonton, AB
Toronto, ON
Ottawa, ON
Montreal, QC
Hunt Valley
Columbia

locations map

Calgary

550 6th Av SW
Suite 475
Calgary, AB
T2P 0S2

Toronto

821A Bloor Street West
Toronto, ON
M6G 1M1

Vancouver

409 Granville St
Suite 902
Vancouver, BC
V6C 1T2

U.S. Office

436 York Road
Suite 1
Jenkintown, PA
19046

Other Locations

Dallas, TX
Miami, FL

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


Email Address: *


Very useful Somewhat useful Not bad Needs many corrections


Comments:
*


( * ) = mandatory field