Creating Documentation with Javadoc - Java Programming: Comprehensive Concepts and Techniques - page 951

Writing Doc Comments
Recall from Chapter 2 that two types of comments are used in Java programming: line comments and
block comments. Line comments are used to provide documentation for single lines of code or for
short descriptions and documentation comments. A line comment, as shown in line 15 of Figure E-2
on page E.03, begins with two forward slashes (//) that cause the line to be ignored during compilation
and execution. Line comments have no ending symbol.
Block comments are used as headers at the beginning of the program or when long descriptions
are appropriate. As shown in lines 1 through 7 of Figure E-2 on page E.03, a block comment begins
with a forward slash followed by an asterisk (/*) and ends with the symbols reversed, an asterisk fol-
lowed by a forward slash (*/).
A second type of block comment — called a doc comment, or a documentation comment — uses
special notation that allows programmers to create HTML-formatted program documentation. A doc
comment is placed in the code just before the declaration of the package, class, or method it describes;
the doc comment begins with a forward slash followed by two asterisks (/**) and ends with an asterisk
followed by a forward slash (*/).
The doc comments then can be extracted to HTML files using the Javadoc tool. Using doc com-
ments does not mean you are required to generate HTML files using the Javadoc tool. By using doc
comments, however, you leave the option open in the event that you later decide to create program
documentation in HTML using the Javadoc tool. Moreover, because doc comments follow a standard
style, other programmers will have an easier time reading code with doc comments than reading code
with a non-standard style of comments.
Writing Doc Comments for the SampleJavadoc Class
Figure E-4 displays the doc comments for the SampleJavadoc class. The doc comment is placed in
the code just before the class declaration and begins with a forward slash followed by two asterisks
(/**) on a line with no other code (line 11). The doc comment ends with the */ symbol (line 15). The
doc comment can span as many lines as necessary within the beginning and ending marks. Typically,
each line within a block comment begins with an asterisk and is indented for ease of reading.
11 /**
12 * This class presents a simple input/output program to demonstrate javadoc.
13 * @see "Java Programming, Third Edition"
14 * @author <A HREF="http://www.scsite.com/">Shelly/Cashman/Starks</A>
15 */
16 public class SampleJavadoc
17 {
FIGURE E-4