Javadoc的使用

阅读更多

在默认的情况下，Javadoc是生成描述包和类型的HTML文件。所生成的每一个HTML文件都描述了一个包或者一个类型。
Javadoc输入是Java源程序，且Javadoc会忽略源代码中任何编译错误。默认的输出是一组HTML文件，但可以定制Javadoc，将输出设置为不同的格式。
文档注解以/**开头，*/结尾，包含一行或多行的文本，每一行前面都可以加一个“*”，解析时，所有的“*”和标签都会被忽略。
例1：
/**
* This is a comment
*/
文档注解也可包含标签，但必须是可处理的特殊关键字，标签必须放在文档注解的描述之后，一条注解可以包含多个标签，也可以只有标签，没有描述。
标签必须出现在一行的最前面，忽略之前的星号、空格和其他分隔符（/**）。
标签有两类：
块标签或独立标签，显示为@tag
内嵌式标签，显示在一对花括号之内：｛@tag｝
例2：
/**
* This is a comment
* @author jack
*/

一般的标签含义：
@author name  指定被标注类或者方法的作者
｛@code｝  以代码字体显示文本
｛@docRoot｝ 指定生成文档的根目录，当需要将一个外部文件放在所生成的所有页面中时，这个标签非常有用
@deprecated  指明已弃用的类型或者方法
@exception  指明该方法或构造器可能抛出异常，也可以用@throws表示相同含义
｛@link｝ 插入一个超文本链接
｛@literal text｝ 将文本中的所有特殊的字符都进行转义
@param parameterName description  描述一个方法或者构造器的参数
@return  描述一个方法的返回值
@see  后面可以带一个引用某个资源的文本条目或者链接
@serial  fieldDescription |include|exclude   描述一个默认的序列化域
@since text 参数text包含某个类或者某个类成员开始可用的软件版本号
｛@value｝/｛@value package.class#field｝ 不带参数用来描述一个静态域，并显示该常量的值；带参数时，该标签可以用来描述任何程序元素
@version text  用来描述版本