Java Reference
In-Depth Information
Of course, you can frame blocks like this in any way that you like, or even not at all, just so long as
there is /* at the beginning and */ at the end.
Documentation Comments
You can also include comments in a program that are intended to produce separate documentation for
the program. These are called documentation comments. All the documentation that you get with the
JDK is produced in this way. A program called javadoc, which contains the documentation comments,
produces the documentation once it is processed.
The documentation that is generated is in the form of HTML web pages that can be viewed using a
browser such as Netscape Navigator or Internet Explorer. A full discussion of documentation comments
is outside the scope of this topic - not because they are difficult, they aren't, but it would need a lot of
pages to cover them properly. We will just describe them sufficiently so that you will recognize
documentation comments when you see them.
A documentation comment begins with /** and ends with */. An example of a simple documentation
comment is:
/**
* This is a documentation comment.
*/
Any asterisks at the beginning of each line in a documentation comment are ignored, as are any spaces
preceding the first *.
A documentation comment can also include HTML tags, as well as special tags beginning with @ that
are used to document methods and classes in a standard form. The @ is followed by a keyword that
defines the purpose of the tag. Here are some of the keywords that you can use:
@author
Used to define the author of the code.
@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.
@exception
Used to document exceptions that the code can throw and the circumstance
which can cause this to occur.
{@link}
Generates a link to another part of the documentation within the
documentation that is produced. The curly brackets are used to separate it
from the rest of the in-line text.
@param
Used to describe the parameters for a method.
@return
Used to document the value returned from a method.
@see
Used to specify cross references to some other part of the code such as
another class or a method. It can also reference a URL.
@throws
A synonym for
@exception
.
@version
Used to describe the current version of the code.
