小议Java中@param注解与@see注解的作用

@ param
@ param标签可以归档方法或构造器的某个单一参数，或者归档类、接口以及泛型方法的类型参数。在使用@ param标签时，我们应该针对方法的每一个参数都使用一个该标签。每个段落的第一个词会被当作参数名，而余下的部分则会被当作是对它的描述:

　　@param max The maximum number of words to read.

　　当归档类型参数时，我们应该在类型参数名两边加上<和>:

　　@param一e element type of this List

　　然而，类型参数通常并不需要显式的文档，因为它们的意义都很明显。

@ see
@ see标签可以创建链接到其他javadoc文档的交叉引用。我们可以在该标签的后面命名任何标识符，尽管我们必须对它们进行充分的限定。例如，通常可以使用某个类的成员的简单名来命名它，但是如果该成员是一个重载方法，我们就必须通过列举各个参数的类型来指定该方法的重载版本。我们可以使用未限定的名字来指定当前包内的接口或类，但必须使用完全限定名来指定其他包中的类型。我们可以通过在成员名的前面使用#来指定类型的成员。下面是所有有效的@ see标签格式:

　　@see #getName

　　@see Attr

　　@see com.magic.attr.Attr

　　@see com.magic.attr.Deck#DECK-SIZE

　　@see com.magic.attr.Attr#getName

　　@see com.magic.attr.Attr#Attr(String)

　　@see com.magic.attr.Attr#Attr(String，Object)

　　@see com.magic.attr

　　@see Attribute Specification

　　@see "The Java Developer's Almanac"

　　第一种形式所指的是名为getName的方法，该方法与文档注释自身位于同一个类或接口中，或者位于某个包围类或包围接口中，这样的语法也可以应用于构造器和字段。第二种形式引用的是当前包中的类或某个导人包中的类。第三种形式使用完全限定名引用了某个类。

　　后4种形式的@see引用的是成员，其中，前两个是关于域(DECK-SIZ日和方法(getName)的形式。我们可以直接使用方法名，因为在Attr类中只定义了一个getName方法。后两种形式引用的是Attr类的构造器，其中一个构造器接受的是字符串引元，而另一个构造器接受的则是字符串和对象。当构造器或方法有重载版本时，我们必须指定想要引用的重载版本的引元。

　　接下来的@see形式将读者引向了一个特定的包:com.magic.attro

　　最后的两种形式使得我们可以引用其他的文档。其中，前一个使用了来定义链接，后一个使用引号将文档名括了起来。我们可以用这两种形式将读者引向其他文档，例如完整的说明书。

　　对语言实体进行命名的@ see形式(除上面的最后两种形式之外的所有形式)可以在实体的后面跟随一个标号(label)。在生成的文档中，这种标号的名字将会替代实体的名字。例如:

　　@ see #getNameAttribute Names

　　将创建一个指向getName的文档的链接，但它所显示的文本是”Attribute Names”而不是"getName"。通常我们应该使用成员的真实名字，但这里所展示的特性偶尔也会很有用。

赞 (0)

相关推荐

  • Java8中的类型注解浅析

    注解大家都知道,从java5开始加入这一特性,发展到现在已然是遍地开花,在很多框架中得到了广泛的使用,用来简化程序中的配置.那充满争议的类型注解究竟是什么?复杂还是便捷? 一.什么是类型注解 在java 8之前,注解只能是在声明的地方所使用,比如类,方法,属性:java 8里面,注解可以应用在任何地方,比如: 创建类实例 复制代码 代码如下: new @Interned MyObject(); 类型映射 复制代码 代码如下: myString = (@NonNull String) str; i

  • 详解Java Spring各种依赖注入注解的区别

    注解注入顾名思义就是通过注解来实现注入,Spring和注入相关的常见注解有Autowired.Resource.Qualifier.Service.Controller.Repository.Component. Autowired是自动注入,自动从spring的上下文找到合适的bean来注入 Resource用来指定名称注入 Qualifier和Autowired配合使用,指定bean的名称 Service,Controller,Repository分别标记类是Service层类,Contro

  • Java中三种简单注解介绍和代码实例

    简单Java注解 JDK5提供的简单注解类型只有3个. 这三个都是用来预防错误或者进行提醒的,分别是: 1.Override 2.Deprecated 3.Suppresswarnings 需要注意,JDK5(另一个说法,Tiger)实际上并没有许多内置注解;相反,它允许核心Java支持注解特性的能力. JSR-175中严格规定它用来定义元数据功能. 需要由程序员编写自定义的注解类型,其他JSR标准也编写了一系列标准注解类型. 下面将用实例来深入讲解这三个简单注解. Override 注解 Ov

  • Java Annotation(Java 注解)的实现代码

    Java Annotation(Java 注解)的实现代码

    如果你想知道java annotation是什么?你可以先看看:"http://www.infoq.com/articles/Annotation-Hammer" 下面是我做的一个demo: 项目结构: 运行效果: ==================================================== 代码部分: 注:很多人会考虑这个问题,"这样做的目的是什么?我们可以做一个配置文件(xml,properties等),不是比这个跟方便...或者说 直接把我们

  • 详解Java的Spring框架中的注解的用法

    1. 使用Spring注解来注入属性 1.1. 使用注解以前我们是怎样注入属性的 类的实现: class UserManagerImpl implements UserManager { private UserDao userDao; public void setUserDao(UserDao userDao) { this.userDao = userDao; } ... } 配置文件: <bean id="userManagerImpl" class="com.

  • java教程之java注解annotation使用方法

    1.概述 注解可以定义到方法上,类上,一个注解相当与一个类,就相当于实例了一个对象,加上了注解,就相当于加了一个标志. 常用的注解:@Override:表示重新父类的方法,这个也可以判断是否覆盖的父类方法,在方法前面加上此语句,如果提示的错误,那么你不是覆盖的父类的方法,要是提示的没有错误,那么就是覆盖的父类的方法.@SuppressWarnings("deprecation"):取消编译器的警告(例如你使用的方法过时了)@Deprecated:在方法的最上边也上此语句,表示此方法过时

  • java注解的全面分析

    全面解析java注解 Java中的常见注解 a.JDK中的注解 @Override 覆盖父类或者父接口的方法     @Deprecated 表示方法已经过时     @SuppressWarnings("deprecation") 忽略方法过时警告 b.常见的第三方注解 例如Spring中的@Autowired(自动注入) 注解的分类 a.按照运行机制分 1.源码注解         注解只在源码中存在,编译成class文件就不存在了 2.编译时注解         注解在源码和cl

  • Java注解之Retention、Documented、Inherited介绍

    Java注解之Retention、Documented、Inherited介绍

    Retention注解 Retention(保留)注解说明,这种类型的注解会被保留到那个阶段. 有三个值: 1.RetentionPolicy.SOURCE -- 这种类型的Annotations只在源代码级别保留,编译时就会被忽略 2.RetentionPolicy.CLASS -- 这种类型的Annotations编译时被保留,在class文件中存在,但JVM将会忽略 3.RetentionPolicy.RUNTIME -- 这种类型的Annotations将被JVM保留,所以他们能在运行时

  • 全面解析Java中的注解与注释

    全面解析Java中的注解与注释

    注解 一.什么是 Annotation? (注解 or 注释) Annotation, 准确的翻译应该是 -- 注解. 和注释的作用完全不一样. Annotation 是JDK5.0及以后版本引入的一个特性. 与类.接口.枚举是在同一个层次,可以成为java 的一个类型. 语法是以@ 开头 简单来说, 注释是程序员对源代码的类,方法,属性等做的一些记忆或提示性描述(比如这个方法是做什么用的),是给人来看的. 注解则是Java 编译器可以理解的部分,是给编译器看的. 举个简单的例子来看一下注解的使

  • java自定义注解接口实现方案

    java注解是附加在代码中的一些元信息,用于一些工具在编译.运行时进行解析和使用,起到说明.配置的功能. 注解不会也不能影响代码的实际逻辑,仅仅起到辅助性的作用.包含在 java.lang.annotation 包中. 1.元注解 元注解是指注解的注解.包括 @Retention @Target @Document @Inherited四种. 1.1.@Retention: 定义注解的保留策略 Java代码 复制代码 代码如下: @Retention(RetentionPolicy.SOURCE

随机推荐