DOCUMENTING CODE IN WEBSPHERE STUDIO APPLICATION DEVELOPER TUTORIAL 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>\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 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. WASKB-009 DOCUMENTING CODE IN WEBSPHERE STUDIO APPLICATION DEVELOPER TUTORIAL was last modified: October 30th, 2018 by admin
DOCUMENTING CODE IN WEBSPHERE STUDIO APPLICATION DEVELOPER TUTORIAL 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>\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 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. WASKB-009 DOCUMENTING CODE IN WEBSPHERE STUDIO APPLICATION DEVELOPER TUTORIAL was last modified: October 30th, 2018 by admin