Various API review fixes to resources and drawables

BUG: 15025565
Change-Id: If00c85816f8288338967f7a85453d21f858f5ca7

3 files changed, 38 insertions, 27 deletions

diff --git a/core/java/android/content/res/ColorStateList.java b/core/java/android/content/res/ColorStateList.java
index 5674154..3f01dd2 100644
--- a/core/java/android/content/res/ColorStateList.java
+++ b/core/java/android/content/res/ColorStateList.java
@@ -64,7 +64,6 @@ import java.util.Arrays;
  * List Resource</a>.</p>
  */
 public class ColorStateList implements Parcelable {
-
     private int[][] mStateSpecs; // must be parallel to mColors
     private int[] mColors;      // must be parallel to mStateSpecs
     private int mDefaultColor = 0xffff0000;
@@ -100,9 +99,9 @@ public class ColorStateList implements Parcelable {
     public static ColorStateList valueOf(int color) {
         // TODO: should we collect these eventually?
         synchronized (sCache) {
-            WeakReference<ColorStateList> ref = sCache.get(color);
-            ColorStateList csl = ref != null ? ref.get() : null;
+            final WeakReference<ColorStateList> ref = sCache.get(color);
 
+            ColorStateList csl = ref != null ? ref.get() : null;
             if (csl != null) {
                 return csl;
             }
@@ -118,8 +117,7 @@ public class ColorStateList implements Parcelable {
      */
     public static ColorStateList createFromXml(Resources r, XmlPullParser parser)
             throws XmlPullParserException, IOException {
-
-        AttributeSet attrs = Xml.asAttributeSet(parser);
+        final AttributeSet attrs = Xml.asAttributeSet(parser);
 
         int type;
         while ((type=parser.next()) != XmlPullParser.START_TAG
@@ -133,22 +131,22 @@ public class ColorStateList implements Parcelable {
         return createFromXmlInner(r, parser, attrs);
     }
 
-    /* Create from inside an XML document.  Called on a parser positioned at
-     * a tag in an XML document, tries to create a ColorStateList from that tag.
-     * Returns null if the tag is not a valid ColorStateList.
+    /**
+     * Create from inside an XML document. Called on a parser positioned at a
+     * tag in an XML document, tries to create a ColorStateList from that tag.
+     *
+     * @throws XmlPullParserException if the current tag is not &lt;selector>
+     * @return A color state list for the current tag.
      */
     private static ColorStateList createFromXmlInner(Resources r, XmlPullParser parser,
             AttributeSet attrs) throws XmlPullParserException, IOException {
-
-        ColorStateList colorStateList;
-
+        final ColorStateList colorStateList;
         final String name = parser.getName();
-
         if (name.equals("selector")) {
             colorStateList = new ColorStateList();
         } else {
             throw new XmlPullParserException(
-                parser.getPositionDescription() + ": invalid drawable tag " + name);
+                    parser.getPositionDescription() + ": invalid drawable tag " + name);
         }
 
         colorStateList.inflate(r, parser, attrs);
@@ -161,9 +159,8 @@ public class ColorStateList implements Parcelable {
      * (0-255).
      */
     public ColorStateList withAlpha(int alpha) {
-        int[] colors = new int[mColors.length];
-
-        int len = colors.length;
+        final int[] colors = new int[mColors.length];
+        final int len = colors.length;
         for (int i = 0; i < len; i++) {
             colors[i] = (mColors[i] & 0xFFFFFF) | (alpha << 24);
         }
@@ -176,7 +173,6 @@ public class ColorStateList implements Parcelable {
      */
     private void inflate(Resources r, XmlPullParser parser, AttributeSet attrs)
             throws XmlPullParserException, IOException {
-
         int type;
 
         final int innerDepth = parser.getDepth()+1;
@@ -259,10 +255,25 @@ public class ColorStateList implements Parcelable {
         System.arraycopy(stateSpecList, 0, mStateSpecs, 0, listSize);
     }
 
+    /**
+     * Indicates whether this color state list contains more than one state spec
+     * and will change color based on state.
+     *
+     * @return True if this color state list changes color based on state, false
+     *         otherwise.
+     * @see #getColorForState(int[], int)
+     */
     public boolean isStateful() {
         return mStateSpecs.length > 1;
     }
 
+    /**
+     * Indicates whether this color state list is opaque, which means that every
+     * color returned from {@link #getColorForState(int[], int)} has an alpha
+     * value of 255.
+     *
+     * @return True if this color state list is opaque.
+     */
     public boolean isOpaque() {
         final int n = mColors.length;
         for (int i = 0; i < n; i++) {
diff --git a/core/java/android/content/res/Resources.java b/core/java/android/content/res/Resources.java
index 1692a79..a78f8e2 100644
--- a/core/java/android/content/res/Resources.java
+++ b/core/java/android/content/res/Resources.java
@@ -21,6 +21,7 @@ import com.android.internal.util.XmlUtils;
 import org.xmlpull.v1.XmlPullParser;
 import org.xmlpull.v1.XmlPullParserException;
 
+import android.annotation.Nullable;
 import android.content.pm.ActivityInfo;
 import android.graphics.Movie;
 import android.graphics.drawable.Drawable;
@@ -719,12 +720,12 @@ public class Resources {
      * @param id The desired resource identifier, as generated by the aapt
      *           tool. This integer encodes the package, type, and resource
      *           entry. The value 0 is an invalid identifier.
-     * @param theme The theme used to style the drawable attributes.
+     * @param theme The theme used to style the drawable attributes, may be {@code null}.
      * @return Drawable An object that can be used to draw this resource.
      * @throws NotFoundException Throws NotFoundException if the given ID does
      *         not exist.
      */
-    public Drawable getDrawable(int id, Theme theme) throws NotFoundException {
+    public Drawable getDrawable(int id, @Nullable Theme theme) throws NotFoundException {
         TypedValue value;
         synchronized (mAccessLock) {
             value = mTmpValue;
@@ -777,12 +778,12 @@ public class Resources {
      *            The value 0 is an invalid identifier.
      * @param density The desired screen density indicated by the resource as
      *            found in {@link DisplayMetrics}.
-     * @param theme The theme used to style the drawable attributes.
+     * @param theme The theme used to style the drawable attributes, may be {@code null}.
      * @return Drawable An object that can be used to draw this resource.
      * @throws NotFoundException Throws NotFoundException if the given ID does
      *             not exist.
      */
-    public Drawable getDrawableForDensity(int id, int density, Theme theme) {
+    public Drawable getDrawableForDensity(int id, int density, @Nullable Theme theme) {
         TypedValue value;
         synchronized (mAccessLock) {
             value = mTmpValue;
diff --git a/graphics/java/android/graphics/drawable/Drawable.java b/graphics/java/android/graphics/drawable/Drawable.java
index 3eabc3a..911fb96 100644
--- a/graphics/java/android/graphics/drawable/Drawable.java
+++ b/graphics/java/android/graphics/drawable/Drawable.java
@@ -512,13 +512,12 @@ public abstract class Drawable {
     }
 
     /**
-     * Indicates whether this view will change its appearance based on state.
-     * Clients can use this to determine whether it is necessary to calculate
-     * their state and call setState.
-     *
-     * @return True if this view changes its appearance based on state, false
-     *         otherwise.
+     * Indicates whether this drawable will change its appearance based on
+     * state. Clients can use this to determine whether it is necessary to
+     * calculate their state and call setState.
      *
+     * @return True if this drawable changes its appearance based on state,
+     *         false otherwise.
      * @see #setState(int[])
      */
     public boolean isStateful() {