Lecture 8 Comments and Documentation

1. Lecture 8Comments and Documentation Richard Gesick

2. Comments • Comments explain the program to yourself and others • Block comments • Can span several lines • Begin with /* • End with */ • Compiler ignores all text between /* and */ Example: /* This program will print a message Anderson, Franceschi */

3. SOFTWARE ENGINEERING TIP Include a block comment at the beginning of each source file. It should • identify the author of the program • briefly describe the function of the program

4. Comments Line comments • Start with // • Compiler ignores all text from // to the end of the line Example System.out.println( "Hello" ); // output Hello

5. Javadoc Documentation • The Java class library documentation on Oracle's website (www.oracle.com/technetwork/java) helps us determine how to instantiate objects and call methods for the classes. • This documentation was generated using Javadoc, a tool provided in the Java Development Toolkit (JDK). • We can also use Javadoc to generate web pages that provide documentation on our class's fields and methods.

6. To Use Javadoc • We need to add Javadoc comments and special tags to our classes. • Javadoc comments begin with /** and end with */ (Note that this is similar to a Java block comment, but with an extra * in the opening syntax.) Example: /** Auto class * Anderson, Franceschi */

7. Block Tags Identify parameters and return values HTML tags can be used in the descriptions • For example, <BR> to insert a new line

8. Sample equals Method Documentation /** * equals method:<BR> * Compares the fields of two Auto objects * @param a1 an Auto object * @return true if this object’s fields have * the same values as a1’s fields; * false, otherwise */ public boolean equals( Object a1 ) { // equals method body }

9. Executing Javadoc • javadoc.exe is located in the bin directory of the Java JDK • To generate documentation for a class: javadoc ClassName.java Example: javadoc Auto.java • To generate documentation for all classes in a directory: javadoc *.java

10. Sample Javadoc Documentation

11. Unified Modeling Language