| 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:
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
This is
*
A comment that continues
*
Across lines
*/
Remember,
however, that everything inside the
/*
and
*/
is ignored so it’s no different to say:
however, that everything inside the
/*
and
*/
is ignored so it’s no different to say:
/*
This is a comment that
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:
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
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.
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.
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.
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.)
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:
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.
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.
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:
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:
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.
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:
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.
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).
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).
This
is of the form:
is of the form:
@version
version-information
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.
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.
This
is of the form:
is of the form:
@author
author-information
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.
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.
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
Method
documentation tags
As
well as embedded documentation and
@see
references, methods allow documentation tags for parameters, return values, and
exceptions.
well as embedded documentation and
@see
references, methods allow documentation tags for parameters, return values, and
exceptions.
This
is of the form:
is of the form:
@param
parameter-name
description
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.
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.
This
is of the form:
is of the form:
@return
description
description
in
which
description
gives you the meaning of the return value. It can continue on subsequent lines.
which
description
gives you the meaning of the return value. It can continue on subsequent lines.
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:
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
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.
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.
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.
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:
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:
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.
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.
