Using Java's Documentation
Comments
A
s explained in Part I, Java supports three types of comments. The first two are the //
and the /* */. The third type is called a documentation comment. It begins with the
character sequence /**. It ends with */. Documentation comments allow you to embed
information about your program into the program itself. You can then use the javadoc utility
program (supplied with the JDK) to extract the information and put it into an HTML file.
Documentation comments make it convenient to document your programs. You have almost
certainly seen documentation generated with javadoc, because that is the way the Java API
library was documented by Sun.
The javadoc Tags
The javadoc utility recognizes the following tags:
Tag
Meaning
@author
Identifies the author of a class.
{@code}
Displays information as-is, without processing HTML styles, in code font.
@deprecated
Specifies that a class or member is deprecated.
{@docRoot}
Specifies the path to the root director y of the current documentation.
@exception
Identifies an exception thrown by a method.
{@inheritDoc}
Inherits a comment from the immediate superclass.
{@link}
Inser ts an in-line link to another topic.
{@linkplain}
Inser ts an in-line link to another topic, but the link is displayed in a plain-text font.
{@literal}
Displays information as is, without processing HTML styles.
@param
Documents a method's parameter.
@return
Documents a method's return value.
@see
Specifies a link to another topic.
Search WWH :
