Overview of This Lesson

Internal program documentation is used inside source code to help or remind a programmer what the code actually does. We often use it to summarize groups of statements, explain what the variables are used for, or identify areas of the code that contain bugs or are unfinished.

External program documentation is documentation that is used to explain how a program works and what to do when errors occur. For object-oriented programs, you will need to create external documentation that describes a class, its fields and methods, how the methods should work (what goes in, what comes out), and what Exceptions the methods might throw. You've already been exposed to this kind of documentation - you read it when you "go to the Java Docs" to find out more about a class or its methods.

To create external program documentation in other languages, you would normally have to write these documents yourself using an editor or word processor after the program has been written. In Java, you can write your external documentation as you write your code. To do this, we surround the comments with the /** and */ characters. Note that we start with a slash and two asterisks, instead of one.

These special comments are usually just called javadocs after the name of the utility that compiles them for you. You write your javadocs before each class declaration (public class Whatever {) and method header. When your documentation is finished, you compile the documents in HTML format using the javadoc utility. The JAVADOC.EXE file is in the JDK directory's bin directory, along with the compiler and interpreter.

Resources

• Sun's Javadoc Reference
• How to Write Doc Comments for the Javadoc Tool

How to Write Javadoc Comments

When writing javadoc for a class or method, you should first write a brief sentence that describes the purpose of the class or method. This should then be followed by whatever additional explanation is required. For constructors/methods, the first sentence is shown in the "Constructor Summary" or "Method Summary" section, and the rest of the text is shown in the details area for that constructor/method.

Example:

/**
   * This class models a very simple bank account that keeps a balance
   * and an interest rate.  The class is not fully functional, and only 
   * the most basic methods have been included.  This is for demonstration
   * of encapsulation and information hiding.
   * 
   * @author Wendi Jollymore
   */
  public class Account {
  
      private double balance = 0.0;
      private double rate = 3.5;
      
      /**
       * Default constructor sets the balance to 0 and the interest
       * rate to a default value of 3.5%.
       *
       * @throws IllegalArgumentException if the balance or rate are invalid
       */
      public Account() throws IllegalArgumentException {
      }
  
      /**
       * Constructs an Account object with a given balance and interest
       * rate.
       
       * @param b the inital balance of the account
       * @param r the intial interest rate of the account
       * @throws IllegalArgumentException if balance or interest rate contain invalid values
       */
      public Account(double b, double r) throws IllegalArgumentException {
          setBalance(b);
          setRate(r);
      }
  
      /**
       * Retrieves the account balance.
       *
       * @return the account balance
       */
      public double getBalance() { 
          return balance; 
      }
  
      // ... etc...
  }

If you examine the code segment above, you'll see how the javadoc comments are written. You'll notice a few interesting things such as @throws, @param, and @return in the documentation. These are called tags and they define parts of the javadocs that you'll see when you read the actual documents that are created.

Here is a description of a few of these tags. We'll learn more as we learn more about Java.

@param - this tag defines one parameter in a method. After the tag, you state the name of the parameter variable, then a brief explanation of what the parameter is for. E.g.:

@param name the name of the cat object

@return - this tag defines the return value of a method. After the tag, you state a brief description of the value returned. E.g.:

@return the amount of pay this employee gets for the week

@throws - if a method throws an exception, you need to specify what exception is thrown and why. E.g.:

@throws IOException if there is a problem reading a record from the file

@author - if you compile your javadocs with the -author switch (see below), the documentation will contain a special Author heading under the class description.

@version - if you compile your javadocs with the -version switch (see below), the documentation will contain this information below the class description.

Where To Use Javadocs

You should use javadoc comments for:

• classes
  • A set of comments should go before a class header to describe the purpose of the class and any special features it has.
  • This is where you would also use the @version and @author tags.
  • These javadocs always go immediately above the class header (no blank line between the docs and the header) e.g.

    /**
       * The CookieInventoryItem class models a cookie record in the cookie inventory
       * file. The cookie inventory file has the following structure:
       * <p>
       * <table summary="" style="border: 1px solid green; padding: 2px;">
       * <tr><th>Description</th><th>Data Type</th><th>Comments</th></tr>
       * <tr><td>cookie ID</td><td>int</td><td>a unique id for each cookie</td></tr>
       * <tr><td>quantity on hand</td><td>int</td><td>the number of this cookie in
       * inventory</td></tr>
       * </table>
       * <p>
       * Each cookie can only be in the inventory file one time, so the cookie ID
       * serves as the primary key field for the cookie inventory file.
       *
       * @author Wendi Jollymore
       */
      public class CookieInventoryItem {

  • Notice that you can use HTML tags and CSS in your Javadocs (this is true of all Javadocs, not just the class documentation)! Some tags are used a bit differently, but it's ok to type the HTML code the correct way you learned it.
  • The first sentence should be a summary of what your class does or what it models. This will appear in the documentation on the summary part of the page. The rest of the paragraph gives more details, and is viewable when someone clicks on the link to your class.
    

    

    
    

    

• methods
  • Always use a set of javadoc comments before a method header to explain what the method does, and to identify any parameters (@param tag) or a return value (@return tag).
  • You don't need to document private methods.
  • These docs should go immediately above the method header (no blank line between the docs and the header).
  • As with class docs, the first sentence should be a summary, and the second and subsequent sentences give more details, if necessary.
  • Example:

    /**
       * Gives this CookieInventoryItem a valid quantity in inventory. Quantity
       * must be greater than 0, otherwise an exception is thrown.
       *
       * @param qty the number of cookies in inventory
       * @throws IllegalArgumentException if the qty is 0 or less
       */
      public void setQuantity(int qty) throws IllegalArgumentException {
      
          // make sure quantity is valid
          if (qty <= 0) {
              throw new IllegalArgumentException("Quantity must be greater than 0.");
          } else {
              this.quantity = qty;
          }
      }
      
      /**
       * Retrieves the number of this kind of cookie in inventory.
       *
       * @return the quantity on hand
       */
      public int getQuantity() {
          return quantity;
      }

    
    

    

    
    

    

  • Avoid using words that are already in the code. For example, notice that the docs for the get-method don't say "gets the number..", they say "retrieves the number..." In all documentaiton, you should attempt to use language that's not already part of the code, to provide alternative ways for people to understand what you're trying to say.
• fields
  • If you have any instance variables or constants that are declared as public or protected, you should place a small javadoc comment before each to explain what the field is for. This is not necessary for private instance fields!
  • The Javadoc should go above the variable being documented (no blank line between the Javadoc and the variable statement).
  • Example:

    /**
       * A Cookies Enumeration constant that contains the cookie name, price, and
       * cookie ID number.
       */
      public Cookies cookie = Cookies.CHOCOLATE_CHIP;
      private int quantity = 0;  // number of this cookie in stock

  
  

  

Generating Javadocs

Most IDEs have some kind of utility for configuring and generating API pages with Javadoc comments. Check your IDE's manual to find out how to use this tool.

Generating Javadocs Manually

To compile your javadocs manually, you run the javadoc utility on the .java source file:

javadoc MyFirstPgm.java

Or if you want to create javadocs for all the files in the current folder:

javadoc *.*

If you want to make javadocs for a certain set of files, for example:

javadoc FirstFile.java SecondFile.java

You can add the following switches after the javadoc command, before the file name:

-version
Will include the @version information in the documentation. This needs to be specified before -author.

-author
Will include the @author information in the documentation.

-d [folder]
Will store all the documentation files in the subdirectory named in [folder]. For example -d docs will put all the documentation files in a subfolder called "docs". This folder must already exist, so you'll have to create it before you run the javadoc utility.

Example:

javadoc -version -author -d docs FirstFile.java SecondFile.java

This command will create javadocs, including the version and author information, for the FirstFile.java and SecondFile.java source files and store all the doc files in the docs folder of the current directory.