Appendix J

javadoc Summary

View Combined Slides

javadoc Comments

• javadoc comments are comments
  • So they are ignored by the Java compiler
  • They do not affect how your program runs
     
• They are specially formatted comments
  • The special format is recognized by a separate program called
  • javadoc
     
• javadoc reads the specially formatted comments and
  • produces HTML code that describes your program
  • this HTML code can be read by any Web browser

Format of javadoc Comments

• A javadoc comment is delimited by
  
  /**
  
     Comment
  
  */

• You can comment
  • Classes
  • Methods
  • Instance Fields

Contents of javadoc Comments

• Each comment has a brief description of the Class / Method / Instance Field
   
• Followed by one or more tags
   
  • Each tag starts with the @ character
     
  • The tags we'll use most in this class are
    • @author
    • @param
    • @return
    • @throws
       
  • We'll discuss these tags as we encounter them throughout the class

The @author Tag

• Used to document the author of a class
   
• In this class, you must include the @author tag in each class you write
   
• Example

/**
* This class checks a candidate Sudoku solution to see if it
* is a valid solution. The constructor takes a 9 x 9 array
* of single digit integers representing the candidate
* solution. There is only one public method called isValid()
* that tells if the solution is valid.
*
* @author Kevin Lillis
*
*/

Running javadoc

• Run from the command line
  • From the directory containing your java source files type
    javadoc -link http://java.sun.com/j2se/1.5.0/docs/api -d docdir *.java
     
  • This will create the HTML code in a new folder called docdir
     
• Run from within Netbeans IDE
  • Right click on the project and select Generate Javadoc for Project
  • This will create the HTML code in a new folder called dist\javadoc under the project folder

Viewing the Generated Comments

• Open the file index.html in that is generated by javadoc