Transcript Introduction to Javadoc

A brief introduction to
javadoc and doxygen
What’s in a program file?
1.
Comments
2.
Code
What’s a compiler?

A program
Input
 Processing
 Output

What’s 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)
What does a compiler do?

A compiler ignores comments and processes the
code.

What does doxygen (or javadoc) do?
It ignores the code and processes to comments.
 Used to create HTML documentation.

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)?
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)
JAVADOC
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
*/
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;
javadoc-umenting a method
/** ConnectFour ctor for a new game. */
public ConnectFour ( ) {
//add code here to start a new game
}
javadoc-umenting a method w/
parameters
/**
* This method loads a previously saved game from the specified file.
* @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
javadoc-umenting a method w/
parameters & a return value
/**
* This method loads a previously saved game from the specified file.
* @param fileName is the name of the file that contains the
*
previously saved game to load.
* @return true if successful; false otherwise.
*/
private boolean onLoad ( final String fileName ) {
//load a previously saved game
}
//---------------------------------------------------------------------/**
* <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.
javadoc

Complete example:


http://people.sju.edu/~ggrevera/cs2/sample/ConnectFour.java
Result:

http://people.sju.edu/~ggrevera/cs2/sample/index.html
Required documentation rules
1.
Each file, class, method, and member variable
must be documented w/ javadoc.
2.
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!)
Running javadoc
Search for javadoc.exe.
1.

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)
2.
3.
4.

Ex. “c:\Program Files\Java\jdk1.5.0_06\bin\javadoc” –d html –private
ConnectFour.java
Running javadoc via jgrasp
Running javadoc via netbeans
Running javadoc via eclipse