JBuilder2005建设开拓文档之标签先容

副标题#e#

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.}

#p#副标题#e#

所有的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 结构函数具体描写

#p#副标题#e#

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

第35~40、45~48为要领的注释，@return为要领返回范例的说明，前面我们已经提到Javadoc文档包括了一个要领摘要列表，每个要领还对应一个具体描写部门，如getSex()的具体描写如下：

图 8 getSex()要领的具体说明

通过这个实例的描写，我们对Javadoc的标签和编写有了大抵的相识。注释一般置于须注释元素的前面，如类的注释位于public class Xxx类声明代码的前面，而值域的注释位于public int xxx前面。为了编写美妙的Javadoc文档，你不单需要把握简朴的HTML编写常识，更需要相识Javadoc标签的常识。

差异版本的JDK所支持的Javadoc标签是纷歧样的，另外还可以按标签合用的处所分成差异范例，如只合用于要领的@return标签，我们称之为要领标签，只合用于变量的@serial标签，我们称之为值域标签，以此类推。往往一个标签合用于多种处所，下表对常用Javadoc标签举办说明：

表 2?1 javadoc标签说明

#p#分页标题#e#

标签	说明	JDK 1.1 doclet	尺度doclet	标签范例
@author 作者	作者标识	√	√	包、 类、接口
@version 版本号	版本号	√	√	包、 类、接口
@param 参数名 描写	要领的入参名及描写信息，如入参有出格要求，可在此注释。	√	√	结构函数、 要领
@return 描写	对函数返回值的注释	√	√	要领
@deprecated 逾期文本	标识跟着措施版本的晋升，当前API已经逾期，仅为了担保兼容性依然存在，以此告之开拓者不该再用这个API。	√	√	包、类、接口、值域、结构函数、 要领
@throws异常类名	结构函数或要领所会抛出的异常。		√	结构函数、 要领
@exception 异常类名	同@throws。	√	√	结构函数、 要领
@see 引用	查察相关内容，如类、要领、变量等。	√	√	包、类、接口、值域、结构函数、 要领
@since 描写文本	API在什么措施的什么版本后开拓支持。	√	√	包、类、接口、值域、结构函数、 要领
{@link包.类#成员 标签}	链接到某个特定的成员对应的文档中。		√	包、类、接口、值域、结构函数、 要领
{@value}	当对常量举办注释时，假如想将其值包括在文档中，则通过该标签来引用常量的值。		√(JDK1.4)	静态值域

#p#副标题#e#

另外尚有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}几个不常用的标签，由于不常利用，我们展开论述，感乐趣的读者可以通过http://www.java.sun.com/J2SE/javadoc查察它们具体的辅佐信息。

下面我们对表中所列的几个不容易领略的Javadoc标签举例说明。

* @see

可以通过这个标签在当前点链接到某个类、值域或要领的说明上。为了链接到当前类的值域或要领上，在值域和要领名前必需带一个#号，如：

@see #getSex()
@see #MALE

也可以通过这个标签链接到其它类的要领、值域的说明处，假设我们建设一个称为javadoc的工程，在这个工程包罗了代码清单 1的javadoc.Person.java文件，此刻我们在工程中再添加一个javadoc.tool.Car类，其措施代码如下所示：

1.package javadoc.tool;
2.
3./**
4.* <pre>汽车工具类。</pre>
5.* @version 1.0, 2005-04-12
6.* @author 陈雄华
7.* @since JDK1.3
8.*/
9.public class Car
10.{
11.public Car()
12.{
13.}
14./**
15.* 按某一偏向驾驶汽车
16.* @param direction int 要领
17.* @param speed int 速度
18.*/
19.public void drive(int direction,int speed)
20.{
21./*do sth*/
22.}
23./**
24.* 朝前驾驶汽车
25.* @param speed int 速度
26.*/
27.public void drive(int speed)
28.{
29./*do sth*/
30.}
31.}

假如Person类和Car类有干系，我们就但愿在Person的Javadoc文档中给出一个拜见的Car文档的链接，以便开拓人员可以或许顺藤摸瓜找到有接洽的Car类的说明文档。要到达这一目标可以在Person类的注释中给出一个@see的标签。

#p#分页标题#e#

1./**
2.* <pre>描写人工具，拥有两个属性，别离是名字和性别。</pre>
3.* @see javadoc.tool.Car
4.* @version 1.0, 2005-04-12
5.* @author 陈雄华
6.* @since JDK1.3
7.*/

请看第3行的@see标签，因为Car和Person类不在同一个包中，所以必需指定类的全名，虽然，假如Person.java已经通过import chapter19.tool.Car;引入Car类，则@see可以直接用利用不带包的类名：@see Car。所以Javadoc中的@see引用注释和在Java代码中引用类是相似的。

一个更出格的应用场所是从当前文档中链接到重载要领，如Car中有两个drive()的重载要领，如何通过@see链接到差异的重载要领和注释中去呢？因为仅通过要领名无法定位，所以在要领名内里还需要指定入参的范例，请看下面的例子：

·@see javadoc.tool.Car#drive(int,int)：链接到drive(int direction,int speed)。

·@see javadoc.tool.Car#drive(int)：链接到drive(int speed)。

假如注释指定不正确，@see部门的注释将不呈此刻Javadoc文档中。

* @link

@link的@see很相似，独一差异的是它可以嵌套在注释的描写文本中，在生成Javadoc文档时转换成一个关联链接。如Person的结构函数的注释中的@link：

1./**
2.* 结构一个Person实例。设定Person的名字和性别。
3.*
4.* @param name String 名字
5.* @param sex int 性别，有效值是{@link #MALE }和{@link #FEMALE}
6.* @throws PersonArgumentException
7.* @see javadoc.tool.Car#drive(int)
8.*/

带{}的Javadoc标签象一个变量，在转换成文档后，将替换成一个详细的值或链接。