Java 注释技巧【总结的不错】

Java 注释技巧
    在最初学习Android时候使用了Eclips IDE工具，编写java程序时，老是要添加一些注释，用以说明某段代码的做用，因为是从C过分来的，也没有太在乎java的注释有何不一样，将鼠标移动到Android sdk 提供的类、方法、属性上时总会有提示信息，并且弹出的提示信息就是代码注释，不一样的是有一些特殊的符号，随着工程代码量的不断增长，文档注释的重要性日渐凸显，索性学习下Java的注释方法，让本身的代码变得更规范化一些。

JavaDoc工具
    Java 有三种注释语句：
    1.//用于单行注释。  
    2./*...*/用于多行注释，从/*开始，到*/结束，不能嵌套。  
    3./**...*/则是为支持 jdk 工具 javadoc.exe 而特有的注释语句。

    当你在代码中填写好注释后，就可使用JavaDoc工具提取程序中文档注释生成API文档，Javadoc 工具能从 java 源文件中读取第三种注释，并能识别注释中用@标识的一些特殊变量，制做成 Html 格式的类说明文档。javadoc 不但能对一个 java 源文件生成注释文档，并且能对目录和包生成交叉连接的 html 格式的类说明文档，十分方便。

    经常使用的Javadoc标记以下：
    @author         指定Java程序的做者
    @version        指定源文件版本
    @parameter      参数名及其意义
    @return         返回值
    @throws         异常类及抛出条件
    @deprecated     引发不推荐使用的警告（标识一个方法已经不推荐使用了）
    @see            “参见”，指定交叉参考的内容
    @since          表示从那个版本起开始有了这个函数 
    @note           表示注解，暴露给源码阅读者的文档 
    {@value}        当对常量进行注释时，若是想将其值包含在文档中，则经过该标签来引用常量的值。
    {@link包.类#成员} 连接到某个特定的成员对应的文档中。
    
    PS:只有/**...*/的注释语句中的内容才能被javadoc工具支持，因此javadoc的标记只能放在/**...*/注释中。

Javadoc与html
    因为Javadoc生成的是html的样式，因此在文档注释中支持部分html的标签，下面是在使用文档注释经常使用的标签：

    段落级标签
    1)段落: <p>用于标记段落的开始，段落结束</p>
    
    2)换行: <br>
    
    3)<pre>预格式化标签: 
    <pre>  </pre> 此标签用于显示预先已定义好格式的文本。当文本显示在浏览器中时，会遵循已在HTML源文档中定义的格式。

    文本格式化标签
    1)<b>标签
    <b>该文本将以粗体显示</b>
    
    2)<i>标签
    <i>该文本将以斜体显示</i>
    
    3)<sub>标签
    _{该文本的显示高度将低于先后的文本}
    
    4)<sup>标签
    ^{该文本的显示高度将高于周围的文本}
    
    5)<blockquote>标签
    定义长的引用，<blockquote> </<blockquote>所包含的文字会被总体分离出来，让这段文字与周围文字造成对比，有缩进效果。

    5)<hr>
    <hr>用于定义水平分隔线
   

    列表标签
    <ul>  无序列表 
    <ol>  有序列表 
    <li>  列表项目的标签

    连接标签
    1)<a>  定义连接 href  指定连接地址
     <a href= "http://blog.csdn.net/jack_chen_00">博客地址</a>

文档注释范例
    
/**
 * <a href= "<a target=_blank href="http://blog.csdn.net/jack_chen_00">http://blog.csdn.net/jack_chen_00</a>">博客地址</a>
 * @author Jack·chen 
 */
public static class Person{
 
 /**男性，值为<a target=_blank href="mailto:{@value}*/">{@value}*/</a> 
 public static final int MALE = 1;
 /**女性，值为<a target=_blank href="mailto:{@value}*/">{@value}*/</a>
 public static final int FEMALE = 2;</p><p> /**
  * use to store person name 
  */
 protected String mName;
 /**
  * use to store second name of person
  * @see #mName
  */
 protected String mSecondName;
 
 /**/
 protected int mAge;</p><p> /**
  * Constructor that is called when inflating a view from XML. 
  * 
  * The class will be created after all children have been added.
  * added.
  * @version 1.0
  * @param mName name of person
  * @param mSndName  second name of person
  * @param mAge age of person
  */
 public Person(String mName,String mSndName, int mAge) {
  super();
  this.mName = mName;
  this.mSecondName = mSndName;
  this.mAge = mAge;
 }
 
 /**
  * ^Constructorthat is called when inflating a view from XML.
     * 
  * <ul>
  * <li>The view receives a hover event with action <a target=_blank href="mailto:{@link">{@link</a> MotionEvent#ACTION_HOVER_ENTER}
  * when the pointer enters the bounds of the view.</li>
  * <li>The view receives a hover event with action <a target=_blank href="mailto:{@link">{@link</a> MotionEvent#ACTION_HOVER_MOVE}
  * when the pointer has already entered the bounds of the view and has moved.</li>
  * <li>The view receives a hover event with action <a target=_blank href="mailto:{@link">{@link</a> MotionEvent#ACTION_HOVER_EXIT}
  * when the pointer has exited the bounds of the view or when the pointer is
  * about to go down due to a button click, tap, or similar user action that
  * causes the view to be touched.</li>
  * </ul>
  * 
  * <pre> public boolean onGenericMotionEvent(MotionEvent event) {
     *     if ((event.getSource() & InputDevice.SOURCE_CLASS_JOYSTICK) != 0) {
     *         if (event.getAction() == MotionEvent.ACTION_MOVE) {
     *             // process the joystick movement...
     *             return true;
     *         }
     *     }
     *     return super.onGenericMotionEvent(event);
     * }</pre>
     * 
  * <p>
  * The class will be created after all children have been added.
  * added.
  * @deprecated use <a target=_blank href="mailto:{@link">{@link</a> #Person(String,String,int)} instead
  * @version 1.0
  * @see Monkey
  * @param mName name of person
  * @param mAge age of person
  */
 public Person(String mName, int mAge) {
  super();
  this.mName = mName;
  this.mAge = mAge;
 }
 
}
Annotation
    从JDK 1.5开始，Java增长了对元数据(MeteData)的支持，也就是annotation(注释)，这种Annotation与前面讲的注释有必定的却别，它是代码一种特殊的标记，这些标记能够在编译、类加载、运行时被读取，并执行相应的处理。经过Annotation，程序员能够在不更改源码的状况下嵌入一些补充信息，访问和处理Annotation的工具统称为APT(Annotation Processing Tool)。代码分析工具、开发工具能够利用这些补充信息进行验证，好比Eclips能够根据@Override检查复写方法的正确性。   

    标准的Annotation
    先看下Java提供的3个最基本的Annotation的用法：
    @Deprecated
    可做用于方法、类、接口等，它的做用于文档中注释中的@deprecated基本相同，是告诉编译器此方法、类等已经不建议使用了，以便在编程时给出警告。
    
    @Override
    只能做用于方法，用于指出该方法是重载父类的方法，它的做用是告诉编译器检查这个方法的语法是否正确，避免犯一些方法名称写错的低级错误。
    
    @SuppressWarnings
    用于消除编译器警告，在某些状况下编译警告是被容许或者合法，在这种状况下就可使用@SuppressWarnings消除编译器警告
    
    若是你是用IDE工具Eclips开发Android 应用程序，你会发现上面提到的三个Annotation不须要手动添加，Eclips会自动提示你警告的缘由以及解决办法，并自动帮你生成合适的Annotation补充信息，基本不须要程序员手动添加。
   

    自定义Annotation
    除了标准的Annotation，程序员还能够编写自定义的Annotation，自定义的Annotation可用于debug和编写一些测试程序。
    java中自定义annotation须要@interface关键字和用到几个内置annotation。用到的元注解有@Target, @Retention, @Documented, @Inherited ，用途以下：
    @Target 表示该注解用于什么地方，可能的 ElemenetType 参数包括： 
        ElemenetType.CONSTRUCTOR 构造器声明 
        ElemenetType.FIELD 域声明（包括 enum 实例） 
        ElemenetType.LOCAL_VARIABLE 局部变量声明 
        ElemenetType.METHOD 方法声明 
        ElemenetType.PACKAGE 包声明 
        ElemenetType.PARAMETER 参数声明 
        ElemenetType.TYPE 类，接口（包括注解类型）或enum声明 
         
    @Retention 表示在什么级别保存该注解信息。可选的 RetentionPolicy 参数包括： 
        RetentionPolicy.SOURCE 注解将被编译器丢弃 
        RetentionPolicy.CLASS 注解在class文件中可用，但会被VM丢弃 
        RetentionPolicy.RUNTIME VM将在运行期也保留注释，所以能够经过反射机制读取注解的信息。 
         
    @Documented 将此注解包含在 javadoc 中 
     
    @Inherited 容许子类继承父类中的注解

   

package javatest;   import java.lang.annotation.Documented; import java.lang.annotation.ElementType; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; import java.lang.reflect.Method; import java.util.HashSet; import java.util.Set;   public class JavaProject {           @Target(ElementType.TYPE)     @Retention(RetentionPolicy.RUNTIME)     @Documented     public @interface Description {         String value() default "no description";     }       @Target(ElementType.METHOD)     @Retention(RetentionPolicy.RUNTIME)     @Documented     public @interface Name {         String originate();         String community();     }       @Description("Mantis,Debug eye")     public static class JavaAnnotation {         @Name(originate = "创始人:jack", community = "sunplus")         public String getDebugProjectName() {             return "Mantis";         }         @Name(originate = "创始人:清风道人", community = "suncompany")         public String getStateName() {             return "debuging";         }     }         public static void main(String[] args) {         Class test = JavaAnnotation.class;         Method[] methods = test.getMethods();         boolean flag = test.isAnnotationPresent(Description.class);         if (flag) {             Description des = (Description) test.getAnnotation(Description.class);             System.out.println("描述:" + des.value());             System.out.println("-----------------");         }         Set<Method> set = new HashSet<Method>();         for (int i = 0; i < methods.length; i++) {             boolean otherflag = methods[i].isAnnotationPresent(Name.class);             if (otherflag) {                 set.add(methods[i]);             }         }         for (Method method : set) {             Name name = method.getAnnotation(Name.class);             System.out.println(name.originate());             System.out.println("建立的社区:" + name.community());         }     }   }