📄 tij0039.html
字号:
<html><body>
<table width="100%"><tr>
<td>
<a href="http://www.bruceeckel.com/javabook.html">Bruce Eckel's Thinking in Java</a>
</td>
<td align="right">
<a href="tij_c.html">Contents</a> | <a href="tij0038.html">Prev</a> | <a href="tij0040.html">Next</a>
</td>
</tr></table>
<hr>
<H2 ALIGN=LEFT>
Comments
and embedded documentation
<P><A NAME="Index81"></A><A NAME="Index82"></A></H2>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">There
are two types of comments in Java. The first is the traditional C-style comment
that was inherited by C++. These comments begin with a
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>/*</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
and continue, possibly across many lines, until a
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>*/</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">.
Note that many programmers will begin each line of a continued comment with a
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>*</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">,
so you’ll often see:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">/*
This is
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
A comment that continues
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
Across lines
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*/</FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Remember,
however, that everything inside the
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>/*</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
and
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>*/</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
is ignored so it’s no different to say:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">/*
This is a comment that
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">continues
across lines */
</FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">The
second form of comment comes from C++. It is the single-line comment, which
starts at a
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>//</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
and continues until the end of the line. This type of comment is convenient and
commonly used because it’s easy. You don’t need to hunt on the
keyboard to find
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>/</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
and then
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>*</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
(you just press the same key twice), and you don’t need to close the
comment. So you will often see:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">//
this is a one-line comment
</FONT></TT><P></DIV><DIV ALIGN=LEFT><a name="_Toc375545235"></a><a name="_Toc408018436"></a><P></DIV>
<A NAME="Heading82"></A><H3 ALIGN=LEFT>
Comment
documentation
</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">One
of the thoughtful parts of the Java language is that the designers didn’t
consider writing code to be the only important activity – they also
thought about documenting it. Possibly the biggest problem with documenting
code has been maintaining that documentation. If the documentation and the code
are separate, it becomes a hassle to change the documentation every time you
change the code. The solution seems simple: link the code to the documentation.
The easiest way to do this is to put everything in the same file. To complete
the picture, however, you need a special comment syntax to mark special
documentation and a tool to extract those comments and put them in a useful
form. This is what Java has done.
</FONT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">The
tool to extract the comments is called
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><I>javadoc.</I></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
It uses some of the technology from the Java compiler to look for special
comment tags you put in your programs. It not only extracts the information
marked by these tags, but it also pulls out the class name or method name that
adjoins the comment. This way you can get away with the minimal amount of work
to generate decent program documentation.
</FONT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">The
output of javadoc is an HTML file that you can view with your Web browser. This
tool allows you to create and maintain a single source file and automatically
generate useful documentation. Because of javadoc we have a standard for
creating documentation, and it’s easy enough that we can expect or even
demand documentation with all Java libraries.
</FONT><a name="_Ref348399283"></a><a name="_Toc375545236"></a><a name="_Toc408018437"></a><P></DIV>
<A NAME="Heading83"></A><H3 ALIGN=LEFT>
Syntax</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">All
of the javadoc commands occur only within
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>/**</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
comments. The comments end with
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>*/
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">as
usual. There are two primary ways to use javadoc: embed HTML, or use “doc
tags.” Doc tags are commands that start with a ‘
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>@</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">’
and are placed at the beginning of a comment line. (A leading ‘
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>*</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">’,
however, is ignored.)
</FONT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">There
are three “types” of comment documentation, which correspond to the
element the comment precedes: class, variable, or method. That is, a class
comment appears right before the definition of a class; a variable comment
appears right in front of the definition of a variable and a method comment
appears right in front of the definition of a method. As a simple example:
</FONT><P></DIV>
<font color="#990000"><PRE><font color="#009900">/** A class comment */</font>
<font color="#0000ff">public</font> <font color="#0000ff">class</font> docTest {
<font color="#009900">/** A variable comment */</font>
<font color="#0000ff">public</font> <font color="#0000ff">int</font> i;
<font color="#009900">/** A method comment */</font>
<font color="#0000ff">public</font> <font color="#0000ff">void</font> f() {}
}</PRE></font><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Note
that javadoc will process comment documentation for only
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>public
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">and
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>protected
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">members.
Comments for
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>private
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">and
“friendly” (see Chapter 5) members are ignored and you’ll see
no output. (You can use the
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>-private
</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">flag
to include
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>private</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
members as well.) This makes sense, since only
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>public</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
and
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>protected</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
members are available outside the file, which is the client programmer’s
perspective. However, all
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B>class</B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
comments are included in the output.
</FONT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">The
output for the above code is an HTML file that has the same standard format as
all the rest of the Java documentation, so users will be comfortable with the
format and can easily navigate your classes. It’s worth entering the
above code, sending it through javadoc and viewing the resulting HTML file to
see the results.
</FONT><a name="_Toc375545237"></a><a name="_Toc408018438"></a><P></DIV>
<A NAME="Heading84"></A><H3 ALIGN=LEFT>
Embedded
HTML
</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Javadoc
passes HTML commands through to the generated HTML document. This allows you
full use of HTML; however, the primary motive is to let you format code, such as:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">/**</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
<pre>
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
System.out.println(new Date());
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
</pre>
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*/</FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">You
can also use HTML just as you would in any other Web document to format the
regular text in your descriptions:
</FONT><P></DIV><DIV ALIGN=LEFT><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">/**</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
You can <em>even</em> insert a list:
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
<ol>
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
<li> Item one
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
<li> Item two
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
<li> Item three
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*
</ol>
</FONT></TT><P><TT><FONT FACE="Courier New" SIZE=3 COLOR="Black">*/</FONT></TT><P></DIV><DIV ALIGN=LEFT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">Note
that within the documentation comment, asterisks at the beginning of a line are
thrown away by javadoc, along with leading spaces. Javadoc reformats everything
so that it conforms to the standard documentation appearance. Don’t use
headings such as
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B><h1></B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
or
</FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black"><B><hr></B></FONT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">
as embedded HTML because javadoc inserts its own headings and yours will
interfere with them.
</FONT><P></DIV><DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">All
types of comment documentation – class, variable, and method – can
support embedded HTML.
</FONT><a name="_Toc375545238"></a><a name="_Toc408018439"></a><P></DIV>
<A NAME="Heading85"></A><H3 ALIGN=LEFT>
@see:
referring to other classes
</H3>
<DIV ALIGN=LEFT><FONT FACE="Carmina Md BT" SIZE=3 COLOR="Black">All
three types of comment documentation can contain
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -