Javadoc Introduction

Using Javadoc

This tutorial will introduce the Javadoc tool, which you are expected to use when completing the assignments for COMP205. Javadoc is the standard way to document Java programs. The documentation itself is placed inside the source files. The idea is that, by having the documentation and code alongside each other, it is more likely that the documentation will be accurate. The Javadoc tool is supplied as standard with the Java distribution and, as a result, you most likely already have it installed on your computer.

A good example of some documentation produced with Javadoc is the Java API. If you follow the link, you will be transported to a complete breakdown of the classes available in the Java API. This looks something like the following:

You should spend some time familiarising yourself with this --- it will certainly pay off in the future! As an example, locate "java.lang" in the top-right pane and click on the link. The bottom pane will now show all classes in the "java.lang" package. Selecting one, such as "Integer", gives the following:

This introduces the Integer class and then provides a thorough description of the fields and methods it contains, including information on method parameters and their constraints.

Writing your own Javadoc documentation

The exciting thing about Javadoc is that it's really easy to make your own documentation look as smart and be as helpful as the Java API discussed above. In fact, Javadoc takes care of all the details of laying out the documentation (such as linking classes together, grouping by package and presenting the information for a given class) for you. All you have to do is write the text that goes in the boxes --- it couldn't be easier!

Let's begin with a simple example:

  /**
   * This is a simple class for representing a bank account.  The
   * balance is stored internally in cents.  This means you can only
   * deposit whole cents, rather than fractional amounts.
   *
   * @author David J. Pearce
   * @version 1.0
   */

  public class Account {
    private int balance;

    /**
     * Deposit an amount in cents into the account.
     *
     * @param b The amount to deposit in cents.
     */
    public void deposit(int b) {
        balance = balance + b;
    }

    /**
     * Returns the current balance.
     *
     * @return The current balance in cents.
     */
    public int getBalance() {
       return balance;
    }
  }

This is a simple Account class, authored by David Pearce. Notice that the comment begins "/**", rather than the usual "/*". That signals to Javadoc that the information in this comment should be included in the documentation it generates. Notice also, the use of "@author", "@version", "@param" and "@return" to indicate special information. These are tags which help Javadoc identify certain types of information that it will present in a particular way.

To generate the Javadoc documentation, you simply run the following command line:

 javadoc -d doc Account.java

This places the documentation into the "doc" directory. Doing this will generate the following documentation:

You can see here that details of the implementation are hidden from the documentation. This is to ensure proper encapsulation (i.e. to prevent the user from relying on specific details of the implementation). As it stands, the author information has been omitted from our documentation. We can include this by using the following command line instead:

 javadoc -author -d doc Account.java

For a complete breakdown of all the command-line switches that javadoc supports, type:

javadoc -help

Javadoc Tag Summary

The following summarises the main Javadoc tags. For a complete listing, see the official Javadoc documentation.

Tag	Description	Where
@param	Details a method parameter	Classes, interfaces, methods and constructors only
@return	Details the return value of a method	Methods only
@throws	Details what exceptions are thrown by method/constructor. Must include all checked exceptions, may include other unchecked exceptions where appropriate	Classes, interfaces, methods and constructors only
@author	Details the author(s) of this class/interface	Classes and interfaces only
@version	Indicates the current version of this class.	Classes and interfaces only
@see	Provides links to additional information.	Anywhere
@since	Indicates which version of this class introduced this method. Or, indicates which version of the program as a whole introduced this class.	Anywhere
@serial	Indicates whether a field will be serialised or not.	Fields
@deprecated	Indicates this method/field has been deprecated and should no longer be used. Deprecate items will eventually be removed from the class definition (probably because they were badly thought through)	Anywhere

Final tips:

• You can use HTML style links in your Javadoc text. E.g.

    /**
     * This is a simple class for representing a bank account.  The
     * balance is stored internally in cents.  This means you can only
     * deposit whole cents, rather than fractional amounts.
     *
     * @author David J. Pearce
     * @version 1.0
     * @see the <a href="README.html">README</a> for more information.
     */
  
    public class Account {
      private int balance;
  

If anyone has any other tips, I'd love to be them here!