# 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;
}



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:
• Don't comment on things that are obvious.
• Don't comment on the what, but the why or how.
• Comments should be at a higher level than the 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:

• Name Variables Well

Name should clearly reflect meaning.

• Indent Consistently

### 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:

• Avoids having to maintain repetitive information.
• The generator can produce different outputs (HTML, PDF etc.)

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

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.


/** 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:

• @author
• @version
• @param
• @return
• @throws
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: