Learn Java: How-To: How to put comments in your code with javadoc

Developer's Daily

Java Education

front page | java | perl | unix | DevDirectory


	Front Page Java Education Pure Java Articles

How to put comments in your code with javadoc

Introduction

One of the very nice things about Java is javadoc. The javadoc utility lets you put your comments right next to your code, inside your ".java" source files. When you're satisfied with your code and comments, you simply run the javadoc command, and your HTML-style documentation is automatically created for you.

A great thing about keeping your comments right next to your code is that it's much easier to keep the code and the documentation in sync. When you change the code, you change the comments, and run javadocagain. Very simple, very clean.

A working example

The code shown in Listing 1 provides a good example of what Javadoc comments look like. Forget for a while what this Java code is doing (it's not doing much anyway), and focus on the comments.

The first thing to notice is that javadoc comments begin with the /** symbol, and end with the */ symbol. This is a little bit different than the standard C or C++ style comments you might be used to seeing.

/**
* Porsche.java - a simple class for demonstrating the use of javadoc comments.
* @author Robert Newey
* @version 1.0
* @see Automobile
*/
public class Porsche extends Automobile {
   protected String color;
   /**
    * Retrieve the value of color.
    * @return A String data type.
    */
   public String getColor() {
      return color;
   }
   /**
    * Set the value of color.
    * @param newColor A variable of type String.
    */
   public void setColor(String newColor) {
      color = newColor;
   }
}

Listing 1: This sample file shows how you can easily embed javadoc style comments into your Java code.

As you can see from the listing, javadoc also lets you define certain tags within your javadoc comments. Use of these tags causes javadoc to create additional (and better) documentation on your behalf. Table 1 briefly describes the purpose of the javadoc tags used in the sample code shown in Listing 1.

@author This tag lets you put the name of the code author into the documentation.

@parameter This tag is used to define parameters that are passed into a method.

@return This tag defines values that are returned from methods.

@see This tag creates "See Also:" output. You'll normally use this tag to refer to related classes.

@version This tag lets you define the version of the Java code you're developing. For instance, the code displayed in Listing 1 is considered to version 1.0.

Table 1: This table provides brief descriptions of the most commonly-used javadoc tags.

How it works

There are only a few rules to worry about with javadoc. Keep these in mind when creating javadoc documentation in your code:

Javadoc comments only have meaning when they appear before a publicclass, or before public or protected variables and methods.
The first line in a javadoc comment is a summary line. You'll see this description at the top of the HTML file for the class (i.e., Prosche.html), and also in the AllNames.html file.

Also note that there is no need to begin each line of comments with an asterisk, as we've done in Listing 1. This is just a convention among many programmers, but not a standard. If you don't like this convention, just begin the comment with the /** characters, and end them with the */ characters.

After you've created your code, just run the javadoc command on your ".java" file, like this:

javadoc Porsche.java

When you do this, javadoc generates documentation in HTML format for all of your public classes, and your public and protected methods and variables. Based on the files you submit and the documentation within those files, javadoc creates four types of HTML files, as shown in Table 2:

packages.html A listing of each package you generated documentation for, and the classes they contain. In a small example like ours, this file won't contain any really useful information.

AllNames.html This file contains an alphabetical index of all the variables (also referred to as fields) and methods you've defined.

tree.html A listing of all the classes you've generated documentation for, and where those classes fit in the class hierarchy.

Porsche.html There will be one file of this type for each class defined. This file contains the actual documentation for the class.

Table 2: This table provides brief descriptions of the files created when the javadoc command is run on your Java source files.

The output javadoc documentation

Well, that's enough about how it works. The best way to show how javadoc really works is to show the output it generates. Follow the links below to see the various output documentation files that javadoccreated for the simple Porsche.java file shown in Listing 1.

I think you'll agree with me after seeing the documentation that javadoc creates that it sure is a lot easier to let javadoc do the hard work! Think of the benefits:

The documentation sits right next to the code. Change the code, and it's easy to change the documentation.

Four different documentation file types are created for you. These are really needed with object-oriented programming.

The four different file types are all cross-linked, so clicking on a link in one file takes you directly to documentation in another file. Can you imagine doing this manually?

Download the example source code

If you're not already using javadoc, I encourage you to give it a try. You can begin by using the sample code we've shown in Listing 1. To download the Porsche.java source code shown in Listing 1, click here. Once the file is displayed in your browser you can select the File | Save As ... option of your browser to save the code to your local filesystem.

After you've downloaded the source file, try generating the code with your own copy of the javadoc utility.

Are you really interested in working with and seeing javadoc code? Try our Class Builder for Java class-generator technology, which can help you easily generate 100% Pure Java (TM) code for your applications. Class Builder generates Java source code and javadoc code - so you don't have to. Best of all, it's 100% free!

Listing 1:	This sample file shows how you can easily embed `javadoc` style comments into your Java code.

`@author`	This tag lets you put the name of the code author into the documentation.
`@parameter`	This tag is used to define parameters that are passed into a method.
`@return`	This tag defines values that are returned from methods.
`@see`	This tag creates "See Also:" output. You'll normally use this tag to refer to related classes.
`@version`	This tag lets you define the version of the Java code you're developing. For instance, the code displayed in Listing 1 is considered to version 1.0.

Table 1:	This table provides brief descriptions of the most commonly-used `javadoc` tags.

`packages.html`	A listing of each package you generated documentation for, and the classes they contain. In a small example like ours, this file won't contain any really useful information.
`AllNames.html`	This file contains an alphabetical index of all the variables (also referred to as fields) and methods you've defined.
`tree.html`	A listing of all the classes you've generated documentation for, and where those classes fit in the class hierarchy.
`Porsche.html`	There will be one file of this type for each class defined. This file contains the actual documentation for the class.

Table 2:	This table provides brief descriptions of the files created when the `javadoc` command is run on your Java source files.

What's Related