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