每天学一点Thinking in java: 6 注释和嵌入文档
注释和嵌入文档(Comments and embedded documentation)
Java里有两种类型的注释。第一种是传统的、C语言风格的注释，是从C++继承而来的。
注释用一个“/*”起头，随后是注释内容，并可跨越多行，最后用一个“*/”结束。
/* 这是
* 一段注释，
* 它跨越了多个行
*/
但请记住，进行编译时，/*和*/之间的所有东西都会被忽略，所以上述注释与下面这段注释并没有什么不同：
/* 这是一段注释，
它跨越了多个行 */
第二种类型的注释也起源于C++。这种注释叫作“单行注释”，以一个“//”起头，表示这一行的所有内容都是注释。这种类型的注释更常用，因为它书写时更方便。没有必要在键盘上寻找“/”，再寻找“*”（只需按同样的键两次），而且不必在注释结尾时加一个结束标记。下面便是这类注释的一个例子：
// 这是一条单行注释
注释文档
用于提取注释的工具叫作javadoc。它采用了部分来自Java编译器的技术，查找我们置入程序的特殊注释标记。它不仅提取由这些标记指示的信息，也将毗邻注释的类名或方法名提取出来。这样一来，我们就可用最轻的工作量，生成十分专业的程序文档。
javadoc输出的是一个HTML文件，可用自己的Web浏览器查看。该工具允许我们创建和管理单个源文件，并生动生成有用的文档。
所有javadoc命令都只能出现于“/**”注释中，注释结束于“*/”。
有两种方式来使用javadoc：
- 嵌入HTML，
- 使用 “文档标记”（Doc tags）, 文档标记是以“@”开头的命令，置于注释行的起始处（但前导的“*”会被忽略）。
有三种类型的注释文档，它们对应于位于注释后面的元素：类、变量或者方法。
类注释在一个类定义之前；
变量注释在变量定义之前；
方法注释在方法定义的前面。
如下例所示：
/** 一个类注释 */
public class docTest {
/** 一个变量注释 */
public int i;
/** 一个方法注释 */
public void f() {}
}
注意javadoc只能为public（公共）和protected（受保护）成员处理注释文档。“private”（私有）和“友好”（详见5章）成员的注释会被忽略，我们看不到任何输出（也可以用-private标记包括private成员）。这样做的理由是，因为只有public和protected成员才可在文件之外使用。所有类注释都会包含到输出结果里。
嵌入HTML
javadoc将HTML命令传递给最终生成的HTML文档。这便能充分利用HTML。这样做的最终目的还是格式化代码。
见下例：
/**
*
* System.out.println(new Date());
*
*/
也可以像在Web文档里使用HTML一样，对普通文本进行格式化，使其更具条理、更加美观：
/**
* 您甚至可以插入一个列表：
*
* - 项目一
*
- 项目二
*
- 项目三
*
*/
注意在文档注释中，每行最开头的星号会被javadoc忽略。同时忽略的还有前方空格（leading spaces）。javadoc会对所有内容进行格式化，使其与标准的文档外观相符。不要将或
所有类型的注释文档——类、变量和方法——都支持嵌入HTML。
@see：引用其他类
所有三种类型的注释文档都可包含@see标记，它允许我们引用其他类里的文档。对于这个标记，javadoc会生成相应的HTML，将其直接链接到其他文档。格式如下：
@see 类名
@see 完整类名
@see 完整类名#方法名
每一格式都会在生成的文档里自动加入一个超链接的“See Also”（参见）条目。注意javadoc不会检查我们指定的超链接，不会验证它们是否有效。
类文档标记
随同嵌入HTML和@see引用，类文档还可以包括用于版本信息以及作者姓名的标记。类文档亦可用于“接口”。
-
@version
格式如下：
@version 版本信息
其中，“版本信息”代表任何适合作为版本说明的资料。在javadoc命令行使用“-version”标记会从生成的HTML文档里提取出版本信息。 -
@author
格式如下：
@author 作者信息
其中，“作者信息”包括姓名、电子函件地址或者其他任何适合的资料。在javadoc命令行使用了“-author”标记会专门从生成的HTML文档里提取出作者信息。
可为一系列作者使用多个这样的标记，但这些必须连续放置。全部作者信息会一起存入最终HTML代码的单独一个段落里。
变量文档标记
变量文档只能包括嵌入的HTML以及@see引用。
方法文档标记
除嵌入HTML和@see引用之外，方法还允许使用针对参数、返回值以及违例的文档标记。
-
@param
格式如下：
@param 参数名 说明
其中，“参数名”是指参数列表内的标识符，而“说明”代表一些可延续到后续行内的说明文字。一旦遇到一个新文档标记，就认为前一个说明结束。可使用任意数量的说明，每个参数一个。 -
@return
格式如下：
@return 说明
其中，“说明”是指返回值的含义，可延续到后面的行内。 -
@exception
有关“异常”（Exception）的详细情况。调用一个方法时，尽管只有一个异常对象出现，但一些特殊的方法也许能产生任意数量且不同类型的异常。所有的异常都需要说明。异常标记的格式如下：
@exception 完整类名 说明
其中，“完整类名”明确指定了一个违例类的名字，可以是在其他某个地方定义好的。而“说明”则解释为什么这个异常会在方法调用中出现。 -
@deprecated
该标记用于指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。
文档示例
下面还是我们的第一个Java程序，只不过已加入了完整的文档注释：
//: object/HelloDate.java
import java.util.*;
/** The first Thinking in Java example program.
* Displays a string and today’s date.
* @author Bruce Eckel
* @author www.MindView.net
* @version 4.0
*/
public class HelloDate {
/** Entry point to class & application.
* @param args array of string arguments
* @throws exceptions No exceptions thrown
*/
public static void main(String[] args) {
System.out.println("Hello, it’s: ");
System.out.println(new Date());
}
} /* Output: (55% match)
Hello, it’s:
Wed Oct 05 14:39:36 MDT 2005