1. A brief introduction to javadoc and doxygen

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

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

4. 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)

5. 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.

6. 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)?

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

8. JAVADOC

9. 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 *.

10. 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;

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

12. 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. * @param fileName is the name of the file that contains the * @param 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

13. 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. * @param fileName is the name of the file that contains the * @param fileName is the name of the file that contains the * previously saved game to load. * previously saved game to load. * @return true if successful; false otherwise. * @return true if successful; false otherwise. */ */ private boolean onLoad ( final String fileName ) { //load a previously saved game //load a previously saved game}

14. //----------------------------------------------------------------------/** * * * 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.

15. javadoc Complete example: Complete example: http://people.sju.edu/~ggrevera/cs2/sample/ConnectFour.java http://people.sju.edu/~ggrevera/cs2/sample/ConnectFour.java http://people.sju.edu/~ggrevera/cs2/sample/ConnectFour.java Result: Result: http://people.sju.edu/~ggrevera/cs2/sample/index.html http://people.sju.edu/~ggrevera/cs2/sample/index.html http://people.sju.edu/~ggrevera/cs2/sample/index.html

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

17. 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

18. Running javadoc via jgrasp

19. Running javadoc via netbeans

20. Running javadoc via eclipse