1. Introduction to javadoc

2. What’s in a program file?
Comments
Code

3. What’s a compiler?
A program
Input
Processing
Output

4. What’s a compiler? A program Input: Processing: Output:
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.
Wouldn’t 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.
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.
fileName is the name of the file that contains the
* previously saved game to load.
true if successful; false otherwise. */
private boolean onLoad ( final String fileName ) {
//load a previously saved game }

12. javadoc-umenting a class//
/**
* <pre>
* 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.
* </pre> */
public class ConnectFour {
/** represents the game board */
private int[][] board; …
javadoc-umenting a class
Note the HTML.

13. javadoc Complete example: Result:
Result:

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. Open a command prompt window.
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

16. Running javadoc via jgrasp