Java Programming Classes Instructor: Greg ShawCOP 2210 and 3337 Java “Documentation Comments”I. DefinitionThe somewhat redundant term “documentation comments” refers to aspecial kind of documentation that appears immediately before theclass definition and before each method definition in a class. Thejavadoc utility program uses these comments to generate a neat set ofHTML "help" pages for that class. These HTML pages have the sameformat as the official Java language documentation from SunMicrosystems.II. General Rules for Java Documentation Comments1. Documentation comments begin with the symbol /** and end withthe symbol */. They may encompass any number of lines, and theopening and closing symbols should begin in the same column.2. Each documentation comment immediately precedes the class ormethod that it documents.3. Every public class and method should be documented.4. The first few sentences of each documentation comment will becopied by javadoc to an HTML summary table. This text shouldsuccinctly describe the purpose of the class or method beingdocumented, and each sentence should begin with a capitalletter, end with a period, and be reasonably close togrammatically correct.III. Class Documentation CommentsClass documentation should succinctly describe the purpose of theclass. What real-world object does it model?IV. Method Documentation Comments1. Method documentation should also begin with a summary sentenceor two describing the purpose of the method. What objectbehavior does it implement?2. There is also a special syntax for documenting the method'sparameters and return value (if the method returns a value):@param name description name is the exact name of the method parameter anddescription is a brief description of the value it represents each @param comment starts a new line within thedocumentation comment block every method parameter should be documented@return description description tells exactly what is returned by the method every method that returns a value should have an @returncomment You should write the documentation comments for each methodbefore you write the method implementation. Begin with just the comment block, and a method "stub." Amethod stub is just the method heading, followed by an"empty" method body (i.e., nothing between the opening andclosing braces). (This way, the program “skeleton” will still compile and run,and you can complete and test each method separately.) If you are unable to properly document a method, then you donot yet understand what that method is supposed to do, andyou are not ready to begin implementing it! V. Etc. Failure to document a class, method, parameter, or return valuewill leave embarrassing blank spaces in the HTML pages generatedby javadoc See the online document "Using the javadoc Utility in NetBeans"for instructions on how to create the HTML documentation pagesonce you have properly documented each class For examples of classes with proper javadoc documentationcomments, see any of the programs on the class web
View Full Document