Lab 5: Generating Documentation with javadoc

Instructions: Follow the steps given in each section below. For each question, click the radio button next to the most correct answer. When you are finished, type your name and your password at the end of the document, print a copy for your records, then press the Submit button. You may submit just one lab response. If you submit more than one, only the first one counts for a grade.

Contents

A. Purpose

The purpose of this lab is to learn how to automatically generate documentation from a Java program. By the end of this lab, you should be able to put documentation comments in your programs so that javadoc can automatically generate documentation for you.

Note: This lab assumes use of javadoc from Sun's JDK 1.4.1.

B. Program Documentation

  1. In your programming assignments so far, you've probably including these kinds of documentation:

    • A header comment at the beginning of the program file, containing your name, the date, the course, and a brief description of the program

    • A comment before each class, describing the purpose of the class

    • A comment before each method, describing the purpose of the method

  2. These comments are certainly good -- they help someone else understand how your program works. However, they suffer from some disadvantages:

    • The comments are buried in the program. If someone wants to use your program without looking at the code, they can't. We should provide some documentation, outside of the source code, for people to refer to when they want to incorporate our classes in their programs. In other words, we need to provide adequate information to our client programmers so that they will know how to correctly use our classes.

    • The comments describe what the program does, in general terms, but they often don't describe the parameters and return values -- in other words, how to use each method.

    • The comments aren't organized in any meaningful way (except that they are close to their respective methods and classes).

    • The comments are not in a printable form.

    • The comments are not searchable electronically.

    • The comments are in the program code with the same font as the program code -- probably not very pleasing to look at.

  3. We could certainly extract these comments from a program and copy them into a word processing program. We could then print the comments or make HTML documents out of them. However, this is a lot of manual work, and if the comments change in the program, we must do this work all over again.

  4. Fortunately, Sun's JDK has a spiffy little program called javadoc that makes all these problems disappear (well, maybe not completely, but almost...). The javadoc program extracts information from your program, including specially-formatted comments, and formats a set of HTML pages from this information. Sun generated all of the standard Java documentation using javadoc, for example.

  5. Let's see how to use javadoc.

C. Using javadoc

  1. You can use javadoc to produce documentation for any Java program. DemonstrateArrayStack.java below is an example program you can use with javadoc.

    DemonstrateArrayStack.javaDownload (Help)
    // Demonstration of how to use stacks in a program

import java.util.Stack;

// Our own stack class, uses a fixed-sized array, no error-checking
class ArrayStack
{
  public boolean empty()
  {
    return top == 0;
  }

  public void push(Object value)
  {
    data[top] = value;
    top++;
  }

  public Object pop()
  {
    top--;
    return data[top];
  }

  public Object peek()
  {
    return data[top];
  }
  
  private int top = 0;  
  private Object[] data = new Object[100];
}

public class DemonstrateArrayStack
{
  // Test the stack classes
  public static void main(String[] args)
  {
    // Here's how to use the ArrayStack class ...
    ArrayStack myStack = new ArrayStack();

    myStack.push("Hello");
    myStack.push(new Character('x'));
    myStack.push(new Integer(123));
    myStack.push(new Double(3.45));

    System.out.print(myStack.pop() + " ");
    System.out.print(myStack.pop() + " ");
    char character = ((Character) myStack.pop()).charValue();
    System.out.print(character + " ");
    System.out.print(myStack.pop() + " ");

    // ... and here's how to use Java's standard Stack class
    // (it's almost exactly the same)
    Stack javaStack = new Stack();
    
    javaStack.push("Hello");
    javaStack.push(new Character('x'));
    javaStack.push(new Integer(123));
    javaStack.push(new Double(3.45));

    System.out.print(javaStack.pop() + " ");
    System.out.print(javaStack.pop() + " ");
    character = ((Character) javaStack.pop()).charValue();
    System.out.print(character + " ");
    System.out.println(javaStack.pop());
  }
}
    DemonstrateArrayStack.javaDownload (Help)

  2. Download DemonstrateArrayStack.java, then compile and run the program to see what it displays.

    Question
    1
    		What does DemonstrateArrayStack.java display when it runs?
    1. 3.45 123 x Hello
    2. 3.45 123 x Hello 3.45 123 x Hello
    3. (it stops with a run-time error)
    4. Hello x 123 3.45 Hello x 123 3.45
    5. 3.45 123 x Hello 3.45 123 x Hello 3.45 123 x Hello

  3. To use javadoc on this program, type this at the command-line prompt: 

    javadoc DemonstrateArrayStack.java

    Question
    2
    		You should see several messages appear when you run javadoc. Which of the following is not a message that javadoc displays?
    1. Building index for all the packages and classes...
    2. Building tree for all the packages and classes...
    3. Loading source file DemonstrateArrayStack.java...
    4. Generating contents page...
    5. Constructing Javadoc information...

D. Viewing the Output of javadoc

  1. You can look at the output of javadoc in a browser, such as Netscape Navigator or Microsoft Internet Explorer. Use the File|Open command to open the file on your disk drive. Browse to the directory or folder containing DemonstrateArrayStack.java, then open the file index.html. This file shows the public classes in the file DemonstrateArrayStack.java.

    Question
    3
    		How many classes (other than Object) does the file index.html show?
    1. 4
    2. 1
    3. 23
    4. 3
    5. 2

  2. You can click on a class name (in the left pane) to view the documentation for that class. Click on DemonstrateArrayStack. You should see the methods for DemonstrateArrayStack. (You may need to scroll down the page.)

    Question
    4
    		How many methods appear in the documentation for DemonstrateArrayStack?
    1. 1
    2. 3
    3. 23
    4. 2
    5. 4

  3. Notice that class ArrayStack is not included in the documentation. By default, javadoc only includes public (and protected) classes and methods in its documentation. This is probably what you want if you are providing documentation for others so they can use your classes. However, you may want to document all classes and methods. To do this, use the -private switch on the javadoc command, like this. 

    javadoc -private DemonstrateArrayStack.java

  4. Leave the browser running, and run the javadoc program again. To update the browser's contents, press the Reload or Refresh button at the top of the browser window. Browse to the index.html file, if the browser isn't there already. (You may need to reload this file.) You should see an entry for the classes DemonstrateArrayStack and ArrayStack.

    Question
    5
    		In the ArrayStack documentation, which appears first?
    1. Method Summary
    2. Constructor Summary
    3. Field Summary
    4. Method Detail
    5. Field Detail

E. Adding Class Comments to the Documentation

  1. Notice that javadoc does not include any comments from DemonstrateArrayStack.java in any of its generated documentation. That's because javadoc looks for specially-formatted comments, and only includes those. A javadoc comment begins with /** and ends with */. For example, here is a javadoc comment. 

    /**
 * This is a javadoc comment.
 * It is on two lines.
*/

  2. This example shows the most common way to format javadoc comments, with the /** and */ symbols on separate lines. All other lines begin with an asterisk lined up under the first asterisk in /**.

  3. javadoc only includes javadoc comments that are just before a class, a method, or a variable in a class. javadoc ignores all other javadoc comments. For example, here's how to put a javadoc comment in DemonstrateArrayStack.java for the ArrayStack class. 

    // Demonstration of how to use stacks in a program

    
import java.util.Stack;

    
/**
 * Our own stack class, uses a fixed-sized array, no error-checking
 */
class ArrayStack
{
  // ...

  4. Note that the javadoc comment for ArrayStack appears immediately before the class. If we put the comment before the import statement, javadoc will ignore the comment.

  5. Change the comment before class ArrayStack to a javadoc comment, as shown in the example. Run javadoc on DemonstrateArrayStack.java again. (Remember to use the -private switch.) Reload the documentation for ArrayStack into the browser.

    Question
    6
    		Where does the comment appear in the documentation?
    1. Right after class ArrayStack extends java.lang.Object
    2. Just after the Field Summary listing
    3. At the bottom of the documentation
    4. In the heading for the class (in bold)
    5. In the browser's title bar

F. Adding Method Comments to the Documentation

  1. Another place we can include javadoc comments is just before a method. Here's an example. 

    class ArrayStack
{
  /**
   * Tells whether the stack is empty
   */
  public boolean empty()
  {
    return top == 0;
  }

  2. Before you run javadoc with this example, let's make the comment a little more useful to a reader. We'll include a special tag that tells the reader what kind of information this method returns. Tags begin with the @ symbol. The two most common tags for methods are @return and @param. These tags must appear at the beginning of a line.

G. The @return Tag

  1. The @return tag tells the reader what kind of information the method returns. In the case of the empty method, it returns true if the stack is empty, and false otherwise. Here's how to add this tag to the empty() method. 

    class ArrayStack
{
  /**
   * Tells whether the stack is empty
   * @return true if the stack is empty, false otherwise
   */
  public boolean empty()
  {
    return top == 0;
  }

  2. Add this javadoc comment to the empty() method, run javadoc, and reload the ArrayStack documentation in the browser.

    Question
    7
    		How does the return information appear in the documentation?
    1. After the words Method return (in bold)
    2. After the words Return value (in bold)
    3. After the word Returns: (in bold)
    4. After the word Return (not in bold)
    5. By itself (no heading)

H. The @param Tag

  1. The empty() method doesn't have any parameters, so we shouldn't use the @param tag with it. The next method, push() takes one parameter, so let's add a javadoc comment with a @param tag to it. Here's how. 

      /**
   * Puts the given value on the top of the stack
   * @param value The object to push on the stack (can be any object)
   */
  public void push(Object value)
  {
    data[top] = value;
    top++;
  }

  2. Notice that after @param, we list the name of the parameter and then a descriptive comment for that parameter.

  3. Add this javadoc comment to the push() method, run javadoc, and reload the ArrayStack documentation in the browser.

    Question
    8
    		What symbol appears between the name of the parameter (value) and the descriptive comment in the javadoc documentation?
    1. A tab
    2. A colon (:)
    3. A comma (,)
    4. A dash (-)
    5. A space

  4. If there are more than one parameter, we list each on a separate line. Some methods may also return a value -- we simply put a @return tag for that as well. Here's an example. 

    /**
 * Adds two numbers together
 * @param firstValue The first value to add
 * @param secondValue The second value to add
 * @return The sum of the two parameters, as an integer
*/
public int add(int firstValue, int secondValue)
{
  return firstValue + secondValue;
}

  5. Add this method and its javadoc comment, run javadoc, and reload the ArrayStack documentation in the browser.

    Question
    9
    		Does it matter whether you put the @param tags before or after the @return tag in the javadoc comment?
    1. Yes, if the @param tags appear first, they are listed before the return value in the documentation. If the @param tags appear after @return, they are listed after the return value in the documentation.
    2. Yes, it is an error to put @return before the two @param tags
    3. Yes, it is an error to put @return between the two @param tags
    4. Yes, the return value is listed as a parameter if it is not at the end
    5. No, the documentation comes out the same no matter what order the tags appear in the comment

I. For More Information

For more information about javadoc, visit Sun's home page at http://www.sun.com.

Turn in this Assignment

First name:
Last name:
Partner's last name:

Write down your answers for your records, then press the Submit button below to turn in the lab assignment.