Documentation

Good documentation is extremely important in programming. Imagine trying to use the Java Arraylist class without the documentation page for it. You would either have to learn from somebody else who already knows how to use the class, or dig through the source code to see what methods it has and how they work.

The goal of the documentation for a class is to list all of the public constructors and methods a class has, what parameters they take, what they return, and anything else one would need to know to use them effectively. One of the goal of object-oriented programming is making classes that can be re-used in many programs and documentation is key for that.

Javadocs

Documentation could take many forms. You could create a document for each class using a word processor. But the common way of doing it in Java is using Java's built-in documentation generator called "Javadocs". (Other languages have similar tools). There are two main ideas behind a documentation generator:

The best place to write documentation is in the code. If you have a separate document where the documentation lives, it will fall out of date as you make changes to the code. By putting the documentation right into the .java files, you can more easily keep it up to date as you will see it as you edit the source.
The best place to read documentation is in a web browser. Hunting through source files to find documentation is not convenient, and sometimes you won't even have the source files available. Viewing the documentation in a web browser allows for hyperlinks to connect to different class's pages and so on.

The way Javadocs works is you include special comments directly into your .java files. Then the Javadocs tool automatically scans your code to see what methods, parameters and so on you have. It pulls out that information, and your special comments, to create the documentation pages. It exports these as HTML web pages.

Writing Javadocs

Javadocs comments start with /**. Any comment that begins this way will signal to the generator that it should include this info in the documentation pages. Note that comments starting with /* (with just the one star) are just regular comments, like those that begin with //.

Not all comments should be included in documentation. For example, if you have comments explaining how a method works, they are valuable to someone reading the code who wants to change it. But they wouldn't be valuable to someone who just wants to use the code which is what Javadocs are intended for.

The special comments should go at the top of every class and every public method or constructor within a class. These comments should explain how to use the class and method, and talk about what it does.

There are also tags that can be included to give extra info. Here are some of the commonly used tags:

Tag	Meaning	Example
@author	Author of the class or method	`@author Jasmine Richards`
@version	A version number associated with the class	`@version 1.3`
@param	Used for describing the parameter into a method.	`@param delayTime The time to delay, in seconds`
@return	Used to describe the meaning of the return value of a method	`@return The item if it is found, or null if it is not`
@throws	Any exception the method may throw, with a description of when	`@throws IllegalArgumentException if the time given is not a positive number`

Here is an example showing these:


/**
 * @author Ian Finlayson
 * this class represents a single playing card from a standard set of 52 cards
 */
public class Card {
    private Suit suit;
    private int value;

    /**
     * create a card given the suit and value
     * @param suit
     * @param value which should be between 2 and 14.  Here 2-10 refer to the number cars,
     *  and 11-14 refer to Jack through Ace
     * @throws IllegalArgumentException when the value given is not a valid number (i.e. 2-14 inclusive)
     */
    public Card(Suit suit, int value) throws IllegalArgumentException {
        if (value < 2 || value > 14) {
            throw new IllegalArgumentException("Invalid card number given");
        }

        this.suit = suit;
        this.value = value;
    }
    
    /**
     * returns the suit of this card
     * @return the suit
     */
    public Suit getSuit() {
        return suit;
    }

    /**
     * returns the value of this card.  Cards with values 2-10 will get their number returned
     *  as the value.  Jacks through Aces will get the values 11 through 14.
     * @return the value
     */
    public int getValue() {
        if (value <= 10) {
            return value;
        } else if (value <= 13) {
            return 10;
        } else {
            return 11;
        }
    }

    /**
     * this method allows for comparing cards for order.  This is based entirely on the
     * value.  For instance two Jacks will be considered equal regardless of their suit
     * @param other the Card object which we will be comparing this one to
     * @return a negative number if this card is less than the one given, a positive number
     *  if it is greater, or 0 if they are equal.
     */
    public int compareTo(Card other) {
        return this.value - other.value;
    }
}

Tips for Good Documentation

Generating the documentation pages is always helpful to anyone using your classes, but ideally the documentation you write will also be of good quality. You should try to put yourself in the shoes of a person who wants to use your class, but doesn't know how it works. What do they need to know? What mistakes might they make that you might be able to avoid for them? Like any writing activity, it's a skill that can be practiced. Below are some tips for writing good documentation:

Explain anything that might not be clear. For example, in the compareTo method above, we could have compared the cards based on suit and value, but in fact only value was taken into account. Things like that should be explained in the documentation.
Include any assumptions made by the class or methods. For example, if you are creating a Deck class which contains a list of Card objects, you might assume that there can only be at most 52 cards in a Deck, and no Card objects are duplicates. If so, including baseline assumptions in the documentation is a good idea.
Don't explain how methods work. To call upon the Collections.sort() method, for example, you do not need to know what sorting algorithm it's using. So your documentation should not explain the implementation details of the methods, but just what the user needs to know to call upon them.

Generating the with IntelliJ

Javadocs is something that comes with Java and can be used with any development environment. IntelliJ provides access to the Javadocs tool under the "Tools → Generate JavaDoc..." menu:

This will pull up a dialog window with several options. For this lab, you can select only the file you are working with, as opposed to the whole project. Also, check the @author checkbox so the author information is included. Also be sure you note where the output directory is — that's where the generated HTML files will go.

When you click OK, it should take a few seconds to produce the documentation for you. It will then open it up in a web browser. (The documentation isn't online. Your web browser is just reading the HTML files off your computer's hard drive.)