JavaSE_JavaDoc注释详解

.javadoc可以根据项目代码的注释（当然是规范化的）自动生成HTML格式的API文档。 
三种注释类型（注释必须紧贴着注释体，不然javadoc会忽略）： 
类注释 
变量注释 
方法注释 

书写格式： 
/** <--> 
* ........ 
* @XXX <--> 
*/ 
参数说明===================== 

javadoc 标记由“@”及其后所跟的标记类型和专用注释引用组成 
javadoc 标记有如下一些： 
@author 标明开发该类模块的作者 
@version 标明该类模块的版本 
@see 参考转向，也就是相关主题 
@param 对方法中某参数的说明 
@return 对方法返回值的说明 
@exception 对方法可能抛出的异常进行说明 

@author 作者名 
@version 版本号 
其中，@author 可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号 (,) 隔开。@version 也可以使用多次，只有第一次有效 

使用 @param、@return 和 @exception 说明方法 
这三个标记都是只用于方法的。@param 描述方法的参数，@return 描述方法的返回值，@exception 描述方法可能抛出的异常。它们的句法如下： 
@param 参数名 参数说明 
@return 返回值说明 
@exception 异常类名 说明 
============================================== 

参数说明： 
@see 生成文档中的“参见xx 的条目”的超链接，后边可以加上：“类名”、“完整类名”、“完整类名#方法”。可用于：类、方法、变量注释。 
@param 参数的说明。可用于：方法注释。 
@return 返回值的说明。可用于：方法注释。 
@exception 可能抛出异常的说明。可用于：方法注释。 
@version 版本信息。可用于：类注释。 
@author 作者名。可用于：类注释。 

@deprecated 对类或方法的说明 该类或方法不建议使用,引起不推荐使用的警告 

@note 表示注解，暴露给源码阅读者的文档 

@remark 表示评论，暴露给客户程序员的文档 

@since 表示从那个版本起开始有了这个函数 

@see 表示交叉参考 

javadoc命令： 
javadoc [options] [packagenames] [sourcefiles] 

-public 仅显示 public 类和成员 
-protected 显示 protected/public 类和成员 (缺省) 
-package 显示 package/protected/public 类和成员 
-private 显示所有类和成员 
-d 输出文件的目标目录 
-version 包含 @version 段 
-author 包含 @author 段 
-splitindex 将索引分为每个字母对应一个文件 

@interface 

它用于定义新的注释类型（annotation type）。新建一个注释类型看起来和定义一Interface 没有什么两样， 
MyTag.java用于新建一个用户自定义标签，代码如下， 

＝=============================================================================== 
package tiger.annotation; 
/** 
* 用户自定义标签??MyTag 
*/ 
public @interface MyTag { } 

定义了一个tag之后，我们就可以在任何java文件中使用这个tag了， 
import tiger.annotation.MyTag; 
public class TagTest{ 
    
    @MyTag 
    public void testTag(){ 
    } 
} 
=============================================================================== 

注释类型还可以有成员变量， 

============================================================================== 
package tiger.annotation; 
/** 
* 用户自定义标签??带有成员变量的MyTag 
*/ 
public @interface MyTag { 

    String name(); 

    int age(); 
} 
============================================================================= 

然后我们可以这么使用这个标签， 
    @MyTag(name="MyTag",age=1) 
    public void testTag(){ 
    } 

    使用标签最终是为了帮助开发人员提取注释信息，然后根据不同需求做进一步处理，下面我们来看看如何获取注释信息。 

============================================================================= 
import java.lang.annotation.Annotation; 
import tiger.annotation.MyTag; 
public class TagTest{ 
    
    @MyTag(name="MyTag",age=1) 
    public void test(){ 
    } 

    public static void main(String[] args){ 
        TagTest tt = new TagTest(); 
        try { 
            Annotation[] annotation =tt.getClass().getMethod("test").getAnnotations(); 
            for (Annotation tag :annotation) {             
              System.out.println("Tag is:" + tag); 
              System.out.println("tag.name()" + ((MyTag)tag).name()); 
              System.out.println("tag.age()" + ((MyTag)(tag)).age()); 
             } 
         } catch(NoSuchMethodException e) { 
             e.printStackTrace(); 
         } 
    } 
} 
=============================================================================== 

     需要注意的一点是，在执行这段代码之前我们还有一点小工作要做，还需要给我们的自定义标签MyTag加上一个说明标签，@ Retention, 表明注释信息将可以在运行时刻通过反射机制得到。如果不加入这个标签，上面的代码将没有任何输出。修改以后的MyTag如下， 

================================================================================ 
/** 
* 用户自定义标签??带有成员变量的MyTag 
*/ 
@Retention(RetentionPolicy.RUNTIME) 
public @interface MyTag { 

    String name(); 

    int age(); 
} 
================================================================================ 

然后我们执行TagTest可以得到输出如下， 

Tag is:@tiger.annotation.MyTag(name=MyTag, age=1) 
tag.name()MyTag 
tag.age()1 

好了，Tiger新的注释语法基本用法就这么简单，基本用法虽然简单，但是获取注释信息之后如何处理确很值得推敲，我们可以用他们来做一些语法检查，文件相关性检查，进行各种统计等等