update SkColor

SkColor.h generated include.

Also add generated comment for all files.
And, added typedef documentation where missing.

TBR=reed@google.com

Bug: skia:6898
Change-Id: Ib7757d70c1926b5ae04a5de557711756fce631b6
Reviewed-on: https://skia-review.googlesource.com/132827
Auto-Submit: Cary Clark <caryclark@skia.org>
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

12 files changed, 334 insertions, 77 deletions

diff --git a/include/core/SkBitmap.h b/include/core/SkBitmap.h
index df0f0f8dd2..5affa3450d 100644
--- a/include/core/SkBitmap.h
+++ b/include/core/SkBitmap.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkBitmap.h and docs/SkBitmap_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkBitmap_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkBitmap_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkBitmap.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkBitmap_DEFINED
 #define SkBitmap_DEFINED
 
diff --git a/include/core/SkCanvas.h b/include/core/SkCanvas.h
index 2c8a0ebe4f..a57d00c0b9 100644
--- a/include/core/SkCanvas.h
+++ b/include/core/SkCanvas.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkCanvas.h and docs/SkCanvas_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkCanvas_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkCanvas_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkCanvas.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkCanvas_DEFINED
 #define SkCanvas_DEFINED
 
diff --git a/include/core/SkColor.h b/include/core/SkColor.h
index 4f7592baee..10b6e5fdca 100644
--- a/include/core/SkColor.h
+++ b/include/core/SkColor.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkColor.h and docs/SkColor_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkColor_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkColor_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkColor.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkColor_DEFINED
 #define SkColor_DEFINED
 
@@ -13,175 +23,294 @@
 
 /** \file SkColor.h
 
-    Types and macros for colors
+    Types, consts, functions, and macros for colors.
 */
 
-/** 8-bit type for an alpha value. 0xFF is 100% opaque, 0x00 is 100% transparent.
+/** 8-bit type for an alpha value. 255 is 100% opaque, zero is 100% transparent.
 */
 typedef uint8_t SkAlpha;
-/** 32 bit ARGB color value, not premultiplied. The color components are always in
+
+/** 32-bit ARGB color value, unpremultiplied. Color components are always in
     a known order. This is different from SkPMColor, which has its bytes in a configuration
-    dependent order, to match the format of kARGB32 bitmaps. SkColor is the type used to
-    specify colors in SkPaint and in gradients.
+    dependent order, to match the format of kBGRA_8888_SkColorType bitmaps. SkColor
+    is the type used to specify colors in SkPaint and in gradients.
+
+    Color that is premultiplied has the same component values as color
+    that is unpremultiplied if alpha is 255, fully opaque, although may have the
+    component values in a different order.
 */
 typedef uint32_t SkColor;
 
-/** Return a SkColor value from 8 bit component values
+/** Returns color value from 8-bit component values. Asserts if SK_DEBUG is defined
+    if a, r, g, or b exceed 255. Since color is unpremultiplied, a may be smaller
+    than the largest of r, g, and b.
+
+    @param a  amount of alpha, from fully transparent (0) to fully opaque (255)
+    @param r  amount of red, from no red (0) to full red (255)
+    @param g  amount of green, from no green (0) to full green (255)
+    @param b  amount of blue, from no blue (0) to full blue (255)
+    @return   color and alpha, unpremultiplied
 */
 static constexpr inline SkColor SkColorSetARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b) {
     return SkASSERT(a <= 255 && r <= 255 && g <= 255 && b <= 255),
            (a << 24) | (r << 16) | (g << 8) | (b << 0);
 }
 
-/** Return a SkColor value from 8 bit component values, with an implied value
-    of 0xFF for alpha (fully opaque)
+/** Returns color value from 8-bit component values, with alpha set
+    fully opaque to 255.
 */
 #define SkColorSetRGB(r, g, b)  SkColorSetARGB(0xFF, r, g, b)
 
-/** return the alpha byte from a SkColor value */
+/** Returns alpha byte from color value.
+*/
 #define SkColorGetA(color)      (((color) >> 24) & 0xFF)
-/** return the red byte from a SkColor value */
+
+/** Returns red component of color, from zero to 255.
+*/
 #define SkColorGetR(color)      (((color) >> 16) & 0xFF)
-/** return the green byte from a SkColor value */
+
+/** Returns green component of color, from zero to 255.
+*/
 #define SkColorGetG(color)      (((color) >>  8) & 0xFF)
-/** return the blue byte from a SkColor value */
+
+/** Returns blue component of color, from zero to 255.
+*/
 #define SkColorGetB(color)      (((color) >>  0) & 0xFF)
 
+/** Returns unpremultiplied color with red, blue, and green set from c; and alpha set
+    from a. Alpha component of c is ignored and is replaced by a in result.
+
+    @param c  packed RGB, eight bits per component
+    @param a  alpha: transparent at zero, fully opaque at 255
+    @return   color with transparency
+*/
 static constexpr inline SkColor SkColorSetA(SkColor c, U8CPU a) {
     return (c & 0x00FFFFFF) | (a << 24);
 }
 
-// common colors
-
-/** transparent SkAlpha value */
+/** Represents fully transparent SkAlpha value. SkAlpha ranges from zero,
+    fully transparent; to 255, fully opaque.
+*/
 constexpr SkAlpha SK_AlphaTRANSPARENT = 0x00;
-/** opaque SkAlpha value */
+
+/** Represents fully opaque SkAlpha value. SkAlpha ranges from zero,
+    fully transparent; to 255, fully opaque.
+*/
 constexpr SkAlpha SK_AlphaOPAQUE      = 0xFF;
 
-/** transparent SkColor value */
+/** Represents fully transparent SkColor. May be used to initialize a destination
+    containing a mask or a non-rectangular image.
+*/
 constexpr SkColor SK_ColorTRANSPARENT = SkColorSetARGB(0x00, 0x00, 0x00, 0x00);
 
-/** black SkColor value */
+/** Represents fully opaque black.
+*/
 constexpr SkColor SK_ColorBLACK       = SkColorSetARGB(0xFF, 0x00, 0x00, 0x00);
-/** dark gray SkColor value */
+
+/** Represents fully opaque dark gray.
+    Note that SVG_darkgray is equivalent to 0xFFA9A9A9.
+*/
 constexpr SkColor SK_ColorDKGRAY      = SkColorSetARGB(0xFF, 0x44, 0x44, 0x44);
-/** gray SkColor value */
+
+/** Represents fully opaque gray.
+    Note that HTML_Gray is equivalent to 0xFF808080.
+*/
 constexpr SkColor SK_ColorGRAY        = SkColorSetARGB(0xFF, 0x88, 0x88, 0x88);
-/** light gray SkColor value */
+
+/** Represents fully opaque light gray. HTML_Silver is equivalent to 0xFFC0C0C0.
+    Note that SVG_lightgray is equivalent to 0xFFD3D3D3.
+*/
 constexpr SkColor SK_ColorLTGRAY      = SkColorSetARGB(0xFF, 0xCC, 0xCC, 0xCC);
-/** white SkColor value */
+
+/** Represents fully opaque white.
+*/
 constexpr SkColor SK_ColorWHITE       = SkColorSetARGB(0xFF, 0xFF, 0xFF, 0xFF);
 
-/** red SkColor value */
+/** Represents fully opaque red.
+*/
 constexpr SkColor SK_ColorRED         = SkColorSetARGB(0xFF, 0xFF, 0x00, 0x00);
-/** green SkColor value */
+
+/** Represents fully opaque green. HTML_Lime is equivalent.
+    Note that HTML_Green is equivalent to 0xFF008000.
+*/
 constexpr SkColor SK_ColorGREEN       = SkColorSetARGB(0xFF, 0x00, 0xFF, 0x00);
-/** blue SkColor value */
+
+/** Represents fully opaque blue.
+*/
 constexpr SkColor SK_ColorBLUE        = SkColorSetARGB(0xFF, 0x00, 0x00, 0xFF);
-/** yellow SkColor value */
+
+/** Represents fully opaque yellow.
+*/
 constexpr SkColor SK_ColorYELLOW      = SkColorSetARGB(0xFF, 0xFF, 0xFF, 0x00);
-/** cyan SkColor value */
+
+/** Represents fully opaque cyan. HTML_Aqua is equivalent.
+*/
 constexpr SkColor SK_ColorCYAN        = SkColorSetARGB(0xFF, 0x00, 0xFF, 0xFF);
-/** magenta SkColor value */
+
+/** Represents fully opaque magenta. HTML_Fuchsia is equivalent.
+*/
 constexpr SkColor SK_ColorMAGENTA     = SkColorSetARGB(0xFF, 0xFF, 0x00, 0xFF);
 
-////////////////////////////////////////////////////////////////////////
+/** Converts RGB to its HSV components.
+    hsv[0] contains hsv hue, a value from zero to less than 360.
+    hsv[1] contains hsv saturation, a value from zero to one.
+    hsv[2] contains hsv value, a value from zero to one.
 
-/** Convert RGB components to HSV.
-        hsv[0] is Hue [0 .. 360)
-        hsv[1] is Saturation [0...1]
-        hsv[2] is Value [0...1]
-    @param red  red component value [0..255]
-    @param green  green component value [0..255]
-    @param blue  blue component value [0..255]
-    @param hsv  3 element array which holds the resulting HSV components.
+    @param red    red component value from zero to 255
+    @param green  green component value from zero to 255
+    @param blue   blue component value from zero to 255
+    @param hsv    three element array which holds the resulting HSV components
 */
 SK_API void SkRGBToHSV(U8CPU red, U8CPU green, U8CPU blue, SkScalar hsv[3]);
 
-/** Convert the argb color to its HSV components.
-        hsv[0] is Hue [0 .. 360)
-        hsv[1] is Saturation [0...1]
-        hsv[2] is Value [0...1]
-    @param color the argb color to convert. Note: the alpha component is ignored.
-    @param hsv  3 element array which holds the resulting HSV components.
+/** Converts ARGB to its HSV components. Alpha in ARGB is ignored.
+    hsv[0] contains hsv hue, and is assigned a value from zero to less than 360.
+    hsv[1] contains hsv saturation, a value from zero to one.
+    hsv[2] contains hsv value, a value from zero to one.
+
+    @param color  ARGB color to convert
+    @param hsv    three element array which holds the resulting HSV components
 */
 static inline void SkColorToHSV(SkColor color, SkScalar hsv[3]) {
     SkRGBToHSV(SkColorGetR(color), SkColorGetG(color), SkColorGetB(color), hsv);
 }
 
-/** Convert HSV components to an ARGB color. The alpha component is passed through unchanged.
-        hsv[0] is Hue [0 .. 360)
-        hsv[1] is Saturation [0...1]
-        hsv[2] is Value [0...1]
-    If hsv values are out of range, they are pinned.
-    @param alpha the alpha component of the returned argb color.
-    @param hsv  3 element array which holds the input HSV components.
-    @return the resulting argb color
+/** Converts HSV components to an ARGB color. Alpha is passed through unchanged.
+    hsv[0] represents hsv hue, an angle from zero to less than 360.
+    hsv[1] represents hsv saturation, and varies from zero to one.
+    hsv[2] represents hsv value, and varies from zero to one.
+
+    Out of range hsv values are pinned.
+
+    @param alpha  alpha component of the returned ARGB color
+    @param hsv    three element array which holds the input HSV components
+    @return       ARGB equivalent to HSV
 */
 SK_API SkColor SkHSVToColor(U8CPU alpha, const SkScalar hsv[3]);
 
-/** Convert HSV components to an ARGB color. The alpha component set to 0xFF.
-        hsv[0] is Hue [0 .. 360)
-        hsv[1] is Saturation [0...1]
-        hsv[2] is Value [0...1]
-    If hsv values are out of range, they are pinned.
-    @param hsv  3 element array which holds the input HSV components.
-    @return the resulting argb color
+/** Converts HSV components to an ARGB color. Alpha is set to 255.
+    hsv[0] represents hsv hue, an angle from zero to less than 360.
+    hsv[1] represents hsv saturation, and varies from zero to one.
+    hsv[2] represents hsv value, and varies from zero to one.
+
+    Out of range hsv values are pinned.
+
+    @param hsv  three element array which holds the input HSV components
+    @return     RGB equivalent to HSV
 */
 static inline SkColor SkHSVToColor(const SkScalar hsv[3]) {
     return SkHSVToColor(0xFF, hsv);
 }
 
-////////////////////////////////////////////////////////////////////////
-
-/** 32 bit ARGB color value, premultiplied. The byte order for this value is
-    configuration dependent, matching the format of kARGB32 bitmaps. This is different
-    from SkColor, which is nonpremultiplied, and is always in the same byte order.
+/** 32-bit ARGB color value, premultiplied. The byte order for this value is
+    configuration dependent, matching the format of kBGRA_8888_SkColorType bitmaps.
+    This is different from SkColor, which is unpremultiplied, and is always in the
+    same byte order.
 */
 typedef uint32_t SkPMColor;
 
-/** Return a SkPMColor value from unpremultiplied 8 bit component values
+/** Returns a SkPMColor value from unpremultiplied 8-bit component values.
+
+    @param a  amount of alpha, from fully transparent (0) to fully opaque (255)
+    @param r  amount of red, from no red (0) to full red (255)
+    @param g  amount of green, from no green (0) to full green (255)
+    @param b  amount of blue, from no blue (0) to full blue (255)
+    @return   premultiplied color
 */
 SK_API SkPMColor SkPreMultiplyARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b);
-/** Return a SkPMColor value from a SkColor value. This is done by multiplying the color
-    components by the color's alpha, and by arranging the bytes in a configuration
-    dependent order, to match the format of kARGB32 bitmaps.
+
+/** Returns pmcolor closest to color c. Multiplies c RGB components by the c alpha,
+    and arranges the bytes to match the format of kN32_SkColorType.
+
+    @param c  unpremultiplied ARGB color
+    @return   premultiplied color
 */
 SK_API SkPMColor SkPreMultiplyColor(SkColor c);
 
-///////////////////////////////////////////////////////////////////////////////////////////////////
-
 struct SkPM4f;
 
-/*
- *  The float values are 0...1 unpremultiplied
- */
+/** \struct SkColor4f
+    Each component is stored as a 32-bit single precision floating point float value.
+    All values are allowed, but only the range from zero to one is meaningful.
+
+    Each component is independent of the others; fA alpha is not premultiplied
+    with fG green, fB blue, or fR red.
+
+    Values smaller than zero or larger than one are allowed. Values out of range
+    may be used with SkBlendMode so that the final component is in range.
+*/
 struct SK_API SkColor4f {
-    float fR;
-    float fG;
-    float fB;
-    float fA;
+    float fR; //!< red component
+    float fG; //!< green component
+    float fB; //!< blue component
+    float fA; //!< alpha component
 
+    /** Compares SkColor4f with other, and returns true if all components are equivalent.
+
+        @param other  SkColor4f to compare
+        @return       true if SkColor4f equals other
+    */
     bool operator==(const SkColor4f& other) const {
         return fA == other.fA && fR == other.fR && fG == other.fG && fB == other.fB;
     }
+
+    /** Compares SkColor4f with other, and returns true if all components are not
+        equivalent.
+
+        @param other  SkColor4f to compare
+        @return       true if SkColor4f is not equal to other
+    */
     bool operator!=(const SkColor4f& other) const {
         return !(*this == other);
     }
 
+    /** Returns SkColor4f components as a read-only array.
+
+        @return  components as read-only array
+    */
     const float* vec() const { return &fR; }
+
+    /** Returns SkColor4f components as a read-only array.
+
+        @return  components as read-only array
+    */
     float* vec() { return &fR; }
 
+    /** Constructs and returns SkColor4f with each component pinned from zero to one.
+
+        @param r  red component
+        @param g  green component
+        @param b  blue component
+        @param a  alpha component
+        @return   SkColor4f with valid components
+    */
     static SkColor4f Pin(float r, float g, float b, float a);
-    /** Convert to SkColor4f, assuming SkColor is sRGB */
+
+    /** Converts to closest SkColor4f.
+
+        @param SkColor  color with alpha, red, blue, and green components
+        @return         SkColor4f equivalent
+    */
     static SkColor4f FromColor(SkColor);
 
+    /** Converts to closest SkColor.
+
+        @return  closest color
+    */
     SkColor toSkColor() const;
 
+    /** Returns SkColor4f with all components in the range from zero to one.
+
+        @return  SkColor4f with valid components
+    */
     SkColor4f pin() const {
         return Pin(fR, fG, fB, fA);
     }
 
+    /** Internal use only.
+
+        @return  premultiplied color
+    */
     SkPM4f premul() const;
 };
 
diff --git a/include/core/SkImage.h b/include/core/SkImage.h
index 28c1be1a2a..828d70d4b6 100644
--- a/include/core/SkImage.h
+++ b/include/core/SkImage.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkImage.h and docs/SkImage_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkImage_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkImage_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkImage.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkImage_DEFINED
 #define SkImage_DEFINED
 
@@ -51,6 +61,9 @@ class GrTexture;
 */
 class SK_API SkImage : public SkRefCnt {
 public:
+
+    /** Caller data passed to RasterReleaseProc; may be nullptr.
+    */
     typedef void* ReleaseContext;
 
     /** Creates SkImage from SkPixmap and copy of pixels. Since pixels are copied, SkPixmap
@@ -85,6 +98,9 @@ public:
     static sk_sp<SkImage> MakeRasterData(const SkImageInfo& info, sk_sp<SkData> pixels,
                                          size_t rowBytes);
 
+    /** Function called when SkImage no longer shares pixels. ReleaseContext is
+        provided by caller when SkImage is created, and may be nullptr.
+    */
     typedef void (*RasterReleaseProc)(const void* pixels, ReleaseContext);
 
     /** Creates SkImage from pixmap, sharing SkPixmap pixels. Pixels must remain valid and
@@ -158,6 +174,8 @@ public:
     */
     static sk_sp<SkImage> MakeFromEncoded(sk_sp<SkData> encoded, const SkIRect* subset = nullptr);
 
+    /** User function called when supplied texture may be deleted.
+    */
     typedef void (*TextureReleaseProc)(ReleaseContext releaseContext);
 
     /** Creates SkImage from GPU texture associated with context. Caller is responsible for
@@ -788,6 +806,9 @@ public:
                                   const SkIRect& clipBounds, SkIRect* outSubset,
                                   SkIPoint* offset) const;
 
+    /** Defines a callback function, taking one parameter of type GrBackendTexture with
+        no return value. Function is called when back-end texture is to be released.
+    */
     typedef std::function<void(GrBackendTexture)> BackendTextureReleaseProc;
 
     /** Creates a GrBackendTexture from the provided SkImage. Returns true and
diff --git a/include/core/SkImageInfo.h b/include/core/SkImageInfo.h
index 6d1b2a942d..f09b8d6b03 100644
--- a/include/core/SkImageInfo.h
+++ b/include/core/SkImageInfo.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkImageInfo.h and docs/SkImageInfo_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkImageInfo_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkImageInfo_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkImageInfo.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkImageInfo_DEFINED
 #define SkImageInfo_DEFINED
 
diff --git a/include/core/SkMatrix.h b/include/core/SkMatrix.h
index a5873b114e..688bfc0194 100644
--- a/include/core/SkMatrix.h
+++ b/include/core/SkMatrix.h
@@ -5,6 +5,15 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkMatrix.h and docs/SkMatrix_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkMatrix_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkMatrix_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkMatrix.h -p
+   to create an updated version of this file.
+ */
 
 #ifndef SkMatrix_DEFINED
 #define SkMatrix_DEFINED
diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h
index 883e5c610e..21d6139f6e 100644
--- a/include/core/SkPaint.h
+++ b/include/core/SkPaint.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkPaint.h and docs/SkPaint_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkPaint_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkPaint_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkPaint.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkPaint_DEFINED
 #define SkPaint_DEFINED
 
diff --git a/include/core/SkPath.h b/include/core/SkPath.h
index 20bcc5179b..6b04dd3d1d 100644
--- a/include/core/SkPath.h
+++ b/include/core/SkPath.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkPath.h and docs/SkPath_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkPath_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkPath_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkPath.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkPath_DEFINED
 #define SkPath_DEFINED
 
diff --git a/include/core/SkPixmap.h b/include/core/SkPixmap.h
index 4575f17000..5e417af2ed 100644
--- a/include/core/SkPixmap.h
+++ b/include/core/SkPixmap.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkPixmap.h and docs/SkPixmap_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkPixmap_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkPixmap_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkPixmap.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkPixmap_DEFINED
 #define SkPixmap_DEFINED
 
diff --git a/include/core/SkPoint.h b/include/core/SkPoint.h
index ffb6eef142..f705888c62 100644
--- a/include/core/SkPoint.h
+++ b/include/core/SkPoint.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkPoint.h and docs/SkPoint_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkPoint_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkPoint_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkPoint.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkPoint_DEFINED
 #define SkPoint_DEFINED
 
@@ -13,6 +23,10 @@
 #include "../private/SkSafe32.h"
 
 struct SkIPoint;
+
+/** SkIVector provides an alternative name for SkIPoint. SkIVector and SkIPoint
+    can be used interchangeably for all purposes.
+*/
 typedef SkIPoint SkIVector;
 
 /** \struct SkIPoint
@@ -143,6 +157,10 @@ struct SkIPoint {
 };
 
 struct SkPoint;
+
+/** SkVector provides an alternative name for SkPoint. SkVector and SkPoint can
+    be used interchangably for all purposes.
+*/
 typedef SkPoint SkVector;
 
 /** \struct SkPoint
diff --git a/include/core/SkRect.h b/include/core/SkRect.h
index c260dacffd..363ecdd53c 100644
--- a/include/core/SkRect.h
+++ b/include/core/SkRect.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkRect.h and docs/SkRect_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkRect_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkRect_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkRect.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkRect_DEFINED
 #define SkRect_DEFINED
 
diff --git a/include/core/SkSurface.h b/include/core/SkSurface.h
index 149637413b..d02928e620 100644
--- a/include/core/SkSurface.h
+++ b/include/core/SkSurface.h
@@ -5,6 +5,16 @@
  * found in the LICENSE file.
  */
 
+/* Generated by tools/bookmaker from include/core/SkSurface.h and docs/SkSurface_Reference.bmh
+   on 2018-06-08 11:48:28. Additional documentation and examples can be found at:
+   https://skia.org/user/api/SkSurface_Reference
+
+   You may edit either file directly. Structural changes to public interfaces require
+   editing both files. After editing docs/SkSurface_Reference.bmh, run:
+       bookmaker -b docs -i include/core/SkSurface.h -p
+   to create an updated version of this file.
+ */
+
 #ifndef SkSurface_DEFINED
 #define SkSurface_DEFINED