Comments and embedded documentation

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

There
are two types of comments in Java. The first is the traditional C-style comment
that was inherited by C++. These comments begin with a
/*
and continue, possibly across many lines, until a
*/.
Note that many programmers will begin each line of a continued comment with a
*,
so you’ll often see:

/*
This is

*
A comment that continues

*
Across lines

*/

Remember,
however, that everything inside the
/*
and
*/
is ignored so it’s no different to say:

/*
This is a comment that

continues
across lines */

The
second form of comment comes from C++. It is the single-line comment, which
starts at a
//
and continues until the end of the line. This type of comment is convenient and
commonly used because it’s easy. You don’t need to hunt on the
keyboard to find
/
and then
*
(you just press the same key twice), and you don’t need to close the
comment. So you will often see:

//
this is a one-line comment

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.

More by Author

Must Read