Java 注释和嵌入式文档 （Think in Java 3rd）
Java里有两种注释风格。一种是传统的C语言风格的注释，C++也继承了这种风格。此种注释以“/*”开始，随后是注释内容，并可跨越多行，最后以“*/”结束。注意，许多程序员在连续的注释内容的每一行都以一个“*”开头，所以经常看到像下面这样的写法：
/* This is a comment
* that continues
* across lines
*/
但请记住，进行编译时，/*和*/之间的所有东西都会被忽略，所以上述注释与下面这段注释并没有什么两样：
/* This is a comment that
continues across lines */
第二种风格的注释也源于C++。这种注释是“单行注释”，以一个“//”起头，直到句末。这种风格的注释因为书写容易，所以更方便、更常用。你无需在键盘上寻找“/”，再寻找“*”（而只需按两次同样的键），而且不必考虑结束注释。下面是这类注释的例子：
// This is a one-line comment
注释文档
Java语言一项更好的设计就是：程序代码的编写并不是唯一重要的事情——文档编写的重要性并不亚于程序代码本身。代码说明文档撰写的最大问题，大概就是对文档的维护了。如果文档与代码是分离的，那么在每次修变代码时，都需要修变相应的文档，这会成为一件相当麻烦的事情。解决的方法似乎很简单：将代码同文档“链接”起来。为达到这个目的，最简单的方法是将所有东西都放在同一个文件内。然而，为实现这一目的，还必须使用一种特殊的注释语法，来标记文档；此外也还需一个工具，用于提取这些注释，并将其转换成有用的形式。这正是Java所做的。
Javadoc便是用于提取注释的工具，它是JDK安装的一部分。它采用了Java编译器的某些技术，查找程序内的特殊注释标签。它不仅解析由这些标签标记的信息，也将毗邻注释的类名或方法名解析出来。如此，我们就可以用最少的工作量，生成相当好的程序文档。
javadoc输出的是一个HTML文件，你可以用自己的Web浏览器来查看。这样，该工具就使得我们只需创建和维护单一的源文件，并能自动生成有用的文档。有了javadoc，我们就有了创建文档的标准；我们可以期望甚至要求所有的Java类库都提供相关的文档。
此外，如果你想对javadoc处理过的信息执行特殊的操作（例如：以不同格式输出），那么你可以通过编写你自己的，被称为“doclets”的Javadoc处理器来实现。关于Doclets，将在第15章介绍。
下面仅对基本的javadoc进行简单介绍和概述。全面翔实的描述可从java.sun.com提供的可下载的JDK文档中找到。（注意此文档并没有与JDK一块打包，需单独下载）。解压缩该文档之后，查阅“Tooldocs”子目录（或点击“Tooldocs”链接）。
语法
所有javadoc命令都只能始于“/**”注释，和一般注释一样，结束于 “*/”。使用javadoc的方式主要有两种：嵌入HTML，或使用“文档标签（doc tag）”。所谓“文档标签”是一些以“@”字符开头的命令，且该“@”字符要置于注释行的最前面（即忽略前导 “*”之后的最前面）。而“行内文档标签（inline doc tag）”则可以出现在javadoc注释中的任何地方，它们也是以“@”字符开头，但要括在花括号内。
共有三种类型的注释文档，分别对应于注释位置后面的三种元素：类、变量和方法。也就是说，类注释正好位于类定义之前；变量注释正好位于变量定义之前；而方法定义也正好位于方法定义的前面。如下面这个简单的例子所示：
/** A class comment */
public class DocTest {
/** A variable comment */
public int i;
/** A method comment */
public void f() {}
}
注意，javadoc只能为“public（公共）”和“protected（受保护）”成员进行文档注释。 “private（私有）”和包内可访问成员（参阅第5章）的注释会被忽略掉，所以输出结果中看不到它们（不过可以用-private进行标记，以便对private成员一并处理）。这样做是有道理的，因为只有public和protected成员才能在文件之外被使用，这是客户端程序员所期望的。至于所有对类所作的注释，则都会包含在输出结果中。
上述代码的输出结果是一个HTML文件，它与其他Java文档具有相同的标准格式。因此，用户会非常熟悉这种格式，从而方便地导航到用户自己设计的类。输入上述代码，然后通过javadoc处理产生HTML文件，最后通过浏览器观看生成的结果，这样做是非常值得的。
嵌入式HTML
javadoc将HTML命令嵌入到它所生成的HTML文档中。这使你能够充分利用HTML的功能。当然，其主要目的还是为了对代码进行格式化。下面列出一个例子：
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
你也可以像在其他Web文档中那样运用HTML，对普通文本按照你自己所描述的进行格式化。
/**
* You can <em>even</em> insert a list:
* <ol>
* <li> Item one
* <li> Item two
* <li> Item three
* </ol>
*/
注意，在文档注释中，位于每一行最开头的星号和前导空格都会被javadoc丢弃。Javadoc会对所有内容重新格式化，使其与标准的文档外观一致。不要在嵌入式HTML中使用标题标签，例如：<h1>或<hr>，因为javadoc会插入自己的标题，而你的标题可能会对它造成干扰。
所有类型的注释文档——类、变量和方法——都支持嵌入式HTML。
一些标签实例
这里将介绍一些可用于代码文档的javadoc标签。在使用javadoc处理重要事情之前，你应该先到可下载的JDK文档那里查阅javadoc参考，以获取全面的javadoc的使用方法。
@see：引用其他类
@see标签允许你引用其他类的文档。javadoc会在其生成的HTML文件中，用@see标签链接到其他文档。格式如下：
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
每种格式都会在生成的文档中加入一个具有超链接的“See Also”条目。但是javadoc不会检查你所提供的超链接是否有效。
{@link package.class#member label}
该标签与@see极其相似，只是它可以用于行内，并且是用“label”作为超链接文本而不用“See Also”。
{@docRoot}
该标签产生到文档根目录的相对路径，用于文档树页面的显式超链接。
{@inheritDoc}
该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。
@version
该标签的格式如下：
@version version-information
其中，“version-information”可以是任何你认为适合作为版本说明的重要信息。如果javadoc命令行使用了“-version”标记，那么就可以从生成的HTML文档中提取出版本信息。
@author
该标签的格式如下：
@author author-information
其中，“author-information”，望文生义你也知道，应该是你的姓名，也可以包括电子邮件地址或者其他任何适宜的信息。如果javadoc命令行使用了“-author”标签，那么就可以从生成的HTML文档中提取作者信息。
你可以使用多个标签，以便列出所有作者，但是它们必须连续放置。全部作者信息会合并到同一段落，置于生成的HTML中。
@since
该标签允许你指定程序代码最早使用的版本，你将会在HTML Java文档中看到它被用来指定所用的JDK版本。
@param
该标签用于方法文档中，形式如下：
@param parameter-name description
其中，“parameter-name”是方法的参数列表中的标识符，“description”的文本可延续数行，终止于新的文档标签出现之前。你可以使用任意数量的此标签，大约每个参数都有一个这样的标签。
@return
该标签用于方法文档，格式如下：
@return description
其中，“description”用来描述返回值的含义，可以延续数行。
@throws
“异常”（Exception）将在第9章论述。简言之，它们是由于某个方法调用失败而“抛出”的对象。尽管在调用一个方法时，只有出现一个异常对象，但是某个特殊方法可能会产生任意多、不同类型的异常，所有这些异常都需要进行说明。所以，异常标签的格式如下：
@throws fully-qualified-class-name description
其中，“fully-qualified-class-name”给出了一个异常类的完整名字，而且该异常类已经在某处定义过。而“description”（同样可以延续数行）告诉你为什么此特殊类型的异常会在方法调用中出现。
@deprecated
该标签用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，因为在不久的将来，它们很可能会被移除。如果使用一个标记为@deprecated的方法，则会引起编译器的警告。
文档示例
下面还是我们的第一个Java程序，但是这次加上了文档注释：
//: c02:HelloDate.java
import java.util.*;
/** The first Thinking in Java example program.
* Displays a string and today's date.
* @author Bruce Eckel
* @author www.BruceEckel.com
* @version 2.0
*/
public class HelloDate {
/** Sole entry point to class & application
* @param args array of string arguments
* @return No return value
* @exception exceptions No exceptions thrown
*/
public static void main(String[] args) {
System.out.println("Hello, it's: ");
System.out.println(new Date());
}
} ///:~
第一行采用了我自己独特的方法，是一行用一个“:”作为特殊记号的注释行，来说明此注释行含有源文件名。该行包含了文件的路径信息（此时，c02代表第2章），随后是文件名6。最后一行也是一行注释， 这个“///:~”标志着源代码清单的结束。这样一来，就可以将这些源代码自动从本书文本中提取出，再用编译器对其进行检查，然后执行。
(摘自 《Think in java》)
Electronic Cigarette