Javadoc Example

Joseph Bergin
Pace University
jbergin@pace.edu
http://csis.pace.edu/~bergin

Javadoc is a subsystem of the Java Development Kit that lets the programmer create useful documentation very easily. Javadoc is a tool that extracts information from "javadoc comments" that you can put into your programs.

A Javadoc comment begins with "/**" and continues until "*/". Note the additional star at the beginning of the comment. By convention, each line of a Javadoc comment also begins with an asterisk.

The most useful Javadoc comments are those that comment your public classes and your public methods, though it can be used for other things as well.

A Javadoc comment must come immediately before the thing it comments. Here is a simple example. Stack.java is part of the standard distribution. Here is an alternate version with some Javadoc comments:

package jb;

import java.util.NoSuchElementException;
import java.util.ArrayList;

/**
 * The Stack class represents a last-in-first-out stack of objects. 
 * @author  Joseph Bergin
 * @version 1.0, May 2000
 * Note that this version is not thread safe. 
 */
public class Stack 
{
	/**
	 * Pushes an item on to the top of this stack. 
	 * @param   item   the item to be pushed.
	 */
	public void push(Object item){this.elements.add(item);}

	/**
	 * Removes the object at the top of this stack and returns that object. 
	 * @return  The object at the top of this stack.
	 * @exception  NoSuchElementException  if this stack is empty.
	 */
	public Object pop() throws NoSuchElementException
	{	int length = this.elements.size();
		if (length == 0) throw new NoSuchElementException();
		return this.elements.remove(length - 1);
	}

	/**
	 * Returns the object at the top of this stack without removing it. 
	 * @return  the object at the top of this stack. 
	 * @exception  NoSuchElementException  if this stack is empty.
	 */
	public Object peek() throws NoSuchElementException
	{	int length = this.elements.size();
		if (length == 0) throw new NoSuchElementException();
		return this.elements.get(length - 1);
	}

	/**
	 * Tests if this stack is empty.
	 * @return  true if this stack is empty and false otherwise.
	 */
	public boolean isEmpty() 
	{	return this.elements.isEmpty();
	}

	private ArrayList elements = new ArrayList();
}

Here (Stack.html) is the equivalent Javadoc (1.3 version). It has a few dead links in it, since I haven't included all the files generated by the Javadoc tool.

Note that within the Javadoc comments there is additional information you can give.

@return is used to give the intent of the value returned by the function

@param gives the intent of any input parameter. The name of the param immediately follows @param.

@exception is intended to say under what conditions an exception will be thrown. The @exception is followed by the exception name.

@author gives the author of the code. Generating these comments is optional as is @version.

The method comments can give the pre and post conditions of the method as well as name or explain any algorithm used. The class comment can give any invariant condition that the user is required to know to use the class properly.

Last Updated: May 29, 2000