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)段落:
用于标记段落的开始，段落结束
2)换行:
3)
预格式化标签:
此标签用于显示预先已定义好格式的文本。当文本显示在浏览器中时，会遵循已在HTML源文档中定义的格式。
文本格式化标签
1)标签
该文本将以粗体显示
2)标签
该文本将以斜体显示
3)标签
该文本的显示高度将低于前后的文本
4)标签
该文本的显示高度将高于周围的文本
5)
标签定义长的引用，
所包含的文字会被整体分离出来，让这段文字与周围文字形成对比，有缩进效果。5)
用于定义水平分隔线列表标签
- 无序列表
- 有序列表
- 列表项目的标签
链接标签
1) 定义链接 href 指定链接地址
文档注释范例
/**
* http://blog.csdn.net/jack_chen_00">博客地址
* @author Jack·chen
*/
public static class Person{
/**男性，值为{@value}*/
public static final int MALE = 1;
/**女性，值为{@value}*/
public static final int FEMALE = 2;
/**
* use to store person name
*/
protected String mName;
/**
* use to store second name of person
* @see #mName
*/
protected String mSecondName;
/**/
protected int mAge;
/**
* 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;
}
/**
* Constructor that is called when inflating a view from XML.
*
*
*
- The view receives a hover event with action {@link MotionEvent#ACTION_HOVER_ENTER}
* when the pointer enters the bounds of the view.
*
The view receives a hover event with action {@link MotionEvent#ACTION_HOVER_MOVE}* when the pointer has already entered the bounds of the view and has moved.
*
The view receives a hover event with action {@link 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.
*
*
*
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);
* }
*
*
* The class will be created after all children have been added.
* added.
* @deprecated use {@link #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 set = new HashSet();
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());
}
}
}
---------------------
作者：不世剑客
来源：CSDN
原文：https://blog.csdn.net/jack_chen_00/article/details/37610071
版权声明：本文为博主原创文章，转载请附上博文链接！
扫一扫
202
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
