Writing API documentation for a system has to be one of the most unpleasant jobs a developer will ever face. Sure, maintenance programming and debugging are chores, but documentation is the kind of job that could drive you to despair. While others are cutting code, and designing cool systems, you’re stuck writing code documentation that people may only glance at, if they ever read it at all. Yet producing high-quality documentation is an important task, particularly if the system is to be maintained in the future by other developers. They’ll come into a new system, and without your polished guide to the project they’ll be totally baffled.
So if you do need to produce code documentation, it’s worth doing it right, and starting early. Leaving documentation till after the system is constructed makes it a nightmare to complete. Ideally, you need to start from day one of coding, and produce daily or weekly updates of the class documentation so that developers working on different parts of the system have easy access to information, such as the various methods and fields each class provides. But manually producing code documentation as frequently as you do a build would be a full-time job. You need a tool to automate the process and cut down some of the laborious and time-consuming tasks associated with producing code documentation. By using an automated tool, you can keep your design documentation, application code, and API documentation in sync. So what tool should you use?
The Solution Is
javadoc
javadoc
When it comes to documenting code, the free
javadoc |
javadoc |
The
javadoc |
javadoc |
What’s that? You already have comments in your code. Yes, comments are good, and help those reading the code understand what is going on — but to produce documentation using
javadoc |
javadoc |
Javadoc-style Comments Make Documentation Easy
Javadoc comments give developers good control over how documentation is produced. The comments may be plain text, or include HTML code for finer control over formatting. They start with the following character sequence
/** |
*/ |
/* */ |
javadoc |
In order to understand
javadoc |
public class MyClass
{
public static final String MESSAGE = "Hello World!";public MyClass()
{
// some initialization code would go here
}public void printMessage()
{
System.out.println (MESSAGE);
}public void printMessage(String prefix, String postfix)
{
if (prefix == null) throw new NullPointerException();
if (postfix == null) throw new NullPointerException();
System.out.print ( prefix );
System.out.print ( " " + MESSAGE );
System.out.println ( " " + postfix );
}
}
Listing 1. MyClass.java.
When
javadoc |
following HTML page
is produced. The documentation generated by the
javadoc |
javadoc |
/**
* MyClass is a sample class that demonstrates how javadoc HTML pages are
* produced. It doesn’t really do much, but is a helpful guide to good
* documentation generation.
*/
public class MyClass
{
/** Message to be displayed */
public static final String MESSAGE = "Hello World!";/** Creates a MyClass object, and initializes it */
public MyClass()
{
// some initialization code would go here
}/** Prints a message to standard output */
public void printMessage()
{
System.out.println (MESSAGE);
}/**
* Prints a message to standard output, preceded and
* followed by the specified strings.
*
* @param prefix String to be printed before message
* @param postfix String to be printed after message
* @throws NullPointerException Thrown if either prefix or postfix strings are null
*/
public void printMessage(String prefix, String postfix)
{
if (prefix == null) throw new NullPointerException();
if (postfix == null) throw new NullPointerException();
System.out.print ( prefix );
System.out.print ( " " + MESSAGE );
System.out.println ( " " + postfix );
}
}
Listing 2. MyClass.java with javadoc comments.
The results of running
javadoc |
resulting HTML output
. If you look closely at the comments, you’ll see that there is more information passed to
javadoc |
printMessage |
@param |
@throws |
javadoc |
|
Javadoc Comment Tags |
|
| @author | Indicates the author, or authors, of a class |
| @deprecated | Indicates that this section of the API is deprecated |
| @exception | Describes the reason for an exception |
| @param | Describes a method parameter |
| @return | Describes a return value |
| @see | Adds a hyperlink to a method, class, or URL |
| @throws | Describes the reason for an exception (see @exception) |
| @version | Describes the version of the source code. |
Table 1. Javadoc comment tags.
If you want to have good documentation, you need comments for every non-private member variable, method and class. This means that you should adopt the practice of putting in
javadoc |
Generating the Documentation
The easiest part of
javadoc |
The
javadoc |
javadoc |
javadoc |
javadoc -link http://java.sun.com/products/jdk/1.2/docs/api/ -nonavbar MyClass.java
You’ll notice that I’ve specified a ‘ -link ‘ parameter. This links documentation to an existing set of
javadoc |
click here
.
Summary
Automatic generation of code documentation doesn’t have to be a long and arduous process. Using a free tool that all developers using JDK will have at their disposal, you can create sophisticated looking HTML pages for all your classes. Not only will they look impressive, they’re also handy during development. Javadoc produced documentation is particularly useful if you’re working with other developers who are changing and "enhancing" classes by adding new methods and member variables. This way the entire development team can understand any changes.
Resources
JavaDoc Tool Documentation: http://java.sun.com/products/jdk/1.3/docs/tooldocs/javadoc/index.html
JavaDoc Comment Tags: http://java.sun.com/products/jdk/1.2/docs/tooldocs/win32/javadoc.html#javadoctags
About the Author
David Reilly is a software engineer and freelance technical writer living in Australia. A Sun Certified Java 1.1 Programmer, his research interests include the Java programming language, networking & distributed systems, and software agents. He can be reached via e-mail at java@davidreilly.com or his personal Web site.
