第2章番外2 令人惊喜的注释文档

单行和多行注释：

Java沿用了C++的注释风格，用//进行单行注释，用/**/进行多行代码的注释，有时候多行注释中间的每一行开头会有一个*，但本质上是一样的。

下面是多行注释的两种形式：

/* This is a comment

* that continues

* across lines

*/

/* This is a comment that

continues across lines */

注释文档：

Java带给我最大的惊喜还是它的注释文档，注释文档的出现将代码和文档链接起来，为我们免去了编写修改文档的麻烦，而且生成的HTML文档格式也是美cry的。

javadoc：

javadoc就是用于提取注释生成文档的工具，它是JDK的一部分。Javadoc不仅整合注释里的信息，还把相邻的类名或者方法名提取出来，让我们用最小的力气生成好看的文档。

生成方式：

1. 命令行：

javadoc -d 文档存放目录 -author -version 源文件名.java

这条命令编译一个名为"源文件名.java"的 java 源文件，并将生成的文档存放在"文档存放目录"指定的目录下，生成的文档中 index.html 就是文档的首页。-author 和 -version 两个选项可以省略。

2. Eclipse可以直接导出。

注释语法：

使用javadoc的方式有两种：嵌入HTML和文档标签。

“独立文档标签”：以“@”字符开头，“@”字符要置于注释行的最前面

“行内文档标签”：以“@”字符开头，可以出现在 javadoc 注释中的任何地方，但要在花括号内。

正如下面的例子：

/** A class comment */

public class DocTest {

/** A variable comment */

public int i;

/** A method comment */

public void f() {}

}

注意，javadoc 只能为public和protected成员进行文档注释。 private和包内可访问成员的注释会被忽略掉。不过可以用-private 进行标记，以便对private成员一并处理。

HTML命令重新嵌入格式化的就不说了，原来的格式已经足够好了。

标签示例：

1. @see：引用其他类

@see 标签允许你引用其他类的文档。javadoc 会在其生成的 HTML 文件中，用@see 标签链接到其他文档。格式如下：

@see classname

@see fully-qualified-classname

@see fully-qualified-classname#method-name

每种格式都会在生成的文档中加入一个具有超链接的“See Also”条目。但是 javadoc 不会

检查你所提供的超链接是否有效。

2. {@link package.class#member label}

该标签与@see 极其相似，只是它可以用于行内，并且是用“label”作为超链接文本而不用

“See Also”。

3. {@docRoot}

该标签产生到文档根目录的相对路径，用于文档树页面的显式超链接。

4. {@inheritDoc}

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

5. @version

该标签的格式如下：

@version version-information

其中，“version-information”可以是任何你认为适合作为版本说明的重要信息。如果 javadoc

命令行使用了“-version”标记，那么就可以从生成的 HTML 文档中提取出版本信息。

6. @author

该标签的格式如下：

@author author-information

其中，“author-information”，望文生义你也知道，应该是你的姓名，也可以包括电子邮件

地址或者其他任何适宜的信息。如果 javadoc 命令行使用了“-author”标签，那么就可以从生成的 HTML 文档中提取作者信息。

可以使用多个标签，以便列出所有作者，但是它们必须连续放置。全部作者信息会合并到

同一段落，置于生成的 HTML 中。

7. @since

该标签允许你指定程序代码最早使用的版本，你将会在 HTML Java 文档中看到它被用来指

定所用的 JDK 版本。

8. @param

该标签用于方法文档中，形式如下：

@param parameter-name description

其中，“parameter-name”是方法的参数列表中的标识符，“description”的文本可延续数行，终止于新的文档标签出现之前。你可以使用任意数量的此标签，大约每个参数都有一个这样的标签。

9. @return

该标签用于方法文档，格式如下：

@return description

其中，“description”用来描述返回值的含义，可以延续数行。

10. @throws

“异常”（Exception）将在第 9 章论述。简言之，它们是由于某个方法调用失败而“抛出”

的对象。尽管在调用一个方法时，只有出现一个异常对象，但是某个特殊方法可能会产生任

意多、不同类型的异常，所有这些异常都需要进行说明。所以，异常标签的格式如下：

@throws fully-qualified-class-name description

其中，“fully-qualified-class-name”给出了一个异常类的完整名字，而且该异常类已经

在某处定义过。而“description”（同样可以延续数行）告诉你为什么此特殊类型的异常会

在方法调用中出现。

11. @deprecated

该标签用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，因

为在不久的将来，它们很可能会被移除。如果使用一个标记为@deprecated 的方法，则会引

起编译器的警告。

示例代码：试下生成HTML文件感受下~~

//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());
}
} ///:~