javadoc的使用

一.javadoc 介绍
我们在开发JAVA程序中, 可以使用Javadoc来进行程序文档的整理, 这有两个好处：
1.编写程序时如果他人引用了你写的类或函数，在引用时会自动显示帮助信息；
2.项目开发完成后，利用Java自带的JavaDoc工具就可以生成规范的API说明手册.


二.javadoc书写格式
Javadoc必须符合规定的书写格式，写法如下：
/** <- 这里一定要用两个星号, 否则会被认为是普通注释的
* 注释部分
*/ <-下边紧邻类型或函数名
public int getCount() { .......}

注释部分写法如下：
/**
* 类的注释信息
* @version 版本信息
* @author 作者名
* @see 类名
* @see 完整类名
* @see 完整类名#方法
*/
/**
* 函数的注释信息
* @param 参数名1 说明
* @param 参数名2 说明
* @return 返回值的说明
* @exception 异常完整类名 说明
* @deprecated
*/


三．参数的说明:
@see : 就是文档中的 参见xx 的条目, 其实就是超链接.
一般来说, 文档有三种类型: 类注释, 变量注释, 方法注释, 这三中类型的注释除了都可以包含 @see 参数外, 其它所包含的参数是不同的.
1. 类注释
类注释是写在类前面的, 用来说明类的一些情况, 可以包涵 @version,@author参数, 但Javadoc缺省情况下不处理, 也就是说不在最后文档中出现的, 为了使用这些信息, 我们可以加入参数 -version和 -author来强制输出到最后的文档中.
2. 变量注释
变量注释写在变量前面, 只能包含注释和@see 参数
3. 方法注释
方法注释可以包括
@param : 参数名是指参数列表内的标识符, 说明就是一些解释性质的文字, 可以多行.
@return : 返回值的说明, 可以多行
@exception : 完整类名应该明确指定一个违例类的名字，它是在其它某个地方定义好的。而说明则阐述为什么这种特殊类型的违例会在方法调用中出现。说明可以多行
@deprecated : 指出一些旧功能已由改进过的新功能取代。该标记的作用是建议用户不必再使用一种特定的功能，因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated，则使用该方法时会收到编译器的警告。

四.实例
/**
* javadoc 的实例
*
* @author zgw
* @version 1.0
*
*/
public class JavaDoc {

/** 说话者的姓名 */
private String talker;

/** 要说的话 */
private String words;

/** 默认构造函数 */
public JavaDoc() {

}

/**
* 初始化说话者和要说的话
*
* @param name  姓名
* @param words  要说的话
* @return 初始化结果
*/
private String initial(String talker, String words) {
this.talker = talker;
this.words = words;
return "talker:" + talker + " 要说的话是:" + words;
}

/**
* 和某人谈话
*
* @param person 谈话对象
*/
private void talk(String person){
System.out.println(talker + "对" + person +"说:"+this.words);
}
}

评论

1 楼 442917934 2009-06-29