Home CPSC 330

Documentation

Overview

Software Documentation is important as it communicates the design and implementation to others. There are a few different audiences for documentation:

  1. Other programmers working on the code.
  2. Other programmers using the code.
  3. Users of a final program.

We will discuss 1. and 2.

We could also document different things to other programmers:

  1. Requirements of the code.
  2. Design of the code.
  3. How the code is implemented.
  4. How to use the code as an API.

What to Comment

Consider the following example:


// a public static function to return the factorial of an int x as an int
public static int fact(int x) {

  // declare an int variable x and set it to 1
  int fact = 1;

  // keep looping until x is less than or equal to zero
  while(x > 0) {
    // multiply fact and x and assign the result to fact
    fact = fact * x;

    // subtract one from x
    x--;
  }

  // return fact back to the caller
  return fact;
}

How about this example factorial function:


public static int fact(int x) {
  // calculate the factorial
  int f = 1;
  x--;
  for(int a = x; a > 0; a--)
    for (int b = f; b > 0; b--)
      for (int c = a; c > 0; c--)
           f++;
  return f;  
}
Tips for commenting code:

Another good use of comments is to mark areas that you need to re-visit. "TODO" and "FIXME" are often put in comments for this purpose.


Self-Documenting Code

Self-documenting code is code that is as clear to read as possible.

Some things that make code easier to read:


Documentation Generators

A documentation generator is a program that scans the comments in your code and produces documentation from it automatically.

The Java class documentation was not written by hand. It was generated from comments in the Java source code.

Benefits of this:

This kind of documentation is useful not for those editing your code, but by those using it.


Javadoc

Javadoc is a documentation generator included with Java. It looks for special comments in your source code and produces HTML documentation based off of them.

Javadoc comments start with /** and end with */


/** this javadoc comment describes the Example class */
public class Example {

  /** this describes the constructor */
  public Example() {

  }

  /** this describes the method foo */
  public void foo() {

  }
}

There are a number of special tags that can be included in Javadoc comments:

The following code listing is the Line class with Javadoc comments included:

/** The Line class represents a line between two points in space
* @author Ian Finlayson
* @version 1.0
*/
public class Line {
  /** construct a line from 2 points
  * @param x0 The x coordinate of the first point
  * @param y0 The y coordinate of the first point
  * @param x1 The x coordinate of the second point
  * @param y1 The y coordinate of the second point
  */
  public Line(int x0, int y0, int x1, int y1) {
    this.x0 = x0;
    this.y0 = y0;
    this.x1 = x1;
    this.y1 = y1;
  }

  /** calculate the slope of the line and return it
  * @return the slope of the line as a double
  * @throws ArithmeticException when the line is vertical
  */
  public double slope() {
    // avoid dividing by zero
    if(x1 == x0) {
      throw new ArithmeticException();
    }

    return (double)(y1 - y0) / (double)(x1 - x0);
  }

  // these don't need javadocs as they're private
  private int x0, y0, x1, y1;
}

To generate the documentation run the javadoc command:


> javadoc Line.java

Copyright © 2018 Ian Finlayson | Licensed under a Creative Commons Attribution 4.0 International License.