JAVA 注释和嵌入式文档

javadoc命令只能始于"/**"，结束于"*/"。

javadoc只能为public或者protected成员进行文档注释。

Javadoc标签介绍

Javadoc注释由Javadoc标签和描述性文本组成，你可以为类、接口添加注释，也可为构造函数、值域、方法等类中的元素添加注释。我们来看一个带Javadoc注释的程序，其代码如下所示：

　　代码清单 1 Person.java

1. package javadoc; 2. import java.io.Serializable; 3. /**  4. * 描述人对象，拥有两个属性，分别是名字和性别。 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行中的

标签是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}
当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。