Comments and embedded documentation

Bruce Eckel's Thinking in Java Contents | Prev | Next

Comment documentation

One of the thoughtful parts of the Java language is that the designers didn’t consider writing code to be the only important activity – they also thought about documenting it. Possibly the biggest problem with documenting code has been maintaining that documentation. If the documentation and the code are separate, it becomes a hassle to change the documentation every time you change the code. The solution seems simple: link the code to the documentation. The easiest way to do this is to put everything in the same file. To complete the picture, however, you need a special comment syntax to mark special documentation and a tool to extract those comments and put them in a useful form. This is what Java has done.

The tool to extract the comments is called javadoc. It uses some of the technology from the Java compiler to look for special comment tags you put in your programs. It not only extracts the information marked by these tags, but it also pulls out the class name or method name that adjoins the comment. This way you can get away with the minimal amount of work to generate decent program documentation.

Syntax

All of the javadoc commands occur only within /** comments. The comments end with */ as usual. There are two primary ways to use javadoc: embed HTML, or use “doc tags.” Doc tags are commands that start with a ‘ @’ and are placed at the beginning of a comment line. (A leading ‘ *’, however, is ignored.)

There are three “types” of comment documentation, which correspond to the element the comment precedes: class, variable, or method. That is, a class comment appears right before the definition of a class; a variable comment appears right in front of the definition of a variable and a method comment appears right in front of the definition of a method. As a simple example:

/** A class comment */
public class docTest {
  /** A variable comment */
  public int i;
  /** A method comment */
  public void f() {}
}

Note that javadoc will process comment documentation for only public and protected members. Comments for private and “friendly” (see Chapter 5) members are ignored and you’ll see no output. (You can use the -private flag to include private members as well.) This makes sense, since only public and protected members are available outside the file, which is the client programmer’s perspective. However, all class comments are included in the output.

Embedded HTML

Javadoc passes HTML commands through to the generated HTML document. This allows you full use of HTML; however, the primary motive is to let you format code, such as:

/**

* <pre>

* System.out.println(new Date());

* </pre>

*/

You can also use HTML just as you would in any other Web document to format the regular text in your descriptions:

/**

* You can <em>even</em> insert a list:

* <ol>

* <li> Item one

* <li> Item two

* <li> Item three

* </ol>

*/

Note that within the documentation comment, asterisks at the beginning of a line are thrown away by javadoc, along with leading spaces. Javadoc reformats everything so that it conforms to the standard documentation appearance. Don’t use headings such as <h1> or <hr> as embedded HTML because javadoc inserts its own headings and yours will interfere with them.

@see: referring to other classes

All three types of comment documentation can contain @see tags, which allow you to refer to the documentation in other classes. Javadoc will generate HTML with the @see tags hyperlinked to the other documentation. The forms are:

@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name

Class documentation tags

Along with embedded HTML and @see references, class documentation can include tags for version information and the author’s name. Class documentation can also be used for interfaces (described later in the book).

@version
This is of the form:

@version version-information

in which version-information is any significant information you see fit to include. When the -version flag is placed on the javadoc command line, the version information will be called out specially in the generated HTML documentation.

@author
This is of the form:

@author author-information

in which author-information is, presumably, your name, but it could also include your email address or any other appropriate information. When the -author flag is placed on the javadoc command line, the author information will be called out specially in the generated HTML documentation.

Variable documentation tags

Method documentation tags

As well as embedded documentation and @see references, methods allow documentation tags for parameters, return values, and exceptions.

@param
This is of the form:

@param parameter-name description

in which parameter-name is the identifier in the parameter list, and description is text that can continue on subsequent lines. The description is considered finished when a new documentation tag is encountered. You can have any number of these, presumably one for each parameter.

@return
This is of the form:

@return description

in which description gives you the meaning of the return value. It can continue on subsequent lines.

@exception
Exceptions will be described in Chapter 9, but briefly they are objects that can be “thrown” out of a method if that method fails. Although only one exception object can emerge when you call a method, a particular method might produce any number of different types of exceptions, all of which need descriptions. So the form for the exception tag is:

@exception fully-qualified-class-name description

in which fully-qualified-class-name gives an unambiguous name of an exception class that’s defined somewhere, and description (which can continue on subsequent lines) tells you why this particular type of exception can emerge from the method call.

@deprecated

Documentation example

Here is the first Java program again, this time with documentation comments added:

//: Property.java
import java.util.*;
 
/** The first Thinking in Java example program.
 * Lists system information on current machine.
 * @author Bruce Eckel
 * @author http://www.BruceEckel.com
 * @version 1.0 
*/
public class Property {
  /** Sole entry point to class &amp; application
   * @param args array of string arguments
   * @return No return value
   * @exception exceptions No exceptions thrown
  */
  public static void main(String[] args) {
    System.out.println(new Date());
    Properties p = System.getProperties();
    p.list(System.out);
    System.out.println("--- Memory Usage:");
    Runtime rt = Runtime.getRuntime();
    System.out.println("Total Memory = "
                       + rt.totalMemory()
                       + " Free Memory = "
                       + rt.freeMemory());
  }
} ///:~ 

The first line:

//: Property.java

uses my own technique of putting a ‘ :’ as a special marker for the comment line containing the source file name. The last line also finishes with a comment, and this one indicates the end of the source code listing, which allows it to be automatically extracted from the text of the book and checked with a compiler. This is described in detail in Chapter 17.



Comments

  • There are no comments yet. Be the first to comment!

Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Managing your company's financials is the backbone of your business and is vital to the long-term health and viability of your company. To continue applying the necessary financial rigor to support rapid growth, the accounting department needs the right tools to most efficiently do their job. Read this white paper to understand the 10 essentials of a complete financial management system and how the right solution can help you keep up with the rapidly changing business world.

  • With 81% of employees using their phones at work, companies have stopped asking: "Is corporate data leaking from personal devices?" and started asking: "How do we effectively prevent corporate data from leaking from personal devices?" The answer has not been simple. ZixOne raises the bar on BYOD security by not allowing email data to reside on the device. In addition, Zix allows employees to maintain complete control of their personal device, therefore satisfying privacy demands of valued employees and the …

Most Popular Programming Stories

More for Developers

Latest Developer Headlines

RSS Feeds