【Java】Java注释 - 单行、块、文档注释

简单记录，Java 核心技术卷I 基础知识（原书第10 版）

注释

我们在编写程序时，经常需要添加一些注释，用来描述某段代码的作用，提高Java源程序代码的可读性，使得Java程序条理清晰。

写代码的时候应遵循注意一些java规范，函数短小精悍，用清晰的命名来解释代码， 整洁的代码， 不要保留不用的代码（注释代码），要么删掉，要么想到更好的方案替换，别留着，注释不要写废话和错误的。

那为什么要写注释呢？在代码不足以表达意思的时候，让自己和别人更容易理解自己写的代码和复用代码，就需要注释来表达。做到之前没有见过这段代码，但能根据代码和一些注释快速地知道这段代码是干什么的。

Java 核心技术卷I 基础知识（原书第10 版）书上的

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 修饰符， 例如， 用于强调的<em>...<em> 、 用于着重强调的<strong>...</strong> 以及包含图像的<img ...>等。不过， 一定不要使用<hl>或<hr> 因为它们会与文档的格式产生冲突。若要键入等宽代码， 需使用{@code ... } 而不是
<code>...</code>——这样一来， 就不用操心对代码中的< 字符转义了。

注释： 如果文档中有到其他文件的链接， 例如， 图像文件（用户界面的组件的图表或图像等）， 就应该将这些文件放到子目录doc-files 中。javadoc 实用程序将从源目录拷贝这些目录及其中的文件到文档目录中。在链接中需要使用doc-files 目录， 例如：<img src="doc-files/uml.png" alt="UML diagram” >。

4.9.2 类注释

类注类注释必须放在import 语句之后，类定义之前。

下面是一个类注释的例子：

/**
* 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 Use <code> setVisible(true) </code> instead
  通过@see 和@link 标记， 可以使用超级链接， 链接到javadoc 文档的相关部分或外部文档。
• @see 引用
  这个标记将在“ see also” 部分增加一个超级链接。它可以用于类中，也可以用于方法中。这里的引用可以选择下列情形之一：
  package, class#feature label <a href="...“>label</a> "text"
  第一种情况是最常见的。只要提供类、方法或变量的名字，javadoc 就在文档中插入一个超链接。例如，
  @see com.horstmann.corejava.Employee#raiseSalary(double)
  建立一个链接到com.horstmann.corejava.Employee 类的raiseSalary(double)方法的超
  链接。可以省略包名， 甚至把包名和类名都省去， 此时， 链接将定位于当前包或当前类。
  需要注意，一定要使用井号（#)，
  而不要使用句号（.）分隔类名与方法名， 或类
  名与变量名。Java 编译器本身可以熟练地断定句点在分隔包、子包类、内部类与方法和变量时的不同含义。但是javadoc 实用程序就没有这么聪明了， 因此必须对它提供帮助。
  如果@see 标记后面有一个< 字符，就需要指定一个超链接。可以超链接到任何URL。例如：
  @see <a href="www.horstmann.com/corejava.html">The Core java home page</a>
  在上述各种情况下， 都可以指定一个可选的标签（ 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 文件。在标记<body>...</body>之间的所有文本都会被抽取出来。
2 ) 提供一个以package-info.java 命名的Java 文件。这个文件必须包含一个初始的以/**和*/ 界定的Javadoc 注释， 跟随在一个包语句之后。它不应该包含更多的代码或注释。

还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html的文件中，这个文件位于包含所有源文件的父目录中。标记<body>... </body>之间的所有文本将被抽取出来。当用户从导航栏中选择“ 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 的联机文档。