JBuilder2005创建开发文档之标签介绍 - 编程入门网

JBuilder2005创建开发文档之标签介绍

Javadoc注释由Javadoc标签和描述性文本组成，你可以为类、接口添加注释，也可为构造函数、值域、方法等类中的元素添加注释。我们来看一个带Javadoc注释的程序，其代码如下所示：

代码清单 1 Person.java

1.package javadoc; 2.import java.io.Serializable; 3./** 4.* <pre>描述人对象，拥有两个属性，分别是名字和性别。</pre> 5.* @see javadoc.tool.Car 6.* @version 1.0, 2005-04-12 7.* @author 陈雄华 8.* @since JDK1.3 9.*/ 10.public class Person implements Serializable 11.{ 12./**男性，值为{@value}*/ 13.public static final int MALE = 1; 14./**女性，值为{@value}*/ 15.public static final int FEMALE = 2; 16./**名字*/ 17.protected String name; 18./**年龄*/ 19.protected int sex; 20./** 21.* 构造一个Person实例。设定Person的名字和性别。 22.* 23.* @param name String 名字 24.* @param sex int 性别，有效值是{@link #MALE 男性}和{@link #FEMALE} 25.* @throws PersonArgumentException 26.* @see javadoc.tool.Car#drive(int) 27.*/ 28.public Person(String name ,int sex) throws PersonArgumentException 29.{ 30.if(sex != MALE && sex != FEMALE) 31.throw new PersonArgumentException("参数不正确"); 32.this.name = name; 33.this.sex = sex; 34.} 35./** 36.* 获取性别代号。 37.* @return int 38.* @see MALE 39.* @see FEMALE 40.*/ 41.public int getSex() 42.{ 43.return sex; 44.} 45./** 46.* 设置性别 47.* @param sex int 48.*/ 49.public void setSex(int sex) 50.{ 51.this.sex = sex; 52.} 53.}

JBuilder2005创建开发文档之标签介绍(2)

所有的Javadoc注释以/**开始，以*/结束，每个注释包含一些描述性的文本及若干个Javadoc标签。描述性的文本不但可以用平面文本，还可以使用HTML文本；Javadoc标签一般以"@"为前缀，有的也以"{@"为前缀，以"}"结束，如{@value }。

第3~9行是类的注释，它位于类定义代码行前，其中第3行中的<pre></pre>标签是HTML标签，而第4~7行是Javadoc标签，这段注释映射在Javadoc文档中的显示样式如下图所示：

图 4 类注释

第12、14行是常量的注释，位于常量定义代码行之前，{@value}表示将常量的值输出到Javadoc文档中，第16、18是成员变量的注释。成员常量和变量统称为值域，它们在一起显示：

图 5 成员常量/变量注释摘要

除注释摘要以外，每个成员值域都有自己独立的详细注释。

第20~27是类构造函数的注释，构造函数有两句描述信息，第一句是"构造一个Person实例。"第二句是"设定Person的名字和性别。"，在构造函数的摘要列表中仅会显示第一句描述信息，用"。"分隔每句描述信息。而在构造函数的详细说明部分，则会显示所有的描述信息。这个原则同样适合于变量、方法的摘要，请看下面Javadoc帮助文档中关于方法摘要及方法详细说明，如图26-6，图26-7所示：

图 6 方法摘要

图 7 构造函数详细描述

JBuilder2005创建开发文档之标签介绍(3)

构造函数的Javadoc标签比较多，@param为方法入参的说明，@throws为方法抛出异常的说明，<@link>标签将在Javadoc文档中提供一个链接到文档中其它部分的URL。

第35~40、45~48为方法的注释，@return为方法返回类型的说明，前面我们已经提到Javadoc文档包含了一个方法摘要列表，每个方法还对应一个详细描述部分，如getSex()的详细描述如

凌众科技专业提供服务器租用、服务器托管、企业邮局、虚拟主机等服务，公司网站：http://www.lingzhong.cn 为了给广大客户了解更多的技术信息，本技术文章收集来源于网络,凌众科技尊重文章作者的版权，如果有涉及你的版权有必要删除你的文章，请和我们联系。以上信息与文章正文是不可分割的一部分,如果您要转载本文章,请保留以上信息，谢谢!