Java语言提供了一种强大的注释形式:文档注释。可以将源代码里的文档注释提取成一份系统的API文档。我们在开发中定义类、方法时可以先添加文档注释,然后使用javadoc工具来生成自己的API文档。
文档注释以斜线后紧跟两个星号(/**)开始,以星号后紧跟一个斜线(*/)作为结尾,中间部分全部都是文档注释,会被提取到API文档中。
例子:
package com.yuchao.javadoc;
/**
* Description:
* <br/>Copyright(C),2011-2012,Jack.Yu
* <br/>This program is protected by copyright laws.
* <br/>Program Name:
* <br/>Data:
* @author Jack.Yu
* @version 1.0
*/
public class JavaDocClass {
/**
* 内部属性:name
*/
private String name;
/**
* Setter方法
* @return name
*/
public String getName() {
return name;
}
/**
* Getter方法
* @param name
*/
public void setName(String name) {
this.name = name;
}
}
javadoc命令可对源文件、包来生成API文档,常用选项有如下几个:
* -d<directory> 该选项指定一个路径,用于将生成API文档放到指定目录下
* -windowtitle<text>:该选项指定一个字符串,用于设置API文档的浏览器窗口标题
* doctitle<html-code>:该选项指定一个HTML格式的文本,用于指定概述页面的标题
* -header<html-code>:该选项指定一个HTML格式的文本,包含每个页面的页眉
例如对刚才的类生成API文档:
javadoc -d apidoc -windowtitle 实例 -doctitle 工具 -header 自定义类 JavaDoc*.java
除此之外,如果我们希望javadoc工具生成更详细的文档信息,例如为方法参数、方法返回值等生成详细的说明信息,则可以利用javadoc标记,有如下标记:
@author
@version
@deprecated
@param
@return
@see
@exception
@throws