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=”https://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=”https://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>AppServerjavabinjavadoc.exe.
GENERATE JAVADOC
Right click on a project and select Export. You can also select File->Export from the menubar. Select the Javadocexport 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.