【JAVA】注释和嵌入文档

注释和嵌入文档(Comments and embedded documentation)

Java里有两种类型的注释。第一种是传统的、C语言风格的注释，是从C++继承而来的。
注释用一个“/*”起头，随后是注释内容，并可跨越多行，最后用一个“*/”结束。

/* 这是
* 一段注释，
* 它跨越了多个行
*/

但请记住，进行编译时，/*和*/之间的所有东西都会被忽略，所以上述注释与下面这段注释并没有什么不同：

/* 这是一段注释，
它跨越了多个行 */

第二种类型的注释也起源于C++。这种注释叫作“单行注释”，以一个“//”起头，表示这一行的所有内容都是注释。这种类型的注释更常用，因为它书写时更方便。没有必要在键盘上寻找“/”，再寻找“*”（只需按同样的键两次），而且不必在注释结尾时加一个结束标记。下面便是这类注释的一个例子：

// 这是一条单行注释

注释文档
用于提取注释的工具叫作javadoc。它采用了部分来自Java编译器的技术，查找我们置入程序的特殊注释标记。它不仅提取由这些标记指示的信息，也将毗邻注释的类名或方法名提取出来。这样一来，我们就可用最轻的工作量，生成十分专业的程序文档。
javadoc输出的是一个HTML文件，可用自己的Web浏览器查看。该工具允许我们创建和管理单个源文件，并生动生成有用的文档。

所有javadoc命令都只能出现于“/**”注释中，注释结束于“*/”。
有两种方式来使用javadoc：

1. 嵌入HTML，
2. 使用 “文档标记”（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。这样做的最终目的还是格式化代码。
见下例：

/**
* <pre>
* System.out.println(new Date());
* </pre>
*/

也可以像在Web文档里使用HTML一样，对普通文本进行格式化，使其更具条理、更加美观：

/**
* 您<em>甚至</em>可以插入一个列表：
* <ol>
* <li> 项目一
* <li> 项目二
* <li> 项目三
* </ol>
*/

注意在文档注释中，每行最开头的星号会被javadoc忽略。同时忽略的还有前方空格（leading spaces）。javadoc会对所有内容进行格式化，使其与标准的文档外观相符。不要将<h1>或<hr>这样的标题当作嵌入HTML使用，因为javadoc会插入自己的标题。
所有类型的注释文档——类、变量和方法——都支持嵌入HTML。

@see：引用其他类
所有三种类型的注释文档都可包含@see标记，它允许我们引用其他类里的文档。对于这个标记，javadoc会生成相应的HTML，将其直接链接到其他文档。格式如下：

@see 类名
@see 完整类名
@see 完整类名#方法名

每一格式都会在生成的文档里自动加入一个超链接的“See Also”（参见）条目。注意javadoc不会检查我们指定的超链接，不会验证它们是否有效。

类文档标记
随同嵌入HTML和@see引用，类文档还可以包括用于版本信息以及作者姓名的标记。类文档亦可用于“接口”。

1. @version
   格式如下：
   @version 版本信息
   其中，“版本信息”代表任何适合作为版本说明的资料。在javadoc命令行使用“-version”标记会从生成的HTML文档里提取出版本信息。

2. @author
   格式如下：
   @author 作者信息
   其中，“作者信息”包括姓名、电子函件地址或者其他任何适合的资料。在javadoc命令行使用了“-author”标记会专门从生成的HTML文档里提取出作者信息。
   可为一系列作者使用多个这样的标记，但这些必须连续放置。全部作者信息会一起存入最终HTML代码的单独一个段落里。

变量文档标记
变量文档只能包括嵌入的HTML以及@see引用。

方法文档标记
除嵌入HTML和@see引用之外，方法还允许使用针对参数、返回值以及违例的文档标记。

1. @param
   格式如下：
   @param 参数名 说明
   其中，“参数名”是指参数列表内的标识符，而“说明”代表一些可延续到后续行内的说明文字。一旦遇到一个新文档标记，就认为前一个说明结束。可使用任意数量的说明，每个参数一个。

2. @return
   格式如下：
   @return 说明
   其中，“说明”是指返回值的含义，可延续到后面的行内。

3. @exception
   有关“异常”（Exception）的详细情况。调用一个方法时，尽管只有一个异常对象出现，但一些特殊的方法也许能产生任意数量且不同类型的异常。所有的异常都需要说明。异常标记的格式如下：
   @exception 完整类名 说明
   其中，“完整类名”明确指定了一个违例类的名字，可以是在其他某个地方定义好的。而“说明”则解释为什么这个异常会在方法调用中出现。

4. @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