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.


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.


   * 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 {
       * 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:

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:

Will include the @version information in the documentation. This needs to be specified before -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.


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.