Espresso: A Concentrated Introduction to Java

Laboratory: Javadoc

Summary: In this laboratory, you will begin working Javadoc, the primary documentation tool for Java

Contents

• Exercises
  • Exercise 0: Preparation
  • Exercise 1: Generic Documentation
  • Exercise 2: Adding Introductory Javadoc Comments
  • Exercise 3: Documenting Methods
  • Documenting Fields and Constants
  • Exercise 5

Exercises

Exercise 0: Preparation

You need not create a new package for this laboratory! You should, however, start Eclipse.

a. If you have not already done so, create a directory named /home/username/public_html. Share that directory with

chmod a+x /home/username
chmod a+rx /home/username/public_html
chmod u+w /home/username/public_html

b. Within that directory, create a new directory for your Javadoc documentation. I'd recommend that you call that directory Documentation.

c. Share that directory with

chmod a+rx /home/username/public_html/Documentation
chmod u+w /home/username/public_html/Documentation

Exercise 1: Generic Documentation

a. Make the Documentation directory from step 0 your current working directory.

b. In Eclipse, select your Code project.

c. From the Project menu, select Generate Javadoc ....

d. In the dialog box that appears, enter the following for the command:

/opt/jdk1.5.0/bin/javadoc

e. In the protection radio buttons, select private.

f. In the Destination field, enter

/home/username/public_html/Documentation

g. Click Next. You should then have the opportunity to configure Javadoc arguments for the standard doclet.

h. You need not change any of the standard arguments. Click Next again.

i. You then have the opportunity to configure additional Javadoc arguments. Enter the following

-tag pre:m:"Preconditions" 
-tag post:m:"Postconditions"

j. Observe what files were created in the current directory (and the directories below).

k. Point your Web browser to http://www.cs.grinnell.edu/~username/Documentation/. What do you see?

Exercise 2: Adding Introductory Javadoc Comments

a. Add an introductory Javadoc comment (directly above the class declaration) to your username.IO class. It should read something like the following:

/**
 * A collection of fields and methods to simplify input and output.
 *
 * @author YOUR NAME HERE
 * @version NNN of DATE
 */

b. Regenerate the Javadoc (using the steps in Exercise 1).

c. Determine the effects of the change you've made.

Exercise 3: Documenting Methods

In your IO class, you should have a method that reads integers, presumably called readInt. Document that method and check your results. Here is some sample documentation.

        /**
         * Read an integer from eyes, printing an (optional) prompt to
         * pen.  If the prompt is null, does not print the prompt.
         *
         * @param eyes
         *   The location from which the integer is read.
         * @param pen
         *    The output to which output is sent.
         * @param prompt
         *   The prompt to print.  If null, does not print.
         * @return
         *   i, the value read.
         * @exception IOException
         *   If there is difficulty reading information.
         * @exception NumberFormatException
         *   If the user enters something that cannot be interpreted
         *   as a number.
         * @pre
         *   If prompt is not null, then pen is available for writing.
         * @pre
         *   eyes is available for reading.
         * @post
         *   Input has been read from eyes.
         * @post
         *   i corresponds to the number entered by the user.
         */

Documenting Fields and Constants

a. Make sure that your IO class has at least one static field and at least one constant. If you lack fields and constants, here are some you might want to add

private static long badInputs;
public static final BufferedReader keyboard =
  new BufferedReader(new InputStreamReader(System.in));
public static final PrintWriter screen =
  new PrintWriter(System.out, true);

b. Enter a Javadoc-style comment for each explaining its purpose. For example

/** A count of the number of times the user entered 'bad' input. */
public static long badInputs;
/** The keyboard, represented as a BufferedReader. */
public static final BufferedReader keyboard =
  new BufferedReader(new InputStreamReader(System.in));
/** The screen, represented as a PrintWriter. */
public static final PrintWriter screen =
  new PrintWriter(System.out, true);

c. Rebuild the Javadoc and determine the effects of those changes.

Exercise 5

Complete the documentation for IO and MyMath.

>

History

Thursday, 24 February 2005 [Samuel A. Rebelsky]

• Created

Monday, 20 February 2006 [Samuel A. Rebelsky]

• Updated to use Eclipse and to remove dependency on the classes lab. (Okay, basically rewritten from scratch.)