java注释文档

使用 javadoc的方式主要有两种：

（1）嵌入HTML

（2）“文档标签（doc tag）”

独立“文档标签”是一些以“@”字符开头的命令，且该“@”字符要置于注释行的最前面（即忽略前导 “*”之后的最前面）。而“行内文档标签（inline doc tag）”则可以出现在javadoc 注释中的任何地方，它们也是以“@”字符开头，但要括在花括号内。

 

共有三种类型的注释文档，分别对应于注释位置后面的三种元素：类、变量和方法。

/** A class comment */
public class DocTest {
    /** A variable comment */
    public int i;

    /** A method comment */
    public void f() {
    }
}

 

javadoc只能为public和protected成员进行文档注释。private和包内可访问成员的注释会被忽略掉，所以输出结果中看不到它们（不过可以通过-private进行标记，以便把private成员的注释 也包括在内）。

 

javadoc通过生成HTML文档传送HTML命令，这使得你能够充分利用HTML。当然，其主要的目的还是为了对代码进行格式化。

注意 ，在文档注释中，位于每一行开头的星号和前导空格都会被javadoc丢弃。javadoc 会对所有内容重新格式化，使其与标准的的文档外观一致。不要在嵌入式 HTML中使用标题标签，例如<h1>，<hr>，因为javadoc会插入自己的标题，而你的标题 可能同它们发生冲突。

所有类型的注释文档——类、变量和方法——都支持嵌入式HTML。

 

一些标签实例

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#member 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”的文本可延续数行，终止于新的文档标签出现之前。你可以使用任意数量的此标签，大约每个参数都有一个这样的标签。

8.@return
该标签用于方法文档，格式如下：
@return description
其中，“description”用来描述返回值的含义，可以延续数行。

9.@throws
简言之，它们是由于某个方法调用失败而“抛出”的对象。尽管在调用一个方法时，只有出现一个异常对象，但是某个特殊方法可能会产生任意多、不同类型的异常，所有这些异常都需要进行说明。所以，异常标签的格式如下：
@throws fully-qualified-class-name description
其中，“fully-qualified-class-name”给出了一个异常类的完整名字，而且该异常类已经在某处定义过。而“description”（同样可以延续数行）告诉你为什么此特殊类型的异常会在方法调用中出现。

10.@deprecated
该标签用于指出一些旧特性已由改进的新特性所取代，建议用户不要再使用这些旧特性，因为在不久的将来，它们很可能会被移除。如果使用一个标记为@deprecated 的方法，则会引起编译器的警告。