Introduction to javadoc

What’s in a program file? Comments Code

What’s a compiler? A program Input Processing Output

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)

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-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 }

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.

javadoc Complete example: Result: http://www.sju.edu/~ggrevera/csc1701/sample/ConnectFour.java Result: http://www.sju.edu/~ggrevera/csc1701/sample/index.html

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!)

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

Running javadoc via jgrasp