原文

4.10.5 通用注释

标记 @since text 会建立一个 "since" （始于）条目，text（文本）可以是对引入这个特性的版本的描述。例如， @since 1.7.1。

类文档注释中可以使用下面的标记:

@author name

这个标记将建立一个“author”(作者)条目。可以有多个@author 标记，每个@author标记对应一个作者。并不是非得使用这个标记，你的版本控制系统能够更好地跟踪作者。

@version text

这个标记将建立一个“version”(版本)条目。这里的 text 可以是对当前版本的任何指述。

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

标记@see reference将在“see also”(参见)部分增加一个超链接。它可以用于类中，也可以用于方法中。这里的 reference (引用)可以有以下选择:

package.class#feature label

<a href="...">label</a>

"text"

第一种情况是最有用的。只要提供类、方法或变量的名字，javadoc 就在文档中插人一个超链接。例如：

@see com.horstmann.coreJava.Employee#ralseSalary(double)

会建立一个超链接，链接到 com.horstmann.coreJava.Employee 类的 ralseSalary(double)方法。可以省略包名，甚至把包和类名都省去，这样一来，这会位于当前包或当前类。

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

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

@see <a hrefa"www.horstmann.com/corejava.html">The Core Java home page</a>

在上述各种情况下，都可以指定一个可选的标签(label)，这会显示为链接锚 (linkanchor)。如果省略了标签，则用户看到的锚就是目标代码名或 URL。

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

@see "Core Java 2 volume 2"

可以为一个特性添加多个 @see 标记，但必须将它们放在一起。

如果愿意，可以在任何文档注释中放置指向其他类或方法的超链接。可以在注释中的任何位置插入一个形式如下的特殊标记:

{@link package.class#feature label}

这里的特性描述规则与 @see 标记的规则相同。

最后，在 Java9中，还可以使用 {@index entry}标记为搜索框增加一个条目。