Day6-17.Some example tags

一些标签示例

这里讲介绍一些可用于代码文档的javadoc标签。

在使用javadoc处理重要事情之前，应该先到JDK文档哪里查阅javadoc参考，以学习javadoc的各种不同的使用方法。

1.@see：引用其他类

@see 标签允许用户引用其他类的文档。javadoc会在其生成的HTML文件中，通过@see标签连接到其他文档。格式如下：

@see classname

@see fully-qualified-classname

@see fully-qualified-classname#method-name

上述每种格式都会在生成的文档中加入一个具有超链接的“See Also”（参见）条目。

但是javadoc不会检查你所提供的超链接是否有效。

2.{@link package.class#method label}

该标签与@see极其相似，只是它用于行内，并且是用“label”作为超链接文本而不用“See Also”。

3.{@docRoot}

该标签产生到文档根目录的相对路径，用于文档树页面的显示超链接。

4.{@inheritDoc}

该标签从当前这个类的最直接的基类中继承相关文档到当前的文档注释中。

5、@version

该标签的格式如下：

@version version -information

其中，“version-information” 可以是任何你认为适合包含在版本说明中的重要信息。

如果javadoc命令行使用了“-version”标记，那么就从生成的HTML文档中特别提取出 版本信息、

6.@author

该标签的格式如下：

@author author-information

其中，author-information一看便知是你的姓名，但是也可以包括电子邮件地址或者其他任何适宜的信息。

如果javadoc命令行使用了-author标记，那么就从生成的HTML文档中特别提取作者信息。

可以使用多个标签，以便列出所有作者，但是它们必须连续放置。

全部作者信息会合并到同一段落，置于生成的HTML。

7.@since

该标签允许你制定程序代码最早使用的版本，可以在HTML java文档中看到它被用来制定所用的JDK版本的情况。

8.@param

该标签用于方法文档中，形式如下：

@param parameter-name description

其中，parameter-name是方法的参数列表中的标识符，description是可延续数行的文本，终止于新的文档标签出现之前。

可以使用任意多个这种标签，大约每个参数都有一个这样的标签。

9.@return

该标签用于方法文档，格式如下：

@return description

其中“description”用来描述返回值的含义，可以延续数行

10.@throw

“异常”将在第9章论述，简言之，他们是由于某个方法调用失败而抛出的对象。

尽管在调用一个方法时，只出现一个异常对象，但是某个特殊方法可能会产生任意多个不同类型的异常，

所有这些异常都需要进行说明。所以，异常标签的格式如下：

@throw fully-qualified-class-name description

其中fully-qualified-class-name给出一个异常类的无歧义的名字，而该异常类在别处定义。

description告诉你为什么此特殊类型的异常会在方法调用中出现。

11.@deprecated

该标签用于指出一些就特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，

因为在不久的将来它们很可能会被删除。

如果使用一个标记为@deprecated的方法，则会引起编译器发布警告。

在Java SE5中，Javadoc标签@deprecated已经被@Deprecated注解所替代。