From: Subject: Horstmann Appendix J - javadoc Summary Date: Sun, 4 Nov 2007 13:08:15 -0700 MIME-Version: 1.0 Content-Type: multipart/related; type="text/html"; boundary="----=_NextPart_000_0000_01C81EE3.C2A21230" X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3198 This is a multi-part message in MIME format. ------=_NextPart_000_0000_01C81EE3.C2A21230 Content-Type: text/html; charset="Windows-1252" Content-Transfer-Encoding: quoted-printable Content-Location: http://web.sau.edu/LillisKevinM/csci195/2007Fall/slides/appJ/appJ.html Horstmann = Appendix J - javadoc Summary

Appendix J

javadoc Summary

javadoc Comments

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

Format of javadoc Comments

  • A javadoc comment is delimited by=20

    /**

       Comment

    */     =
  • You can comment
    • Classes=20
    • Methods=20
    • Instance Fields

Contents of javadoc Comments

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

The @author Tag

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

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

Running javadoc

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

Viewing the Generated Comments

  • Open the file index.html in that is generated by=20 javadoc
------=_NextPart_000_0000_01C81EE3.C2A21230 Content-Type: text/css; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Location: http://web.sau.edu/LillisKevinM/csci195/2007Fall/195.css BODY { BACKGROUND-COLOR: #ccdff2 } H1 { COLOR: #0000cc } H2 { COLOR: #6633ff } H3 { COLOR: #3366ff } ------=_NextPart_000_0000_01C81EE3.C2A21230 Content-Type: text/css; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Location: http://web.sau.edu/LillisKevinM/csci195/2007Fall/slides/slides.css .code { WIDTH: 90%; HEIGHT: 600px } SPAN.kem { FONT-WEIGHT: bold; COLOR: #0000ff; FONT-STYLE: italic } .codeSmall { WIDTH: 90%; HEIGHT: 400px } .codeSplit { WIDTH: 100%; HEIGHT: 600px } ------=_NextPart_000_0000_01C81EE3.C2A21230--