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

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的名字和性别。"，在构造函数的摘要列表中仅会显示第一句描述信息，用"。"分隔每句描述信息。而在构造函数的详细说明部分，则会显示所有的描述信息。