Javadoc-代码文档

写代码时可以用Javadoc来声明一些参数，以明确的指示参数的类型，让编译器帮助检查代码，让代码更安全，更具可读性，即代码就是文档。

文档标记，可以尽量尝试使用：把自己的思想通过适合的方式表达给他人是一种好习惯。

@author

做好事留名，表明作者、时间、描述等，还阔以顺带推广博客网站

Android Studio中可以使用该模板，新建类文件时，自动生成

/**
 * <pre>
 *     author : VeiZhang
 *     blog   : https://veizhang.github.io/
 *     time   : 2016/6/1
 *     desc   : ListView、GridView通用适配器
 * </pre>
 */

@version

记录版本号

/**
  * @version 1.0
  */

@NonNull

告诉编译器，这个参数是非空的，编译器会帮你做出检查

栗子：传入的view不能为空，返回值不能为空

@NonNull
public static Snackbar make(@NonNull View view, @StringRes int resId, @Duration int duration) {
     return make(view, view.getResources().getText(resId), duration);
}

@Nullable

声明参数是可能为空的

栗子：传入的id可能为空，返回值可能为空

@Nullable
protected List<String> count(@Nullable String id) 
{
    return null;
}

@param

输入参数的名称说明，可以自动创建，在Android Studio中，先写好一个方法，然后在方法的上一行输入/**然后Enter即可自动创建模板

栗子：说明传参的String

/**
  * @param String 传入的id
  */
protected List<String> count(@Nullable String id) 
{
    return null;
}

@return

输出参数说明，跟@param一样的创建步骤

栗子：说明返回值List

/**
  * @param String 传入的id
  * 
  * @return 字符串数组
  */
protected List<String> count(@Nullable String id) 
{
    return null;
}

/**
  * @return {@code true}:空<br>{@code false}:不为空
  */
public boolean isNULL()
{
    return true;
}

@see

链接目标，表示参考。会在java 文档中生成一个超链接，链接到参考的类容

在注释中指向类或方法或变量，用.或#链接

/**
  * @see #field // 当前类中的变量
  * @see #Constructor(Type, Type...)    // 当前类中的构造函数
  * @see #method(Type, Type,...)    // 当前类中的方法
  * @see Class  // 链接类
  * @see Class#field    // 链接类中的变量
  * @see Class#Constructor(Type, Type...)   //类的构造函数
  * @see Class#method(Type, Type,...)   // 类的方法
  * @see package.Class
  * @see package.Class#field
  * @see package.Class#method(Type, Type,...)
  */

@link

链接到一个目标，用法同@see，形式如{@link …}

/**
  * {@link #field}
  * ...
  */

@deprecated

标识对象过期

适用范围：文件、类、方法

栗子：表明该方法过期，如果使用该方法则会出现删除线：isNULL

@deprecated
public boolean isNULL()
{
    return true;
}

@throws

标识出方法可能抛出的异常

适用范围：方法

栗子：可能抛出IO异常

/**
  * @throws IOException  If an input or output exception occurred
  * 
  * return 
  */
public boolean isNULL() throws IOException
{
    return true;
}

资源

声明参数是资源类型

常用的

• @StringRes 字符串资源
• @DrawableRes 图片资源
• @ColorRes 颜色资源
• @ColorInt 颜色值
• @AnimationRes 动画资源
• @AnyRes 任何资源
• @IdRes id资源
• @LayoutRes 布局资源

其他

• @IntArrayRes
• @IntegerRes
• @MovieRes
• @TextRes
• @TextArrayRes
• @StringArrayRes

栗子：表示传参的类型

public void setTextColor(@ColorRes int textColorRes)
{
	// 表示传参颜色资源：R.color.black
	// getResources().getColor(textColorRes) 即为颜色值
}

public void setTextColor(@ColorInt int textColor)
{
	// 表示传参颜色值：Color.BLACK
}

枚举

• IntDef
  整形枚举

• StringDef
  字符串类型枚举

StringDef 同用法 IntDef

栗子：

• 单一选择

  //visible只能是View.VISIBLE、View.INVISIBLE、View.GONE，不能用0 1 2 替代，更不能用其他的数值，如果传参是其他的数值，则编译器会报错
  new View().setVisible(int visible); 
  
  public class View
  {
  	private int mVisible;
  
  	public static final int VISIBLE = 0;
  	public static final int INVISIBLE = 1;
  	public static final int GONE = 2;
  
  	@IntDef({ VISIBLE, INVISIBLE, GONE })
  	public @interface Visible
  	{
  
  	}
  
  	public void setVisible(@Visible int visible)
  	{
  		mVisible = visible;
  	}
  
  	@Visible
  	public int getVisible()
  	{
  		return mVisible;
  	}
  }

• 多种选择

  //多种模式结合，即flag = false时，变成单一选择
  view.setVisible(View.INVISIBLE | View.GONE);
  
  public class View
  {
  	private int mVisible;
  
  	public static final int VISIBLE = 0;
  	public static final int INVISIBLE = 1;
  	public static final int GONE = 2;
  
  	@IntDef(flag = true, value = { VISIBLE, INVISIBLE, GONE })
  	public @interface Visible
  	{
  
  	}
  
  	public void setVisible(@Visible int visible)
  	{
  		mVisible = visible;
  	}
  
  	@Visible
  	public int getVisible()
  	{
  		return mVisible;
  	}
  }

值约束

用于约束参数的范围，很好避免参数出错

• @IntRange
  约束int或long类型的范围

• @FloatRange
  约束float或double类型的范围

栗子：@FloatRange：范围是0-1，不是此范围会报错

public void setAlpha(@FloatRange(from = 0.0, to = 1.0) float value)
{
    
}

public void setAlpha(@IntRange(from = 0, to = 255) int value)
{
    
}

• @Size
  约束数据、集合以及字符串

例子：

1. 集合不能为空：@size(min=1)
2. 字符串最大6个：@size(max=6)
3. 数组大小只能是2个：@size(2)
4. 数组大小是2的倍数：@size(multiple=2)

// 传入 text 长度为8，则会报错，现在最大为6
public void setAlpha(@size(max=6) String text)
{
    
}

大神都是从细节抓起