A brief introduction to javadoc and doxygen

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

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

What’s a compiler? A program A program Input: Input: Text file (your program) Text file (your program) Processing: Processing: Convert HLL statements into machine code (or similar) Convert HLL statements into machine code (or similar) Ignore comments Ignore comments Output: Output: A binary file of machine code (or similar) A binary file of machine code (or similar)

What does a compiler do? A compiler ignores comments and processes the code. A compiler ignores comments and processes the code. What does doxygen (or javadoc) do? What does doxygen (or javadoc) do? It ignores the code and processes to comments. It ignores the code and processes to comments. Used to create HTML documentation. Used to create HTML documentation.

Traditional documentation Code files are separate from design documents. 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)? 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 A program Input: Input: Text file (your program) Text file (your program) Processing: Processing: Convert (specially formatted) comments into documentation Convert (specially formatted) comments into documentation Ignore HLL statements Ignore HLL statements Output: Output: Documentation (typically in HTML) Documentation (typically in HTML)

JAVADOC

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

javadoc-umenting a variable /** * The number of students in the class. This variable must not be * The number of students in the class. This variable must not be * negative or greater than 200. * 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. */ /** ConnectFour ctor for a new game. */ public ConnectFour ( ) { public ConnectFour ( ) { //add code here to start a new game //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. * This method loads a previously saved game from the specified file. fileName is the name of the file that contains the fileName is the name of the file that contains the * previously saved game to load. * previously saved game to load. */ */ private void onLoad ( final String fileName ) { //load a previously saved game //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. * This method loads a previously saved game from the specified file. fileName is the name of the file that contains the fileName is the name of the file that contains the * previously saved game to load. * previously saved game to load. true if successful; false otherwise. true if successful; false otherwise. */ */ private boolean onLoad ( final String fileName ) { //load a previously saved game //load a previously saved game}

// /** * * * File name:ConnectFour.java * File name:ConnectFour.java * Author:George J. Grevera, Ph.D. * Author:George J. Grevera, Ph.D. * Date:8/1/2007 * Date:8/1/2007 * Program/Lab #:0 * Program/Lab #:0 * * Detailed description: * Detailed description: * This file contains the ConnectFour class that implements a game of * This file contains the ConnectFour class that implements a game of * Connect Four. * Connect Four. * * Description of the input and output: * Description of the input and output: * Input consists of an optional file that contains a previously saved * Input consists of an optional file that contains a previously saved * game. * game. * Output consists of an optional file to save a game. * Output consists of an optional file to save a game. * * */ */// public class ConnectFour { /** represents the game board */ /** represents the game board */ private int[][] board; private int[][] board;… javadoc-umenting a class Note the HTML.

javadoc Complete example: Complete example: Result: Result:

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 1. Search for javadoc.exe. Ex. c:\Program Files\Java\jdk1.5.0_06\bin\javadoc.exe Ex. c:\Program Files\Java\jdk1.5.0_06\bin\javadoc.exe 2. Open a command prompt window. 3. cd to the folder (directory) where your.java files are. 4. Run javadoc (“” required because of space) Ex. “c:\Program Files\Java\jdk1.5.0_06\bin\javadoc” –d html –private ConnectFour.java 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