java注释文档(javadoc),是便于提取注释的工具。通过javadoc,文档与代码建立了链接,不再是彼此分离的。大大方便了文档的维护工作。
javadoc执行之后会输出要提个HTML文件,可以用浏览器查看。这样改工具就使得我们只需创建和维护单一源文件,不需要单独写文档。
语法
javadoc文档以"/**"开头,"*/"结尾。
示例
/** A class comment */
public class Documentation1 {
/** A field comment */
public int i;
/** A method comment */
public void f() {}
}
注意Javadoc只能为public和protected成员进行文档注释,private和包访问成员的注释会被忽略掉 ,这点要注意。
javadoc可以内嵌HTML标签,如在pre标签之间写代码:
/**
* <pre>
* System.out.println(new Date());
* </pre>
*/
当然也可以写普通HTML:
/**
* You can <em>even</em> insert a list:
* <ol>
* <li> Item one
* <li> Item two
* <li> Item three
* </ol>
*/
常用javadoc标签
javadoc中又一些特殊的文档标签,用"@"开头的命令,有一些特殊的作用。
如果学习JDK源码,这些会发现这些文档注解经常出现
1.@see:引用其他类,链接到其他文档,格式如下:
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
使用后会出现"See Also"条目
2.{@link package.class#member}
与@see相似,只能用于行内作为超链接标签。不会出现"See Also"
3.{@docRoot}
链接到文档根路径
4.{@inheritDoc}
从这个类的父类中继承相关文档到当前文档注释
5.@version
包含版本信息说明。格式:
@version version-information
6.@author
作者信息。格式:
@author author-information
7.@since
指定代码最早使用版本
8.@param
用于方法文档中,说明参数含义。格式:
@param parameter-name description
9.@return
用于方法文档中,说明返回值含义。格式:
@return description
10.@throws
对异常进行说明。格式:
@throws fully-qualified-class-name description
11.@deprecated
指出该特性已经被改进或者被新特性取代,建议用户不要使用这些旧特性,因为将来可能会被删除。
使用带有此标记的方法,编译器会发出警告。
现在该注释已经被@Deprecated注解替代