【Java】Java注释 - 单行、块、文档注释
简单记录，Java 核心技术卷I 基础知识（原书第10 版）
注释
我们在编写程序时，经常需要添加一些注释，用来描述某段代码的作用，提高Java源程序代码的可读性，使得Java程序条理清晰。
写代码的时候应遵循注意一些java规范，函数短小精悍，用清晰的命名来解释代码， 整洁的代码， 不要保留不用的代码（注释代码），要么删掉，要么想到更好的方案替换，别留着，注释不要写废话和错误的。
那为什么要写注释呢？在代码不足以表达意思的时候，让自己和别人更容易理解自己写的代码和复用代码，就需要注释来表达。做到之前没有见过这段代码，但能根据代码和一些注释快速地知道这段代码是干什么的。
Java 核心技术卷I 基础知识（原书第10 版）书上的
文章目录
- 3.2 注释
-
- 单行 (single-line) 注释
- 块 (block) 注释(多行)
- 文档注释
- 4.9 文档注释
-
- 4.9.1 注释的插入
- 4.9.2 类注释
- 4.9.3 方法注释
- 4.9.4 域注释
- 4.9.5 通用注释
- 4.9.6 包与概述注释
- 4.9.7 注释的抽取
3.2 注释
Java 与大多数程序设计语言一样，它的注释也不会出现在可执行程序中。因此， 可以在源程序中根据需要添加任意多的注释，而不必担心可执行代码会膨胀。
在Java 中，有3 种标记注释的方式。
- 单行注释
- 多行注释
- 文档注释
单行 (single-line) 注释
最常用的方式是使用//，其注释内容从// 开始到本行结尾。
System.out.println("We will not use 'Hello, World!’"）；// is this too cute?
块 (block) 注释(多行)
当需要长篇的注释时， 既可以在每行的注释前面标记//，
也可以使用/*和*/ 将一段比较长的注释括起来。
/*
This is the first sample program in Core Java Chapter 3
一个最简单的Java应用程序，它只发送一条消息"We will not use 'Hello, World! '"到控制台窗口中.
*/
public class FirstSample
{
public static void main(String[] args)
{
System.out.println("We will not use 'Hello, World! '");
}
}
警告：在Java 中，/* */ 注释不能嵌套„ 也就是说， 不能简单地把代码用/* 和*/ 括起来,作为注释， 因为这段代码本身可能也包含一个*/ 。
文档注释
最后，第3 种注释可以用来自动地生成文档。这种注释以/**开始， 以*/结束。
/**
* This is the first sample program in Core Java Chapter 3
* @version 1.01 1997-03-22
* @author Gary Cornell
*/
public class FirstSample
{
public static void main(String[] args)
{
System.out.println("We will not use 'Hello, World!'");
}
}
4.9 文档注释
JDK 包含一个很有用的工具， 叫做javadoc, 它可以由源文件生成一个HTML 文档。事实上，API 文档就是通过对标准Java 类库的源代码运行javadoc 生成的。
如果在源代码中添加以专用的定界符/** 开始的注释， 那么可以很容易地生成一个看上去具有专业水准的文档。这是一种很好的方式， 因为这种方式可以将代码与注释保存在一个地方。如果将文档存入一个独立的文件中， 就有可能会随着时间的推移， 出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源代码的同时， 重新运
行javadoc 就可以轻而易举地保持两者的一致性。
javadoc注释标签语法
@author 对类的说明标明开发该类模块的作者
@version 对类的说明标明该类模块的版本
@see 对类、属性、方法的说明 参考转向，也就是相关主题
@param 对方法的说明对方法中某参数的说明
@return 对方法的说明对方法返回值的说明
@exception 对方法的说明对方法可能抛出的异常进行说明
4.9.1 注释的插入
javadoc 实用程序（utility ) 从下面几个特性中抽取信息：
- 包
- 公有类与接口
- 公有的和受保护的构造器及方法
- 公有的和受保护的域
应该为上面几部分编写注释、注释应该放置在所描述特性的前面。注释以/** 开始， 并以*/ 结束。
每个/** . . . */ 文档注释在标记之后紧跟着自由格式文本（ free-form text )。标记由@开始， 如@author 或@param。
自由格式文本的第一句应该是一个概要性的句子。javadoc 实用程序自动地将这些句子抽取出来形成概要页。
在自由格式文本中， 可以使用HTML 修饰符， 例如， 用于强调的... 、 用于着重强调的... 以及包含图像的{@code ... } 而不是
...
注释： 如果文档中有到其他文件的链接， 例如， 图像文件（用户界面的组件的图表或图像等）， 就应该将这些文件放到子目录doc-files 中。javadoc 实用程序将从源目录拷贝这些目录及其中的文件到文档目录中。在链接中需要使用doc-files 目录， 例如：
/**
* A {©code Card} object represents a playing card , such
* as "Queen of Hearts". A card has a suit (Diamond, Heart ,
* Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 *=Jack, 12 = Queen , 13 = King)
*/
public class Card
{
...
}
注释： 没有必要在每一行的开始用星号*， 例如， 以下注释同样是合法的：*
/**
A {©code Card} object represents a playing card , such
as "Queen of Hearts". A card has a suit (Diamond, Heart ,
Spade or Club) and a value (1 = Ace, 2 . . . 10, 11 =Jack, 12 = Queen , 13 = King)
*/
然而， 大部分IDE 提供了自动添加星号*, 并且当注释行改变时， 自动重新排列这些星号的功能。
4.9.3 方法注释
每一个方法注释必须放在所描述的方法之前。除了通用标记之外， 还可以使用下面的标记：
- @param 变量描述
这个标记将对当前方法的“ param ” （参数）部分添加一个条目。这个描述可以占据多行， 并可以使用HTML 标记。一个方法的所有@param 标记必须放在一起。 - @return 描述
这个标记将对当前方法添加“ return” （返回）部分。这个描述可以跨越多行， 并可以使用HTML 标记。 - @throws 类描述
这个标记将添加一个注释， 用于表示这个方法有可能抛出异常。
下面是一个方法注释的示例：
/**
* Raises the salary of an employee.
* @param byPercent the percentage by which to raise the *salary (e.g. 10 means 10%)
* ©return the amount of the raise
*/
public double raiseSalary(double byPercent)
{
double raise = salary * byPercent / 100;
salary += raise;
return raise;
}
4.9.4 域注释
只需要对公有域（通常指的是静态常量）建立文档。例如,
/**
* The "Hearts" card suit
*/
public static final int HEARTS = 1;
4.9.5 通用注释
下面的标记可以用在类文档的注释中。
- author 姓名
这个标记将产生一个“author” ( 作者）条目。可以使用多个@author 标记， 每个@author 标记对应一个作者。 - @version
这个标记将产生一个“ version”（版本）条目。这里的文本可以是对当前版本的任何描述。
下面的标记可以用于所有的文档注释中。 - @since 文本
这个标记将产生一个“ since” （始于）条目。这里的text 可以是对引人特性的版本描述。例如，©since version 1.7.1。 - @deprecated
这个标记将对类、方法或变量添加一个不再使用的注释。文本中给出了取代的建议。
例如，@deprecated UsesetVisible(true)instead
通过@see 和@link 标记， 可以使用超级链接， 链接到javadoc 文档的相关部分或外部文档。 - @see 引用
这个标记将在“ see also” 部分增加一个超级链接。它可以用于类中，也可以用于方法中。这里的引用可以选择下列情形之一：
package, class#feature label
第一种情况是最常见的。只要提供类、方法或变量的名字，javadoc 就在文档中插入一个超链接。例如，
@see com.horstmann.corejava.Employee#raiseSalary(double)
建立一个链接到com.horstmann.corejava.Employee类的raiseSalary(double)方法的超
链接。可以省略包名， 甚至把包名和类名都省去， 此时， 链接将定位于当前包或当前类。
需要注意，一定要使用井号（#)，
而不要使用句号（.）分隔类名与方法名， 或类
名与变量名。Java 编译器本身可以熟练地断定句点在分隔包、子包类、内部类与方法和变量时的不同含义。但是javadoc 实用程序就没有这么聪明了， 因此必须对它提供帮助。
如果@see 标记后面有一个<字符，就需要指定一个超链接。可以超链接到任何URL。例如：
@see The Core java home page
在上述各种情况下， 都可以指定一个可选的标签（ label ) 作为链接锚（ link anchor) 。 如果省略了label , 用户看到的锚的名称就是目标代码名或URL。如果@see 标记后面有一个双引号（"）字符， 文本就会显示在“ see also” 部分。
例如，
@see "Core Java 2 volume 2
可以为一个特性添加多个@see 标记，但必须将它们放在一起。 - 如果愿意的话， 还可以在注释中的任何位置放置指向其他类或方法的超级链接， 以及插人一个专用的标记， 例如，
{@link package, class#feature label }
这里的特性描述规则与@see 标记规则一样。
4.9.6 包与概述注释
可以直接将类、方法和变量的注释放置在Java 源文件中， 只要用/** . . . */ 文档注释界定就可以了。但是， 要想产生包注释，就需要在每一个包目录中添加一个单独的文件。可以有如下两个选择：
1 ) 提供一个以package.html 命名的HTML 文件。在标记...之间的所有文本都会被抽取出来。
2 ) 提供一个以package-info.java 命名的Java 文件。这个文件必须包含一个初始的以/**和*/ 界定的Javadoc 注释， 跟随在一个包语句之后。它不应该包含更多的代码或注释。
还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html的文件中，这个文件位于包含所有源文件的父目录中。标记... 之间的所有文本将被抽取出来。当用户从导航栏中选择“ Overview” 时，就会显示出这些注释内容。
4.9.7 注释的抽取
这里， 假设HTML 文件将被存放在目录docDirectory 下。执行以下步骤：
1 ) 切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档， 例如com.horstmann.corejava, 就必须切换到包含子目录com 的目录（如果存在overview.html 文件的话， 这也是它的所在目录)。
2 ) 如果是一个包，应该运行命令:
javadoc -d docDirectory nameOfPackage
或对于多个包生成文档， 运行:
javadoc -d docDirectory nameOfPackage nameOfPackage . . .
如果文件在默认包中， 就应该运行：
javadoc -d docDirectory *. java
如果省略了-d docDirectory 选项， 那HTML 文件就会被提取到当前目录下。这样有可能会带来混乱，因此不提倡这种做法。
可以使用多种形式的命令行选项对javadoc 程序进行调整。例如， 可以使用-author 和 -version 选项在文档中包含@author 和@version 标记（默认情况下， 这些标记会被省略)。另一个很有用的选项是-link, 用来为标准类添加超链接。例如， 如果使用命令
javadoc -link http://docs.oracle.com/javase/8/docs/api *.java
那么，所有的标准类库类都会自动地链接到Oracle 网站的文档。
如果使用-linksource 选项， 则每个源文件被转换为HTML ( 不对代码着色， 但包含行编号)，并且每个类和方法名将转变为指向源代码的超链接。
有关其他的选项， 请查阅javadoc 实用程序的联机文档，http://docs.orade.com/javase/8/docs/guides/javadoc 。
注释： 如果需要进一步的定制，例如， 生成非HTML 格式的文档， 可以提供自定义的doclet, 以便生成想要的任何输出形式。显然， 这是一种特殊的需求， 有关细节内容请查阅http://docs.oracle.com/javase/8/docs/guides/javadoc/doclet/overview.html 的联机文档。