October 31, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Automatic Code Documentation with javadoc

  • August 31, 2000
  • By David Reilly
  • Send Email »
  • More Articles »

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

When it comes to documenting code, the free

javadoc
tool that ships with JDK makes life simple. Most readers will be familiar with the Java API documentation, which covers all the various packages and classes that make up the ever-growing core API. This is a set of beautifully rendered HTML pages. HTML is a convenient and platform-independent way of distributing documentation (either from a Web site or an intranet server, or as an archive in ZIP or TAR format that can be downloaded for offline reading). Individual classes, member variables, and methods are covered in rich detail, and hyperlinks within the documentation make it easy to jump from one section to another. You may be surprised to know that the
javadoc
tool was used to create this documentation. You'll probably be even more surprised to know that you too can produce the same style of documentation for all your code.

The

javadoc
tool works by reading your original Java source files (ending in a .java extension), and producing a set of HTML pages. It works automatically, and will include all of the methods and fields of a class (though by default, anything marked as private is omitted). However, unless you have meaningful method and parameter names, the quality of information produced is fairly limited. It is up to you, as the programmer, to give
javadoc
some assistance and provide comments for all of the important methods and member variables.

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
you need to use a special type of comment. People reading your documentation won't want to look inside your source code files to understand how things work — and if you distribute the binaries for your system, they may not even have the source code. So a special type of comment is used, one that distinguishes comments within code meant for developers creating and modifying the system from comments meant for developers who are using your classes. These comments, referred to as
javadoc
-style comments, will be used as the text description in the HTML documentation. 

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

/**
and end with a
*/
. You may even be using
/* */
comments already — but note that
javadoc
comments start with a double asterisk. As a general rule, you should place comments before every class, to offer a brief description of what the purpose of the class is, and before every non-private member variable and method.

In order to understand

javadoc
comments, you need to see how they are written. Let's look at a sample class, MyClass, which has a public member variable, a constructor, and two methods.

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
is run on this source file, the following HTML page is produced. The documentation generated by the
javadoc
tool for this class is a good start, but there is no indication of how the constructor works, or the methods, or even the meaning of the MESSAGE member variables. To fill in the blanks,
javadoc
comments need to be added. Examine the comments carefully, and see how they work.

/**
  *  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
again over MyClass.java reveals an impressive difference in the resulting HTML output . If you look closely at the comments, you'll see that there is more information passed to
javadoc
than just text comments. Special parameters can also be passed, to allow tighter control over documentation. For example, in the
printMessage
method, there are two parameter descriptions and an exception description specified, by using the
@param
and
@throws
tags. These illustrate a fraction of the many tags that
javadoc
supports, however. The following table shows list of common javadoc tags supported by Java. Coverage of further tags can be found in Resources below.

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
comments as you write code, so that it doesn't become a big job towards the end of the project. In addition, this practice gives you the opportunity to produce documentation part-way through a project, which can assist other developers, and even you. As you work with code, you'll have easy-to-navigate HTML documentation of all the classes in your project.

Generating the Documentation

The easiest part of

javadoc
is producing the HTML pages. It's a fairly fast process, but slows down a little as the number of classes in a project increases. You can do documentation builds as frequently as you require them. Since it is an automated process, there's no need to rewrite documentation as changes to a class are made. Simply generate the documentation again, and the changes will be incorporated.

The

javadoc
tool can be found in your JDK\bin directory, so if you have a path statement set you can run the
javadoc
tool from your source code directory. Simply specify all of the source files (using wildcards if possible) and any optional parameters you require. There are plenty of parameters, and if you use
javadoc
frequently, you'll probably want to familiarize yourself with their features. To start, though, let's look at the command-line parameters to generate the documentation for MyClass.

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
HTML pages (in this case, the core Java API). Without this parameter, references to external classes (like String in the case of MyClass) won't be hyperlinked. To see the final documentation, 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.






Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel