java的注释

首先先感叹一下,java真的是十分强大。

好,我们进入正题,java注释可谓是相当完善了,java的注释不但在实际源代码中的可读性相当好,而且还能够生成html甚至其他类型的配套文档。今天,我们就来看看如何使用java中提供的javadoc工具帮我们的代码生成一些十分专业和有用的文档。其实我们通常所查阅的API文档,就是对类库文件运行javadoc生成的,所以说,当你想查阅API文档却发现自己的计算机没有联网,而且你下载的离线文档也找不到的时候,可以使用javadoc自己做一个哦。。


下面,就来看看如何使用注释。

javadoc会从以下四个特性中抽取信息:

分别是包、公有类与接口、公有的和受保护的构造器和方法、公有的和受保护的域。

注释的形式都一样,都是/**... ...*/的形式,其中在/**后紧跟的是自由文本,自由文本中可以使用HTML修饰符,例如<em>...<em>,<strong></strong>,<img...>等,但是不能使用<h1>或<hr>因为这样会产生冲突,如果要写入等宽代码,需要使用{@code...}。然后后面可以跟各种标记,例如@author,@version


下面就来说明一下各种注释的位置:

首先是类注释:类注释需要放在import语句之后,类定义之前。

然后是方法注释:方法注释必须放在所描述的方法之前。

再就是域注释:放到域的前面

最后是包注释:提供一个以package.html命名的HTML文件(将描述内容放入<body></body>中)或者提供一个package-info.java的文件(对哪个包进行注释,就要在这个文件中加入注释信息,并在最后写一行package 包名)。


上面提到了标记:标记可以更加清楚使我们的描述源文件,所有的标记并不多,下面来介绍一下常用标记的详细使用方法。

首先来看看它们的作用吧

标记分为通用标记和专门的标记,比如说方法注释中可以使用@param和@return标记,而包注释中却没有,这很好理解,包当然不会有参数和返回值了。。。。而它们却有共同的标记如@author,因为它们都是人写的。

首先是通用标记

(1)@author:这个标记会产生一个作者条目,使用方法为    @author 作者名    当然,允许在同一个注释中插入多个作者

(2)@see:这个标记会产生一个链接,后面的参数可以以下形式之一:

    --包名.类名#方法名(参数)

    --一个超链接

    --"文本"

当然也可以使用{link args}来替代,这个形式的优势是可以放在注释的任何部分,其中args是上面3种形式之一。(什么,为什么我的只能引用第一种,这可能是javadoc的版本不一样,不用担心,没办法。。。博主我的就不行,但书上说可以,我也是醉了)

(3)@category:表示属于哪一类

(4)@since:这个标记将产生一个"since"(始于)条目。使用方法为    @since 文本    这里的文本可以是对引入特性的版本描述。例如:@since fun方法的参数由int替换为Integer

然后是专门的标记

(1)@deprecated:这个标记将对类、方法或变量添加一个不再使用的注解。文本中给出了取代的建议。

例如@deprecated Use <code>setVisible(true)</code> instead +(@see或@link的引用)

还有一个比较重要的是,一个方法会有@exception、@throws、@param、@return等经常用的注解,具体顾名思义,不再解释。


具体生成文档和进一步了解java注释的有关内容请参阅人参米博主的文章

以下是一个例子以及生成的文档效果:

代码:

AnnotationTest.java

package Annotation;

import java.util.ArrayList;
/**
 * (类注释)该类演示了如何使用Java的各种注释
 * @author Administrator
 * @version 1.0
 * 
 */
public class AnnotationTest {
	
	/**
	 * (域注释)一个常量,圆周率
	 * 
	 */
	public static final double PI=3.1415926535;
	
	/**
	 * 
	 * 一个static域
	 */
	public static int t=7;
	
	/**
	 * 
	 * (方法注释)该方法将字符串容器中的字符挨行输出,并返回字符串的总数量
	 * @param sList 要进行输出的字符串容器的引用
	 * @return 容器中字符串的数量
	 */
	public static int output(ArrayList<String> sList) {
		int count=0;
		for(String s:sList) {
			System.out.println(s);
			++count;
		}
		return count;
	}
	
	/**
	 * (方法注释)这个不用多说了,main方法
	 * @param args 运行时参数
	 */
	public static void main(String[] args) {
		
	}

}

package-info.java

/**
 * 
 */
/**
 * (包注释)该包系统的演示的各种注释的使用方法
 * 
 */
package Annotation;

下面是生成文档的效果图:



参考资料:java核心技术第9版

阅读更多 登录后自动展开
想对作者说点什么? 我来说一句

没有更多推荐了,返回首页