All Categories :
Java
Chapter 10
Automating Software Documentation
CONTENTS
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.

Contact
reference@developer.com with questions or comments.
Copyright 1998
EarthWeb Inc., All rights reserved.
PLEASE READ THE ACCEPTABLE USAGE STATEMENT.
Copyright 1998 Macmillan Computer Publishing. All rights reserved.