update autogenerated includes

SkImageInfo.h is generated for the first time.
Minor corrections in the other includes.

TBR=reed@google.com
Bug: skia:6898
Change-Id: I9a16753e234ace3bfbcc5b58381347fd0e63b1c8
Reviewed-on: https://skia-review.googlesource.com/118168
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

8 files changed, 629 insertions, 265 deletions

diff --git a/include/core/SkBitmap.h b/include/core/SkBitmap.h
index b7471e5bc7..f3855725b1 100644
--- a/include/core/SkBitmap.h
+++ b/include/core/SkBitmap.h
@@ -131,16 +131,19 @@ public:
     */
     int height() const { return fPixmap.height(); }
 
-    /** Returns SkColorType, one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-        kRGB_565_SkColorType, kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
-        kBGRA_8888_SkColorType, kGray_8_SkColorType, kRGBA_F16_SkColorType.
+    /** Returns SkColorType, one of:
+        kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+        kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+        kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+        kGray_8_SkColorType, kRGBA_F16_SkColorType.
 
         @return  SkColorType in SkImageInfo
     */
     SkColorType colorType() const { return fPixmap.colorType(); }
 
-    /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-        kPremul_SkAlphaType, kUnpremul_SkAlphaType.
+    /** Returns SkAlphaType, one of:
+        kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+        kUnpremul_SkAlphaType.
 
         @return  SkAlphaType in SkImageInfo
     */
@@ -154,7 +157,7 @@ public:
     */
     SkColorSpace* colorSpace() const { return fPixmap.colorSpace(); }
 
-    /** Returns a smart pointer to SkColorSpace, the range of colors, associated with
+    /** Returns smart pointer to SkColorSpace, the range of colors, associated with
         SkImageInfo. The smart pointer tracks the number of objects sharing this
         SkColorSpace reference so the memory is released when the owners destruct.
 
@@ -245,8 +248,9 @@ public:
         This changes SkAlphaType in SkPixelRef; all bitmaps sharing SkPixelRef
         are affected.
 
-        @param alphaType  one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-                          kPremul_SkAlphaType, kUnpremul_SkAlphaType
+        @param alphaType  one of:
+                          kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                          kUnpremul_SkAlphaType
         @return           true if SkAlphaType is set
     */
     bool setAlphaType(SkAlphaType alphaType);
@@ -283,11 +287,14 @@ public:
     */
     void setImmutable();
 
-    /** Returns true if SkAlphaType is kOpaque_SkAlphaType.
+    /** Returns true if SkAlphaType is set to hint that all pixels are opaque; their
+        color alpha value is implicitly or explicitly 1.0. If true, and all pixels are
+        not opaque, Skia may draw incorrectly.
+
         Does not check if SkColorType allows alpha, or if any pixel value has
         transparency.
 
-        @return  true if SkImageInfo describes opaque alpha
+        @return  true if SkImageInfo SkAlphaType is kOpaque_SkAlphaType
     */
     bool isOpaque() const {
         return SkAlphaTypeIsOpaque(this->alphaType());
@@ -428,8 +435,8 @@ public:
         implementation of malloc(), if flags is zero, and calloc(), if flags is
         kZeroPixels_AllocFlag.
 
-        Passing kZeroPixels_AllocFlag is usually faster than separately calling
-        eraseColor(SK_ColorTRANSPARENT).
+        flags set to kZeroPixels_AllocFlag offers equal or better performance than
+        subsequently calling eraseColor() with SK_ColorTRANSPARENT.
 
         @param info   contains width, height, SkAlphaType, SkColorType, SkColorSpace
         @param flags  kZeroPixels_AllocFlag, or zero
@@ -451,8 +458,8 @@ public:
         implementation of malloc(), if flags is zero, and calloc(), if flags is
         kZeroPixels_AllocFlag.
 
-        Passing kZeroPixels_AllocFlag is usually faster than separately calling
-        eraseColor(SK_ColorTRANSPARENT).
+        flags set to kZeroPixels_AllocFlag offers equal or better performance than
+        subsequently calling eraseColor() with SK_ColorTRANSPARENT.
 
         @param info   contains width, height, SkAlphaType, SkColorType, SkColorSpace
         @param flags  kZeroPixels_AllocFlag, or zero
@@ -785,11 +792,7 @@ public:
         this->eraseColor(SkColorSetARGB(a, r, g, b));
     }
 
-    /** Deprecated. Use eraseARGB() or eraseColor().
-
-        @param r  amount of red
-        @param g  amount of green
-        @param b  amount of blue
+    /** Deprecated.
     */
     SK_ATTR_DEPRECATED("use eraseARGB or eraseColor")
     void eraseRGB(U8CPU r, U8CPU g, U8CPU b) const {
diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h
index 1170c76d34..aa64683872 100644
--- a/include/core/SkCanvas.h
+++ b/include/core/SkCanvas.h
@@ -1895,7 +1895,8 @@ public:
                   const SkPaint& paint);
 
     /** Draw null terminated string, with origin at (x, y), using clip, SkMatrix, and
-        SkPaint paint.
+        SkPaint paint. Note that this per-glyph xform does not affect the shader (if present)
+        on the paint, just the glyph's geometry.
 
         string meaning depends on SkPaint::TextEncoding; by default, strings are encoded
         as UTF-8. Other values of SkPaint::TextEncoding are unlikely to produce the desired
@@ -2055,8 +2056,7 @@ public:
         using clip, SkMatrix, and SkPaint paint.
 
         SkRSXform array specifies a separate square scale, rotation, and translation for
-        each glyph. Note that this per-glyph xform does not affect the shader (if present)
-        on the paint, just the glyph's geometry.
+        each glyph.
 
         Optional SkRect cullRect is a conservative bounds of text, taking into account
         SkRSXform and paint. If cullRect is outside of clip, canvas can skip drawing.
@@ -2762,7 +2762,7 @@ private:
 };
 
 /** \class SkAutoCanvasRestore
-    Stack helper class calls SkCanvas::restoreToCount() when SkAutoCanvasRestore
+    Stack helper class calls SkCanvas::restoreToCount when SkAutoCanvasRestore
     goes out of scope. Use this to guarantee that the canvas is restored to a known
     state.
 */
diff --git a/include/core/SkImage.h b/include/core/SkImage.h
index 17d2564914..aed0843e06 100644
--- a/include/core/SkImage.h
+++ b/include/core/SkImage.h
@@ -169,12 +169,14 @@ public:
         @param context         GPU context
         @param backendTexture  texture residing on GPU
         @param origin          one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
-        @param colorType       one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-                               kRGB_565_SkColorType, kARGB_4444_SkColorType,
-                               kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+        @param colorType       one of:
+                               kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                               kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                               kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
                                kGray_8_SkColorType, kRGBA_F16_SkColorType
-        @param alphaType       one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-                               kPremul_SkAlphaType, kUnpremul_SkAlphaType
+        @param alphaType       one of:
+                               kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                               kUnpremul_SkAlphaType
         @param colorSpace      range of colors; may be nullptr
         @return                created SkImage, or nullptr
     */
@@ -198,12 +200,14 @@ public:
         @param context             GPU context
         @param backendTexture      texture residing on GPU
         @param origin              one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
-        @param colorType           one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-                                   kRGB_565_SkColorType, kARGB_4444_SkColorType,
-                                   kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+        @param colorType           one of:
+                                   kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                                   kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                                   kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
                                    kGray_8_SkColorType, kRGBA_F16_SkColorType
-        @param alphaType           one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-                                   kPremul_SkAlphaType, kUnpremul_SkAlphaType
+        @param alphaType           one of:
+                                   kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                                   kUnpremul_SkAlphaType
         @param colorSpace          range of colors; may be nullptr
         @param textureReleaseProc  function called when texture can be released
         @param releaseContext      state passed to textureReleaseProc
@@ -281,12 +285,14 @@ public:
         @param context         GPU context
         @param backendTexture  texture residing on GPU
         @param surfaceOrigin   one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
-        @param colorType       one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-                               kRGB_565_SkColorType, kARGB_4444_SkColorType,
-                               kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+        @param colorType       one of:
+                               kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                               kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                               kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
                                kGray_8_SkColorType, kRGBA_F16_SkColorType
-        @param alphaType       one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-                               kPremul_SkAlphaType, kUnpremul_SkAlphaType
+        @param alphaType       one of:
+                               kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                               kUnpremul_SkAlphaType
         @param colorSpace      range of colors; may be nullptr
         @return                created SkImage, or nullptr
     */
@@ -298,37 +304,36 @@ public:
                                                  sk_sp<SkColorSpace> colorSpace = nullptr);
 
     /** Creates SkImage from copy of yuvTextures, an array of textures on GPU.
-        yuvTextures contain pixels for YUV planes of SkImage.
-        Returned SkImage has the dimensions yuvTextures[0]. yuvColorSpace describes how YUV colors
-        convert to RGB colors.
-
-        @param context            GPU context
-        @param yuvColorSpace      one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
-                                  kRec709_SkYUVColorSpace
-        @param yuvTextures        array of YUV textures on GPU
-        @param surfaceOrigin      one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
-        @param colorSpace         range of colors; may be nullptr
-        @return                   created SkImage, or nullptr
+        yuvTextures contain pixels for YUV planes of SkImage. Returned SkImage has the dimensions
+        yuvTextures[0]. yuvColorSpace describes how YUV colors convert to RGB colors.
+
+        @param context        GPU context
+        @param yuvColorSpace  one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
+                              kRec709_SkYUVColorSpace
+        @param yuvTextures    array of YUV textures on GPU
+        @param surfaceOrigin  one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+        @param colorSpace     range of colors; may be nullptr
+        @return               created SkImage, or nullptr
     */
     static sk_sp<SkImage> MakeFromYUVTexturesCopy(GrContext* context, SkYUVColorSpace yuvColorSpace,
                                                   const GrBackendTexture yuvTextures[3],
                                                   GrSurfaceOrigin surfaceOrigin,
                                                   sk_sp<SkColorSpace> colorSpace = nullptr);
 
-    /** Creates SkImage from copy of nv12TextureHandles, an array of textures on GPU.
-        yuvTextures[0] contains pixels for YUV_Component_Y plane.
-        yuvTextures[1] contains pixels for YUV_Component_U plane,
+    /** Creates SkImage from copy of nv12Textures, an array of textures on GPU.
+        nv12Textures[0] contains pixels for YUV_Component_Y plane.
+        nv12Textures[1] contains pixels for YUV_Component_U plane,
         followed by pixels for YUV_Component_V plane.
-        Returned SkImage has the dimensions nv12Textures[0]. yuvColorSpace describes how YUV colors
-        convert to RGB colors.
+        Returned SkImage has the dimensions nv12Textures[2].
+        yuvColorSpace describes how YUV colors convert to RGB colors.
 
-        @param context             GPU context
-        @param yuvColorSpace       one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
-                                   kRec709_SkYUVColorSpace
-        @param nv12Textures        array of YUV textures on GPU
-        @param surfaceOrigin       one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
-        @param colorSpace          range of colors; may be nullptr
-        @return                    created SkImage, or nullptr
+        @param context        GPU context
+        @param yuvColorSpace  one of: kJPEG_SkYUVColorSpace, kRec601_SkYUVColorSpace,
+                              kRec709_SkYUVColorSpace
+        @param nv12Textures   array of YUV textures on GPU
+        @param surfaceOrigin  one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
+        @param colorSpace     range of colors; may be nullptr
+        @return               created SkImage, or nullptr
     */
     static sk_sp<SkImage> MakeFromNV12TexturesCopy(GrContext* context,
                                                    SkYUVColorSpace yuvColorSpace,
@@ -368,8 +373,9 @@ public:
         Only available on Android, when __ANDROID_API__ is defined to be 26 or greater.
 
         @param hardwareBuffer  AHardwareBuffer Android hardware buffer
-        @param alphaType       one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-                               kPremul_SkAlphaType, kUnpremul_SkAlphaType
+        @param alphaType       one of:
+                               kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                               kUnpremul_SkAlphaType
         @param colorSpace      range of colors; may be nullptr
         @return                created SkImage, or nullptr
     */
@@ -410,8 +416,9 @@ public:
     */
     uint32_t uniqueID() const { return fUniqueID; }
 
-    /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-        kPremul_SkAlphaType, kUnpremul_SkAlphaType.
+    /** Returns SkAlphaType, one of:
+        kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+        kUnpremul_SkAlphaType.
 
         SkAlphaType returned was a parameter to an SkImage constructor,
         or was parsed from encoded data.
@@ -422,7 +429,7 @@ public:
 
     /** Returns SkColorType if known; otherwise, returns kUnknown_SkColorType.
 
-        @return SkColorType of SkImage
+        @return  SkColorType of SkImage
     */
     SkColorType colorType() const;
 
diff --git a/include/core/SkImageInfo.h b/include/core/SkImageInfo.h
index 1efb332750..7cd271d07c 100644
--- a/include/core/SkImageInfo.h
+++ b/include/core/SkImageInfo.h
@@ -16,38 +16,52 @@
 class SkReadBuffer;
 class SkWriteBuffer;
 
-/**
- *  Describes how to interpret the alpha component of a pixel.
- */
+/** \enum SkImageInfo::SkAlphaType
+    Describes how to interpret the alpha component of a pixel. A pixel may
+    be opaque, or color alpha, describing multiple levels of transparency.
+
+    In simple blending, color alpha weights the draw color and the destination
+    color to create a new color. If alpha describes a weight from zero to one:In practice alpha is encoded in two or more bits, where 1.0 equals all bits set.
+
+    RGB may have color alpha included in each component value; the stored
+    value is the original RGB multiplied by color alpha. Premultiplied color
+    components improve performance.
+*/
 enum SkAlphaType {
-    kUnknown_SkAlphaType,
+    kUnknown_SkAlphaType,                          //!< SkAlphaType is uninitialized.
 
-    /**
-     *  All pixels are stored as opaque. This differs slightly from kIgnore in
-     *  that kOpaque has correct "opaque" values stored in the pixels, while
-     *  kIgnore may not, but in both cases the caller should treat the pixels
-     *  as opaque.
-     */
+    /** Pixels are opaque. The SkColorType must have no explicit alpha
+        component, or all alpha components must be set to their maximum value.
+    */
     kOpaque_SkAlphaType,
 
-    /**
-     *  All pixels have their alpha premultiplied in their color components.
-     *  This is the natural format for the rendering target pixels.
-     */
+    /** Pixels have alpha premultiplied into color components.
+        SkSurface pixels must be premultiplied.
+    */
     kPremul_SkAlphaType,
 
-    /**
-     *  All pixels have their color components stored without any regard to the
-     *  alpha. e.g. this is the default configuration for PNG images.
-     *
-     *  This alpha-type is ONLY supported for input images. Rendering cannot
-     *  generate this on output.
-     */
+    /** Pixel color component values are independent of alpha value.
+        Images generated from encoded data like PNG do not premultiply pixel color
+        components. kUnpremul_SkAlphaType is supported for SkImage pixels, but not for
+        SkSurface pixels.
+    */
     kUnpremul_SkAlphaType,
 
+    /** Pixel color component values are independent of alpha value.
+        Images generated from encoded data like PNG do not premultiply pixel color
+        components. kUnpremul_SkAlphaType is supported for SkImage pixels, but not for
+        SkSurface pixels.
+    */
     kLastEnum_SkAlphaType = kUnpremul_SkAlphaType,
 };
 
+    /**
+
+        @param at  one of:
+                   kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                   kUnpremul_SkAlphaType
+        @return    true if at equals kOpaque_SkAlphaType
+    */
 static inline bool SkAlphaTypeIsOpaque(SkAlphaType at) {
     return kOpaque_SkAlphaType == at;
 }
@@ -57,95 +71,168 @@ static inline bool SkAlphaTypeIsOpaque(SkAlphaType at) {
 /** Temporary macro that allows us to add new color types without breaking Chrome compile. */
 #define SK_EXTENDED_COLOR_TYPES
 
-/**
- *  Describes how to interpret the components of a pixel.
- *
- *  kN32_SkColorType is an alias for whichever 32bit ARGB format is the "native"
- *  form for skia's blitters. Use this if you don't have a swizzle preference
- *  for 32bit pixels.
- */
-enum SkColorType {
-    kUnknown_SkColorType,
-    kAlpha_8_SkColorType,
-    kRGB_565_SkColorType,
-    kARGB_4444_SkColorType,
-    kRGBA_8888_SkColorType,
-    kRGB_888x_SkColorType,
-    kBGRA_8888_SkColorType,
-    kRGBA_1010102_SkColorType,
-    kRGB_101010x_SkColorType,
-    kGray_8_SkColorType,
-    kRGBA_F16_SkColorType,
-
-    kLastEnum_SkColorType = kRGBA_F16_SkColorType,
+    /** \enum SkImageInfo::SkColorType
+        Describes how pixel bits encode color. A pixel may be an alpha mask, a
+        gray level, RGB, or ARGB.
 
-#if SK_PMCOLOR_BYTE_ORDER(B,G,R,A)
-    kN32_SkColorType = kBGRA_8888_SkColorType,
-#elif SK_PMCOLOR_BYTE_ORDER(R,G,B,A)
-    kN32_SkColorType = kRGBA_8888_SkColorType,
-#else
-    #error "SK_*32_SHIFT values must correspond to BGRA or RGBA byte order"
-#endif
-};
+        kN32_SkColorType selects the native 32-bit ARGB format. On Little_Endian
+        processors, pixels containing 8-bit ARGB components pack into 32-bit
+        kBGRA_8888_SkColorType. On Big_Endian processors, pixels pack into 32-bit
+        kRGBA_8888_SkColorType.
+    */
+    enum SkColorType {
+        /** SkColorType is uninitialized; encoding format and size is unknown. */
+        kUnknown_SkColorType,
 
-/**
- *  Returns the number of bytes-per-pixel for the specified colortype, or 0 if invalid.
- */
-SK_API int SkColorTypeBytesPerPixel(SkColorType ct);
+        /** Encodes color alpha as alpha 8 pixel in an 8-bit byte. */
+        kAlpha_8_SkColorType,
 
-/**
- *  Returns true iff the colortype is always considered opaque (i.e. does not store alpha).
- */
-SK_API bool SkColorTypeIsAlwaysOpaque(SkColorType ct);
+        /** Encodes RGB as bgr 565 pixel in a 16-bit word. */
+        kRGB_565_SkColorType,
 
-/**
- *  Tries to validate the colortype, alphatype pair. In all cases if it returns true, it
- *  will set canonical to the "canonical" answer if it is non-null, and ignore the parameter if
- *  it is set to null.
- *
- *  If the specified colortype has only 1 valid alphatype (e.g. 565 must always be opaque) then
- *  canonical will be set to that valid alphatype.
- *
- *  If the specified colortype treats more than one alphatype the same (e.g. Alpha_8 colortype
- *  treates Premul and Unpremul the same) and the specified alphatype is one of those,
- *  then canonical will be set to the "canonical" answer (Premul in the case of Alpha_8 colortype).
- *
- *  If the colortype supports multiple alphatypes, and the specified alphatype is one of them,
- *  then canonical will be set to the specified alphatype. If the specified alphatype is not
- *  one of them (e.g. kUnknown_SkAlphaType is not valid for any colortype except
- *  kUnknown_SkColorType), then the function returns false, and canonical's value is undefined.
- */
-SK_API bool SkColorTypeValidateAlphaType(SkColorType colorType, SkAlphaType alphaType,
-                                         SkAlphaType* canonical = nullptr);
+        /** Encodes ARGB as abgr 4444 pixel in a 16-bit word. */
+        kARGB_4444_SkColorType,
 
+        /** Encodes ARGB as rgba 8888 pixel in a 32-bit word. */
+        kRGBA_8888_SkColorType,
 
-///////////////////////////////////////////////////////////////////////////////
+        /** Encodes RGB as rgb 888x pixel in a 32-bit word. */
+        kRGB_888x_SkColorType,
 
-/**
- *  Describes the color space a YUV pixel.
- */
-enum SkYUVColorSpace {
-    /** Standard JPEG color space. */
-    kJPEG_SkYUVColorSpace,
-    /** SDTV standard Rec. 601 color space. Uses "studio swing" [16, 235] color
-       range. See http://en.wikipedia.org/wiki/Rec._601 for details. */
-    kRec601_SkYUVColorSpace,
-    /** HDTV standard Rec. 709 color space. Uses "studio swing" [16, 235] color
-       range. See http://en.wikipedia.org/wiki/Rec._709 for details. */
-    kRec709_SkYUVColorSpace,
-
-    kLastEnum_SkYUVColorSpace = kRec709_SkYUVColorSpace,
-};
+        /** Encodes ARGB as bgra 8888 pixel in a 32-bit word. */
+        kBGRA_8888_SkColorType,
 
-///////////////////////////////////////////////////////////////////////////////
+        /** Encodes ARGB as rgba 1010102 pixel in a 32-bit word. */
+        kRGBA_1010102_SkColorType,
 
-/**
- *  Describe an image's dimensions and pixel type.
- *  Used for both src images and render-targets (surfaces).
- */
-struct SK_API SkImageInfo {
+        /** Encodes RGB as rgb 101010x pixel in a 32-bit word. */
+        kRGB_101010x_SkColorType,
+
+        /** Encodes color gray as gray 8 in an 8-bit byte. */
+        kGray_8_SkColorType,
+
+        /** Encodes ARGB as rgba f16 in a 64-bit word. */
+        kRGBA_F16_SkColorType,
+
+        /** Encodes ARGB as rgba f16 in a 64-bit word. */
+        kLastEnum_SkColorType     = kRGBA_F16_SkColorType,
+
+#if SK_PMCOLOR_BYTE_ORDER(B,G,R,A)
+        /** Encodes ARGB as either rgba 8888 or bgra 8888, whichever
+            is native to the platform.
+        */
+        kN32_SkColorType          = kBGRA_8888_SkColorType,
+
+#elif SK_PMCOLOR_BYTE_ORDER(R,G,B,A)
+
+        /** Encodes ARGB as either rgba 8888 or bgra 8888, whichever
+            is native to the platform.
+        */
+        kN32_SkColorType          = kRGBA_8888_SkColorType,
+
+#else
+    #error "SK_*32_SHIFT values must correspond to BGRA or RGBA byte order"
+#endif
+    };
+
+    /** Returns the number of bytes required to store a pixel, including unused padding.
+        Returns zero if ct is kUnknown_SkColorType or invalid.
+
+        @param ct  one of:
+                   kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                   kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                   kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+                   kGray_8_SkColorType, kRGBA_F16_SkColorType
+        @return    bytes per pixel
+    */
+    SK_API int SkColorTypeBytesPerPixel(SkColorType ct);
+
+    /** Returns true if SkColorType always decodes color alpha to 1.0, making the pixel
+        fully opaque. If true, SkColorType does not reserve bits to encode color alpha.
+
+        @param ct  one of:
+                   kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                   kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                   kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+                   kGray_8_SkColorType, kRGBA_F16_SkColorType
+        @return    true if color alpha is always set to 1.0
+    */
+    SK_API bool SkColorTypeIsAlwaysOpaque(SkColorType ct);
+
+    /** Returns true if canonical can be set to a valid SkAlphaType for colorType. If
+        there is more than one valid canonical SkAlphaType, set to alphaType, if valid.
+        If true is returned and canonical is not nullptr, store valid SkAlphaType.
+
+        Returns false only if alphaType is kUnknown_SkAlphaType, color type is not
+        kUnknown_SkColorType, and SkColorType is not always opaque. If false is returned,
+        canonical is ignored.
+
+        For kUnknown_SkColorType: set canonical to kUnknown_SkAlphaType and return true.
+        For kAlpha_8_SkColorType: set canonical to kPremul_SkAlphaType or
+        kOpaque_SkAlphaType and return true if alphaType is not kUnknown_SkAlphaType.
+        For kRGB_565_SkColorType, kRGB_888x_SkColorType, kRGB_101010x_SkColorType, and
+        kGray_8_SkColorType: set canonical to kOpaque_SkAlphaType and return true.
+        For kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+        kRGBA_1010102_SkColorType, and kRGBA_F16_SkColorType: set canonical to alphaType
+        and return true if alphaType is not kUnknown_SkAlphaType.
+
+        @param colorType  one of:
+                          kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                          kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                          kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+                          kGray_8_SkColorType, kRGBA_F16_SkColorType
+        @param alphaType  one of:
+                          kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                          kUnpremul_SkAlphaType
+        @param canonical  storage for SkAlphaType
+        @return           true if valid SkAlphaType can be associated with colorType
+    */
+    SK_API bool SkColorTypeValidateAlphaType(SkColorType colorType, SkAlphaType alphaType,
+                                         SkAlphaType* canonical = nullptr);
+
+    /** \enum SkImageInfo::SkYUVColorSpace
+        Describes color range of YUV pixels. The color mapping from YUV to RGB varies
+        depending on the source. YUV pixels may be generated by JPEG images, standard
+        video streams, or high definition video streams. Each has its own mapping from
+        YUV and RGB.
+
+        JPEG YUV values encode the full range of 0 to 255 for all three components.
+        Video YUV values range from 16 to 235 for all three components. Details of
+        encoding and conversion to RGB are described in YCbCr color space.
+    */
+    enum SkYUVColorSpace {
+        /** Describes standard JPEG color space; */
+        kJPEG_SkYUVColorSpace,
+
+        /** Describes standard used by SDTV; */
+        kRec601_SkYUVColorSpace,
+
+        /** Describes standard used by HDTV; */
+        kRec709_SkYUVColorSpace,
+
+        /** Describes standard used by HDTV; */
+        kLastEnum_SkYUVColorSpace = kRec709_SkYUVColorSpace,
+    };
+
+    /** \struct SkImageInfo
+        Describes pixel dimensions and encoding. SkBitmap, SkImage, PixMap, and SkSurface
+        can be created from SkImageInfo. SkImageInfo can be retrieved from SkBitmap and
+        SkPixmap, but not from SkImage and SkSurface. For example, SkImage and SkSurface
+        implementations may defer pixel depth, so may not completely specify SkImageInfo.
+
+        SkImageInfo contains dimensions, the pixel integral width and height. It encodes
+        how pixel bits describe color alpha, transparency; color components red, blue,
+        and green; and SkColorSpace, the range and linearity of colors.
+    */
+    struct SK_API SkImageInfo {
 public:
-    SkImageInfo()
+
+        /** Creates an empty SkImageInfo with kUnknown_SkColorType, kUnknown_SkAlphaType,
+            a width and height of zero, and no SkColorSpace.
+
+            @return  empty SkImageInfo
+        */
+        SkImageInfo()
         : fColorSpace(nullptr)
         , fWidth(0)
         , fHeight(0)
@@ -153,95 +240,312 @@ public:
         , fAlphaType(kUnknown_SkAlphaType)
     {}
 
-    static SkImageInfo Make(int width, int height, SkColorType ct, SkAlphaType at,
+        /** Creates SkImageInfo from integral dimensions width and height, SkColorType ct,
+            SkAlphaType at, and optionally SkColorSpace cs.
+
+            If SkColorSpace cs is nullptr and SkImageInfo is part of drawing source: SkColorSpace
+            defaults to sRGB, mapping into SkSurface SkColorSpace.
+
+            Parameters are not validated to see if their values are legal, or that the
+            combination is supported.
+
+            @param width   pixel column count; must be zero or greater
+            @param height  pixel row count; must be zero or greater
+            @param ct      one of:
+                           kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                           kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                           kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+                           kGray_8_SkColorType, kRGBA_F16_SkColorType
+            @param at      one of:
+                           kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                           kUnpremul_SkAlphaType
+            @param cs      range of colors; may be nullptr
+            @return        created SkImageInfo
+        */
+        static SkImageInfo Make(int width, int height, SkColorType ct, SkAlphaType at,
                             sk_sp<SkColorSpace> cs = nullptr) {
         return SkImageInfo(width, height, ct, at, std::move(cs));
     }
 
-    /**
-     *  Sets colortype to the native ARGB32 type.
-     */
-    static SkImageInfo MakeN32(int width, int height, SkAlphaType at,
+        /** Creates SkImageInfo from integral dimensions width and height, kN32_SkColorType,
+            SkAlphaType at, and optionally SkColorSpace cs. kN32_SkColorType will equal either
+            kBGRA_8888_SkColorType or kRGBA_8888_SkColorType, whichever is optimal.
+
+            If SkColorSpace cs is nullptr and SkImageInfo is part of drawing source: SkColorSpace
+            defaults to sRGB, mapping into SkSurface SkColorSpace.
+
+            Parameters are not validated to see if their values are legal, or that the
+            combination is supported.
+
+            @param width   pixel column count; must be zero or greater
+            @param height  pixel row count; must be zero or greater
+            @param at      one of:
+                           kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                           kUnpremul_SkAlphaType
+            @param cs      range of colors; may be nullptr
+            @return        created SkImageInfo
+        */
+        static SkImageInfo MakeN32(int width, int height, SkAlphaType at,
                                sk_sp<SkColorSpace> cs = nullptr) {
         return Make(width, height, kN32_SkColorType, at, cs);
     }
 
-    /**
-     *  Create an ImageInfo marked as SRGB with N32 swizzle.
-     */
-    static SkImageInfo MakeS32(int width, int height, SkAlphaType at);
+        /** Creates SkImageInfo from integral dimensions width and height, kN32_SkColorType,
+            SkAlphaType at, with sRGB SkColorSpace.
 
-    /**
-     *  Sets colortype to the native ARGB32 type, and the alphatype to premul.
-     */
-    static SkImageInfo MakeN32Premul(int width, int height, sk_sp<SkColorSpace> cs = nullptr) {
+            Parameters are not validated to see if their values are legal, or that the
+            combination is supported.
+
+            @param width   pixel column count; must be zero or greater
+            @param height  pixel row count; must be zero or greater
+            @param at      one of:
+                           kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                           kUnpremul_SkAlphaType
+            @return        created SkImageInfo
+        */
+        static SkImageInfo MakeS32(int width, int height, SkAlphaType at);
+
+        /** Creates SkImageInfo from integral dimensions width and height, kN32_SkColorType,
+            kPremul_SkAlphaType, with optional SkColorSpace.
+
+            If SkColorSpace cs is nullptr and SkImageInfo is part of drawing source: SkColorSpace
+            defaults to sRGB, mapping into SkSurface SkColorSpace.
+
+            Parameters are not validated to see if their values are legal, or that the
+            combination is supported.
+
+            @param width   pixel column count; must be zero or greater
+            @param height  pixel row count; must be zero or greater
+            @param cs      range of colors; may be nullptr
+            @return        created SkImageInfo
+        */
+        static SkImageInfo MakeN32Premul(int width, int height, sk_sp<SkColorSpace> cs = nullptr) {
         return Make(width, height, kN32_SkColorType, kPremul_SkAlphaType, cs);
     }
 
-    static SkImageInfo MakeN32Premul(const SkISize& size) {
+        /** Creates SkImageInfo from integral dimensions width and height, kN32_SkColorType,
+            kPremul_SkAlphaType, with SkColorSpace set to nullptr.
+
+            If SkImageInfo is part of drawing source: SkColorSpace defaults to sRGB, mapping
+            into SkSurface SkColorSpace.
+
+            Parameters are not validated to see if their values are legal, or that the
+            combination is supported.
+
+            @param size  width and height, each must be zero or greater
+            @return      created SkImageInfo
+        */
+        static SkImageInfo MakeN32Premul(const SkISize& size) {
         return MakeN32Premul(size.width(), size.height());
     }
 
-    static SkImageInfo MakeA8(int width, int height) {
+        /** Creates SkImageInfo from integral dimensions width and height, kAlpha_8_SkColorType,
+            kPremul_SkAlphaType, with SkColorSpace set to nullptr.
+
+            @param width   pixel column count; must be zero or greater
+            @param height  pixel row count; must be zero or greater
+            @return        created SkImageInfo
+        */
+        static SkImageInfo MakeA8(int width, int height) {
         return Make(width, height, kAlpha_8_SkColorType, kPremul_SkAlphaType, nullptr);
     }
 
-    static SkImageInfo MakeUnknown(int width, int height) {
+        /** Creates SkImageInfo from integral dimensions width and height, kUnknown_SkColorType,
+            kUnknown_SkAlphaType, with SkColorSpace set to nullptr.
+
+            Returned SkImageInfo as part of source does not draw, and as part of destination
+            can not be drawn to.
+
+            @param width   pixel column count; must be zero or greater
+            @param height  pixel row count; must be zero or greater
+            @return        created SkImageInfo
+        */
+        static SkImageInfo MakeUnknown(int width, int height) {
         return Make(width, height, kUnknown_SkColorType, kUnknown_SkAlphaType, nullptr);
     }
 
-    static SkImageInfo MakeUnknown() {
+        /** Creates SkImageInfo from integral dimensions width and height set to zero,
+            kUnknown_SkColorType, kUnknown_SkAlphaType, with SkColorSpace set to nullptr.
+
+            Returned SkImageInfo as part of source does not draw, and as part of destination
+            can not be drawn to.
+
+            @return  created SkImageInfo
+        */
+        static SkImageInfo MakeUnknown() {
         return MakeUnknown(0, 0);
     }
 
-    int width() const { return fWidth; }
-    int height() const { return fHeight; }
-    SkColorType colorType() const { return fColorType; }
-    SkAlphaType alphaType() const { return fAlphaType; }
-    SkColorSpace* colorSpace() const { return fColorSpace.get(); }
-    sk_sp<SkColorSpace> refColorSpace() const { return fColorSpace; }
+        /** Returns pixel count in each row.
+
+            @return  pixel width
+        */
+        int width() const { return fWidth; }
+
+        /** Returns pixel row count.
+
+            @return  pixel height
+        */
+        int height() const { return fHeight; }
+
+        /** Returns SkColorType, one of:
+            kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+            kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+            kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+            kGray_8_SkColorType, kRGBA_F16_SkColorType.
 
-    bool isEmpty() const { return fWidth <= 0 || fHeight <= 0; }
+            @return  SkColorType
+        */
+        SkColorType colorType() const { return fColorType; }
 
-    bool isOpaque() const {
+        /** Returns SkAlphaType, one of:
+            kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+            kUnpremul_SkAlphaType.
+
+            @return  SkAlphaType
+        */
+        SkAlphaType alphaType() const { return fAlphaType; }
+
+        /** Returns SkColorSpace, the range of colors. The reference count of
+            SkColorSpace is unchanged. The returned SkColorSpace is immutable.
+
+            @return  SkColorSpace, or nullptr
+        */
+        SkColorSpace* colorSpace() const { return fColorSpace.get(); }
+
+        /** Returns smart pointer to SkColorSpace, the range of colors. The smart pointer
+            tracks the number of objects sharing this SkColorSpace reference so the memory
+            is released when the owners destruct.
+
+            The returned SkColorSpace is immutable.
+
+            @return  SkColorSpace wrapped in a smart pointer
+        */
+        sk_sp<SkColorSpace> refColorSpace() const { return fColorSpace; }
+
+        /** Returns if SkImageInfo describes an empty area of pixels by checking if either
+            width or height is zero or smaller.
+
+            @return  true if either dimension is zero or smaller
+        */
+        bool isEmpty() const { return fWidth <= 0 || fHeight <= 0; }
+
+        /** Returns true if SkAlphaType is set to hint that all pixels are opaque; their
+            color alpha value is implicitly or explicitly 1.0. If true, and all pixels are
+            not opaque, Skia may draw incorrectly.
+
+            Does not check if SkColorType allows alpha, or if any pixel value has
+            transparency.
+
+            @return  true if SkAlphaType is kOpaque_SkAlphaType
+        */
+        bool isOpaque() const {
         return SkAlphaTypeIsOpaque(fAlphaType);
     }
 
-    SkISize dimensions() const { return SkISize::Make(fWidth, fHeight); }
-    SkIRect bounds() const { return SkIRect::MakeWH(fWidth, fHeight); }
+        /** Returns SkISize { width(), height() }.
+
+            @return  integral size of width() and height()
+        */
+        SkISize dimensions() const { return SkISize::Make(fWidth, fHeight); }
+
+        /** Returns SkIRect { 0, 0, width(), height() }.
 
-    bool gammaCloseToSRGB() const {
+            @return  integral rectangle from origin to width() and height()
+        */
+        SkIRect bounds() const { return SkIRect::MakeWH(fWidth, fHeight); }
+
+        /** Returns true if associated SkColorSpace is not nullptr, and SkColorSpace gamma
+            is approximately the same as sRGB.
+            This includes the
+
+            @return  true if SkColorSpace gamma is approximately the same as sRGB
+        */
+        bool gammaCloseToSRGB() const {
         return fColorSpace && fColorSpace->gammaCloseToSRGB();
     }
 
-    /**
-     *  Return a new ImageInfo with the same colortype and alphatype as this info,
-     *  but with the specified width and height.
-     */
-    SkImageInfo makeWH(int newWidth, int newHeight) const {
+        /** Creates SkImageInfo with the same SkColorType, SkColorSpace, and SkAlphaType,
+            with dimensions set to width and height.
+
+            @param newWidth   pixel column count; must be zero or greater
+            @param newHeight  pixel row count; must be zero or greater
+            @return           created SkImageInfo
+        */
+        SkImageInfo makeWH(int newWidth, int newHeight) const {
         return Make(newWidth, newHeight, fColorType, fAlphaType, fColorSpace);
     }
 
-    SkImageInfo makeAlphaType(SkAlphaType newAlphaType) const {
+        /** Creates SkImageInfo with same SkColorType, SkColorSpace, width, and height,
+            with SkAlphaType set to newAlphaType.
+
+            Created SkImageInfo contains newAlphaType even if it is incompatible with
+            SkColorType, in which case SkAlphaType in SkImageInfo is ignored.
+
+            @param newAlphaType  one of:
+                                 kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+                                 kUnpremul_SkAlphaType
+            @return              created SkImageInfo
+        */
+        SkImageInfo makeAlphaType(SkAlphaType newAlphaType) const {
         return Make(fWidth, fHeight, fColorType, newAlphaType, fColorSpace);
     }
 
-    SkImageInfo makeColorType(SkColorType newColorType) const {
+        /** Creates SkImageInfo with same SkAlphaType, SkColorSpace, width, and height,
+            with SkColorType set to newColorType.
+
+            @param newColorType  one of:
+                                 kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                                 kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                                 kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+                                 kGray_8_SkColorType, kRGBA_F16_SkColorType
+            @return              created SkImageInfo
+        */
+        SkImageInfo makeColorType(SkColorType newColorType) const {
         return Make(fWidth, fHeight, newColorType, fAlphaType, fColorSpace);
     }
 
-    SkImageInfo makeColorSpace(sk_sp<SkColorSpace> cs) const {
+        /** Creates SkImageInfo with same SkAlphaType, SkColorType, width, and height,
+            with SkColorSpace set to cs.
+
+            @param cs  range of colors; may be nullptr
+            @return    created SkImageInfo
+        */
+        SkImageInfo makeColorSpace(sk_sp<SkColorSpace> cs) const {
         return Make(fWidth, fHeight, fColorType, fAlphaType, std::move(cs));
     }
 
-    int bytesPerPixel() const;
-    int shiftPerPixel() const;
+        /** Returns number of bytes per pixel required by SkColorType.
+            Returns zero if colorType( is kUnknown_SkColorType.
 
-    uint64_t minRowBytes64() const {
+            @return  bytes in pixel
+        */
+        int bytesPerPixel() const;
+
+        /** Returns bit shift converting row bytes to row pixels.
+            Returns zero for kUnknown_SkColorType.
+
+            @return  one of: 0, 1, 2, 3; left shift to convert pixels to bytes
+        */
+        int shiftPerPixel() const;
+
+        /** Returns minimum bytes per row, computed from pixel width() and SkColorType, which
+            specifies bytesPerPixel(). SkBitmap maximum value for row bytes must be representable
+            as a positive value in a 32-bit signed integer.
+
+            @return  width() times bytesPerPixel() as unsigned 64-bit integer
+        */
+        uint64_t minRowBytes64() const {
         return sk_64_mul(fWidth, this->bytesPerPixel());
     }
 
-    size_t minRowBytes() const {
+        /** Returns minimum bytes per row, computed from pixel width() and SkColorType, which
+            specifies bytesPerPixel(). SkBitmap maximum value for row bytes must be representable
+            as a positive value in a 32-bit signed integer.
+
+            @return  width() times bytesPerPixel() as signed 32-bit integer
+        */
+        size_t minRowBytes() const {
         uint64_t minRowBytes = this->minRowBytes64();
         if (!sk_64_isS32(minRowBytes)) {
             return 0;
@@ -249,50 +553,87 @@ public:
         return sk_64_asS32(minRowBytes);
     }
 
-    size_t computeOffset(int x, int y, size_t rowBytes) const;
+        /** Returns byte offset of pixel from pixel base address.
+
+            Asserts in debug build if x or y is outside of bounds. Does not assert if
+            rowBytes is smaller than minRowBytes(), even though result may be incorrect.
 
-    bool operator==(const SkImageInfo& other) const {
+            @param x         column index, zero or greater, and less than width()
+            @param y         row index, zero or greater, and less than height()
+            @param rowBytes  size of pixel row or larger
+            @return          offset within pixel array
+        */
+        size_t computeOffset(int x, int y, size_t rowBytes) const;
+
+        /** Compares SkImageInfo with other, and returns true if width, height, SkColorType,
+            SkAlphaType, and SkColorSpace are equivalent.
+
+            @param other  SkImageInfo to compare
+            @return       true if SkImageInfo equals other
+        */
+        bool operator==(const SkImageInfo& other) const {
         return fWidth == other.fWidth && fHeight == other.fHeight &&
                fColorType == other.fColorType && fAlphaType == other.fAlphaType &&
                SkColorSpace::Equals(fColorSpace.get(), other.fColorSpace.get());
     }
-    bool operator!=(const SkImageInfo& other) const {
+
+        /** Compares SkImageInfo with other, and returns true if width, height, SkColorType,
+            SkAlphaType, and SkColorSpace are equivalent.
+
+            @param other  SkImageInfo to compare
+            @return       true if SkImageInfo is not equal to other
+        */
+        bool operator!=(const SkImageInfo& other) const {
         return !(*this == other);
     }
 
-    /**
-     *  Returns the size (in bytes) of the image buffer that this info needs, given the specified
-     *  rowBytes. The rowBytes must be >= this->minRowBytes().
-     *
-     *  if (height == 0) {
-     *      return 0;
-     *  } else {
-     *      return (height - 1) * rowBytes + width * bytes_per_pixel;
-     *  }
-     *
-     *  If the calculation overflows this returns SK_MaxSizeT
-     */
-    size_t computeByteSize(size_t rowBytes) const;
+        /** Returns storage required by pixel array, given SkImageInfo dimensions, SkColorType,
+            and rowBytes. rowBytes is assumed to be at least as large as minRowBytes().
 
-    /**
-     *  Returns the minimum size (in bytes) of the image buffer that this info needs.
-     *  If the calculation overflows, or if the height is 0, this returns 0.
-     */
-    size_t computeMinByteSize() const {
+            Returns zero if height is zero.
+            Returns SK_MaxSizeT if answer exceeds the range of size_t.
+
+            @param rowBytes  size of pixel row or larger
+            @return          memory required by pixel buffer
+        */
+        size_t computeByteSize(size_t rowBytes) const;
+
+        /** Returns storage required by pixel array, given SkImageInfo dimensions, and
+            SkColorType. Uses minRowBytes() to compute bytes for pixel row.
+
+            Returns zero if height is zero.
+            Returns SK_MaxSizeT if answer exceeds the range of size_t.
+
+            @return  least memory required by pixel buffer
+        */
+        size_t computeMinByteSize() const {
         return this->computeByteSize(this->minRowBytes());
     }
 
-    // Returns true if the result of computeByteSize (or computeMinByteSize) overflowed
-    static bool ByteSizeOverflowed(size_t byteSize) {
+        /** Returns true if byteSize equals SK_MaxSizeT. computeByteSize() and
+            computeMinByteSize() return SK_MaxSizeT if size_t can not hold buffer size.
+
+            @param byteSize  result of computeByteSize() or computeMinByteSize()
+            @return          true if computeByteSize() or computeMinByteSize() result exceeds size_t
+        */
+        static bool ByteSizeOverflowed(size_t byteSize) {
         return SK_MaxSizeT == byteSize;
     }
 
-    bool validRowBytes(size_t rowBytes) const {
+        /** Returns true if rowBytes is smaller than width times pixel size.
+
+            @param rowBytes  size of pixel row or larger
+            @return          true if rowBytes is large enough to contain pixel row
+        */
+        bool validRowBytes(size_t rowBytes) const {
         uint64_t minRB = sk_64_mul(fWidth, this->bytesPerPixel());
         return rowBytes >= minRB;
     }
 
-    void reset() {
+        /** Creates an empty SkImageInfo with kUnknown_SkColorType, kUnknown_SkAlphaType,
+            a width and height of zero, and no SkColorSpace.
+        */
+        void reset() {
         fColorSpace = nullptr;
         fWidth = 0;
         fHeight = 0;
@@ -300,7 +641,10 @@ public:
         fAlphaType = kUnknown_SkAlphaType;
     }
 
-    SkDEBUGCODE(void validate() const;)
+        /** Asserts if internal values are illegal or inconsistent. Only available if
+            SK_DEBUG is defined at compile time.
+        */
+        SkDEBUGCODE(void validate() const;)
 
 private:
     sk_sp<SkColorSpace> fColorSpace;
diff --git a/include/core/SkPath.h b/include/core/SkPath.h
index 1586f2bf60..2aab341505 100644
--- a/include/core/SkPath.h
+++ b/include/core/SkPath.h
@@ -1052,8 +1052,6 @@ public:
         and half oval height. Oval begins at (oval.fRight, oval.centerY()) and continues
         clockwise if dir is kCW_Direction, counterclockwise if dir is kCCW_Direction.
 
-        This form is identical to addOval(oval, dir, 1).
-
         @param oval  bounds of ellipse added
         @param dir   SkPath::Direction to wind ellipse
     */
@@ -1278,15 +1276,15 @@ public:
     bool getLastPt(SkPoint* lastPt) const;
 
     /** Set last point to (x, y). If SkPoint array is empty, append kMove_Verb to
-        verb array and (x, y) to SkPoint array.
+        verb array and append (x, y) to SkPoint array.
 
         @param x  set x-coordinate of last point
         @param y  set y-coordinate of last point
     */
     void setLastPt(SkScalar x, SkScalar y);
 
-    /** Set the last point on the path. If no points have been added, moveTo(p)
-        is automatically called.
+    /** Set the last point on the path. If SkPoint array is empty, append kMove_Verb to
+        verb array and append p to SkPoint array.
 
         @param p  set value of last point
     */
diff --git a/include/core/SkPixmap.h b/include/core/SkPixmap.h
index 1d53d2adc0..4575f17000 100644
--- a/include/core/SkPixmap.h
+++ b/include/core/SkPixmap.h
@@ -149,27 +149,29 @@ public:
     */
     int height() const { return fInfo.height(); }
 
-    /** Returns SkColorType, one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-        kRGB_565_SkColorType, kARGB_4444_SkColorType, kRGBA_8888_SkColorType,
-        kRGB_888x_SkColorType, kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType,
-        kRGB_101010x_SkColorType, kGray_8_SkColorType, kRGBA_F16_SkColorType.
+    /** Returns SkColorType, one of:
+        kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+        kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+        kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
+        kGray_8_SkColorType, kRGBA_F16_SkColorType.
 
         @return  SkColorType in SkImageInfo
     */
     SkColorType colorType() const { return fInfo.colorType(); }
 
-    /** Returns SkAlphaType, one of: kUnknown_SkAlphaType, kOpaque_SkAlphaType,
-        kPremul_SkAlphaType, kUnpremul_SkAlphaType.
+    /** Returns SkAlphaType, one of:
+        kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
+        kUnpremul_SkAlphaType.
 
         @return  SkAlphaType in SkImageInfo
     */
     SkAlphaType alphaType() const { return fInfo.alphaType(); }
 
-    /** Returns SkColorSpace associated with SkImageInfo. The
+    /** Returns SkColorSpace, the range of colors, associated with SkImageInfo. The
         reference count of SkColorSpace is unchanged. The returned SkColorSpace is
         immutable.
 
-        @return  SkColorSpace, the range of colors, in SkImageInfo
+        @return  SkColorSpace in SkImageInfo, or nullptr
     */
     SkColorSpace* colorSpace() const { return fInfo.colorSpace(); }
 
diff --git a/include/core/SkRect.h b/include/core/SkRect.h
index f9a5bff4ff..d94b358255 100644
--- a/include/core/SkRect.h
+++ b/include/core/SkRect.h
@@ -176,7 +176,7 @@ struct SK_API SkIRect {
     SkISize size() const { return SkISize::Make(this->width(), this->height()); }
 
     /** Returns average of left edge and right edge. Result does not change if SkIRect
-        is sorted. Result may be incorrect if SkIRect is far from the origin.
+        is sorted.
 
         Result is rounded down.
 
@@ -185,7 +185,7 @@ struct SK_API SkIRect {
     int32_t centerX() const { return SkToS32(((int64_t)fRight + fLeft) >> 1); }
 
     /** Returns average of top edge and bottom edge. Result does not change if SkIRect
-        is sorted. Result may be incorrect if SkIRect is far from the origin.
+        is sorted.
 
         Result is rounded down.
 
diff --git a/include/core/SkSurface.h b/include/core/SkSurface.h
index 28b830dc27..55a34fc9fc 100644
--- a/include/core/SkSurface.h
+++ b/include/core/SkSurface.h
@@ -173,11 +173,12 @@ public:
         @param backendTexture  texture residing on GPU
         @param origin          one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
         @param sampleCnt       samples per pixel, or 0 to disable full scene anti-aliasing
-        @param colorType       one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-                               kRGB_565_SkColorType, kARGB_4444_SkColorType,
-                               kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+        @param colorType       one of:
+                               kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                               kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                               kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
                                kGray_8_SkColorType, kRGBA_F16_SkColorType
-        @param colorSpace      range of colors
+        @param colorSpace      range of colors; may be nullptr
         @param surfaceProps    LCD striping orientation and setting for device independent
                                fonts; may be nullptr
         @return                SkSurface if all parameters are valid; otherwise, nullptr
@@ -189,8 +190,8 @@ public:
                                                    sk_sp<SkColorSpace> colorSpace,
                                                    const SkSurfaceProps* surfaceProps);
 
-    /** Wraps a GPU-backed buffer into SkSurface. Caller must ensure render target is
-        valid for the lifetime of returned SkSurface.
+    /** Wraps a GPU-backed buffer into SkSurface. Caller must ensure backendRenderTarget
+        is valid for the lifetime of returned SkSurface.
 
         SkSurface is returned if all parameters are valid. backendRenderTarget is valid if
         its pixel configuration agrees with colorSpace and context; for instance, if
@@ -204,9 +205,10 @@ public:
         @param context              GPU context
         @param backendRenderTarget  GPU intermediate memory buffer
         @param origin               one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
-        @param colorType            one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-                                    kRGB_565_SkColorType, kARGB_4444_SkColorType,
-                                    kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+        @param colorType            one of:
+                                    kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                                    kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                                    kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
                                     kGray_8_SkColorType, kRGBA_F16_SkColorType
         @param colorSpace           range of colors
         @param surfaceProps         LCD striping orientation and setting for device independent
@@ -220,11 +222,18 @@ public:
                                                 sk_sp<SkColorSpace> colorSpace,
                                                 const SkSurfaceProps* surfaceProps);
 
-    /** Used to wrap a GPU-backed texture as a SkSurface. Skia will treat the texture as
-        a rendering target only, but unlike NewFromBackendRenderTarget, Skia will manage and own
-        the associated render target objects (but not the provided texture). Skia will not assume
-        ownership of the texture and the client must ensure the texture is valid for the lifetime
-        of the SkSurface.
+    /** Wraps a GPU-backed texture into SkSurface. Caller must ensure backendTexture is
+        valid for the lifetime of returned SkSurface. If sampleCnt greater than zero,
+        creates an intermediate MSAA SkSurface which is used for drawing backendTexture.
+
+        SkSurface is returned if all parameters are valid. backendTexture is valid if
+        its pixel configuration agrees with colorSpace and context; for instance, if
+        backendTexture has an sRGB configuration, then context must support sRGB,
+        and colorSpace must be present. Further, backendTexture width and height must
+        not exceed context capabilities.
+
+        Returned SkSurface is available only for drawing into, and cannot generate an
+        SkImage.
 
         If SK_SUPPORT_GPU is defined as zero, has no effect and returns nullptr.
 
@@ -232,11 +241,12 @@ public:
         @param backendTexture  texture residing on GPU
         @param origin          one of: kBottomLeft_GrSurfaceOrigin, kTopLeft_GrSurfaceOrigin
         @param sampleCnt       samples per pixel, or 0 to disable full scene anti-aliasing
-        @param colorType       one of: kUnknown_SkColorType, kAlpha_8_SkColorType,
-                               kRGB_565_SkColorType, kARGB_4444_SkColorType,
-                               kRGBA_8888_SkColorType, kBGRA_8888_SkColorType,
+        @param colorType       one of:
+                               kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
+                               kARGB_4444_SkColorType, kRGBA_8888_SkColorType, kRGB_888x_SkColorType,
+                               kBGRA_8888_SkColorType, kRGBA_1010102_SkColorType, kRGB_101010x_SkColorType,
                                kGray_8_SkColorType, kRGBA_F16_SkColorType
-        @param colorSpace      range of colors
+        @param colorSpace      range of colors; may be nullptr
         @param surfaceProps    LCD striping orientation and setting for device independent
                                fonts; may be nullptr
         @return                SkSurface if all parameters are valid; otherwise, nullptr