前言

曾经看到过一句话：“我最烦的就是写注释和看不写注释的代码”，也许有玩笑的成分的在，但是不可否认的是，注释对于代码来说，是必不可少的，它可以大大的增加代码的可读性，好的注释就像好看的皮囊，让人赏心悦目。

JDK给我们提供一个很有用的工具，叫做javadoc,它可以由源文件生成一个HTML文档，理想状态下的注释就是要起到这样的效果，而大多数的时候我们并不能做到这一点，下面我们来了解一下注释都可以用到哪些地方：

  1. 包
  2. 公有类和接口
  3. 公有的和受保护的构造器及方法
  4. 公有的和受保护的域

注释的格式是以/**开始，并以 */结束，每个/**...*/文档注释在标记之后紧跟着自由格式文本，标记于@开始，比如@author或@param。

自由格式文本的第一句应该是一个概要性的句子。javadoc实用程序自动地将这些句子抽取出来形成概要页。

在自由格式的文本中，可以使用HTML的修饰符，比如：用于强调的<em>...</em>，用于着重强调的<strong>...</strong>以及包含图像的<img...>等等。如果要使用等宽代码，可以使用{@code...}。

包与概述注释

如果想要产生包注释，不能使用上面说的那个方法，如果想要产生包注释，需要在每一个包目录中添加一个单独的文件。在这里，我们有两种选择：

  1. 提供一个以package.html命名的HTML文件。在标记<body>...</body>之间的所有文本都会被抽取出来。
  2. 提供一个以package-info.java命名的Java文件。这个文件必须包含一个初始的以/**和*/界定的Javadoc注释，跟随在一个包语句之后，不包含其他的代码和注释。

我们还可以为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html的文件中，这个文件位于包含所有的源文件的父目录中。标记<body>...</body>之间的所有文本都会被抽取出来。当用户从导航栏中选择“Overview”时，就会显示出这些注释内容。

类注释

类注释的位置必须位于import语句之后，类定义之前。如下所示：

  1. /**
  2.  * {@code Card} 类，纸牌类包括四个花色（红桃，黑桃，梅花，方块），
  3.  * 13个数字（A，2，3，4，5，6，7，8，9，10，J，Q，K）
  4.  */
  5. public class Card {
  6.     ...
  7. }

方法注释

每一个方法注释必须放在所描述的方法之前。除了通用标记以外，方法注释还可以使用以下的标记：

  • @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标记。

公众号

扫码或微信搜索Vi的技术博客，关注公众号，不定期送书活动各种福利~

Java基础系列（十一）：注释 - 图1