From 26ca96ecb82cdbc058a39cebbfb16b402bf0fe03 Mon Sep 17 00:00:00 2001
From: Romain Guy <romainguy@google.com>
Date: Thu, 13 Apr 2017 20:40:46 -0700
Subject: [PATCH] Fix API feedback on Color

Bug: 37323188
Test: Color_ColorLongTest and ColorSpaceTest in CtsGraphicsTestCases
Change-Id: I1e52d3f63f95b9bdb4410938b727a87c45429aac
---
 graphics/java/android/graphics/Color.java      | 14 +++++++++-----
 graphics/java/android/graphics/ColorSpace.java | 10 ++++++----
 2 files changed, 15 insertions(+), 9 deletions(-)

diff --git a/graphics/java/android/graphics/Color.java b/graphics/java/android/graphics/Color.java
index 218b857ce83c4..8cbf921f6a34a 100644
--- a/graphics/java/android/graphics/Color.java
+++ b/graphics/java/android/graphics/Color.java
@@ -538,7 +538,7 @@ public class Color {
     /**
      * Returns the value of the alpha component in the range \([0..1]\).
      * Calling this method is equivalent to
-     * <code>getComponent(getComponentCount())</code>.
+     * <code>getComponent(getComponentCount() - 1)</code>.
      *
      * @see #red()
      * @see #green()
@@ -690,9 +690,8 @@ public class Color {
      * Returns the color space encoded in the specified color long.
      *
      * @param color The color long whose color space to extract
-     * @return A non-null color space instance. If the color long encodes
-     * an unknown or invalid color space, the {@link ColorSpace.Named#SRGB sRGB}
-     * color space is returned
+     * @return A non-null color space instance
+     * @throws IllegalArgumentException If the encoded color space is invalid or unknown
      *
      * @see #red(long)
      * @see #green(long)
@@ -787,6 +786,7 @@ public class Color {
      *
      * @param color The color to test
      * @return True if the color is in the sRGB color space, false otherwise
+     * @throws IllegalArgumentException If the encoded color space is invalid or unknown
      *
      * @see #isInColorSpace(long, ColorSpace)
      * @see #isWideGamut(long)
@@ -802,6 +802,7 @@ public class Color {
      *
      * @param color The color to test
      * @return True if the color is in a wide-gamut color space, false otherwise
+     * @throws IllegalArgumentException If the encoded color space is invalid or unknown
      *
      * @see #isInColorSpace(long, ColorSpace)
      * @see #isSrgb(long)
@@ -831,6 +832,7 @@ public class Color {
      * a color space conversion is applied if needed.
      *
      * @return An ARGB color in the sRGB color space
+     * @throws IllegalArgumentException If the encoded color space is invalid or unknown
      */
     @ColorInt
     public static int toArgb(@ColorLong long color) {
@@ -873,6 +875,7 @@ public class Color {
      *
      * @param color The color long to create a <code>Color</code> from
      * @return A non-null instance of {@link Color}
+     * @throws IllegalArgumentException If the encoded color space is invalid or unknown
      */
     @NonNull
     public static Color valueOf(@ColorLong long color) {
@@ -1100,6 +1103,7 @@ public class Color {
      * @param color The color long to convert
      * @param colorSpace The destination color space
      * @return A color long in the destination color space
+     * @throws IllegalArgumentException If the encoded color space is invalid or unknown
      */
     @ColorLong
     public static long convert(@ColorLong long color, @NonNull ColorSpace colorSpace) {
@@ -1206,7 +1210,7 @@ public class Color {
      * @return A value between 0 (darkest black) and 1 (lightest white)
      *
      * @throws IllegalArgumentException If the specified color's color space
-     * does not use the {@link ColorSpace.Model#RGB RGB} color model
+     * is unknown or does not use the {@link ColorSpace.Model#RGB RGB} color model
      */
     public static float luminance(@ColorLong long color) {
         ColorSpace colorSpace = colorSpace(color);
diff --git a/graphics/java/android/graphics/ColorSpace.java b/graphics/java/android/graphics/ColorSpace.java
index f1804e5976dec..97c834faf1a42 100644
--- a/graphics/java/android/graphics/ColorSpace.java
+++ b/graphics/java/android/graphics/ColorSpace.java
@@ -1314,9 +1314,8 @@ public abstract class ColorSpace {
     }
 
     /**
-     * <p>Returns an instance of {@link ColorSpace} whose ID matches the specified
-     * ID. If the ID is < 0 or &gt; {@link #MAX_ID}, calling this method is equivalent
-     * to calling <code>get(Named.SRGB)</code>.</p>
+     * <p>Returns an instance of {@link ColorSpace} whose ID matches the
+     * specified ID.</p>
      *
      * <p>This method always returns the same instance for a given ID.</p>
      *
@@ -1324,11 +1323,14 @@ public abstract class ColorSpace {
      *
      * @param index An integer ID between {@link #MIN_ID} and {@link #MAX_ID}
      * @return A non-null {@link ColorSpace} instance
+     * @throws IllegalArgumentException If the ID does not match the ID of one of the
+     *         {@link Named named color spaces}
      */
     @NonNull
     static ColorSpace get(@IntRange(from = MIN_ID, to = MAX_ID) int index) {
         if (index < 0 || index > Named.values().length) {
-            return get(Named.SRGB);
+            throw new IllegalArgumentException("Invalid ID, must be in the range [0.." +
+                    Named.values().length + "]");
         }
         return sNamedColorSpaces[index];
     }