Java基础系列（十一）：注释
前言
曾经看到过一句话：“我最烦的就是写注释和看不写注释的代码”，也许有玩笑的成分的在，但是不可否认的是，注释对于代码来说，是必不可少的，它可以大大的增加代码的可读性，好的注释就像好看的皮囊，让人赏心悦目。
JDK给我们提供一个很有用的工具，叫做javadoc,它可以由源文件生成一个HTML文档，理想状态下的注释就是要起到这样的效果，而大多数的时候我们并不能做到这一点，下面我们来了解一下注释都可以用到哪些地方：
- 包
- 公有类和接口
- 公有的和受保护的构造器及方法
- 公有的和受保护的域
注释的格式是以 /**开始，并以 */结束，每个 /**...*/文档注释在标记之后紧跟着自由格式文本，标记于@开始，比如 @author或 @param。
自由格式文本的第一句应该是一个概要性的句子。javadoc实用程序自动地将这些句子抽取出来形成概要页。
在自由格式的文本中，可以使用HTML的修饰符，比如：用于强调的 <em>...</em>，用于着重强调的 <strong>...</strong>以及包含图像的 <img...>等等。如果要使用等宽代码，可以使用 {@code...}。
包与概述注释
如果想要产生包注释，不能使用上面说的那个方法，如果想要产生包注释，需要在每一个包目录中添加一个单独的文件。在这里，我们有两种选择：
- 提供一个以package.html命名的HTML文件。在标记
<body>...</body>之间的所有文本都会被抽取出来。 - 提供一个以package-info.java命名的Java文件。这个文件必须包含一个初始的以
/**和*/界定的Javadoc注释，跟随在一个包语句之后，不包含其他的代码和注释。
我们还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html的文件中，这个文件位于包含所有的源文件的父目录中。标记 <body>...</body>之间的所有文本都会被抽取出来。当用户从导航栏中选择“Overview”时，就会显示出这些注释内容。
类注释
类注释的位置必须位于import语句之后，类定义之前。如下所示：
/**
* {@code Card} 类，纸牌类包括四个花色（红桃，黑桃，梅花，方块），
* 13个数字（A，2，3，4，5，6，7，8，9，10，J，Q，K）
*/
public class Card {
...
}方法注释
每一个方法注释必须放在所描述的方法之前。除了通用标记以外，方法注释还可以使用以下的标记：
@param变量描述，为当前方法的参数添加一个条目，可以占据多行，并使用HTML标记。一个方法的所有参数必须放在一起@return描述，用于描述这个方法的返回值，可以有多行，可以使用HTML标记@throws类描述，用于描述这个类可能会抛出的异常。
下面是一个方法注释的例子：
/**
* 提高雇员的薪资
* @param byPercent 提高工资的比例(比如：20就代表提高20%)
*/
public double raiseSalary(double byPercent) {
double raise = salary * byPercent / 100;
salary += raise;
return raise;
}域注释
只需要对公有域（通常是静态常量）建立文档。比如：
/**
* 红桃张数13张
*/
public static final int HEARTS = 13;通用注释
下面的标记可以用在类文档的注释中
@author作者姓名@version版本信息@since始于@deprecated不再使用的标记@see引用，用于引入一个超链接
注释的抽取
假设HTML文档被存放在目录docDirectory下面。执行以下步骤：
1） 切换到包含想要生成文档的源文件目录。 2） 如果是一个包，应该运行命令：
javadoc -d docDirectory 包名如果是对于多个包生成文档，运行：
javadoc -d docDirectory 包名1 包名2如果文件在默认包中，就应该运行：
javadoc -d docDirectory *.java当然我们可以使用多种命令行方式来调整javadoc，可以使用 --author和 --version选项在让文档中包含 @author和 @version标记。