Javadoc

When we wrote our first example that used the Basketball class, we didn't actually have to read the code to figure out how to use it. We just looked at the documentation. The designers of Java made it very easy to embed documentation directly into the code we write and produce nice looking webpages like you saw for the String class. This documentation is called Javadoc.

Examine the modified class below and notice how we've inserted documentation between /** and */ for every primitive, method, and the class as a whole. These are called javadoc comments. Special keywords @param and @return help us clearly describe the interface for the methods.

package lab2;
/**
 * Model of a basketball for use in quality control simulations.
 */
public class Basketball
{
  /**
   * Inflation status of this Basketball.
   */
  private boolean isInflated;

  /**
   * Diameter of this Basketball.
   */
  private double diameter;

  /**
   * Constructs an uninflated Basketball with the given diameter.
   * @param givenDiameter
   *   the diameter for this Basketball
   */
  public Basketball(double givenDiameter)
  {
    isInflated = false;
    diameter = givenDiameter;
  }

  /**
   * Inflates this Basketball.
   */
  public void inflate()
  {
    isInflated = true;
  }

  /**
   * Returns the diameter of this Basketball.
   * @return
   *   diameter of this Basketball
   */
  public double getDiameter()
  {
    return diameter;
  }

  /**
   * Determines whether this Basketball can be dribbled.
   * @return
   *   true if the basketball is inflated, false otherwise
   */
  public boolean isDribbleable()
  {
    // can be dribbled only if it is inflated
    return isInflated;
  }

  /**
   * Returns the circumference of this Basketball.
   * @return
   *   circumference of this Basketball
   */
  public double getCircumference()
  {
    // PI times the diameter
    double result = Math.PI * diameter;
    return result;
  }
}

You may think we've just made our code look very bloated. This class is so simple that there are more lines of documentation than code! But it is easy to imagine that if you are trying to use a more complex class, such as String, you don't want to have to read all the code just to find out how to use it. Concise and accurate documentation is essential if your work is ever going to be useful to anyone, so in this course, complete documentation in Javadoc format will be required on all the programming assignments.