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

2024-07-21 02:15:16

字体：大中小

来源：转载

供稿：网友

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

　　所有的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 构造函数详细描述

　　构造函数的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标签说明

标签	说明	jdk 1.1 doclet	标准doclet	标签类型
@author 作者	作者标识	√	√	包、类、接口
@version 版本号	版本号	√	√	包、类、接口
@param 参数名描述	方法的入参名及描述信息，如入参有特别要求，可在此注释。	√	√	构造函数、方法
@return 描述	对函数返回值的注释	√	√	方法
@deprecated 过期文本	标识随着程序版本的提升，当前api已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个api。	√	√	包、类、接口、值域、构造函数、方法
@throws异常类名	构造函数或方法所会抛出的异常。		√	构造函数、方法
@exception 异常类名	同@throws。	√	√	构造函数、方法
@see 引用	查看相关内容，如类、方法、变量等。	√	√	包、类、接口、值域、构造函数、方法
@since 描述文本	api在什么程序的什么版本后开发支持。	√	√	包、类、接口、值域、构造函数、方法
{@link包.类#成员标签}	链接到某个特定的成员对应的文档中。		√	包、类、接口、值域、构造函数、方法
{@value}	当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。		√(jdk1.4)	静态值域

　　此外还有@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的标签。

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标签象一个变量，在转换成文档后，将替换成一个具体的值或链接。

上一篇：JBuilder2005创建开发文档之编写注释

下一篇：Eclipse Form程序设计指南之入门