Java注释

Java注释

Java中的注释不会出现在可执行程序中。

Java中为我们提供了3种注释:

// 单行注释其注释内容从//开始到本行结尾。

/**/多行注释:/*注释内容在此处写*/  多行注释

/***/文档注释:注释以/**开始,以*/结束。可以用来自动生成文档。

下面注重来讲文档注释

 

文档注释

注释以/**开始,以*/结束。可以用来自动生成文档。

JDK包含一个很有用的工具,叫做javadoc,它可以生成一个HTML文档。

比如联机的API文档就是通过对标准Java类库的源代码运行javadoc生成的。

可以直接将类、方法和变量的注释放置在java源文件中,只要用/**...*/文档注释就可以。


          如果编写Java源代码时添加了合适的文档注释,然后通过JDK提供的javadoc工具可以直接将源代码里的文档注释提取成一份系统的API文档。

 

API文档

 

1,API文档是什么?

    开发一个大型软件时,需要定义上千万个类,并且可能由多个程序员来开发这个软件,每个人都会定义一些类,并在这个类里定义方法、属性提供给他人使用,但其他人怎么知道如何使用呢?这时候急需要提供一份说明文档,用于说明每个类、每个方法的用途。当其他人使用一个类或方法时,他无须关心这个类或这个方法的具体实现,只要知道这个类或这个方法的功能即可,然后使用这个类或方法来实现具体的目的,也就是通过调用应用程序接口(API)来编程。API文档就是以说明这些应用程序接口的文档。对于Java语言而言,API文档通常详细说明了每个类、每个方法的功能,用法等。

 

2,下载JDK的API文档

(1)登录:http://java.sun.com/javase/downloads/index.jsp站点,下载”Java SE 8

 Documentation“项,通过该下载项下载Java SE 6文档,这份文档里包含了JDK的

API文档。下载成功后得到一个jdk-6-doc.zip文件。

(2)将jdk-6-doc.zip文件加压到任意路径,将得到一个docs文件夹。这个文件夹内

就是JDK文档,JDK文档不仅包含API文档,还包含了JDK的其他说明文档,如果直接打开

docs文件夹下的index.xml文件

         API文档页面被分成3个部分,左上角部分是API文档“包列表区”,在该区域内可以查看Java基类的所有包;左下角是API稳定啊的“类列表区”,用于查看Java基类的所有类;右边页面是“详细说明区”,默认显示的是各包空间的说明信息。

         我们在开发中定义类、方法时也可以先添加文档注释,然后使用javadoc工具来生成自己的API文档。

 

3,我们要掌握查看API文档的方法的原因?

         API是Java提供的基库编程接口,当使用Java语言进行编程时,不可能把所有的Java类、所有的方法全部记录下来,那么当我们遇到不确定的地方时,必须通过API文档来查看某个类、某个方法的功能和用法。掌握查看API文档是学习Java的一个最基本的技能。


    由于文档注释是用于生成API文档,而API文档主要用于说明类、方法、属性的功能。

javadoc工具默认只处理以public或protected修饰的类、接口、方法、属性、构造器

之前的文档注释,忽略其他地方的文档注释。

    如果开发者希望javadoc工具可以提取private的内容,则可以在使用javadoc工具时

增加-private选项。

 

4,javadoc的常用选项:

 

-d<directory>:

该选项指定一个路径,用于将生成的API文档放到指定目录下。

 

-windowtitle<text>:

该选项指定一个字符串,用于设置API文档的浏览器窗口标题。

 

doctitle<html-code>:

该选项制定一个HTML格式文本,用于指定概述页面的标题。

注意:一定要对处于多个包下的源文件来生成API文档,才有概述页面。

 

-header<html-code>:该选项指定一个HTML格式的文本,包含每个页面的页眉。

读者可以使用javadoc-help来查看javadoc命令的所有选项。

 

6,常用的javadoc标记:


@author:指定Java程序的作者



@version:指定源文件的版本



@deprecated:不推荐使用的方法



@param:方法的参数的说明信息



@return:方法的返回值的说明信息



@see:“参见”,用于指定交叉参考的内容



@exception:抛出异常的类型



@throws:抛出异常,和exception同义。





标记的使用是有位置限制的



可以出现在类或借口文档注释中的有:


@see、@deprecated、@author、@version等。



可以出现在方法或构造器中的:


@see、@deprecated、@param、@return、@throws和@exception等。


可以出现在属性文档注释的有:

@see、@deprecated等。

文档注释注重点

1,注释的插入:

公有类与接口

公有的的和受保护的方法

公有的和受保护的域

注意:

每个/**...*/文档注释在标记之后紧跟着自由格式(free-form-text)。

标记由@开始,如@author或@param

自由格式文本的第一句应该是一个概要性的句子。javadoc实用程序自动地将这些句子抽取出来形成概要页。

在自由格式文本中可以使用HTML修饰符。

如果文档中有到其他文件的链接,例如图片,就应该将这些文件放到子目录doc-files中。javadoc实用程序将从源目录拷贝这些目录以及其中的文件到文档目录中。如:<img src="doc-files/uml.png" alt="UML diagram">


2,类注释:

类注释必须放在import语句之后,类定义之前。

注释没有必要在每一行的开始用星号*,


3,方法注释:

每一个方法注释必须放在所描述的方法之前。除了通用标记之外,还可以使用以下标记:

@param variable description

这个标记将对当前方法的“param”(参数)部分添加一个条目。这个描述可以占据多行,并使用HTML标记。一个方法的所有@param标记必须放在一起。

 

@return description

这个标记将对当前方法添加“return”(返回)部分。这个描述可以跨越多行,并可以使用HTML标记。

 

@throws class description

这个标记将添加一个注释,用于表示这个方法有可能抛出异常。


4,域注释

只需要对公有域(通常指的是静态常量)建立文档


5,通用注释:

@author name

这个标记将产生一个“author”(作者)条目。可以使用多个@author标记,

每个@author标记对应一名作者

 

@version text

这个标记将产生一个“version”(版本)条目。

text:可以是对当前版本的任何描述

 

@since text

这个标记将产生一个“since”(始于)条目

text:可以是对引入特性的版本描述。

例如:@since version 1.7.1

 

@deprecated test

这个标记将对类、方法或变量添加一个不再使用的注释。

text:给出了取代的建议

例如:@deprecated Use <code>SetVisible(true)</code> instead

 

@see reference

这个标记将在“see also”部分增加一个超级链接。它可以用于类中,也可以用于方法中。

(1)只要提供类、方法或变量的名字,javadoc就会在文档中插入一个超链接,例如:@see com.gaiwu.javanote.MyNoteUseing#raiseSalary(double),

建立一个链接到com.gaiwu.javanote.MyNoteUseing类的raiseSalary(double)

方法的超链接。

注意:当在当前包或当前类时,可以省略包名或包名和类名都省略掉。

(2)指定一个可选的标签作为锚链接,例如:@see <a href=#>www.horstan.com/corejava.html">The Core Java home page</a>

注意:也可以省略标签,用户看到的锚的名称就是目标代码名或URL

(3)如果@see 标记后面有一个双引号字符,文本就会显示在“see also”部分,

例如:@see “Core java 2volume 2”,可以为这特性添加多个@see标记,

但必须将他们放在一起。

(4)可以在注释中的任何位置放置指向其他类或方法的超级链接,

以及插入一个专用的标记,例如:@link package.class#feature label

 

6,包注释:

若需要产生包注释,就需要在每一个包目录中添加一个单独的文件。有两个选择:

(1)提供一个以package.html命名的HTML文件,在标记<body>...</body>

之间的所有文本都会被抽取出来。

(2)提供一个以package-info.java命名的Java文件。这个文件必须包含一个

初始的以/**和*/界定的javadoc注释,跟随在一个包语句之后。它不应该包含更多的代码或注释。

         为所有的源文件提供一个概述性的注释。这个注释将被放置在一个名为overview.html的文件中,这个文件位于包含所有源文件的父目录中。标记<body></body>之间的所有文本将被抽取出来。当用户从导航栏中选择“Overview”时,就会显示出这些注释内容。


7,注释抽取:

假设将HTML文件将被存放在目录docDirectory下,执行如下命令:

(1)切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档,例如com.horsetmann.core.java,就必须切换到包含子目录com的目录。

(2)如果是一个包,

运行命令:javadoc -d docDirectory nameOfPackage

或对于多个包生成文档,

运行:javadoc -d docDirectory nameOfPackage1 nameOfPackage2...

若文件在默认包中,

运行:javadoc -d docDirectory *.java

若省略了-d docDirectory 选项,那么HTML文件就会被提取到当前目录下。

这样有可能产生混乱,不提倡这样做,

http://java.sun.com/j2se/javadoc 联机文档


代码示例:

package com.gaiwu.javanote;

//类文档注释

/**

 * 

 * 

 * 

 * */

public class MyNoteUseing {

    //域文档注释

    /**

     * The "Hearts" card suit

     * */

    public static final int HEARTS = 1;



    //方法文档注释

    /**

     * Raises the salary of an employee

     * @param byPercent the percentage by with to raise the salary(e.g. 10=10%)

     * @retuen the amount of the raise

     * */

    public double raiseSalary(double byPercent)

    {

        double salary = 0;

        salary++;

        double raise=salary*byPercent/100;

        salary+=raise;

        return raise;

    }


    /*

     * 多行文本注释

     * */

    public static void main(String[] args) {


    }

}

 

Annotation(注释)

         Annotation必须使用工具来处理,工具负责提取Annotation里包含的元素,还可以根据这些元素增加额外的功能。

 

Java提供的三个基本Annotation的用法:

1,限定重写父类方法:@Override

@Override就是用来指定方法覆载的,它可以强制一个子类必须覆盖父类的方法。

@Override只能作用于方法,不能作用于其他程序元素。

代码示例:

public class Fruit

{

    public void foo()

    {

        System.out.println("水果的info方法...");

    }

}

class Apple extends Fruit

{

    //使用@override指定下面方法必须重写父类方法

    @Override

    public void foo()

    {

        System.out.println("苹果重写水果的foo方法...");

    }

}

从以上中可能丝毫看不出程序中的@Override有何作用,因为@Override Annotation的

作用是告诉编译器检查这个方法,并从弗雷查找是否包含一个被该方法重写的方法,否

则就编译出错。它主要是帮助我们避免一些低级错误,例如,我们把Apple类中的foo方

法不小心写成fio,这样的“低级错误”可能导致后期排错时的巨大障碍。


2,标记已过时:@Deprecated

@Deprecated用于表示某个程序元素(类、方法等)已过时,当其他程序使用已过时的类

、方法时,编译器将会出现警告。

代码示例:

public class Fruit

{

    //定义info方法已过时

    @Deprecated

    public void foo()

    {

        System.out.println("水果的info方法...");

    }

    public static void main(String[] args)

    {

        //下面使用info方法时将会被编译器警告

        new Apple().info();

    }

}

@Deprecatted Annotation与文档注释中的@deprecated标记的作用基本相同,但它们的

用法不同,前者是JDK1.5才支持的注释,无须放在文档注释语法(/**...*/部分)中,

而是直接用于修饰程序中的程序单元,如类、方法、接口等。

3,抑制编译器警告:@SuppressWarnings

@SuppressWarnings指示被Annotation表示的程序元素取消显示指定的编译器警告。

代码示例:

//关闭整个类里的编译器警告

@SuppressWarnings(value="unchecked")

public class SuppressWarningsTest

{

    public static void main(String[] args)

    {

        List<String> myList=new ArrayList();

    }

}

 

自定义注释

代码示例:

//定义一个简单的Annotation类型

public @interface Test

{

}

使用Annotation时的语法非常类似于public、final这样的修饰符。通常可用于修饰程

序中的类、方法、变量、接口等定义,通常我们会把Annotation放在所有修饰符之前,

而且由于使用Annotation时可能还需要为其成员变量指定值,因而Annotation的长度可

能较长,所以通常把Annotation另放一行,如下程序所示:

//使用@Test修饰类dingyi

@Test

public class MyClass

{

    ...

}

默认情况下,Annotation可用于修饰任何程序元素,包括类、接口、方法等,如下程序

使用@TestAnnotation来修饰方法。

public class MyClass

{

    //使用@testAnnotation修饰方法

    @Test

    public void info()

    {

        ...

    }

    ...

}

Annotation可以带成员变量,Annotation定义中以无参数方法的形式来声明。其方法名和返回值定义了该成员的名字和类型。如下代码所示:

public @interface MyTag

{

    //定义了两个成员变量的Annotation

    //Annotation中的成员变量以方法的形式来定义

  //以defauly为两个成员变量指定初始值。

    String name() default "lili";

    int age() default 32;

}

public class Test

{

    //使用带成员变量的Annotation时,需要为成员变量赋值

    @MyTag(name="xx",age=6)

    public void info()

    {

    }

}


根据Annotation是否可以包含成员变量,我们可以把Annotation分为两类:

1,标记Annotation:

一个没有成员定义的Annotation类型被称为标记。这种Annotation仅使用自身的存在与否来为我们提供信息。

2,元数据Annotation:

那些包含成员变量的Annotation,因为它们可接受更多元数据,所以被称为元数据Annotation。

提取Annotation的信息

         java在java.lang.reflect包下新增了AnnotatedElement接口,该接口代表程序中可以接受注释的程序元素,该接口主要有如下几个实现类:

1,Class:类定义

2,Constructor:构造器定义

3,Field:类的成员变量定义。

4,Method:类的方法定义。

5,Package:类的包定义。

AnnotationElement接口是所有程序元素(如Class、Method、Constructor)的父接口程序通过反射获取了某个类的AnnotationElement对象(如Class、Method、Constructor)之后,程序就可以调用该对象的如下三个方法来访问Annotation信息:

getAnnotation(Class<T> annotationClass):

返回改程序元素上存在的、指定类型的注释,如果该类型的注释不存在,则返回null。

 

Annotation[] getAnnotations():

返回该程序元素上存在的所有注释

boolean isAnnotationPresent(Class<? extends Annotation>annotationClass):

判断改程序元素上是否包含指定类型的注释,存在则返回true,否则返回false。


获取Test类的info方法里的所有注释,并将这些注释打印出来。

//获取Test类的info方法的所有注释

Annotation[] aArray=Class.forName("Test").getMethod("info").getAnnotations();

//遍历所有注释

for(Anotation an:aArray)

{

    System.out.println(an);

}

如果我们需要获取某个注释里的元数据,则可以将注释强制类型转换成所需的注释类型,然后通过注释对象的抽象方法来访问这些元数据,代码如下所示:

//获取tt对象的info方法所包含的所有注释

Annotation[] annotation=tt.getClass().getMethod("info").getAnnotations();

//遍历每个注释对象

for(Annotation tag:annotation)

{

    //如果注释类型是MyTagl类型

    if(tag instanceof MyTag1)

    {

        System.out.println("Tag is:"+tag);

        //将tag强制类型转换为MyTag1

        //并调用tag对象的method1和method2两个方法

        System.out.println("tag.name():"+(MyTag1)tag.method1);

        System.out.println("tag.name():"+(MyTag1)tag.method2);

    }

    //如果注释类型是MyTag2

    if(tag instanceof MyTag2)

    {

        System.out.println("Tag is:"+tag);

        //将tag强制类型转换为MyTag2

        //并调用tag对象的method1和method2两个方法

        System.out.println("tag.name():"+(MyTag2)tag.method1);

        System.out.println("tag.name():"+(MyTag2)tag.method2);

    }

}

 

使用Annotation例子

 

JDK元Annotation

JDK在java.lang.annotation包下提供了四个Meta Annotation(元 Annotation),这四个Annotation都是用于修饰其他Annotation定义。

1,使用@Retention

@Retention只能用于修饰一个Annotation定义,用于指定该Annotation可以保罗多长时间。@Retention包含一个RetentionPolicy类型的value成员变量,所以使用@Retention必须为该value成员变量指定值,值只有如下三个:

RetentionPolicy.CLASS:编译器将把注释记录在class文件中。当运行Java程序时,JVM不再保留注释。这是默认值。

RetentionPolicy.RUNTIME:编译器将把注释记录在class文件中。当运行Java程序时,JVM也会保留注释,程序可以通过反射获取该注释。

Ret.SOUREC:编译器直接丢弃这种策略的注释。

代码示例:

//定义下面的Testable Annotation的保留到运行时

@Retention(value=RetentionPolicy.RUNTIME)

public @interface Testable{}

//定义下面的Testable Annotation将被编译器直接丢弃

@Retention(RetentionPolicy.SOURCE)

public @interface Testable{}

注意:若我们定义的Annotation类型里只有一个value成员变量,使用该Annotation时可以直接在Annotation后的括号里指定value成员变量的值,无须使用name=value的形式。

 

2,使用@Target

@Target用于指定被修饰的Annotation能用于修饰哪些程序元素。@Target Annotation包含一个名为value的成员变量,成员变量的值只能是下面的几个:

ElementType.ANNOTATION_TYPE:

指定该策略的Annotation只能修饰Annotation。

 

ElementType.CONSTRUCTOR:

指定该策略的Annotation能修饰构造器。

 

ElementType.FIELD:

指定该策略的Annotation只能修饰成员变量。

 

ElementType.LOCAL_VARIABLE:

指定该策略的Annotation只能修饰局部变量。

 

ElementType.METHOD:

指定该策略的Annotation只能修饰方法定义。

 

ElementType.PACKAGE:

指定该策略的Annotation只能修饰包定义。

 

ElementType.PARAMETER:

指定该策略的Annotation可以修饰参数。

 

ElementType.TYPE:

指定该策略的Annotation可以修饰类、接口(包括注释类型)或枚举定义。

代码示例:

@Target(ElementType.FIELD)

public @interface ActionListenerFor{}

@Target(ElementType.METHOD)

public @interface Testable{}

 

3,使用@Documented

@Documented用于指定被该元Annotation修饰的Annotation类将被javadoc工具提取成文档,如果定义Annotation类时使用了@Documented修饰,则所有使用该Annotation修饰的程序元素的API文档中将会包含该Annotation说明。

代码定义:

@Retention(RetentionPolicy.RUNTIME)

@Target(ElementType.METHOD)

//定义Testable Annotation将被javadoc工具提取

@Documented

public @interface Testable{}

public class MyTest

{

    //使用@Test修饰info方法

    @Test

    public void info()

    {

        System.out.println("info方法...");

    }

}

4,使用@Inherited

@Inherited元Annotation指定被它修饰的Annotation将具有继承性:如果某个类使用了Annotation(定义该Annotation时使用了@Inherited修饰)修饰,则其子类将自动具有A注释。

代码示例:

@Target(ElementType.TYPE)

@Retention(RetentionPolicy.RUNTIME)

@Inherited

public @interface Inheritable{}


//使用@Inheritable修饰的Base类

@Inheritable

class Base

{


}

//TestInheritable类只是继承了Base类。

//并未直接使用@Inheritable Annotation修饰

public class TestInheritable extends Base

{

    public static void main(String[] args)

    {

        //打印TestInheritable类是否具有Inheritable Annotation

        Sy

本页内容版权归属为原作者,如有侵犯您的权益,请通知我们删除。
          我们画常规图形时一般用word上面自带的插件或visio画图。但是我在画linux内核文件系统结构图、内存分配以及学习数据结构树、图时,发现使用 Graphviz 非常的方便快捷。鉴于网上关于它的安装、使用不是特别具体,本博文将一步步告诉大家如何快速地使用 Graphviz 画相关的流程图、树形图等。 1.安装 Graphviz 在官网上面下载相关文件,地址: http://www.graphviz.org/Download..php 。如果遇到官网进不去,可以等待一旦时间或者在网上直
原文: Partial functions in Swift, Part 1: Avoidance 作者: Matt Gallagher 译者: kmyhy 作为我重返 Cocoa with Love 的第一篇正式文章,我想介绍的是“不完全函数”(带前置条件的函数)。 这是一个不寻常的 App 编程博客主题,它超出了 API 设计或者按合同设计的范围,带前置条件的函数并没有在大范围内经过讨论。并不是说我们的函数没有前置条件。而是因为我们习惯于在小范围内测试 App,我们永远不会考虑传递给函数的所有可能值。

[Android] Service全面总结 - 2016-05-04 19:05:10

什么是服务? Service是一个应用程序组件,它能够在后台执行一些耗时较长的操作,并且不提供用户界面。服务能被其它应用程序的组件启动,即使用户切换到另外的应用时还能保持后台运行。此外,应用程序组件还能与服务绑定,并与服务进行交互,甚至能进行进程间通信(IPC)。 比如,服务可以处理网络传输、音乐播放、执行文件I/O、或者与content provider进行交互,所有这些都是后台进行的。 Service 与 Thread 的区别 服务仅仅是一个组件,即使用户不再与你的应用程序发生交互,它仍然能在后台运行
目标效果:   在上一个的导航基础上,导航过后进入了主页面,手指向右滑动或者点击左上角的菜单图标,可以显示菜单侧栏,点击某一项可以吐司信息。 素材包: http://pan.baidu.com/s/1i5nRUfV   项目压缩包: http://pan.baidu.com/s/1dEGQfE5 1.素材包中有个SlideMenu.java页面,新建包并保存该包中。 2.新建leftmenu.xml页面,用于存储侧滑菜单的控件信息。 leftmenu.xml页面: ?xml version="1.0" e
对编程稍稍深入了解一点的工程师来说,设计模式并不陌生。但设计模式的理解和运用每个层次的人有不同深度和广度的理解。 接下来我就来讲述一下我所理解的设计模式。 若有其他理解的工程师,欢迎前来探讨! 若想了解设计模式,那么就要先摸清它的原则和行为模式。 设计模式不针对哪种编程语言,而是针对编程思想。所以我把设计模式归为内功心法之中。 先来说说设计模式的原则(包括标准原则描述和自己理解的描述)。 1,开闭原则(Open Close Principle) *对扩展开放,对修改关闭。 在程序需要进行拓展的时候,不能去

Java认识 - 2016-05-04 18:05:03

Java 概述 一、java的历史: 1,它是由一个错误来的(在1990年末,Sun公司预料嵌入式系统将在未来家用电器领域大显身手,于是成立了一个由James Gosling领导的“Green计划”,准备为下一代智能家电(如电视机、微波炉、电话)编写一个通用控制系统。),刚开始的名字,叫Oak,但是在最后因为在当时oak这个商标已被别人注册,于是只得将oak更名为Java 。 2, 到1998年12月,Sun发布了Java历史上最重要的JDK版本:     JDK1.2,并将Java分成了J2EE、J2S

Hello,服务端 Swift - 2016-05-04 17:05:00

原文: Hello Server Side Swift 作者: Logan Wright 译者: kmyhy 自从苹果官方发布了一个 Swift 的 Linux 开源版本之后,服务端 Swift 终于迎来了一个令人激动的前景。我的好奇心终于无法克制,是时候尝试一下服务端 Swift 了! 除了用过几个 Baas 以外,我没有任何后端编程经验,但幸运的是开源社区已经提供了现成的框架。我试了一下 Tanner Nelson 推荐的 Vapor 框架。它的使用非常简单,非常适合我当前的任务,在这篇文档中还会使用
一、前言 今天我们开启Android系统篇的文章了,其实一直想弄,只是之前一直没有太多深入的了解,最近又把这块拿出来好好看了一下,所以想从新梳理一下,来看看Android中的这块知识,首先我们今天来看一下:Android中的智能指针的概念,为什么说先看一下智能指针这个知识呢?因为我们在看Android源码的时候,会发现几乎好多地方都用到了这个东东,所以我们在介绍后面的知识点,先来看看这个吧。 二、问题 那么Android中的智能指针是个什么东西呢?我们知道Android用的Java语言开发的,Java语言
C++中不要使用包含中文字符串,否则打包的时候编译错误();虚幻中提供了使用中文的工具:本地化。 1. 启用本地化功能 这样,在菜单“窗口”项就会出现“本地化面板” 2. 使用本地化    a. 添加目标              b.修改Config中 DefaultEngine.ini。    添加下面内容:     [Internationalization]     +LocalizationPaths=/Game/Localization/Game   c.添加收集目录       d.添加新语
/prep最近半年来身边开发的朋友越来越多的提到OkHttp,上谷歌百度一下,确实OkHttp成了时下最火的HTTP框架,于是我也开始放下Volley,转而关注OkHttp,五一期间仔细看了官方WiKi介绍(我喜欢学习官方的文档),现在把自己整理的官方教程分享给大家,希望给初学者带来帮助。 br /       OkHttp官网地址:a target=_blank href=#>        OkHttp perseveres when the network is troublesome: it wi