A Javadoc™  Primer

Printer Friendly Version

For most experienced Java programmers, the Javadoc tool that generates API documentation for a Java application is second nature.  However, to those of us newer to the Java world, this is not so.  Even though the basic features of Javadoc are not difficult to master, as with many things programming , it's not immediately intuitive if you’re not used to working with it.

Over recent months, I have had the opportunity to explore Javadoc and use it in a practical application. In this article I’d like to pass along what I learned to help get you up and running with documenting your Java intranet applications.  Before we start, however, lets cover a little background.

What is Javadoc?
Javadoc is an API documentation tool that comes as part of a standard Java Development Kit (JDK) distribution.  For this reason, before you can use Javadoc, you must download the JDK first (which you probably have already done or you wouldn’t have developed anything needing documentation!).  The Javadoc executable is located in the /bin directory of the JDK installation.  All things Javadoc, including a much more in-depth discussion and instruction on using it can be found here. 

In this article I will be giving you a step by step instroduction to the basics of Javadoc, but for a more advanced and unabridged treatment of the subject, this is the site to visit.

In a nutshell, Javadoc allows you to use special syntax within your Java classes and packages to denote comments.  Within those comments you can use regular text, HTML, and Javadoc tags to identify information you wish to include in your documentation.  The Javadoc tool adds a lot of the standard documentation for you, behind the scenes, based on your actual Java code.  For example, it automatically generates the details regarding an object’s hierarchy, scope, the interfaces it implements, and known subclasses based on the syntax and content of your code.  The tool is just that smart and makes your life much easier right off the bat.

If you’ve been developing in Java already, for certain, you will have reviewed the standard Java API.  If not, you can find the latest version 1.4 specification here.   The HTML look and feel of the standard (and all) Java API’s is what you’ll be generating for your own applications using Javadoc.

Entering Javadoc comments in your code
Basically a Javadoc comment is entered into your code as follows:

/**

*Comments and more comments

*

*@tag      comments for your tag

*/

A Javadoc comment is made up of a leading /** and an ending */ to let the compiler and Javadoc tool know this is a block of Javadoc comments.  In between are your comments in plain text (you can use HTML tags to format and make them more readable (such as <p> to separate paragraphs, <b></b> to bold, etc.)) and optionally one or more Javadoc tags followed by the tag’s description.

Comments should be written in a way that you only have to write them once and they will apply anywhere this code might be implemented.  Also, keep in mind that Javadoc will reuse your comments for methods that override or implement other methods.

Placement of your Javadoc comments is critical.  They must be placed immediately before the class or method they pertain to and only one Javadoc block per object is allowed.  If you place them elsewhere or have multiple blocks, your comments will not be picked up when the Javadoc is generated.

The finer points of writing comments can be found in the reference “How to Write Comments for the Javadoc™ Tool”.

Earlier I mentioned the Javadoc tags.  Javadoc tags are special tags you embed within your Javadoc comments that enable you to automatically generate a complete, well-formatted API from your source code.  Tags are case-sensitive and begin with the @ sign.  A tag must appear at the beginning of a line (after the optional *) or they will be treated as normal text.   It is recommended you group tags with the same name together.  I will discuss a few of the more commonly used tags here. 

@author  name-text value

Adds an author entry with the specified name-text value you enter after the tag.You can specify multiple authors by either using multiple @author tags or separating the name-text values by commas.  For example:

@author Jane Doe, John Smith

      Or

@author Jane Doe

@author John Smith

@param parameter name  description

Adds a parameter name and its description to the parameter listing for a method.

@see reference

Adds a “see also” heading with a link or text entry to the reference you specify.  For example:

@see java.lang.String

@throws class-name description

The @throws and @exception tags are synonymous.  They specify the name of the exception that a method will throw.

For a complete listing of tags and their usage, refer to the “Javadoc™-The Java API Generator”.   

Go to page: 1  2