Creating Your Own JavaDocs

Creating Your Own JavaDocs

One important component of a good program is its documentation. One of the downsides of documentation is that it is often separate from the source code that it describes, leading to the possibility that they can become out of sync, and therefore useless.

Java has a nice built-in way of dealing with this problem. It allows the incorporation of certain tags into source code, which will then become processed by a separate program to create human-readable documentation. By combining the files used for the docs with those used for the code, it reduces the chance that they’ll be out of sync.

As we expect you to document your code with comments as part of being a responsible programmer, you should start using these Javadoc tags in your code.

The basic structure of a Javadoc block is a comment, except with extra asterisks. Below is a javadoc comment and the code (from ArrayList) that it documents.

The first line of the comment is the documentation for the method in general.

The two lines that start with @param tell us what the parameters do. Their format is @param, followed by the name of the parameter, followed by a description of the parameter. Likewise, @return gives us a description of the return value.

/**
 * Set the array at index to element
 * @param index index into array
 * @param element element to insert
 * @return old value at index
 */
public AnyType set(int index, AnyType element) {
	AnyType oldVal;

	// Make sure my index is within bound
	if ( (index < 0) || (index > this.size)) {
		throw new IndexOutOfBoundsException("Index Out of Bounds! You tried to get " +
				index + " but the size is " + size);
	}

	// Save the old value
	oldVal = data[index];

	// Set array at index to element
	data[index] = element;

	// Return the old element
	return(oldVal);
}

Take a look at StackADT.java. You can see we have already written javadoc comments for it - now, let’s generate the documentation!

First, create a directory to keep all our documentation in by typing the following command in your lab5 directory using the command line:

mkdir docs

Now, in your lab5 directory in the terminal, run the following command

javadoc -d ./docs StackADT.java

This will generate javadoc webpages for the StackADT.java file and save them to the docs directory. If you navigate to /docs, and open StackADT.html you should see something that looks like this.

All of the javadoc comments have been used to automatically generate a Java documentation page.

For this part of the warmup, you and a partner will write JavaDoc comments for Maze.java, a class we have provided you to use in Lab 5, but neglected to write JavaDocs for (oops!).

Some useful tags to include in your documentation:

  • @author – The author of the program
  • @param – Parameters that are used for a function
  • @return – What a function returns
  • @throws – Exceptions that your function may throw
  • @see – Links to other documentation that your function might require. You can include an HTML anchor tag (… or another .java file here.

After you’ve written it up, type

javadoc -d ./docs Maze.java

In the command line. Now go to the documentation directory and check out your new Maze.html documentation page!

Make sure you add and commit your docs directory to github.