Comments and embedded documentation

---

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.

The

output of javadoc is an HTML file that you can view with your Web browser. This

tool allows you to create and maintain a single source file and automatically

generate useful documentation. Because of javadoc we have a standard for

creating documentation, and it’s easy enough that we can expect or even

demand documentation with all Java libraries.

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.

The

output for the above code is an HTML file that has the same standard format as

all the rest of the Java documentation, so users will be comfortable with the

format and can easily navigate your classes. It’s worth entering the

above code, sending it through javadoc and viewing the resulting HTML file to

see the results.

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.

All

types of comment documentation – class, variable, and method – can

support embedded HTML.

@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

Each

one adds a hyperlinked “See Also” entry to the generated

documentation. Javadoc will not check the hyperlinks you give it to make sure

they are valid.

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.

You

can have multiple author tags for a list of authors, but they must be placed

consecutively. All the author information will be lumped together into a single

paragraph in the generated HTML.

Variable
documentation tags

Variable

documentation can include only embedded HTML and

@see

references.

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

This

is new in Java 1.1

.
It is used to tag features that were superseded by an improved feature. The
deprecated tag is a suggestion that you no longer use this particular feature,
since sometime in the future it is likely to be removed. Methods that are marked
@deprecated
cause the compiler to issue warnings if it is used.

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 & 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.

Contents

|

Prev

|

Next