A brief A brief introduction to introduction to

javadoc and javadoc and doxygendoxygen

What’s in a program file?What’s in a program file?

1.1. CommentsComments

2.2. CodeCode

What’s a compiler?What’s a compiler?

A programA program InputInput ProcessingProcessing OutputOutput

What’s a compiler?What’s a compiler?

A programA program Input:Input:

Text file (your program)Text file (your program) Processing:Processing:

Convert HLL statements into machine code Convert HLL statements into machine code (or similar)(or similar)

Ignore commentsIgnore comments Output:Output:

A binary file of machine code (or similar)A binary file of machine code (or similar)

What does a compiler What does a compiler do?do?

A compiler ignores comments and A compiler ignores comments and processes the code.processes the code.

What does doxygen (or javadoc) do?What does doxygen (or javadoc) do? It ignores the code and processes to It ignores the code and processes to

comments.comments. Used to create HTML documentation.Used to create HTML documentation.

Traditional Traditional documentationdocumentation

Code files are separate from design Code files are separate from design documents.documents.

Wouldn’t it be great if we could Wouldn’t it be great if we could bring code and documentation bring code and documentation together into the same file(s)?together into the same file(s)?

Tools like javadoc and Tools like javadoc and doxygendoxygen

A programA program Input:Input:

Text file (your program)Text file (your program) Processing:Processing:

Convert (specially formatted) comments Convert (specially formatted) comments into documentationinto documentation

Ignore HLL statementsIgnore HLL statements Output:Output:

Documentation (typically in HTML)Documentation (typically in HTML)

JAVADOCJAVADOC

javadoc-formatted javadoc-formatted commentscomments

/**/** * 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 javadoc-umenting a variablevariable

/**/**

* The number of students in the class. This * The number of students in the class. This variable must not bevariable must not be

* negative or greater than 200.* negative or greater than 200.

*/*/

public int numStudents; public int numStudents;

/** represents the game board *//** represents the game board */

private int[][] board;private int[][] board;

javadoc-umenting a javadoc-umenting a methodmethod

/** ConnectFour ctor for a new game. /** ConnectFour ctor for a new game. */*/

public ConnectFour ( ) {public ConnectFour ( ) {

//add code here to start a new //add code here to start a new gamegame

}}

javadoc-umenting a method javadoc-umenting a method w/ parametersw/ parameters

/**/** * This method loads a previously saved game from * This method loads a previously saved game from

the specified file.the specified file. * @param fileName is the name of the file that * @param fileName is the name of the file that

contains thecontains the * previously saved game to load.* previously saved game to load. */*/private void onLoad ( final String fileName ) {private void onLoad ( final String fileName ) { //load a previously saved game//load a previously saved game}}

param tag

javadoc-umenting a method javadoc-umenting a method w/ parameters & a return w/ parameters & a return

valuevalue /**/** * This method loads a previously saved game from * This method loads a previously saved game from

the specified file.the specified file. * @param fileName is the name of the file that * @param fileName is the name of the file that

contains thecontains 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 ) {private boolean onLoad ( final String fileName ) { //load a previously saved game//load a previously saved game}}

//----------------------------------------------------------------------//----------------------------------------------------------------------/**/** * <pre>* <pre> * File name:* File name: ConnectFour.javaConnectFour.java * Author:* Author: George J. Grevera, Ph.D.George J. Grevera, Ph.D. * Date:* Date: 8/1/20078/1/2007 * Program/Lab #:* Program/Lab #: 00 ** * 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.* </pre>* </pre> */*///----------------------------------------------------------------------//----------------------------------------------------------------------public class ConnectFour {public class ConnectFour { /** represents the game board *//** represents the game board */ private int[][] board;private int[][] board;……

javadoc-umenting javadoc-umenting a classa class

Note the HTML.

javadocjavadoc

Complete example:Complete example: http://people.sju.edu/~ggrevera/cs2/sample/Connect

Four.java

Result:Result: http://people.sju.edu/~ggrevera/cs2/sample/index.ht

ml

Required documentation Required documentation rulesrules

1.1. Each file, class, method, and member Each file, class, method, and member variable variable mustmust be documented w/ be documented w/ javadoc.javadoc.

2.2. The contents of the body of each The contents of the body of each method may and should contains method may and should contains comments, but comments, but nonenone of these comments of these comments should be in the javadoc format. (Not should be in the javadoc format. (Not every comment is a javadoc comment!)every comment is a javadoc comment!)

Running javadocRunning javadoc

1.1. Search for javadoc.exe.Search for javadoc.exe. Ex. c:\Program Files\Java\jdk1.5.0_06\bin\javadoc.exeEx. c:\Program Files\Java\jdk1.5.0_06\bin\javadoc.exe

2.2. Open a command prompt window.Open a command prompt window.

3.3. cd to the folder (directory) where cd to the folder (directory) where your .java files are.your .java files are.

4.4. Run javadoc (“” required because of Run javadoc (“” required because of space)space)

Ex. “c:\Program Files\Java\jdk1.5.0_06\bin\javadoc” –d Ex. “c:\Program Files\Java\jdk1.5.0_06\bin\javadoc” –d html –private ConnectFour.javahtml –private ConnectFour.java

Running javadoc via Running javadoc via jgraspjgrasp

Running javadoc via Running javadoc via netbeansnetbeans

Running javadoc via Running javadoc via eclipseeclipse