From fda4f610605a3e9330f1a4a66d435902cdcaf206 Mon Sep 17 00:00:00 2001 From: Leon Scroggins III Date: Thu, 21 Mar 2019 15:10:24 -0400 Subject: [PATCH] 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 --- .../android/view/inspector/PropertyReader.java | 5 +++-- graphics/java/android/graphics/Bitmap.java | 13 +++++++------ graphics/java/android/graphics/Canvas.java | 14 ++++++++------ graphics/java/android/graphics/Paint.java | 18 ++++++++++-------- 4 files changed, 28 insertions(+), 22 deletions(-) diff --git a/core/java/android/view/inspector/PropertyReader.java b/core/java/android/view/inspector/PropertyReader.java index b5020ce6495f4..5be0e3f3ccf2e 100644 --- a/core/java/android/view/inspector/PropertyReader.java +++ b/core/java/android/view/inspector/PropertyReader.java @@ -133,10 +133,11 @@ public interface PropertyReader { void readColor(int id, @ColorInt int value); /** - * Read a color packed into a {@link ColorLong} as a property. + * Read a color packed into a {@code ColorLong} as a property. * * @param id Identifier of the property from a {@link PropertyMapper} - * @param value Value of the property + * @param value Value of the property packed as a {@code ColorLong}. See the + * {@link Color} class for details of the packing. * @throws PropertyTypeMismatchException If the property ID is not mapped as a color */ void readColor(int id, @ColorLong long value); diff --git a/graphics/java/android/graphics/Bitmap.java b/graphics/java/android/graphics/Bitmap.java index 4bd344f1964fe..170dec26f361b 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 7b3f3da111d5c..df64204d8647b 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 346c7ab970dd9..25bf4427591a5 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;