Java Reference
In-Depth Information
Table E-1
Commonly Used Javadoc Tags
(continued)
TAG NAME
DOCUMENTATION RESULT
SYNTAX
@see
Adds a See Also section with a link or text entry. A doc
@see
reference
comment may contain any number of @see tags, which are
all grouped under the same heading.
@throws
Adds a Throws section to describe the kind of data returned
@throws
class-name
to the method. It is a synonym for @exception.
description
In line 13 of Figure E-4 on page E.05, the @see tag instructs the Javadoc tool to add a See Also
heading to the program documentation, with a text entry that refers the user to the textbook, Java
Programming, Third Edition.
Line 14 in Figure E-4 shows a @author tag that instructs the Javadoc tool to add an Author head-
ing, followed by the specified name, to the program documentation. The HTML tag, HREF, instructs
the Javadoc tool to include a link to the Web site www.scsite.com.
Writing Doc Comments for the main() Method
Figure E-5 displays the doc comments for the main() method of the SampleJavadoc program. In
line 20, the @param tag is used to define the parameters that the main() method may use. In this
example, the parameter, args, is the parameter passed to the main() method. For multiple parameters,
you can list multiple @param tags. When the Javadoc tool executes, the @param tag tells it to add a
Parameter heading to the resulting HTML files.
18
/**
19
*
20
* The main method is where execution begins in a standalone program.
21
* @param args is the named parameter passed to main.
22
* @throws <code>IOException</code> in the case of illegal user input.
23
* @see BufferedReader
24
*/
25
public static void
main
(
String
[]
args
)
throws
IOException
26
{
FIGURE E-5
The @throws tag in line 22 allows you to document what kind of exception is thrown and when
that exception might occur. The @throws tag also uses a general HTML tag,
<code>,
and its closing
tag, </code>, to create a link to the API documentation
.
In the case of @throws, if the exception is a
Java-defined exception, you can enter the exception name between the opening and closing <code>
tags; Javadoc will convert the text into a link when it generates HTML-formatted documentation.
The @see tag, as shown in line 23 of Figure E-5, is used to enter other Java keywords, methods, and
data types that are related to the class or method. Again, Javadoc automatically will create a link to the
API documentation for these keywords, methods, or data types when it generates HTML-formatted
documentation.
Search WWH ::
Custom Search