分享
 
 
 

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

王朝other·作者佚名  2006-11-24
窄屏简体版  字體: |||超大  

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标签说明

此外还有@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. */

 
 
 
免责声明:本文为网络用户发布,其观点仅代表作者个人观点,与本站无关,本站仅提供信息存储服务。文中陈述内容未经本站证实,其真实性、完整性、及时性本站不作任何保证或承诺,请读者仅作参考,并请自行核实相关内容。
2023年上半年GDP全球前十五强
 百态   2023-10-24
美众议院议长启动对拜登的弹劾调查
 百态   2023-09-13
上海、济南、武汉等多地出现不明坠落物
 探索   2023-09-06
印度或要将国名改为“巴拉特”
 百态   2023-09-06
男子为女友送行,买票不登机被捕
 百态   2023-08-20
手机地震预警功能怎么开?
 干货   2023-08-06
女子4年卖2套房花700多万做美容:不但没变美脸,面部还出现变形
 百态   2023-08-04
住户一楼被水淹 还冲来8头猪
 百态   2023-07-31
女子体内爬出大量瓜子状活虫
 百态   2023-07-25
地球连续35年收到神秘规律性信号,网友:不要回答!
 探索   2023-07-21
全球镓价格本周大涨27%
 探索   2023-07-09
钱都流向了那些不缺钱的人,苦都留给了能吃苦的人
 探索   2023-07-02
倩女手游刀客魅者强控制(强混乱强眩晕强睡眠)和对应控制抗性的关系
 百态   2020-08-20
美国5月9日最新疫情:美国确诊人数突破131万
 百态   2020-05-09
荷兰政府宣布将集体辞职
 干货   2020-04-30
倩女幽魂手游师徒任务情义春秋猜成语答案逍遥观:鹏程万里
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案神机营:射石饮羽
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案昆仑山:拔刀相助
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案天工阁:鬼斧神工
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案丝路古道:单枪匹马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:与虎谋皮
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:李代桃僵
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案镇郊荒野:指鹿为马
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:小鸟依人
 干货   2019-11-12
倩女幽魂手游师徒任务情义春秋猜成语答案金陵:千金买邻
 干货   2019-11-12
 
推荐阅读
 
 
 
>>返回首頁<<
 
靜靜地坐在廢墟上,四周的荒凉一望無際,忽然覺得,淒涼也很美
© 2005- 王朝網路 版權所有