Introduction to Javadoc

1
Introduction to Javadoc
2
Whats in a program file?

• Comments
• Code

3
Whats a compiler?

• A program
• Input
• Processing
• Output

4
Whats a compiler?

• A program
• Input
• Text file (your program)
• Processing
• Convert HLL statements into machine code (or
  similar)
• Ignore comments
• Output
• A binary file of machine code (or similar)

5
Traditional documentation

• Code files are separate from design documents.
• Wouldnt it be great if we could bring code and
  documentation together into the same file(s)?

6
Tools like Javadoc (and doxygen)

• A program
• Input
• Text file (your program)
• Processing
• Convert (specially formatted) comments into
  documentation
• Ignore HLL statements
• Output
• Documentation (typically in HTML)

7
Javadoc-formatted comments
Note the extra .

• /
• Summary sentence.
• More general information about the
• program, class, method or variable which
• follows the comment, using as many lines
• as necessary.
• zero or more tags to specify more specific
  kinds
• of information, such as parameters and return
• values for a method
• /

8
Javadoc-umenting a variable

• /
• The number of students in the class. This
  variable must not be
• negative or greater than 200.
• /
• public int numStudents
• / represents the game board /
• private int board

9
Javadoc-umenting a method

• / ConnectFour ctor for a new game. /
• public ConnectFour ( )
• //add code here to start a new game

10
Javadoc-umenting a method w/ parameters

• /
• This method loads a previously saved game
  from the specified file.
• _at_param fileName is the name of the file that
  contains the
• previously saved game to load.
• /
• private void onLoad ( final String fileName )
• //load a previously saved game

param tag
11
Javadoc-umenting a method w/ parameters a
return value

• /
• This method loads a previously saved game
  from the specified file.
• _at_param fileName is the name of the file that
  contains the
• previously saved game to load.
• _at_return true if successful false otherwise.
• /
• private boolean onLoad ( final String fileName )
  
• //load a previously saved game

12
Javadoc-umenting a class

• //------------------------------------------------
  ----------------------
• /
• ltpregt
• File name ConnectFour.java
• Author George J. Grevera, Ph.D.
• Date 8/1/2007
• Program/Lab 0
• Detailed description
• This file contains the ConnectFour class
  that implements a game of
• Connect Four.
• Description of the input and output
• Input consists of an optional file that
  contains a previously saved
• game.
• Output consists of an optional file to save
  a game.
• lt/pregt
• /
• //------------------------------------------------
  ----------------------

Note the HTML.
13
Javadoc

• Complete example
• http//www.sju.edu/ggrevera/csc1601/sample/Connec
  tFour.java
• Result
• http//www.sju.edu/ggrevera/csc1601/sample/index.
  html

14
Required documentation rules

• Each file, class, method, and member variable
  must be documented w/ javadoc.
• The contents of the body of each method may and
  should contains comments but none of these
  comments should be in the javadoc format. (Not
  every comment is a javadoc comment.)

15
Running Javadoc

• Search for javadoc.exe.
• Ex. c\Program Files\Java\jdk1.5.0_06\bin\javadoc.
  exe
• Open a command prompt window.
• cd to the folder (directory) where your .java
  files are.
• Run javadoc ( required because of space)
• Ex. c\Program Files\Java\jdk1.5.0_06\bin\javadoc
  d html private ConnectFour.java