From 9ef94efaea82bcd534499c3ca9389f475cfd26f3 Mon Sep 17 00:00:00 2001 From: Rich Slogar Date: Tue, 19 May 2015 10:18:37 -0700 Subject: docs: studio 1.3 annotation-update Change-Id: I36bcdb314bbf319d7e4a8da6ec5f4a8ff8487c94 --- docs/html/tools/debugging/annotations.jd | 160 ++++++++++++++++++++++++++++--- 1 file changed, 149 insertions(+), 11 deletions(-) diff --git a/docs/html/tools/debugging/annotations.jd b/docs/html/tools/debugging/annotations.jd index fe9f9cc59c98..b0d5a228ac70 100644 --- a/docs/html/tools/debugging/annotations.jd +++ b/docs/html/tools/debugging/annotations.jd @@ -7,7 +7,12 @@ page.title=Improving Code Inspection with Annotations

In this document

  1. Adding Nullness Annotations
    2. -
  2. Adding Resource Annotation
    3. +
  3. Adding Resource Annotations
    4. +
  4. Adding Thread Annotations
    5. +
  5. Adding Value Constraint Annotations
    6. +
  6. Adding Permission Annotations
    7. +
  7. Adding CheckResult Annotations
    8. +
  8. Adding CallSuper Annotations
  9. Creating Enumerated Annotations
@@ -70,6 +75,10 @@ values in your code, for example:

{@link android.support.annotation.AnyRes @AnyRes}
References any type of R. resource.
+ +
@UiThread
+
Calls from a UI + thread.

For a complete list of the supported annotations, either examine the contents of the @@ -85,11 +94,14 @@ development tools.

To add annotations to your code, first add a dependency to the {@link android.support.annotation Support-Annotations} library. In Android Studio, -add the dependency to your build.gradle file.

+add the dependency using the File > Project Structure > Dependencies menu +option or your build.gradle file. The following example shows how to add the +{@link android.support.annotation Support-Annotations} library dependency in the +build.gradle file: 

 dependencies {
-    compile 'com.android.support:support-annotations:22.0.0'
+    compile 'com.android.support:support-annotations:22.2.0'
 }
@@ -143,18 +155,20 @@ inferring nullability in Android Studio, see

Adding Resource Annotations

-

Add {@link android.support.annotation.StringRes @StringRes} annotations to check that -a resource parameter contains a +

Validating resource types can be useful as Android references to resources, such as +Drawables and +R.string resources, are +passed as integers. Code that expects a parameter to reference a specific type of resource, for +example Drawables, +can be passed the expected reference type of int, but actually reference a different +type of resource, such as a R.string resource.

+ +

For example, add {@link android.support.annotation.StringRes @StringRes} annotations to check +that a resource parameter contains a R.string reference. During code inspection, the annotation generates a warning if a R.string reference is not passed in the parameter.

-

Validating resource types can be useful as Android references to -Drawables and -R.string resources are both -passed as integers. Code that expects a parameter to reference a Drawable can be passed -the expected reference type of int, but actually reference a R.string resource.

-

This example attaches the {@link android.support.annotation.StringRes @StringRes} annotation to the resId parameter to validate that it is really a string resource.

@@ -168,11 +182,135 @@ import android.support.annotation.StringRes;

Annotations for the other resource types, such as {@link android.support.annotation.DrawableRes @DrawableRes}, +{@link android.support.annotation.DimenRes @DimenRes}, {@link android.support.annotation.ColorRes @ColorRes}, and {@link android.support.annotation.InterpolatorRes @InterpolatorRes} can be added using the same annotation format and run during the code inspection.

+ + +

Adding Thread Annotations

+

Thread annotations check if a method is called from a specific type of +thread. The following thread +annotations are supported:

+ + +

Note: The @MainThread +and the @UiThread annotations are interchangeable so +methods calls from either thread type are allowed for these annotations.

+ + +

If all methods in a class share the same threading requirement, you can add a single +thread +annotation to the class to verify that all methods in the class are called from the same type of +thread.

+ +

A common use of the thread +annotation is to validate method overrides in the +AsyncTask class as this class performs +background operations and publishes results only on the UI +thread.

+ + + +

Adding Value Constraint Annotations

+

Use the @IntRange, +@FloatRange, and +@Size annotations to validate the values of passed +parameters.

+ +

The @IntRange annotation validates that the parameter +value is within a specified range. The following example ensures that the alpha +parameter contains an integer value from 0 to 255:

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

The @FloatRange annotation checks that the parameter +value is within a specified range of floating point values. The following example ensures that the +alpha parameter contains a float value from 0.0 to 1.0:

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

The @Size annotation checks the size of a collection or +array, as well as the length of a string. For example, use the @Size(min=1) +annotation to check if a collection is not empty, and the @Size(2) annotation to +validate that an array contains exactly two values. The following example ensures that the +location array contains at least one element:

+ +
+int[] location = new int[3];
+button.getLocationOnScreen(@Size(min=1) location);
+
+ + +

Adding Permission Annotations

+

Use the @RequiresPermission annotation to +validate the permissions of the caller of a method. To check for a single permission from a +list the valid permissions, use the anyOf attribute. To check for a set of +permissions, use the allOf attribute. The following example annotates the +setWallpaper method to ensure that the caller of the method has the +permission.SET_WALLPAPERS permission.

+ +
+@RequiresPermission(Manifest.permission.SET_WALLPAPER)
+public abstract void setWallpaper(Bitmap bitmap) throws IOException;
+
+ +

This example requires the caller of the +updateVisitedHistory method to have both read and write bookmark history permissions.

+ +
+@RequiresPermission(allOf = {
+    Manifest.permission.READ_HISTORY_BOOKMARKS,
+    Manifest.permission.WRITE_HISTORY_BOOKMARKS})
+public static final void updateVisitedHistory(ContentResolver cr, String url, boolean real) {
+    ...
+}
+
+ + +

Adding CheckResults Annotations

+

Use the @CheckResults annotation to +validate that a method's result or return value is actually used. The following example annotates +the checkPermissions method to ensure the return value of the method is actually +referenced. It also names the +enforcePermission +method as a method to be suggested to the developer as a replacement.

+ + + +
+@CheckResult(suggest="#enforcePermission(String,int,int,String)")
+public abstract int checkPermission(@NonNull String permission, int pid, int uid);
+
+ +{@link android.support.annotation.StringDef @StringDef} + + +

Adding CallSuper Annotations

+

Use the @CallSuper annotation to validate that an +overriding method calls the super implementation of the method. The following example annotates +the onCreate method to ensure that any overriding method implementations call +super.onCreate().

+ +
+@CallSuper
+protected void onCreate(Bundle savedInstanceState) {
+}
+
+ + +

Creating Enumerated Annotations

Use the {@link android.support.annotation.IntDef @IntDef} and {@link android.support.annotation.StringDef @StringDef} annotations -- cgit v1.2.3-59-g8ed1b