文档注释-CSDN博客

本文链接：https://blog.csdn.net/zyl_yjy_yi/article/details/103915837

JDK 包含一个很有用的工具，叫做 javadoc, 它可以由源文件生成一个 HTML 文档。事实上，在第 3 章讲述的联机 API 文档就是通过对标准 Java 类库的源代码运行 javadoc 生成的。

如果在源代码中添加以专用的定界符 /** 开始的注释，那么可以很容易地生成一个看上去具有专业水准的文档。这是一种很好的方式，因为这种方式可以将代码与注释保存在一个地方。如果将文档存人一个独立的文件中，就有可能会随着时间的推移，出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源代码的同时，重新运行 javadoc 就可以轻而易举地保持两者的一致性。

注释的插入

javadoc 实用程序(utility) 从下面几个特性中抽取信息:

•包 •公有类与接口

•公有的和受保护的构造器及方法 •公有的和受保护的域
在第 5 章中将介绍受保护特性，在第 6 章将介绍接口。

应该为上面几部分编写注释、注释应该放置在所描述特性的前面。注释以 /** 开始，并以 */ 结束。

每个 /** . . . */ 文档注释在标记之后紧跟着自由格式文本 ( free-form text )。标记由 @ 开始，如 @author 或 @param。

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

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

释如果文档中有到其他文件的链接例如图像文件(用户界面的组件的图表或图 :，，

像等)，就应该将这些文件放到子目录 doc-files 中。javadoc 实用程序将从源目录拷贝这

些目录及其中的文件到文档目录中。在链接中需要使用 doc-files 目录，例如: <img src= “ doc-files/uml_png” alt=“ UML diagram” >。

类注释
类注释必须放在 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)
V

public class Card

注释: 没有必要在每一行的开始用星号 *，例如，以下注释同样是合法的:

/**

A <code>Card</code> 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 提供了自动添加星号 *, 并且当注释行改变时，自动重新排列这些星号的功能。

方法注释

每一个方法注释必须放在所描述的方法之前。除了通用标记之外，还可以使用下面的标记: •@param 变量描述

这个标记将对当前方法的“ param” (参数)部分添加一个条目。这个描述可以占据多

行，并可以使用 HTML 标记。一个方法的所有 @param 标记必须放在一起。 • @return 描述

这个标记将对当前方法添加“ return” (返回)部分。这个描述可以跨越多行，并可以

使用 HTML 标记。 • ©throws 类描述

这个标记将添加一个注释，用于表

域注释

只需要对公有域 (通常指的是静态常量)建立文档。例如 ,

/**

* The "Hearts" card suit

V
public static final int HEARTS = 1;

通用注释

下面的标记可以用在类文档的注释中。 •eauthor 姓名

这个标记将产生一个 ** author" ( 作者)条目。可以使用多个 @aUthor 标记，每个 @

author 标记对应一个作者參 ©version

这个标记将产生一个“ version ”(版本)条目。这里的文本可以是对当前版本的任何描

述。

下面的标记可以用于所有的文档注释中。 •@sinee文本

这个标记将产生一个“ since” (始于)条目。这里的 text 可以是对引人特性的版本描述例如 ©since version 1.7.10

•。， @deprecated

这个标记将对类、方法或变量添加一个不再使用的注释。文本中给出了取代的建议。例如，

@deprecated Use <code> setVIsible(true) </code> instead

通过 @see 和 @link 标记，可以使用超级链接，链接到 javadoc 文档的相关部分或外

部文档。 •®see引用

这个标记将在“ see also” 部分增加一个超级链接。它可以用于类中，也可以用于方法中。这里的引用可以选择下列情形之一:

package, class眷feature label <a href=" ..n>hbek/a>

• ntextn

第一种情况是最常见的。只要提供类、方法或变量的名字，javadoc 就在文档中插入一个超链接。例如，
@see com.horstraann.corejava.Employee#raiseSalary(double)

建立一个链接到 com.horstmann.corejava.Employee 类的 raiseSalary(double) 方法的超链接。可以省略包名，

甚至把包名和类名都省去，此时，链接将定位于当前包或当前类

需要注意，一定要使用井号(#，) 而不要使用句号(.)分隔类名与方法名，或类名与变量名。Java 编译器本身可以熟练地断定句点在分隔包、子包、类、内部类与方法和变量时的不同含义。但是 javadoc 实用程序就没有这么聪明了，因此必须对它提供帮助。

如果 @see 标记后面有一个 < 字符，就需要指定一个超链接。可以超链接到任何 URL。例如:

@see <a href="m«w.horstmann.com/corejava.htinl">The Core ]ava home page</a>

在上述各种情况下，都可以指定一个可选的标签(label) 作为链接锚(link anchor) o 如果省略了 label , 用户看到的锚的名称就是目标代码名或 URL。

如果 @see 标记后面有一个双引号(")字符，文本就会显示在 “ see also” 部分。例如，

Isee "Core Java 2 volume 2n

可以为一个特性添加多个 @see 标记，但必须将它们放在一起。
•如果愿意的话，还可以在注释中的任何位置放置指向其他类或方法的超级链接，以及

插人一个专用的标记，例如，

{@link package,classifeaturelabel] 这里的特性描述规则与 @see 标记规则一样。

4.9.6 包与概述注释

可以直接将类、方法和变量的注释放置在 Java 源文件中，只要用 /** . . . */ 文档注释界定就可以了。但是，要想产生包注释，就需要在每一个包目录中添加一个单独的文件。可以有如下两个选择:

1 ) 提供一个以 package.html 命名的 HTML 文件。在标记 <body>—</body> 之间的所有文本都会被抽取出来。

2 ) 提供一个以 package-info.java 命名的 Java 文件。这个文件必须包含一个初始的以 /** 和 */ 界定的 Javadoc 注释，跟随在一个包语句之后。它不应该包含更多的代码或注释。

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

那么，所有的标准类库类都会自动地链接到 Oracle 网站的文档。
如果使用 -linksource 选项，则每个源文件被转换为 HTML ( 不对代码着色，但包含行编

号，) 并且每个类和方法名将转变为指向源代码的超链接。
有关其他的选项，请查阅 javadoc 实用程序的联机文档， http://docs.orade.eom/javase /8/

docs/guides/javadoc 0

注释: 如果需要进一步的定制，例如，生成非 HTML 格式的文档，可以提供自定义的 doclet, 以便生成想要的任何输出形式。显然，这是一种特殊的需求，有关细节内容请查阅 http://docs.oracle.com/javase/8/docs/guides/javadoc/doclet/overview.html 的联机文档。

1. 一定要保证数据私有

这是最重要的; 绝对不要破坏封装性。有时候，需要编写一个访问器方法或更改器方法，但是最好还是保持实例域的私有性。很多惨痛的经验告诉我们，数据的表示形式很可能会改变，但它们的使用方式却不会经常发生变化。当数据保持私有时，它们的表示形式的变化不会对类的使用者产生影响，即使出现 bug 也易于检测。

2. 一定要对数据初始化

Java 不对局部变量进行初始化，但是会对对象的实例域进行初始化。最好不要依赖于系统的默认值，而是应该显式地初始化所有的数据，具体的初始化方式可以是提供默认值，也可以是在所有构造器中设置默认值。

3. 不要在类中使用过多的基本类型

就是说，用其他的类代替多个相关的基本类型的使用。这样会使类更加易于理解且易于修改。例如，用一个称为 Address 的新的类替换一个 Customer 类中以下的实例域:

private String street; private String city; private String state; private int zip;

这样，可以很容易处理地址的变化，例如，需要增加对国际地址的处理。
4. 不是所有的域都需要独立的域访问器和域更改器
或许，需要获得或设置雇员的薪金。而一旦构造了雇员对象，就应该禁止更改雇用日

期，并且在对象中，常常包含一些不希望别人获得或设置的实例域，例如，在 Address 类中，存放州缩写的数组。

5. 将职责过多的类进行分解

这样说似乎有点含糊不清，究竟多少算是“ 过多” ? 每个人的看法不同。但是，如果明显地可以将一个复杂的类分解成两个更为简单的类，就应该将其分解(但另一方面，也不要走极端。设计 10 个类，每个类只有一个方法，显然有些矫枉过正了)。

下面是一个反面的设计示例。

public class CardDeck // bad design {

private int 口 value; private int[] suit;

public CardDeck() { . . . }
public void shuffle0 {•••} public int getTopValueO { . . . } public int getTopSuitO { . . . }

实际上，这个类实现了两个独立的概念: 一副牌(含有 shuffle 方法和 draw 方法)和一张牌(含有查看面值和花色的方法)。另外，引入一个表示单张牌的 Card类。现在有两个类，每个类完成自己的职责:

public class CardDeck

{
private Card[] cards;

public CardDeckO { • . . } public void shuffle() { . . . } public Card getTopO { . . . } public void draw() { . . . }

}

public class Card {

private int value; private int suit;

public void drawO {• }

■

第4章?象与? 145

146 Java核心技?

public Card(int aValue, int aSuit) { . . . } public int getValueO { . . . }
public int getSuitO { . . . }

}

6. 类名和方法名要能够体现它们的职责

与变量应该有一个能够反映其含义的名字一样，类也应该如此(在标准类库中，也存在着一些含义不明确的例子，如: Date 类实际上是一个用于描述时间的类 )。

命名类名的良好习惯是采用一个名词(Order)、前面有形容词修饰的名词( RushOrder) 或动名词(有“ -ing”后缀)修饰名词(例如，BillingAddress)。对于方法来说，习惯是访问器方法用小写 get 开头 ( getSalary ), 更改器方法用小写的 set 开头(setSalary )

7. 优先使用不可变的类 —

LocalDate 类以及 java.time 包中的其他类是不可变的没有方法能修改对象的状态。类似 plusDays 的方法并不是更改对象，而是返回状态已修改的新对象。

更改对象的问题在于，如果多个线程试图同时更新一个对象，就会发生并发更改。其结果是不可预料的。如果类是不可变的，就可以安全地在多个线程间共享其对象。

因此，要尽可能让类是不可变的，这是一个很好的想法。对于表示值的类，如一个字符串或一个时间点，这尤其容易。计算会生成新值，而不是更新原来的值。

当然，并不是所有类都应当是不可变的。如果员工加薪时让 raiseSalary 方法返回一个新的 Employee 对象，这会很奇怪。