Clean up references to @ColorLong

Bug: 120904891
Test: make docs && look at the output

Remove instances of {@link ColorLong}. Although the link is supposed to
go to
    https://developer.android.com/reference/android/annotation/ColorLong.html
my web browser redirects me to
    https://developer.android.com/reference
Perhaps there's a bug somewhere in the generation (I am able to navigate
to
    https://developer.android.com/reference/android/support/annotation/ColorLong?hl=en
by searching on developer.android.com - notice the addition of
"support"), but I still think it would make more sense to send users to
the page for android.graphics.Color directly.

Switch over to {@code ColorLong} (which does not generate a link) and a
reference to look at the {@link Color} class.

Update parameter named "c" to one named "color".

Unify various Canvas#drawColor APIs to say "to draw onto the canvas"
(previously some said this, while others said "to draw with").

Change-Id: I78eff5c35e350f763aac0416f6ec1ccf12f89418

3 files changed, 25 insertions, 20 deletions

diff --git a/graphics/java/android/graphics/Bitmap.java b/graphics/java/android/graphics/Bitmap.java
index 4bd344f1964f..170dec26f361 100644
--- a/graphics/java/android/graphics/Bitmap.java
+++ b/graphics/java/android/graphics/Bitmap.java
@@ -1813,21 +1813,22 @@ public final class Bitmap implements Parcelable {
     }
 
     /**
-     * Fills the bitmap's pixels with the specified {@link Color}.
+     * Fills the bitmap's pixels with the specified {@code ColorLong}.
      *
+     * @param color The color to fill as packed by the {@link Color} class.
      * @throws IllegalStateException if the bitmap is not mutable.
-     * @throws IllegalArgumentException if the color space encoded in the long
-     *                                  is invalid or unknown.
+     * @throws IllegalArgumentException if the color space encoded in the
+     *                                  {@code ColorLong} is invalid or unknown.
      *
      */
-    public void eraseColor(@ColorLong long c) {
+    public void eraseColor(@ColorLong long color) {
         checkRecycled("Can't erase a recycled bitmap");
         if (!isMutable()) {
             throw new IllegalStateException("cannot erase immutable bitmaps");
         }
 
-        ColorSpace cs = Color.colorSpace(c);
-        nativeErase(mNativePtr, cs.getNativeInstance(), c);
+        ColorSpace cs = Color.colorSpace(color);
+        nativeErase(mNativePtr, cs.getNativeInstance(), color);
     }
 
     /**
diff --git a/graphics/java/android/graphics/Canvas.java b/graphics/java/android/graphics/Canvas.java
index 7b3f3da111d5..df64204d8647 100644
--- a/graphics/java/android/graphics/Canvas.java
+++ b/graphics/java/android/graphics/Canvas.java
@@ -1683,8 +1683,9 @@ public class Canvas extends BaseCanvas {
      * Fill the entire canvas' bitmap (restricted to the current clip) with the specified color,
      * using srcover porterduff mode.
      *
-     * @param color the color to draw onto the canvas
-     * @throws IllegalArgumentException if the color space encoded in the long
+     * @param color the {@code ColorLong} to draw onto the canvas. See the {@link Color}
+     *              class for details about {@code ColorLong}s.
+     * @throws IllegalArgumentException if the color space encoded in the {@code ColorLong}
      *                                  is invalid or unknown.
      */
     public void drawColor(@ColorLong long color) {
@@ -1695,7 +1696,7 @@ public class Canvas extends BaseCanvas {
      * Fill the entire canvas' bitmap (restricted to the current clip) with the specified color and
      * porter-duff xfermode.
      *
-     * @param color the color to draw with
+     * @param color the color to draw onto the canvas
      * @param mode the porter-duff mode to apply to the color
      *
      * @deprecated use {@link #drawColor(int, BlendMode)} instead
@@ -1709,7 +1710,7 @@ public class Canvas extends BaseCanvas {
      * Fill the entire canvas' bitmap (restricted to the current clip) with the specified color and
      * blendmode.
      *
-     * @param color the color to draw with
+     * @param color the color to draw onto the canvas
      * @param mode the blendmode to apply to the color
      */
     public void drawColor(@ColorInt int color, @NonNull BlendMode mode) {
@@ -1720,9 +1721,10 @@ public class Canvas extends BaseCanvas {
      * Fill the entire canvas' bitmap (restricted to the current clip) with the specified color and
      * blendmode.
      *
-     * @param color the color to draw with
+     * @param color the {@code ColorLong} to draw onto the canvas. See the {@link Color}
+     *              class for details about {@code ColorLong}s.
      * @param mode the blendmode to apply to the color
-     * @throws IllegalArgumentException if the color space encoded in the long
+     * @throws IllegalArgumentException if the color space encoded in the {@code ColorLong}
      *                                  is invalid or unknown.
      */
     public void drawColor(@ColorLong long color, @NonNull BlendMode mode) {
diff --git a/graphics/java/android/graphics/Paint.java b/graphics/java/android/graphics/Paint.java
index 346c7ab970dd..25bf4427591a 100644
--- a/graphics/java/android/graphics/Paint.java
+++ b/graphics/java/android/graphics/Paint.java
@@ -1028,9 +1028,8 @@ public class Paint {
      * premultiplied, meaning that alpha can be any value, regardless of the
      * values of r,g,b. See the {@link Color} class for more details.
      *
-     * @see Color for APIs that help manipulate a color long.
-     *
-     * @return the paint's color (and alpha).
+     * @return the paint's color, alpha, and {@code ColorSpace} encoded as a
+     *      {@code ColorLong}
      */
     @ColorLong
     public long getColorLong() {
@@ -1051,7 +1050,7 @@ public class Paint {
     }
 
     /**
-     * Set the paint's color with a {@link ColorLong}. Note that the color is
+     * Set the paint's color with a {@code ColorLong}. Note that the color is
      * a long with an encoded {@link ColorSpace} as well as alpha and r,g,b.
      * These values are not premultiplied, meaning that alpha can be any value,
      * regardless of the values of r,g,b. See the {@link Color} class for more
@@ -1059,8 +1058,8 @@ public class Paint {
      *
      * @param color The new color (including alpha and {@link ColorSpace})
      *      to set in the paint.
-     * @throws IllegalArgumentException if the color space encoded in the long
-     *      is invalid or unknown.
+     * @throws IllegalArgumentException if the color space encoded in the
+     *      {@code ColorLong} is invalid or unknown.
      */
     public void setColor(@ColorLong long color) {
         ColorSpace cs = Color.colorSpace(color);
@@ -1490,8 +1489,8 @@ public class Paint {
      * The alpha of the shadow will be the paint's alpha if the shadow color is
      * opaque, or the alpha from the shadow color if not.
      *
-     * @throws IllegalArgumentException if the color space encoded in the long
-     *      is invalid or unknown.
+     * @throws IllegalArgumentException if the color space encoded in the
+     *      {@code ColorLong} is invalid or unknown.
      */
     public void setShadowLayer(float radius, float dx, float dy, @ColorLong long shadowColor) {
         ColorSpace cs = Color.colorSpace(shadowColor);
@@ -1558,8 +1557,11 @@ public class Paint {
 
     /**
      * Returns the color of the shadow layer.
+     *
+     * @return the shadow layer's color encoded as a {@link ColorLong}.
      * @see #setShadowLayer(float,float,float,int)
      * @see #setShadowLayer(float,float,float,long)
+     * @see Color
      */
     public @ColorLong long getShadowLayerColorLong() {
         return mShadowLayerColor;