Javadoc and Linked Lists

Javadoc

Oracle Javadoc Tutorial

• Javadoc is the standard way of documenting Java source code
• JDK provides the javadoc tool to turn Javadoc comments into browsable web page (e.g. Java API)
• Classes, variables, methods, and packages can include Javadoc
• Provides a high level view of the code (doesn't just explain what the code does, we can read the code for that)
• All Javadoc comments start with /** and end with */
• Sentences must begin with a capital letter and end with a period.
• The first sentence provides a high-level general overview.
• Later sentences include the details.
• Refer to the instance of a class as this.

Documenting a class

• Describes what the class does at a high level

/**
 * This class stores generic items as a List backed by an array.
 */
public class ArrayList<E> {
  ...
}

Compare the above with the class description of Java's ArrayList.

Documenting instance variables

• Describe at a high level the use of instance variables

public class ArrayList<E> {
  /**
   * Stores the items in this list. 
   *
   * This array is initially set to store 10 items, but as the array fills up, a new array must
   * be created and the contents of the original array must be copied into the new array. Once the
   * the new array has been setup, this array should point to the new array.
   */
  private E[] list;

  ...
}

Documenting methods

• Should provide a high-level overview of the method.
• Document all method parameters with the @param annotation.
• Document what the method returns with the @return annotation.
• Document any exceptions that the method may throw with the @throws annotation.

/** 
 * Inserts the specified element at the specified position in this list.
 *
 * Shifts the element currently at that position (if any) and any subsequent elements to the right (adds one to their indices).
 * @param index Index at which the specified element is to be inserted.
 * @param element Element to be inserted.
 * @throws IndexOutOfBoundsException If the index is out of range (index < 0 || index > size())
public void add(int index, E element) {
  ...
}

/**
 * Returns the number of elements in this list.
 * @return The number of elements in this list.
public int size() {
  ...
}

And more

• See Oracle's Javadoc Tutorial for more information.
• Should everything be documented? Getters? Setters? Constructors? toString?

Generating Javadoc

• Using a command prompt
• Navigate to the directory with your source files
• Run the Javadoc tool

The basic usage of Javadoc is as follows:

javadoc [ options ] [ packagenames ] [ sourcefilenames ] [ -subpackages pkg1:pkg2:... ] [ @argfiles ]

Common options include:

• -author (display author information is generated javadoc)
• -private (display all public, protected, and private methods and members)
• -d (specify where generated documentation will be saved)

Generating Javadoc from Netbeans screencast

Netbeans Javadoc Screencast

Javadoc Activity

• Copy Point.java and Point3D.java from https://github.com/anthonyjchriste/ics211f13/tree/master/src/javadoc
• Write Javadoc for classes, instance variables, and methods
• Be sure to include @param and @return where appropriate
• Create a subdirectory in your source directory called javadoc (mkdir javadoc)
• Generate Javadoc with the following command

javadoc -private -d javadoc/ Point.java Point3D.java

• View the result by opening javadoc/index.html

Activity: Comparing and Contrasting Lists

In your group:

• Come up with a list of pros/cons for array based lists versus node based lists
• Discuss and write up methods assigned to your group
• Pseudo-code should use Java style getters and setters (getNext(), setNext(), getPrev(), setPrev())

Group A

• Provide pseudo-code for adding to an empty list for Linked Lists, Doubly Linked Lists, and Circular Linked Lists
• Discuss Big-O for searching through the three different types of lists
• Discuss Big-O for searching through the three different types of lists in reverse
• Discuss how to avoid searching in an infinite loop on Circular Lists

Group B

• Provide pseudo-code for adding into the middle of Linked Lists, Double Linked Lists, and Circular Linked List
• Discuss the pros/cons and Big-O for the three different list implementations

Group C

• Provide pseudo-code for removing from front and end of Single, Double, and Circular Linked Lists
• Discuss the pro/cons and Big-O for the three different list implementations

Group D

• Provide pseudo-code for removing from the middle of Single, Double, and Circular Linked Lists
• Discuss the pros/cons and Big-O for the three different list implementations