tij0039.html

学习java的经典书籍

</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>@see</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
tags, which allow you to refer to the documentation in other classes. Javadoc
will generate HTML with the 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>@see</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
tags hyperlinked to the other documentation. The forms are:
</FONT><P></DIV>

<font color="#990000"><PRE>@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name </PRE></font><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Each
one adds a hyperlinked &#8220;See Also&#8221; entry to the generated
documentation. Javadoc will not check the hyperlinks you give it to make sure
they are valid.
</FONT><a name="_Toc375545239"></a><a name="_Toc408018440"></a><P></DIV>
<A NAME="Heading86"></A><H3 ALIGN=LEFT>
Class
documentation tags
</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Along
with embedded HTML and 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>@see
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">references,
class documentation can include tags for version information and the
author&#8217;s name. Class documentation can also be used for 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><I>interfaces</I></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
(described later in the book).
</FONT><P></DIV>
<A NAME="Heading87"></A><H4 ALIGN=LEFT>
@version</H4>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">This
is of the form:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">@version
version-information
</FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">in
which 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>version-information</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
is any significant information you see fit to include. When the 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>-version</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
flag is placed on the javadoc command line, the version information will be
called out specially in the generated HTML documentation.
</FONT><P></DIV>
<A NAME="Heading88"></A><H4 ALIGN=LEFT>
@author</H4>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">This
is of the form:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">@author
author-information
</FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">in
which 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>author-information</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
is, presumably, your name, but it could also include your email address or any
other appropriate information. When the 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>-author
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">flag
is placed on the javadoc command line, the author information will be called
out specially in the generated HTML documentation.
</FONT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">You
can have multiple author tags for a list of authors, but they must be placed
consecutively. All the author information will be lumped together into a single
paragraph in the generated HTML.
</FONT><a name="_Toc375545240"></a><a name="_Toc408018441"></a><P></DIV>
<A NAME="Heading89"></A><H3 ALIGN=LEFT>
Variable
documentation tags
</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Variable
documentation can include only embedded HTML and 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>@see</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
references.
</FONT><a name="_Toc375545241"></a><a name="_Toc408018442"></a><P></DIV>
<A NAME="Heading90"></A><H3 ALIGN=LEFT>
Method
documentation tags
</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">As
well as embedded documentation and 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>@see</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
references, methods allow documentation tags for parameters, return values, and
exceptions.
</FONT><P></DIV>
<A NAME="Heading91"></A><H4 ALIGN=LEFT>
@param</H4>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">This
is of the form:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">@param
</FONT></TT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black"><I>parameter</I></FONT></TT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">-</FONT></TT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black"><I>name</I></FONT></TT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">
</FONT></TT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black"><I>description</I></FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">in
which 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>parameter-name
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">is
the identifier in the parameter list, and 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>description
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">is
text that can continue on subsequent lines. The description is considered
finished when a new documentation tag is encountered. You can have any number
of these, presumably one for each parameter.
</FONT><P></DIV>
<A NAME="Heading92"></A><H4 ALIGN=LEFT>
@return</H4>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">This
is of the form:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">@return
</FONT></TT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black"><I>description</I></FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">in
which 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>description</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
gives you the meaning of the return value. It can continue on subsequent lines.
</FONT><P></DIV>
<A NAME="Heading93"></A><H4 ALIGN=LEFT>
@exception</H4>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Exceptions
will be described in Chapter 9, but briefly they are objects that can be
&#8220;thrown&#8221; out of a method if that method fails. Although only one
exception object can emerge when you call a method, a particular method might
produce any number of different types of exceptions, all of which need
descriptions. So the form for the exception tag is:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">@exception
</FONT></TT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black"><I>fully-qualified-class-name
description
</I></FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">in
which 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>fully-qualified-class-name</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
gives an unambiguous name of an exception class that&#8217;s defined somewhere,
and 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>description</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
(which can continue on subsequent lines) tells you why this particular type of
exception can emerge from the method call.
</FONT><P></DIV>
<A NAME="Heading94"></A><H4 ALIGN=LEFT>
@deprecated</H4>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">This
is new in Java 1.1<A NAME="Index83"></A>.
It is used to tag features that were superseded by an improved feature. The
deprecated tag is a suggestion that you no longer use this particular feature,
since sometime in the future it is likely to be removed. Methods that are marked 
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>@deprecated</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
cause the compiler to issue warnings if it is used.
</FONT><a name="_Toc375545242"></a><a name="_Toc408018443"></a><P></DIV>
<A NAME="Heading95"></A><H3 ALIGN=LEFT>
Documentation
example
</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
Here is the first Java program again, this time with documentation comments
added:
</FONT><P></DIV>

<font color="#990000"><PRE><font color="#009900">//: Property.java</font>
<font color="#0000ff">import</font> java.util.*;

<font color="#009900">/** The first Thinking in Java example program.
 * Lists system information on current machine.
 * @author Bruce Eckel
 * @author http://www.BruceEckel.com
 * @version 1.0 
*/</font>
<font color="#0000ff">public</font> <font color="#0000ff">class</font> Property {
  <font color="#009900">/** Sole entry point to class &amp; application
   * @param args array of string arguments
   * @return No return value
   * @exception exceptions No exceptions thrown
  */</font>
  <font color="#0000ff">public</font> <font color="#0000ff">static</font> <font color="#0000ff">void</font> main(String[] args) {
    System.out.println(<font color="#0000ff">new</font> Date());
    Properties p = System.getProperties();
    p.list(System.out);
    System.out.println("--- Memory Usage:");
    Runtime rt = Runtime.getRuntime();
    System.out.println("Total Memory = "
                       + rt.totalMemory()
                       + " Free Memory = "
                       + rt.freeMemory());
  }
} <font color="#009900">///:~ </PRE></font></font><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">The
first line:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">
  //: Property.java
</FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">uses
my own technique of putting a &#8216;
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>:</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">&#8217;
as a special marker for the comment line containing the source file name. The
last line also finishes with a comment, and this one indicates the end of the
source code listing, which allows it to be automatically extracted from the
text of the book and checked with a compiler. This is described in detail in
Chapter 17.
</FONT><a name="_Toc375545243"></a><a name="_Toc408018444"></a><a name="_Toc312373851"></a><P></DIV>

<div align="right">
<a href="tij_c.html">Contents</a> | <a href="tij0038.html">Prev</a> | <a href="tij0040.html">Next</a>
</div>
</body></html>