In this chapter you'll learn how to use the Java documentation tool, javadoc, to automate the documentation of your software. This is the tool that is used to create the superb Java API documentation. It translates your source code into Hypertext Markup Language (HTML) files that can be displayed by a Web browser. When you finish this chapter, you'll be able to quickly and easily document your software using javadoc.
The javadoc program examines your source code and generates HTML files that provide a fully integrated set of documentation for your Java software. The HTML files generated by javadoc document the classes, interfaces, variables, methods, and exceptions that you declare and use in your programs. These files describe your software at the package and class level. The linking capabilities of HTML are used to provide extensive cross-referencing between related software components. These links allow you to quickly access all of the documentation that is relevant to a particular topic.
javadoc differs from other documentation generators in that it goes beyond simple comment-scanning and actually parses your source code in order to generate documentation that describes the structure and behavior of your programs. It makes judicious use of HTML links to generate documentation that allows you to easily traverse the structure of your software.
javadoc recognizes special types of comments that you insert in your source code. When it parses your source code, it combines these comments with the structural information it generates. Your comments are then integrated into your software's HTML description. The special comments recognized by javadoc consist of doc comments, javadoc tags, and HTML tags.
Doc comments are based on the traditional C /* and */ comment delimiters. They are distinguished from ordinary C comments in that they begin with /** instead of /*. They are used to identify comments that are to be automatically added to the HTML documentation produced by javadoc.
The javadoc tags are special tags that are embedded in doc comments. These tags allow you to include reference information in your software. For example, you can include a javadoc comment that says, See also: class X. Some references result in links being automatically inserted into your software's documentation.
javadoc also allows you to insert HTML tags directly in your source code. However, javadoc recommends that you limit your HTML to small, simple, and correctly formatted HTML elements so as not to conflict with the HTML that it generates. Your HTML tags are combined with those produced by javadoc to create an integrated set of HTML pages.
The best way to understand how javadoc works is by using it and then exploring the documentation that it produces. Javadoc is so simple to use that it requires only a single command line to generate integrated software documentation for multiple software packages.
To use javadoc, create a separate ch10 directory under your c:\java\jdg path. This directory will be used to store the HTML files that javadoc produces. You could store these files in the same directory in which you store your Java API documentation, but it's not a good idea to clutter up your API directory with other documentation. Because you will not be storing your documentation in your API directory, you will have to copy the images subdirectory from your API directory to ch10. The images are needed by your documentation so that Web browsers can display all the fancy icons, images, and bullets that are characteristic of the API documentation. With these images, your documentation looks outstanding. Without the images, your browser will substitute its missing icon images for the Java images, and your documentation will look horrendous.
After you have copied the images subdirectory to your ch10 directory, launch a DOS shell and enter the following DOS command line:
C:\java\jdg\ch10>javadoc jdg.ch05 jdg.ch06
Loading source files for jdg.ch05
Loading source files for jdg.ch06
Generating packages.html
generating documentation for class jdg.ch05.BorderedPrintCGrid
generating documentation for class jdg.ch05.CGBox
generating documentation for class jdg.ch05.CGObject
generating documentation for class jdg.ch05.CGPoint
generating documentation for class jdg.ch05.CGText
generating documentation for class jdg.ch05.CGrid
generating documentation for class jdg.ch05.KeyboardInput
generating documentation for class jdg.ch05.Point
generating documentation for class jdg.ch05.PrintCGrid
generating documentation for interface jdg.ch06.CGTextEdit
generating documentation for interface jdg.ch06.ColorConstants
generating documentation for class jdg.ch06.CGText
generating documentation for class jdg.ch06.CGTextBox
generating documentation for class jdg.ch06.CGTextPoint
Generating index
Sorting 90 items . . . done
Generating tree
C:\java\jdg\ch10>
As the result of that single command line, javadoc generates a complete set of HTML documentation for the software you produced in Chapters 5 , "Classes and Objects," and 6, "Interfaces." This documentation will have the same look and feel as the Java API documentation.
When javadoc has finished producing the documentation, use your browser to view it. I'll be using Netscape 2.0. It is my favorite browser, and it's Java compatible.
Launch your browser and use its local file open feature to open the file packages.html, located in the ch10 directory. Your browser will display a Sun-style Package Index page, as shown in Figure 10.1.
Figure 10.1 : The Package Index page.
This page looks great, but has two defects owing to the fact that it was not created in the same directory as your Java API. The link to the API User's Guide doesn't work, and your packages are mislabeled as Applet API packages. That's a small price to pay in order to avoid messing up your Java API directory. The rest of the links work fine.
With your browser open to the Package Index, click on the Class Hierarchy link. A Web page showing all the classes in the jdg.ch05 and jdg.ch06 packages is presented to you. The page shows how your classes fit within the rest of the Java class hierarchy. It also identifies the interfaces that are implemented by your classes. The information presented in the class hierarchy page is extremely useful in understanding the structure of Java programs. (See Figure 10.2.)
Figure 10.2 : The Class Hierarchy description page.
While you have the Class Hierarchy page loaded, click on the Index link. Another great Web page is displayed that contains an alphabetized index of all the fields (variables) and methods declared in the jdg.ch05 and jdg.ch06 packages. When I first saw this page, my immediate reaction was, "Where did all this come from?" Go ahead and click around this page to see some of the items that you've used in your programs. When you have finished, click on the All Packages link to go back to the Package Index. (See Figure 10.3.)
Figure 10.3 : The Index of all Fields and Methods page.
From the package index, click on the jdg.ch05 link. This will bring you into the Class Index for the jdg.ch05 package. This page documents the classes that are declared in this package. (See Figure 10.4.)
Figure 10.4 : The jdg. ch05 Class Index page.
From here, click on the BorderedPrintCGrid link. The class's description is displayed. Notice how it identifies the branch of the class hierarchy leading to the BorderedPrintCGrid class. You can click on the links in the class hierarchy branch to find out information about the variables and methods that are inherited by a class. A list of constructors appears under the class hierarchy diagram. Click on any of the constructor links to find a more detailed description of the constructors. (See Figure 10.5.)
Figure 10.5 : The BorderedPrintCGrid class page.
Under the constructor list is a list of access methods that are declared for the BorderedPrintCGrid class. The class-specific Web pages document only the public and protected variables, constructors, and methods of a class. To see a description of class variables, click on the link to the CGrid class, at the top of the BorderedPrintCGrid Web page. (See Figure 10.6.)
Figure 10.6 : The CGrid class page.
The CGrid class defines three protected variables: depth, grid, and width. You can click on the link to the depth variable to see how these variables are documented. (See Figure 10.7.)
Figure 10.7 : How javadoc variables .
You should now have a pretty good idea of the kind of documentation that can be produced using javadoc. The most remarkable fact about the documentation produced in this section is that you did not have to write a single comment in your source code. It was generated automatically and is far more effective than any traditional program comments. However, if this level of documentation is not enough to satisfy your requirements, you can insert additional comments in your source code that will be integrated with the documentation produced by javadoc.
Doc comments, as discussed in the beginning of this chapter, are normal C comments that begin with an extra asterisk. They are easy to insert into your Java programs, and they add implementation-specific information to your documentation. To show how they are used, I've added doc comments to the CGBox.java source code. These comments can be easily identified in the new program listing for CGBox. (See Listing 10.1.) I haven't included the whole listing, just the part where I've added doc comments.
Listing 10.1. The new CGBox.java.package jdg.ch05;
// CGBox.java
/**
* The CGBox class describes box objects that
* are displayed on a PrintCGrid.
*/
public class CGBox extends CGObject {
// Variable declarations
/**
* The lr is used to identify the lower right-hand
* corner of a box.
*/
protected Point lr; // Lower right corner of a box
// Method declarations
/**
* A CGBox object is constructed using an upper
* left-hand corner point, a lower right-hand corner
* point, and a box drawing character.
*/
public CGBox(Point ulCorner, Point lrCorner,char ch) {
location = ulCorner;
lr = lrCorner;
drawCharacter = ch;
}
You can see how these doc comments were integrated into the appropriate class, variable, and constructor descriptions by looking for them in my browser's display. (See Figure 10.8.)
Figure 10.8 : Doc comments as displayed by a browses.
javadoc tags are special tags that are inserted in doc comments. They are used to identify specific references in your code. Special javadoc tags are provided for documenting classes, variables, and methods.
javadoc tags consist of an at sign (@) followed by a tag type and then a specific comment reference. Their syntax is as follows:
@tagType commentReference
Java classes are allowed to use the see, version, and author tag types. Variables can use only the see tag type. Methods are allowed to use the see, param, return, and exception tag types.
The see tag type has the following syntax:
@see className
@see fullClassName
@see fullClassName#methodName
The version and author tag types are used like this:
@version versionID
@author authorName
The param, return, and exception tags are used as follows:
@param parameterName description
@return description
@exception fullClassName description
In order to demonstrate the use of these tags, I have modified the jdg.ch05.CGText.java file to include param tags. (See Listing 10.2.)
Listing 10.2. The new CGText./**
* @param p Text location
* @param s Text string
*/
public CGText(Point p,String s) {
location = p;
drawCharacter = ' ';
text = s;
}
Figure 10.9 shows how the javadoc tags are integrated by javadoc and displayed by my browser.
Figure 10.9 : The browser's display of the javadoc tags.
If the doc comments and javadoc tags still aren't enough to meet your documentation requirements, you can always insert your own HTML markup into a doc comment. However, using HTML is a little bit dangerous because your HTML tags might conflict with the HTML tags inserted by javadoc. If you're going to use HTML in your documentation, try to keep it as simple as possible.
I've modified the source code in CGPoint.java to include HTML address tags so that I can put my e-mail address in the doc comment. (See Listing 10.3.)
Listing 10.3. The new CGPoint.// CGPoint.java
/**
* Send your bug reports to:
* <ADDRESS>jamie@jaworski.com</ADDRESS>
*/
public class CGPoint extends CGObject {
// Method declarations
public CGPoint(int x, int y,char ch) {
location = new Point(x,y);
drawCharacter = ch;
}
Figure 10.10 shows how the HTML tags are integrated by javadoc and displayed by my browser.
Figure 10.10 : How a browser displays javadoc tags.
In this chapter you have learned how to use the Java documentation tool javadoc to automate the documentation of your software. You have used it to document the software you developed in Chapters 5 and 6. You have also learned how to use doc comments, javadoc tags, and HTML elements with javadoc. You have now covered most of the elements of the Java language and have learned how to use the compiler, interpreter, debuggger, and documentation generator. Chapter 11, "Language Summary," provides a complete description of the Java language before you move out of this part of the book and go on to the details of the Java API.