2008年（5645）
分类：
2008-04-28 21:44:52
描述人对象，拥有两个属性，分别是名字和性别。5. * @see javadoc.tool.Car6. * @version 1.0, 2005-04-127. * @author 陈雄华8. * @since JDK1.39. */10. public class Person implements Serializable11. {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 PersonArgumentException26. * @see javadoc.tool.Car#drive(int)27. */28. public Person(String name ,int sex) throws PersonArgumentException29. {30. if(sex != MALE && sex != FEMALE)31. throw new PersonArgumentException("参数不正确");32. this.name = name;33. this.sex = sex;34. }35. /**36. * 获取性别代号。37. * @return int38. * @see MALE39. * @see FEMALE40. */41. public int getSex()42. {43. return sex;44. }45. /**46. * 设置性别 47. * @param sex int48. */49. public void setSex(int sex)50. {51. this.sex = sex;52. }53. } 所有的Javadoc注释以/**开始，以*/结束，每个注释包含一些描述性的文本及若干个Javadoc标签。描述性的文本不但可以用平面文本，还可以使用HTML文本；Javadoc标签一般以"@"为前缀，有的也以"{@"为前缀，以"}"结束，如{@value }。 第3~9行是类的注释，它位于类定义代码行前，其中第3行中的标签是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}几个不常用的标签，由于不常使用，我们展开叙述，感兴趣的读者可以通过查看它们详细的帮助信息。 下面我们对表中所列的几个不容易理解的Javadoc标签举例说明。 * @see 可以通过这个标签在当前点链接到某个类、值域或方法的说明上。为了链接到当前类的值域或方法上，在值域和方法名前必须带一个#号，如： @see #getSex()@see #MALE 也可以通过这个标签链接到其它类的方法、值域的说明处，假设我们创建一个称为javadoc的工程，在这个工程包括了代码清单 1的javadoc.Person.java文件，现在我们在工程中再添加一个javadoc.tool.Car类，其程序代码如下所示： 1. package javadoc.tool;2. 3. /**4. *
汽车对象类。5. * @version 1.0, 2005-04-126. * @author 陈雄华7. * @since JDK1.38. */9. public class Car10. {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. *
描述人对象，拥有两个属性，分别是名字和性别。3. * @see javadoc.tool.Car4. * @version 1.0, 2005-04-125. * @author 陈雄华6. * @since JDK1.37. */ 请看第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 PersonArgumentException7. * @see javadoc.tool.Car#drive(int)8. */ 带{}的Javadoc标签象一个变量，在转换成文档后，将替换成一个具体的值或链接。 Javadoc注释由Javadoc标签和描述性文本组成，你可以为类、接口添加注释，也可为构造函数、值域、方法等类中的元素添加注释。我们来看一个带Javadoc注释的程序，其代码如下所示： 代码清单 1 Person.java 1. package javadoc;2. import java.io.Serializable;3. /** 4. *
描述人对象，拥有两个属性，分别是名字和性别。5. * @see javadoc.tool.Car6. * @version 1.0, 2005-04-127. * @author 陈雄华8. * @since JDK1.39. */10. public class Person implements Serializable11. {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 PersonArgumentException26. * @see javadoc.tool.Car#drive(int)27. */28. public Person(String name ,int sex) throws PersonArgumentException29. {30. if(sex != MALE && sex != FEMALE)31. throw new PersonArgumentException("参数不正确");32. this.name = name;33. this.sex = sex;34. }35. /**36. * 获取性别代号。37. * @return int38. * @see MALE39. * @see FEMALE40. */41. public int getSex()42. {43. return sex;44. }45. /**46. * 设置性别 47. * @param sex int48. */49. public void setSex(int sex)50. {51. this.sex = sex;52. }53. } 所有的Javadoc注释以/**开始，以*/结束，每个注释包含一些描述性的文本及若干个Javadoc标签。描述性的文本不但可以用平面文本，还可以使用HTML文本；Javadoc标签一般以"@"为前缀，有的也以"{@"为前缀，以"}"结束，如{@value }。 第3~9行是类的注释，它位于类定义代码行前，其中第3行中的标签是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}几个不常用的标签，由于不常使用，我们展开叙述，感兴趣的读者可以通过查看它们详细的帮助信息。 下面我们对表中所列的几个不容易理解的Javadoc标签举例说明。 * @see 可以通过这个标签在当前点链接到某个类、值域或方法的说明上。为了链接到当前类的值域或方法上，在值域和方法名前必须带一个#号，如： @see #getSex()@see #MALE 也可以通过这个标签链接到其它类的方法、值域的说明处，假设我们创建一个称为javadoc的工程，在这个工程包括了代码清单 1的javadoc.Person.java文件，现在我们在工程中再添加一个javadoc.tool.Car类，其程序代码如下所示： 1. package javadoc.tool;2. 3. /**4. *
汽车对象类。5. * @version 1.0, 2005-04-126. * @author 陈雄华7. * @since JDK1.38. */9. public class Car10. {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. *
描述人对象，拥有两个属性，分别是名字和性别。3. * @see javadoc.tool.Car4. * @version 1.0, 2005-04-125. * @author 陈雄华6. * @since JDK1.37. */ 请看第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 PersonArgumentException7. * @see javadoc.tool.Car#drive(int)8. */ 带{}的Javadoc标签象一个变量，在转换成文档后，将替换成一个具体的值或链接。 下载本文示例代码
