- 微信
- 微博
  
  分享文章到微博
- 复制链接
  
  复制链接到剪贴板

疯狂JAVA之学习笔记（5）----------注释

brucexiaogui 发表于 2021/12/30 01:29:55 2021/12/30

【摘要】疯狂JAVA之学习笔记（5）----------注释     注释：程序的注释非常有用，大多数人在开始学习JAVA时候，非常努力的写程序，但大意了添加注释，可能他懒得原因，可能没有这种习惯。但是，添加注释具有很强大的作用。虽然注解不参加实际的编译过程，但是仍然被认为是程序中重要的部分。希望大家养成编码...

疯狂JAVA之学习笔记（5）----------注释

注释：

程序的注释非常有用，大多数人在开始学习JAVA时候，非常努力的写程序，但大意了添加注释，

可能他懒得原因，可能没有这种习惯。

但是，添加注释具有很强大的作用。虽然注解不参加实际的编译过程，但是仍然被认为是程序中重要的部分。

希望大家养成编码的好习惯，对后期的应用非常关键！

那么下面讲解一下注解的三种形式！

注解作用：每当你创建描述符性质的类或者接口时,一旦其中包含重复性的工作，就可以考虑使用注解来简化与自动化该过程。

Java提供了四种元注解，专门负责新注解的创建工作。

元注解

　　元注解的作用就是负责注解其他注解。Java5.0定义了4个标准的meta-annotation类型，它们被用来提供对其它 annotation类型作说明。Java5.0定义的元注解：
　　　1.@Target,
　　　 2.@Retention,
　　　 3.@Documented,
　　　 4.@Inherited

　　这些类型和它们所支持的类在java.lang.annotation包中可以找到。下面我们看一下每个元注解的作用和相应分参数的使用说明。

@Target

　　　@Target说明了Annotation所修饰的对象范围：Annotation可被用于 packages、types（类、接口、枚举、Annotation类型）、类型成员（方法、构造方法、成员变量、枚举值）、方法参数和本地变量（如循环变量、catch参数）。在Annotation类型的声明中使用了target可更加明晰其修饰的目标。

　　作用：用于描述注解的使用范围（即：被描述的注解可以用在什么地方）

　　取值(ElementType)有：

　　　　1.CONSTRUCTOR:用于描述构造器
　　　　2.FIELD:用于描述域
　　　　3.LOCAL_VARIABLE:用于描述局部变量
　　　　4.METHOD:用于描述方法
　　　　5.PACKAGE:用于描述包
　　　　6.PARAMETER:用于描述参数
　　　　7.TYPE:用于描述类、接口(包括注解类型) 或enum声明

使用示例：


  
   
    
     
    
    
     
      /***
     
    
   
    
     
    
    
     
       *
     
    
   
    
     
    
    
     
       * 实体注解接口
     
    
   
    
     
    
    
     
       */
     
    
   
    
     
    
    
     
      @Target(value = {ElementType.TYPE})
     
    
   
    
     
    
    
     
      @Retention(value = RetentionPolicy.RUNTIME)
     
    
   
    
     
    
    
     
      public @interface Entity {
     
    
   
    
     
    
    
         /***
     
    
   
    
     
    
    
     
       * 实体默认firstLevelCache属性为false
     
    
   
    
     
    
    
     
       * @return boolean
     
    
   
    
     
    
    
     
       */
     
    
   
    
     
    
    
         boolean firstLevelCache() default false;
     
    
   
    
     
    
    
         /***
     
    
   
    
     
    
    
     
       * 实体默认secondLevelCache属性为false
     
    
   
    
     
    
    
     
       * @return boolean
     
    
   
    
     
    
    
     
       */
     
    
   
    
     
    
    
         boolean secondLevelCache() default true;
     
    
   
    
     
    
    
         /***
     
    
   
    
     
    
    
     
       * 表名默认为空
     
    
   
    
     
    
    
     
       * @return String
     
    
   
    
     
    
    
     
       */
     
    
   
    
     
    
    
     
          String tableName() default "";
     
    
   
    
     
    
    
         /***
     
    
   
    
     
    
    
     
       * 默认以""分割注解
     
    
   
    
     
    
    
     
       */
     
    
   
    
     
    
    
     
          String split() default "";
     
    
   
    
     
    
    
     
      }

@Retention

　　@Retention定义了该Annotation被保留的时间长短：某些Annotation仅出现在源代码中，而被编译器丢弃；而另一些却被编译在class文件中；编译在class文件中的Annotation可能会被虚拟机忽略，而另一些在class被装载时将被读取（请注意并不影响class的执行，因为Annotation与class在使用上是被分离的）。使用这个meta-Annotation可以对 Annotation的“生命周期”限制。

　　作用：表示需要在什么级别保存该注释信息，用于描述注解的生命周期（即：被描述的注解在什么范围内有效）

　　取值（RetentionPoicy）有：

　　　　1.SOURCE:在源文件中有效（即源文件保留）
　　　　2.CLASS:在class文件中有效（即class保留）
　　　　3.RUNTIME:在运行时有效（即运行时保留）

使用示例：


  
   
    
     
    
    
     
      /***
     
    
   
    
     
    
    
     
       * 字段注解接口
     
    
   
    
     
    
    
     
       */
     
    
   
    
     
    
    
     
      @Target(value = {ElementType.FIELD})//注解可以被添加在属性上
     
    
   
    
     
    
    
     
      @Retention(value = RetentionPolicy.RUNTIME)//注解保存在JVM运行时刻,能够在运行时刻通过反射API来获取到注解的信息
     
    
   
    
     
    
    
     
      public @interface Column {
     
    
   
    
     
    
    
     
          String name();//注解的name属性

------------------------------

Column注解的的RetentionPolicy的属性值是RUTIME,这样注解处理器可以通过反射，获取到该注解的属性值，从而去做一些运行时的逻辑处理

@Documented

　　@Documented用于描述其它类型的annotation应该被作为被标注的程序成员的公共API，因此可以被例如javadoc此类的工具文档化。Documented是一个标记注解，没有成员。

@Inherited

　　@Inherited 元注解是一个标记注解，@Inherited阐述了某个被标注的类型是被继承的。如果一个使用了@Inherited修饰的annotation类型被用于一个class，则这个annotation将被用于该class的子类。

　　注意：@Inherited annotation类型是被标注过的class的子类所继承。类并不从它所实现的接口继承annotation，方法并不从它所重载的方法继承annotation。

　　当@Inherited annotation类型标注的annotation的Retention是RetentionPolicy.RUNTIME，则反射API增强了这种继承性。如果我们使用java.lang.reflect去查询一个@Inherited annotation类型的annotation时，反射代码检查将展开工作：检查class和其父类，直到发现指定的annotation类型被发现，或者到达类继承结构的顶层。

自定义注解

　　使用@interface自定义注解时，自动继承了java.lang.annotation.Annotation接口，由编译程序自动完成其他细节。在定义注解时，不能继承其他的注解或接口。@interface用来声明一个注解，其中的每一个方法实际上是声明了一个配置参数。方法的名称就是参数的名称，返回值类型就是参数的类型（返回值类型只能是基本类型、Class、String、enum）。可以通过default来声明参数的默认值。

　　定义注解格式：
　　public @interface 注解名 {定义体}

　　注解参数的可支持数据类型：

　　　　1.所有基本数据类型（int,float,boolean,byte,double,char,long,short)
　　　　2.String类型
　　　　3.Class类型
　　　　4.enum类型
　　　　5.Annotation类型
　　　　6.以上所有类型的数组

　　Annotation类型里面的参数该怎么设定:
　　第一,只能用public或默认(default)这两个访问权修饰.例如,String value();这里把方法设为defaul默认类型；　　
　　第二,参数成员只能用基本类型byte,short,char,int,long,float,double,boolean八种基本数据类型和 String,Enum,Class,annotations等数据类型,以及这一些类型的数组.例如,String value();这里的参数成员就为String;　　
　　第三,如果只有一个参数成员,最好把参数名称设为"value",后加小括号.例:下面的例子FruitName注解就只有一个参数成员。

　　简单的自定义注解和使用注解实例：

示例1：


  
   
    
     
    
    
     
      /***
     
    
   
    
     
    
    
     
       *主键注解接口
     
    
   
    
     
    
    
     
       */
     
    
   
    
     
    
    
     
      @Target(value = {ElementType.FIELD})
     
    
   
    
     
    
    
     
      @Retention(value = RetentionPolicy.RUNTIME)
     
    
   
    
     
    
    
     
      public @interface Id {
     
    
   
    
     
    
    
     
      }


  
   
    
     
    
    
     
      /**属性不需要被持久化注解**/
     
    
   
    
     
    
    
     
      @Target(value = {ElementType.FIELD})
     
    
   
    
     
    
    
     
      @Retention(value = RetentionPolicy.RUNTIME)
     
    
   
    
     
    
    
     
      @Documented
     
    
   
    
     
    
    
     
      public @interface Transient {
     
    
   
    
     
    
    
     
      }

-----------------------

注解元素的默认值：

　　注解元素必须有确定的值，要么在定义注解的默认值中指定，要么在使用注解时指定，非基本类型的注解元素的值不可为null。因此, 使用空字符串或0作为默认值是一种常用的做法。这个约束使得处理器很难表现一个元素的存在或缺失的状态，因为每个注解的声明中，所有元素都存在，并且都具有相应的值，为了绕开这个约束，我们只能定义一些特殊的值，例如空字符串或者负数，一次表示某个元素不存在，在定义注解时，这已经成为一个习惯用法。

定义了注解，并在需要的时候给相关类，类属性加上注解信息，如果没有响应的注解信息处理流程，注解可以说是没有实用价值。如何让注解真真的发挥作用，主要就在于注解处理方法，下一步我们将学习注解信息的获取和处理！

如果没有用来读取注解的方法和工作，那么注解也就不会比注释更有用处了。使用注解的过程中，很重要的一部分就是创建于使用注解处理器。Java SE5扩展了反射机制的API，以帮助程序员快速的构造自定义注解处理器。

注解处理器类库(java.lang.reflect.AnnotatedElement)：

　　Java使用Annotation接口来代表程序元素前面的注解，该接口是所有Annotation类型的父接口。除此之外，Java在java.lang.reflect 包下新增了AnnotatedElement接口，该接口代表程序中可以接受注解的程序元素，该接口主要有如下几个实现类：

　　Class：类定义
　　Constructor：构造器定义
　　Field：累的成员变量定义
　　Method：类的方法定义
　　Package：类的包定义

　　java.lang.reflect 包下主要包含一些实现反射功能的工具类，实际上，java.lang.reflect 包所有提供的反射API扩充了读取运行时Annotation信息的能力。当一个Annotation类型被定义为运行时的Annotation后，该注解才能是运行时可见，当class文件被装载时被保存在class文件中的Annotation才会被虚拟机读取。
　　AnnotatedElement 接口是所有程序元素（Class、Method和Constructor）的父接口，所以程序通过反射获取了某个类的AnnotatedElement对象之后，

程序就可以调用该对象的如下四个个方法来访问Annotation信息：

方法1：<T extends Annotation> T getAnnotation(Class<T> annotationClass): 返回改程序元素上存在的、指定类型的注解，如果该类型注解不存在，则返回null。
　　方法2：Annotation[] getAnnotations():返回该程序元素上存在的所有注解。
　　方法3：boolean is AnnotationPresent(Class<?extends Annotation> annotationClass):判断该程序元素上是否包含指定类型的注解，存在则返回true，否则返回false.
　　方法4：Annotation[] getDeclaredAnnotations()：返回直接存在于此元素上的所有注释。与此接口中的其他方法不同，该方法将忽略继承的注释。（如果没有注释直接存在于此元素上，则返回长度为零的一个数组。）该方法的调用者可以随意修改返回的数组；这不会对其他调用者返回的数组产生任何影响。

　　一个简单的注解处理器：

/***********注解声明***************/

/**
 * 水果名称注解
 * @author peida
 *
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitName {
    String value() default "";
}

/**
 * 水果颜色注解
 * @author peida
 *
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitColor {
    /**
     * 颜色枚举
     * @author peida
     *
     */
    public enum Color{ BULE,RED,GREEN};
    
    /**
     * 颜色属性
     * @return
     */
    Color fruitColor() default Color.GREEN;

}

/**
 * 水果供应者注解
 * @author peida
 *
 */
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitProvider {
    /**
     * 供应商编号
     * @return
     */
    public int id() default -1;
    
    /**
     * 供应商名称
     * @return
     */
    public String name() default "";
    
    /**
     * 供应商地址
     * @return
     */
    public String address() default "";
}

/***********注解使用***************/


  
   
    
     
    
    
     
      public class Apple {  
     
    
   
    
     
    
    
           
     
    
   
    
     
    
    
         @FruitName("Apple")  
     
    
   
    
     
    
    
         private String appleName;  
     
    
   
    
     
    
    
           
     
    
   
    
     
    
    
         @FruitColor(fruitColor=Color.RED)  
     
    
   
    
     
    
    
         private String appleColor;  
     
    
   
    
     
    
    
           
     
    
   
    
     
    
    
         @FruitProvider(id=1,name="陕西红富士集团",address="陕西省西安市延安路89号红富士大厦")  
     
    
   
    
     
    
    
         private String appleProvider;  
     
    
   
    
     
    
    
           
     
    
   
    
     
    
    
         public void setAppleColor(String appleColor) {  
     
    
   
    
     
    
    
             this.appleColor = appleColor;  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
         public String getAppleColor() {  
     
    
   
    
     
    
    
             return appleColor;  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
           
     
    
   
    
     
    
    
         public void setAppleName(String appleName) {  
     
    
   
    
     
    
    
             this.appleName = appleName;  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
         public String getAppleName() {  
     
    
   
    
     
    
    
             return appleName;  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
           
     
    
   
    
     
    
    
         public void setAppleProvider(String appleProvider) {  
     
    
   
    
     
    
    
             this.appleProvider = appleProvider;  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
         public String getAppleProvider() {  
     
    
   
    
     
    
    
             return appleProvider;  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
           
     
    
   
    
     
    
    
         public void displayName(){  
     
    
   
    
     
    
    
     
              System.out.println("水果的名字是：苹果");  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
     
      }  
     
    
   
    
     
    
    
       
     
    
   
    
     
    
    
     
      /***********注解处理器***************/  
     
    
   
    
     
    
    
       
     
    
   
    
     
    
    
     
      public class FruitInfoUtil {  
     
    
   
    
     
    
    
         public static void getFruitInfo(Class<?> clazz){  
     
    
   
    
     
    
    
               
     
    
   
    
     
    
    
     
              String strFruitName=" 水果名称：";  
     
    
   
    
     
    
    
     
              String strFruitColor=" 水果颜色：";  
     
    
   
    
     
    
    
     
              String strFruitProvicer="供应商信息：";  
     
    
   
    
     
    
    
               
     
    
   
    
     
    
    
     
              Field[] fields = clazz.getDeclaredFields();  
     
    
   
    
     
    
    
               
     
    
   
    
     
    
    
             for(Field field :fields){  
     
    
   
    
     
    
    
                 if(field.isAnnotationPresent(FruitName.class)){  
     
    
   
    
     
    
    
                     FruitName fruitName = (FruitName) field.getAnnotation(FruitName.class);  
     
    
   
    
     
    
    
     
                      strFruitName=strFruitName+fruitName.value();  
     
    
   
    
     
    
    
     
                      System.out.println(strFruitName);  
     
    
   
    
     
    
    
     
                  }  
     
    
   
    
     
    
    
                 else if(field.isAnnotationPresent(FruitColor.class)){  
     
    
   
    
     
    
    
     
                      FruitColor fruitColor= (FruitColor) field.getAnnotation(FruitColor.class);  
     
    
   
    
     
    
    
     
                      strFruitColor=strFruitColor+fruitColor.fruitColor().toString();  
     
    
   
    
     
    
    
     
                      System.out.println(strFruitColor);  
     
    
   
    
     
    
    
     
                  }  
     
    
   
    
     
    
    
                 else if(field.isAnnotationPresent(FruitProvider.class)){  
     
    
   
    
     
    
    
     
                      FruitProvider fruitProvider= (FruitProvider) field.getAnnotation(FruitProvider.class);  
     
    
   
    
     
    
    
     
                      strFruitProvicer=" 供应商编号："+fruitProvider.id()+" 供应商名称："+fruitProvider.name()+" 供应商地址："+fruitProvider.address();  
     
    
   
    
     
    
    
     
                      System.out.println(strFruitProvicer);  
     
    
   
    
     
    
    
     
                  }  
     
    
   
    
     
    
    
     
              }  
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
     
      }  
     
    
   
    
     
    
    
       
     
    
   
    
     
    
    
     
      /***********输出结果***************/  
     
    
   
    
     
    
    
     
      public class FruitRun {  
     
    
   
    
     
    
    
       
     
    
   
    
     
    
    
         /** 
     
    
   
    
     
    
    
     
       * @param args 
     
    
   
    
     
    
    
     
       */  
     
    
   
    
     
    
    
         public static void main(String[] args) {  
     
    
   
    
     
    
    
               
     
    
   
    
     
    
    
     
              FruitInfoUtil.getFruitInfo(Apple.class);  
     
    
   
    
     
    
    
               
     
    
   
    
     
    
    
     
          }  
     
    
   
    
     
    
    
       
     
    
   
    
     
    
    
     
      }  
     
    
   
    
     
    
    
       
     
    
   
    
     
    
    
     
      ====================================  
     
    
   
    
     
    
    
     
       水果名称：Apple  
     
    
   
    
     
    
    
     
       水果颜色：RED  
     
    
   
    
     
    
    
     
       供应商编号：1 供应商名称：陕西红富士集团 供应商地址：陕西省西安市延安路89号红富士大厦

--------------

Java注解的基础知识基本都过了一遍希望对你的学习有所帮助！

本文借鉴http://www.cnblogs.com/peida/archive/2013/04/26/3038503.html

附加一点其他借鉴来的注释学习内容。感觉很全面分享给大家！

在Java里面主要有三种注释：行注释、段落注释、文档注释

　　1)行注释：行注释也成为单行注释，行注释使用 “//注释文字”的格式来对某一行的代码进行注释或者加以说明

public class LineComment

{

//这是单行注释的范例

public static void main(String args[])

{

//这只是一个单行注释的例子

System.out.println("Single Line Comment");

}

　　上边代码里面//后边的文字就是行注释的一个例子

　　2)段注释：段注释也成为多行注释，通常是当说明文字比较长的时候的注释方法

public class MultiCommont

{

*这是段注释的一个简单的例子

*这里是函数入口main方法

public static void main(String args[])

{

System.out.println("Multi Lines Comments");

}

　　3)文档注释：文档注释是Java里面的一个比较厉害的功能，它可以用于注释类、属性、方法等说明，而且通过JDK工具javadoc直接生成相关文档，文档注释的基本格式为“/**...*/”，不仅仅如此，文档注释本身还存在语法

　　[1]文档和文档注释的格式化：

　　生成的文档是HTML格式的，而这些HTML格式的标识符并不是javadoc加的，而是我们在写注释的时候写上去的。因此在格式化文档的时候需要适当地加入HTML标签，例如：

/**

*This is first line.

*This is second line.

*This is third line.

**/

　　[2]文档注释的三部分：

　　根据在文档中显示的效果，文档注释可以分为三个部分，这里举个例子：

/**

*testDoc方法的简单描述

*testDoc方法的详细说明

*@param testInput String 打印输入的字符串

*@return 没有任何返回值

**/

public void testDoc(String testInput)

{

System.out.println(testInput);

}

　　简述：文档中，对于属性和方法都是现有一个列表，然后才在后面一个一个的详细说明，列表中属性名或者方法名后面那段说明都是简述。

　　详细说明：该部门对属性或者方法进行了详细说明，在格式上不需要特殊的要求，可以写成前边讲的HTML的格式，如同上边第二行的内容。【*：这里有个技巧就是简述和详细说明尽量不要重复，在简述中出现过的内容不需要在详细说明中进行第二次描述，可以理解为详细说明是简述的一种扩展。后边章节的概念说明代码大部分我都没有写注释，也请各位读者见谅！】

　　特殊说明：除开上边的两部分，最后一个部分就是特殊说明部分，特殊说明部分使用JavaDoc标记进行，这些都是JavaDoc工具能够解析的特殊标记，这一点下边章节将会讲到

　　[3]使用javadoc标记：

　　javadoc标记是java插入文档注释中的特殊标记，它们用于识别代码中的特殊引用。javadoc标记由“@”以及其后跟着的标记类型和专用注释引用组成。它的格式包含了三个部分：

　　@、标记类型、专用注释引用

　　有时候我们也可以直接理解为两个方面：@和标记类型、专用注释引用；Javadoc工具可以解析Java文档注释中嵌入的特殊标记，这些文档标记可以帮助自动从源代码生成完整的格式化API，标记用“@”符号开头，区分大小写，必须按照正确的大小写字母输入。标记必须从一行的开头开始，否则会被视为普通文本，而且按照规定应将相同名字的标记放一起，比如所有的@see标记应该放到一起，接下来看一看每一种标记的含义。

　　@author(1.0)：语法[@author name-text]

　　当使用-author选项的时候，用指定的name-text在生成文档的时候添加“Author”项，文档注释可以包含多个@author标记，可以对每个@author指定一个或者多个名字。

　　@deprecated(1.0)：语法[@deprecated deprecated-text]

　　添加注释，只是不应该再使用该API（尽管是可用的），Javadoc工具会将deprecated-text移动到描述前面，用斜体显示，并且在它前边添加粗体警告：“不鼓励使用”。deprecated-text的首句至少应该告诉用户什么时候开始不鼓励使用该API以及使用什么替代它。Javadoc仅将首句复制到概览部分和索引中，后面的语句还可解释为什么不鼓励使用，应该还包括一个指向替代API的{@link}标记【1.2版本用法】

对于Javadoc 1.2，使用{@link}标记，这将在需要的地方创建内嵌链接，如：

/**

*@deprecated 在JDK X.X中，被{@link #methodName(paramList)}取代

**/

【*：在上边的标记里面X.X指代JDK的版本，后边的链接链接的是方法的签名，methodName为方法名，paramList为参数列表】

对于Javadoc 1.1，标准格式是为每个@deprecated标记创建@see标记（它不可内嵌）

　　@exception(1.0)：语法[@exception class-name description]

　　@throws(1.2)：语法[@throws class-name description]

　　以上两个标记是同义词，用class-name和description文本给生成的文档添加“抛出”子标题，其中class-name是该方法可抛出的异常名。

　　{@link}(1.2)：语法[{@link name label}]

　　出入指向指定name的内嵌链接，该标记中name和label的语法与@see标记完全相同，如下所述，但是产生的内嵌链接而不是在“参见”部分防止链接。该标记用花括号开始并用花括号结束，以使它区别于其他内嵌文本，如果需要在标签内使用“}”，直接使用HTML的实体表示法：}

　　@param(1.0)：语法[@param parameter-name description]

　　给“参见”部分添加参数，描述可以继续到下一行进行操作，主要是提供了一些参数的格式以及描述

　　@return(1.0)：语法[@return description]

　　用description本文添加“返回”部分，该文本应描述值的返回类型和容许范围

　　@see(1.0)：语法[@see reference]

　　该标记是一个相对复杂的标记，添加“参见”标题，其中有指向reference的链接或者文本项，文档注释可包含任意数目的@see标记，它们都分组在相同的标题下，@see有三种格式：

@see “string” 注：该形式在JDK 1.2中没有用，它不打印引用文本

为string添加文本项，不产生链接，string是通过该URL不可用的书籍或者其他信息引用，Javadoc通过查找第一个字符为双引号（"）的情形来区分它前边的情况，比如：

@see "这是Java教材，主要是提供给初学者"

上边的注释将会生成：

参见：

　　“这是Java教材，主要是提供给初学者”

@see <a href="page.html#section">Java某章节</a>

添加URL#value定义的链接，其中URL#value是相对URL或者绝对URL，JavaDoc工具通过查找第一个字符小写符号（<）区分它与其他情况，比如：

@see <a href="page.html#section">测试规范</a>

上边的注释将会生成：

参见：

　　测试规范

@see package.class#member label【比较常用的一种格式】

添加带可见文本label的链接，它指向Java语言中指定名字的文档。其中label是可选的，如果省略，则名字作为可见文本出现，而且嵌在<code>HTML标记中，当想要缩写可见文本或不同于名字的可见文本的时候，可以使用label。

——package.class#member是Java语言中的任何有效名字——包名、类名、接口名、构造函数名、方法名或域名——除了用hash字符(#)取代成员名前面的点之外，如果该名字位于带文档的类中，则Javadoc将自动创建到它的链接，要创建到外部的引用链接，可使用-link选项，使用另外两种@see形式中的任何一种引用不属于引用类的名字的文档。

——label是可选文本，它是链接的可见标签，label可包含空白，如果省略label，则将显示package.class.member，并相对于当前类和包适当缩短

——空格是package.class#member和label之间的分界符，括号内的空格不表示标签的开始，因此在方法各参数之间可使用空格

@see package.class#member的典型形式

引用当前类的成员

@see #field

@see #method(Type,Type,...)

@see #method(Type argname,Type argname,...)

引用当前包或导入包中的其他类

@see Class#field

@see Class#method(Type,Type,...)

@see Class#method(Type argname,Type argname,...)

@see Class

引用其他包（全限定）

@see package.Class#field

@see package.Class#method(Type,Type,...)

@see package.Class#method(Type argname,Type argname,...)

@see package.Class

@see package简单说明一下：

——第一套形式（没有类和包）将导致 Javadoc 仅搜索当前类层次。它将查找当前类或接口、其父类或超接口、或其包含类或接口的成员。它不会搜索当前包的其余部分或其他包（搜索步骤 4-5）。

——如果任何方法或构造函数输入为不带括号的名字，例如 getValue，且如果没有具有相同名字的域，则 Javadoc 将正确创建到它的链接，但是将显示警告信息，提示添加括号和参数。如果该方法被重载，则 Javadoc 将链接到它搜索到的第一个未指定方法。

——对于所有形式，内部类必须指定为 outer.inner，而不是简单的 inner。

——如上所述，hash 字符（#）而不是点（.）用于分隔类和成员。这使 Javadoc 可正确解析，因为点还用于分隔类、内部类、包和子包。当 hash 字符（#）是第一个字符时，它是绝对不可少的。但是，在其他情况下，Javadoc 通常不严格，并允许在不产生歧义时使用点号，但是它将显示警告。

　　@see标记的搜索次序——JavaDoc将处理出现在源文件（.java）、包文件（package.html）或概述文件（overview.html）中的@see标记，在后两种文件中，必须完全限定使用@see提供的名字，在源文件中，可指定全限定或部分限定的名字，@see的搜索顺序为：

当前类或接口

任何包含类和接口，先搜索最近的

任何父类和超接口，先搜索最近的

当前包

任何导入包、类和接口，按导入语句的次序搜索

　　@since(1.1)：语法[@since since-text]

　　用since-text指定的内容给生成文档添加“Since”标题，该文本没有特殊内部结构，该标记表示该改变或功能自since-text所指定的软件件版本后就存在了，例如：@since JDK 1.4

　　@serial(1.2)：语法[@serial field-description]

　　用于缺省的可序列化域的文档注释中，可选的field-description增强了文档注释对域的描述能力，该组合描述必须解释该域的意义并列出可接受值，如果有需要描述可以多行，应该对自Serializable类的最初版本之后添加的每个可序列化的域添加@since标记。

　　@serialField(1.2)：语法[@serialField field-name field-type field-description]

　　简历Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档，应该对每个ObjectStreamField使用一个@serialField标记

　　@serialData(1.2)：语法[@serialData data-description]

　　data-description建立数据（尤其是writeObject方法所写入的可选数据和Externalizable.writeExternal方法写入的全部数据）序列和类型的文档，@serialData标记可用于writeObject、readObject、writeExternal和readExternal方法的文档注释中

　　@version(1.0)：语法[@version version-text]

　　当使用-version选项时用version-text指定的内容给生成文档添加“版本”子标题，该文本没有特殊内部结构，文档注释最多只能包含一个@version标记。

　　{@code}(1.5)：语法[{@code text}]

该标签等同于<code>{@literal}</code>，里面可以直接过滤掉HTML的标签，可以不用<和>来显示（<和>），在这个代码块里面的text部分，可以直接书写代码，即使使用了Hello，在HTML里面也不会识别成为加粗的Hello，而还是原来的代码段Hello的格式输出

　　{@docRoot}(1.3)：语法[{@docRoot}]

　　代表相对路径生成的文件的（目标）的根从任何产生的网页目录，当您要包括如版权页或公司徽标文件的时候它是有用的，你要引用所生成的网页，链接从每个页面底部的版权页面是常见的。（@docRoot将标记可用于在命令行，并在两个文档注释：这个标记是有效的，在所有文档注释：概述、包装类、接口、构造、方法和领域，包括任何标记文本的一部分（如@return ，@param和@deprecated的使用）。

　　比如：

/**

* See the <a href="{@docRoot}/copyright.html">Copyright</a>.

**/

　　{@inheritDoc}(1.4)：语法[{@inheritDoc}]

　　继承（拷贝）文档从最近的“继承类或可执行的接口”到当前在这个标签的位置的文档注释内容，这使您可以编写更多与继承相关的一般性文档

　　下边的情况比较适合：

在一个方法的主要描述块，在这种情况下，主要描述是整个继承树结构里面的类和接口的一个拷贝。

在文本参数返回的@return @param和@throws等方法标记，在这种情况下，文本标记是整个层次结构里面标签的拷贝。

　　{@linkplain}(1.4)：语法[{@linkplain package.class#member label}]

　　和{@link}类似，除非链接的label是用普通文本的格式显示的，当文本是普通文本的时候该标签就能够起作用，例如：

Refer to {@linkplain add() the overridden method}

　　这个会显示成：

Refer to the overridden method

　　{@value}(1.4)：语法[{@value package.class#field}]

　　主要用来显示静态字段的值：

/**

* The value of this constant is {@value}

**/

public static final String SCRIPT_START = "script";

　　[4]JavaDoc标记的举例：

　　——[$]一个使用JavaDoc标记的例子——

/**

* @author Lang Yu

* @version 1.2

public class JavaDocBasic {

/**

* @see "Main Function JavaDoc"

* @since JDK 1.4

* @param args The params of console

**/

public static void main(String args[]){

System.out.println("Hello World!");

}

　　例如有这样一小段代码，在我机器上我放在了D:\Source\work下，然后进入该目录下，使用下边的命令：

D:\Source\work>javadoc -d doc JavaDocBasic.java

　　通过这样的命令使用，在执行该命令了过后电脑上有下边这样的输出，而且去目录下边可以看到一个doc文件夹，用浏览器打开里面的index.html就可以看到生成的文档的内容：

Loading source file JavaDocBasic.java...

Constructing Javadoc information...

Standard Doclet version 1.6.0_16

Building tree for all the packages and classes...

Generating doc\JavaDocBasic.html...

Generating doc\package-frame.html...

Generating doc\package-summary.html...

Generating doc\package-tree.html...

Generating doc\constant-values.html...

Building index for all the packages and classes...

Generating doc\overview-tree.html...

Generating doc\index-all.html...

Generating doc\deprecated-list.html...

Building index for all classes...

Generating doc\allclasses-frame.html...

Generating doc\allclasses-noframe.html...

Generating doc\index.html...

Generating doc\help-doc.html...

Generating doc\stylesheet.css...

　　——[$]一个使用{@link}的例子——

/**

* @author Lang Yu

* @see java.lang.String

public class JavaDocLink {

private int a;

private int b;

/**

* {@link #getAdd() getAdd()} Method

* @return the result of (a + b)

**/

public int getAdd(){

return a + b;

}

本文借鉴http://my.oschina.net/u/141149/blog/283363

转载自：https://blog.csdn.net/u011225629/article/details/45268227

文章来源: brucelong.blog.csdn.net，作者：Bruce小鬼，版权归原作者所有，如需转载，请联系作者。

原文链接：brucelong.blog.csdn.net/article/details/79996199

点赞
收藏
关注作者

0/1000

抱歉，系统识别当前为高风险访问，暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称，即可参与社区互动！

*长度不超过10个汉字或20个英文字符，设置后3个月内不可修改。

确认取消

加入云驻计划，成为创作者

华为云周边好礼
免费体验产品
特殊身份标识
线下官方门票
内部专家零距离
与10000+优质创作者共同成长

立即加入

疯狂JAVA之学习笔记（5）----------注释

疯狂JAVA之学习笔记（5）----------注释

注释：

元注解

@Target

@Retention

@Documented

@Inherited

自定义注解

全部回复

设置昵称

关于作者

目录

加入云驻计划，成为创作者

推荐阅读

相关产品