【Java】 入门 — —（六）
1、文档注释
A、JDK 包含一个很有用的工具，叫做 javadoc，它可以由源文件生成一个HTML 文档。
B、文档提取的是以 /** 开头，到 */ 结束。
C、javadoc 实用程序（utility）从下面几个特性中抽取信息:
· 包
· 公有类与接口
· 公有的和受保护的构造器及方法
· 公有的和受保护的域
应该在上面几部分，编写注释
D、标记是由 @开始.
E、标记 之后紧跟自由格式文本（free-form text），自由格式文本的第一句应该是一个概要性的句子；
javadoc 实用程序自动地将这些句子抽取出来形成概要页。
更详细的自己去看吧，我觉得不太常用。
2、类注释:
A、类注释必须放在 import 语句之后，类定义之前。
3、方法注释：
A、每一个方法注释必须放在所描述的方法之前。
B、除了通用标记外，还有下面的标记：
| 标记 | 描述说明 |
| @param |
A、变量描述 B、将对当前方法的 "param"（参数）部分添加条目。 C、这个描述可以占据多行，并可以用 HTML 标记。 D、一个方法的所有@param 标记必须放在一起 |
| @return |
A、返回描述 B、这个描述可以占据多行，并可以用 HTML 标记。 |
| @throws |
A、类描述 B、这个标记将添加一个注释，用于表示这个方法可能抛出的异常。 |
4、域注释：
只需要对公有域（通常指的是静态常量）建立文档。
5、通用注释：
| 标记 | 描述说明 |
| @author |
A、这个标记产生一个 作者 条目。 B、可以使用多个 @author 标记，每个 @author 标记对应一个作者 |
| @version |
A、这个标记将产生一个 版本 条目。 B、@version 文本，这里的文本可以是对当前版本的任何描述。 |
| @since | A、这个标记将产生一个 始于 条目，这里的text 可以是对引入特性的版本描述，例如：@since version 1.71 |
| @deprecated |
A、这个标记，将对类，方法或者变量添加一个不再使用的注释。 B、文本中给出取代建议。 |
| @see |
A、可以连接到内部的 类、方法或者变量。只需要提供它们的名字。（可以把当前包，或者包名，类名都省去）例如：@see com.horstmann.corejava.Employee#raiseSalary(double) B、连接到外部文档 @see <a href="....">这是外部文档</a> C、连接到内部的时候，注意用的是 # 而不是 . 。 D、如果 @see 后面 有双引号字符，文本就会显示在 see also 部分。例如: @see "also 部分" E、可以为一个特性添加多个 @see 标记，但必须将它们放在一起。 F、也可以使用 @link ，规则跟 @see 一样 |
6、包与概述注释：
A、可以直接把 类、方法和变量的注释放置在 Java 源文件中，只要以 /** ... */ 文档注释界定就可以了。
B、生产包的注释，就需要在每一个包目录中，添加一个单独的文件。有下面选择：
| 文件名 | 描述 |
| package.html | A、在这个HTML文件中 body 标签中，所有的文本都会被抽取出来。 |
| package-info.java |
A、这个文件必须包含一个以 /** 和 */ 界定的 javadoc 注释，跟随在包语句之后。 B、它不应该包含更多的代码或注释。 |
C、可以为所有的源文件提供一个概述性的注释；这个注释将放被放置在一个名为 overview.html 的文件中。
D、overview.html 这个文件位于包含所有源文件的父目录中；提取body 标签中的所有文本，用户可以在 overview 的导航栏中查看。
7、注释的抽取：
A、使用 javadoc 命令。
B、假设要把注释抽取到一个叫 docDirectory 的目录下：
| 命令 | 描述说明 |
| javadoc -d docDirectory nameOfPackage | A、一个包的抽取。 |
| javadoc -d docDirectory nameOfPackage1 nameOfPackage2.... | A、多个包的抽取。 |
| javadoc -d docDirectory *.java | A、默认包的抽取 |
C、省略 -d docDirectory 的话，html 文件就会被提取到当前的目录下，会造成混乱，不建议着这样做。
D、-version 标记，是提取 author 和 version 标记的，默认情况下，会省略提取这两个标记。
E、其他选项自己查吧。
