Javadoc


North Carolina State University
CSC 326 - Software Engineering
Laurie Williams, Dright Ho, and Sarah Heckman. [Contact Authors]


0.0 Outline
1.0 Introduction to Javadoc
2.0

Types of Javadoc

3.0 Javadoc Templates in Eclipse
4.0 Generate HTML Document
5.0 Resources

1.0 Introduction

Have you ever had an experience of reading your code months after you last worked on it? You probably had problems remembering exactly what the code does. We can actually do two things to avoid such a situation. One is to strive to make your program simple and readable. The other is to write good documentation.

Javadoc is a convenient, standard way to document your Java code. Javadoc is actually a special format of comments. There are some utilities that read the comments, and then generate HTML document based on the comments. HTML files give us the convenience of hyperlinks from one document to another. Most class libraries, both commercial and open source, provide Javadoc documents.

In this tutorial, we are going to learn several ways to write Javadoc comments with the assistance of Eclipse, and generate HTML files with the Javadoc Export WIzard. There are several tags for Javadoc comments. However, you don't have to try to memorize them all.

Note: Most frequently used tags can be generated by the code template, and you can find others with Content Assist by pressing Ctrl-SPACE.

Top | Contents

2.0 Types of Javadoc

There are two kinds of Javadoc comments: class-level comments, and member-level comments. Class-level comments provide the description of the classes, and member-level comments describe the purposes of the members. Both types of comments start with /** and end with */. For example, this is a Javadoc comment:

/** This is a Javadoc comment */

2.1 Class-level Comments

Class-level comments provide a description of the class, and they are placed right above the code that declares the class. Class-level comments generally contain author tags, and a description of the class. An example class-level comment is below:

/**
* @author Sarah Heckman
* * The Inventory class contains the amounts of all the
* inventory in the CoffeeMaker system. The types of
* inventory in the system include coffee, milk, sugar
* and chocolate.
*/
public class Inventory { //Inventory code here }

2.2 Member-level Comments

Member-level comments describe the fields, methods, and constructors. Method and constructor comments may contain tags that describe the parameters of the method. Method comments may also contain return tags. An example of these member-level comments are below:

/**
* @author Sarah Heckman *
* The Inventory class contains the amounts of all the
* inventory in the CoffeeMaker system. The types of
* inventory in the system include coffee, milk, sugar
* and chocolate.
*/
public class Inventory { /** * Inventory for coffee */ private int amtCoffee; /** * Default constructor for Inventory * Sets all ingredients to 15 units */ public Inventory() { this.coffee = 15; } /** * Returns the units of coffee in the Inventory * * @return int */ public int getAmtCoffee() { return coffee; } /** * Sets the units of coffee in the Inventory * * @param int new units coffee */ public void setAmtCoffee(int newCoffee) { this.coffee = newCoffee; } }

2.3 Javadoc Tags

2.3.1 To add a class hyperlink, we have to add a tag in the comment. The format of class hyperlink tag is:

{@link <FullClassName> [Display Text]}

FullClassName is the name of the class you wish to link to. The class name must also include the package name if the target class is not in the same package. Display Text is optional. It is the text that will be displayed in the document. If the display text is ignored, the result document will display the full class name.

2.3.2 To add a hyper link to a method of the same class, we use the @link tag like this:

{@link #<MethodSignature> [Display Text]}

MethodSignature is the signature of the target method, including the method name and the parameter types.

Note: It's sometimes difficult to type the right method signature. You may simply type # and some beginning characters of the method name, press Ctrl-SPACE, and a list of the method signatures that match will pop up. You can select a method from the list.

2.3.3 To add a hyper link to a method in a different class, we use the @link tag like this:

{@link <ClassName>#<MethodSignature> [Dsplay Option]}

ClassName is the full name of the class where the method resides. It must include the package name if the class is not in the same package. MethodSignature is the the method signature where this comment links to. If Display Option is not specified, the name of the class and method will be displayed in the document.

Note: Also, you can use Ctrl-SPACE to assist you typing.

2.3.4 The most common Javadoc tags are:

  • @author: Describes the author of the document. Used in class-level comments
  • @param: Describes a parameter of a method or constructor.
  • @return: Describes the return type of a method.
  • @throws: Describes an exception a method may throw.
  • @exception: Describes an exception.

2.3.5 Some words, like null, true, or false, are better displayed in a fixed-width font. Fixed-width font indicates that the word is used in source code. We can enclose those words in <code></code> segments.

2.3.6 Actually you can use HTML tags in any Javadoc comments. And you have to use special symbols to represent special characters, too. For example, you can use <table><tr><td> in the comments to create a table. Also, you'll need to use &lt; if you want to display <.

Top | Contents

3.0 Javadoc Templates in Eclipse

Eclipse generates Javadoc everytime you create a class, method, or field, using templates built into the IDE. These templates can be modified to create Javadoc in the format that you want. Or you can turn off the Javadoc generation property.

The Javadoc templates are found by selecting Window > Preferences. Under the tree on the left of the Preferences dialog, open up Java > Code Style > Code Templates.

There is a check box at the bottom of the Code Templates page that says Automatically add comments for new methods and types. If you uncheck this box, Javadoc comments will not be generated.

To configure generated comments, open the Comments tree. Select a type of comment to modify, and select Edit.... Text that looks like ${ } is a variable. Use the Insert Variable... button to see what variables are avaliable to you.

Top | Contents

4.0 Generate HTML Document

4.1 Right click on the project and select Export.... Select Javadoc, and click Next.

4.2 Make sure the Javadoc command refers to the Javadoc command line tool. This tool is provided with JDK. The name is usually javadoc.exe. In the lab, you can find javadoc.exe in C:\j2sdk1.4.2\bin\ (that is, the Javadoc command is C:\j2sdk1.4.2\bin\javadoc.exe .)

4.3 Select the types that you want to create Javadoc for.

4.4 Make sure that the Use Standard Doclet radio button is chosen, and Browse for a destination folder.

4.5 Click Next for more options if you wish; otherwise click Finish.


Step 4.2 to 4.5

Top | Contents

5.0 Resources
 
Top | Contents

Back to Software Engineering Tutorials
Getting Started with Rational XDE Tutorial ©2003-2004 North Carolina State University, Laurie Williams, Dright Ho, Sarah Heckman
Email the authors with any questions or comments about this tutorial.
Last Updated: August 16, 2004