java编程思想练习题-第2章练习13-javadoc

题目：通过javadoc运行Documentation1.java，然后通过web浏览器验证所产生的文档

 

分析：javadoc是一个非常强大的工具，只要代码中符合规则添加相应域以及方法的注释，可以轻松的生成友好的api文档。这对于经常编写jar包的朋友来说是一个很好并且触手可得的工具。

/** A class comment */
public class Documentation1 {
	/** A field comment */
	public int i;
	/** A method comment */
	public void f() {}
}

 

javadoc注释中有两个*注意。

这是一个最简单的例子，执行javadoc

效果感人。当然因为生成的是html，所以注释中写html语言是可以的，这里就不深入讲了。

 

javadoc标记：

javadoc 标记由"@"及其后所跟的标记类型和专用注释引用组成
javadoc标记有如下一些：

1. @author 标明开发该类模块的作者 
2. @version 标明该类模块的版本 
3. @see 参考转向，也就是相关主题 
4. @param 对方法中某参数的说明 
5. @return 对方法返回值的说明 
6. @exception 对方法可能抛出的异常进行说明 

@author作者名
@version版本号
其中，@author可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号(,)隔开。@version也可以使用多次，只有第一次有效

使用@param、@return和@exception说明方法
这三个标记都是只用于方法的。@param描述方法的参数，@return描述方法的返回值，@exception描述方法可能抛出的异常。它们的句法如下：
@param参数名参数说明
@return返回值说明
@exception异常类名说明

 

一个例子来把这几个标记串一下就是：

/**
* @author chj
* @version 1.0
*/
public class test {
	/**
* show 方法的简述.
* <p>show 方法的详细说明第一行<br>
* show 方法的详细说明第二行
* @param b true 表示显示，false 表示隐藏
* @return true or false
* @exception java.lang.Exception throw when switch is 1
* @see  test#anothersshow
*/

public boolean show(boolean b) throws Exception {
if(b==false)
	throw new Exception("Test Only");
return b;
}

public void anothersshow(boolean b) {
frame.show(b);
}	
	

}

 总结：javadoc工具很好很强大，养成使用的习惯往往事半功倍