Javadocs

Introduction

Programmers know that comments make their code much more readable, since they help explain the code to others as well as reminding themselves exactly what they have done. The Java language supports three types of comments with the last type being specific to a Java tool called Javadoc:

Type 1	/* text */	the compiler ignores all text
Type 2	// text	the compiler ignores text from the // to the end of the line
Type 3	/** documentation */	this is a Javadoc comment

In Java, generating comments that appear in a standard format from program to program requires the use of an executable tool, called Javadoc.exe. This is an executable that is included within the Java SDK and can be invoked by the programmer to generate a complete set of documentation for a source file or a package. Since this documentation always follows a specific format, it makes the documentation much more useful for understanding and maintaining code. Its standard format allows for easy reminders to the programmer as well as others who may work on the file.

Javadoc is a very extensive system; only those features of interest to beginning Java programmers will be covered here. For a more thorough treatment of the subject, see the online documentation provided by Sun Microsystems at: http://java.sun.com/j2se/1.4.2/docs/tooldocs/javadoc/index.html

Exploring an example of Javadoc output

We’ll work at adding Javadoc compatible comments to the class PizzaParlor (it was found in Worksheet A5.1, although a second version containing Javadoc comments is shown at the end of this handout). A file named pizzaparlor.html is the output of the Javadoc process, called a “doclet”. Browse the output of this file in the Javadoc folder in this lesson, to see the structure of Javadoc documentation (Hint: Open up the pizzaparlor.html file in your Web browser by double-clicking on it.)

Look for each of the following in the file.

1. The Constructor Summary section
2. The PizzaParlor constructor summary
3. The Method Summary section
4. The orderCheese method summary
5. The getNumPepperoniPizzas method summary
6. The Field Detail section
7. The Constructor Detail section
8. The Method Detail section

• You should notice something right away. The comments that you will enter are used in two places, in a Summary section and in a Detail section.

• Also notice that there is a Field Summary section that includes comments about the instance variables in the class.

• Spend some more time exploring and look for the difference between the getNumPepperoniPizzas Detail and Summary sections.

The Components of a “Doclet” and How to Produce Them

Javadoc comments are placed in your source code, directly before classes, methods and constructors. They may also include additional parameters. Here’s an example, again based on the PizzaParlor class. This example includes the optional parameters @author and @version. Most programmers try to leave a blank line between the Javadoc comment and the class header itself! The blank line is not required, but stylistically it’s a good idea.

The Javadoc result of these comments is shown at the right. Notice what is and is not produced from the Javadocs comment in the above example.

Here are the Javadoc comments for the class constructor.

/**
* constructor PizzaParlor - initializes the name and the inventory
* for the Pizza Parlor
* as well as the cash register and the bank account
*/

PizzaParlor()
...

Here is the Constructor Summary section of the “doclet” after it has been generated. The same information also appears in the Constructor Detail section.

Here are the Javadoc comments for the method called orderCheese( ).

/**
* <b>summary</b>: provides a method ordering cheese pizzas -
* this updates myRevenue, myBankAccount and
* maintains the cheese inventory (myCheeseSupply).
*/

void orderCheese ( )
...

Here is the portion of the Javadoc “doclet” that results: this is how the comments appear in the Method Summary section and in the Method Detail section.

Here are the Javadoc comments for the method called getNumPepperoniPizzas()

/**
* <b>summary</b>: provides a method for obtaining the number
* of pepperoni pizzas ordered by returning the instance variable
* myNumPeppPizzas
*
* @return myNumPeppPizzas the total # of pepperoni pizzas ordered
*/
int getNumPepperoniPizzas()
...

Here is what the actual Javadoc “doclet” looks like after it has been generated - this is how the comments appear in the Method Summary section.

and here is what the comments look like in the Method Detail section. The optional parameter @return is ONLY shown in the detail section.

getNumPepperoniPizzas
int getNumPepperoniPizzas()

summary: provides a method for obtaining the number of pepperoni pizzas ordered by returning the instance variable myNumPeppPizzas
Returns:
myNumPeppPizzas the total # of pepperoni pizzas ordered

Additional details

There are a few things in the preceding sections code that need to be explained.

First, note the <b> and the </b> notations in the OrderCheese comment, where the word summary has been placed in boldface. If you aren’t familiar with this, the two tags are part of HTML, or HyperText Markup Language. In this case, they turn boldface on and off for anything placed between the brackets! HTML can be used freely in your Javadoc comments! Using HTML coding is optional, but it adds a lot to the comment.

Next, the first sentence of any Javadoc comment should be a summary comment because it will be used in two places in the actual Javadoc “doclet,” in the summary section as well as in the detail section. You’ll see this in the actual file that is generated by the Javadoc tool! The summary statement ends at the first period, so you can actually get in a long summary just by adding more comments and avoiding a period. The HTML and the actual word SUMMARY are also optional, but it emphasizes the summary sentence in the “doclet”.

How Do We Actually Generate the Javadoc “Doclet”?

After you enter your Javadoc comments into your source code, you’ll want to see the actual html file with your formatted Javadoc comments. This html file is the Javadoc “doclet”. Here’s a general guideline to help you accomplish this.

Since there are many Java IDE’s available to programmers, it is not practical to cover each of them in terms of how they implement the Javadoc tool. But remember that Javadoc is an executable, so it can also be called from the MS-DOS window. Here are the steps.

1. Create a folder on either the C: or the A: drive (preferably at the root level because it’s easier)
2. Copy your Java source file to the created folder
3. Invoke the MS-DOS window (usually in the START menu)
4. Change your directory to that of the folder you created (use the command cd C:\yourfolder)
5. Invoke the command string that leads MS-DOS to your Javadoc executable (similar to the one below.)

6. Here is how your DOS window will look after you press ENTER after step 5. The folder that is used here is called javawork. The boldface lines are ones that YOU enter (of course you may have to change the pathname and filename to suit your needs.). The rest is generated by Javadoc.exe.

Making Sense of the Different Files

If you open up the folder that you have created, you will find MANY files. The one you want to look at first has the name of your Java source file, with the extension html.

To see the doclet file generated by Javadoc.exe from PizzaParlor.java: double click on PizzaParlor.html

At the end of the doclet, you can get a complete index of all of your methods and variables just by clicking on the word INDEX within the doclet:

To see the complete index of PizzaParlor.java: double click on index-all.html

There is also a HELP file available by clicking on HELP:

To see the HELP file for PizzaParlor.java: double click on help-doc.html

Further Exploration

At this point, you should review the Javadoc compatible listing of the class PizzaParlor at the end of this handout to familiarize yourself with all of the included Javadoc comments. Javadoc comments have not been entered for every item. The only comments that are in this listing are those discussed in the text.

The best way to learn the Javadoc tool and all it can do is to make changes and then generate a new “doclet” to see the effect of your change. Here are a few suggestions for some things to try.

1. Change the name of the author
2. Change the version number
3. Add a line to the class PizzaParlor definition - don’t forget the additional *
4. Add a Javadoc comment for myRevenue and myBankAccount
5. Add boldfacing to the class constructor
6. Add a Javadoc comment for the method orderVeggie

Class Pizzaparlor With Some Javadoc Comments

/**
    * class PizzaParlor - a class used to demonstrate
    * the construction of a class including
    * constructors, methods, and instance variables
    * @author P. Pie
    * @version 1.1
    */
class PizzaParlor{
    // instance variables
    /** # of cheese pizzas ordered*/
    private int myNumCheesePizzas;
    /** # of pepperoni pizzas ordered */
    private int myNumPeppPizzas;
    /** # of veggie pizzas ordered */
    private int myNumVegPizzas;
    /** ounces of cheese in the inventory */
    private int myCheeseSupply;
    /** ounces of pepperoni in the inventory*/
    private int myPepperoniSupply;
    /** ounces of veggies in the inventory*/
    private int myVeggieSupply;
    private double myRevenue;
    private double myBankAccount;


    // constructor
    /**
      * constructor PizzaParlor - initializes the inventory for the
      * Pizza Parlor as well as the cash register and the bank account
      */

    PizzaParlor(){
      myNumCheesePizzas = 0;
      myNumPeppPizzas = 0;
      myNumVegPizzas = 0;
      myCheeseSupply = 400;
      myPepperoniSupply = 200;
      myVeggieSupply = 200;
      myRevenue = 0;
      myBankAccount = 1000;
    }

    /**
      * <b>summary</b>: provides a method ordering cheese pizzas -
      * this updates myRevenue, myBankAccount and
      * maintains the cheese inventory (myCheeseSupply).
      *
      */

    void orderCheese(){
      myNumCheesePizzas++;
      myRevenue += 8; //cheese pizza price:$8
      myBankAccount += 8;
      myCheeseSupply -= 12;//cheese needed per cheese pizza
    }

    /**
      * <b>summary</b>: provides a method ordering pepperoni pizzas -
      * this updates myRevenue, myBankAccount and
      * maintains the cheese inventory (myCheeseSupply) as well
      * as the pepperoni inventory (myPepperoniSupply)
      */

    void orderPepperoni(){
      myNumPeppPizzas++;
      myRevenue += 10;//pepperoni pizza price:$10
      myBankAccount +=10;
      myCheeseSupply -= 8;//cheese needed per pepp pizza
      myPepperoniSupply -= 6;//pepperoni needed per pepp pizza
    }

    void orderVeggie(){
      myNumVegPizzas++;
      myRevenue += 11;//veggie pizza price:$11
      myBankAccount += 11;
      myCheeseSupply -= 8;//cheese needed per veggie pizza
      myVeggieSupply -= 12;//veggies needed per veggie pizza
    }

    int getNumCheesePizzas(){
      return myNumCheesePizzas;
    }

    /**
    * <b>summary</b>: provides a method for obtaining the number
    * of pepperoni pizzas ordered by returning the instance variable
    * myNumPeppPizzas
    *
    * @return myNumPeppPizzas the total # of pepp pizzas ordered
    */
    int getNumPepperoniPizzas(){
      return myNumPeppPizzas;
    }

    int getNumVeggiePizzas(){
      return myNumVegPizzas;
    }

    int getCheeseSupply(){
      return myCheeseSupply;
    }

    int getPepperoniSupply(){
      return myPepperoniSupply;
    }

    int getVeggieSupply(){
      return myVeggieSupply;
    }

    double getRevenueTotal(){
      return myRevenue;
    }

    double getBankAccountBalance(){
      return myBankAccount;
    }

}