Java Reference
In-Depth Information
KEYWORD DESCRIPTION
@author
Used to define the author of the code. For example, I could specify that I am the author by adding the
tag:
/**
* @author Ivor Horton
*/
@deprecated
Used in the documentation of library classes and methods to indicate that they have been superseded and
generally should not be used in new applications. This is primarily used within the class libraries to
identify obsolete methods.
@exception
Used to document exceptions that the code can throw and the circumstance that can cause this to occur.
For example, you might add the following documentation comment preceding your definition of a meth-
od to indicate the type of exception that the method may throw:
/**
* @exception IOException When an I/O error occurs.
*/
Generates a link to another part of the documentation within the documentation that is produced. You
can use this tag to embed a link to another class or method within descriptive text for your code. The
curly brackets are used to separate the link from the rest of the in-line text.
{@link}
Used to describe the parameters for a method.
@param
Used to document the value returned from a method.
@return
Used to specify cross-references to some other part of the code such as another class or a method. For
example:
/**
* @see Object#clone()
*/
It can also just specify a string that represents an external reference not identifiable by a URL. For ex-
ample:
/**
* @see "Beginning Java 7"
*/
It can also reference a URL.
@see
A synonym for
@exception
.
@throws
Used to describe the current version of the code.
@version
You can use any HTML tags within a documentation comment except for header tags. The HTML tags
you insert are used to structure and format the documentation appropriately when it is viewed, and
javadoc
adds HTML tags to format the comments that include the special
@
tags that I mentioned in the preceding
table.
The outline here really only gives you a hint as to what documentation comments are and doesn't do
justice to the power and scope of
javadoc
. For that you need to look into it in detail. If you want to see real
examples of
javadoc
comments, take a look at one or other of the source code files for the library classes.
The SDK comes with the
javadoc
program and its documentation.
javadoc
also has its own home page on
the Javasoft website at
www.oracle.com/technetwork/java/javase/documentation/javadoc-137458.html
.
SUMMARY
In this chapter you have seen all of the basic types of variables that are available in Java. All other types that
you define for yourself are ultimately defined in terms of these primitive types. The discussion of
boolean
