include refresh

Update the includes to match the bookmaker docs.
All edits are generated; if something looks amiss, I
probably introduced a bug in the generator. Please
let me know.

I was careful to pick up all direct edits to the includes
and add them to their bookmaker counterpart. Please take
a look to see if your favorites are there.

Note that enum and struct members have been shortened
to fit on one line. The intent is to provide more verbose
documentation online. Let me know if this is too terse.

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

1 files changed, 69 insertions, 225 deletions

diff --git a/include/core/SkPaint.h b/include/core/SkPaint.h
index 6c60fc3587..883e5c610e 100644
--- a/include/core/SkPaint.h
+++ b/include/core/SkPaint.h
@@ -172,36 +172,10 @@ public:
         as the font engine.
     */
     enum Hinting {
-        /** Leaves glyph outlines unchanged from their native representation.
-            With FreeType, this is equivalent to the FT_LOAD_NO_HINTING
-            bit-field constant supplied to FT_Load_Glyph, which indicates that the vector
-            outline being loaded should not be fitted to the pixel grid but simply scaled
-            to 26.6 fractional pixels.
-        */
-        kNo_Hinting     = 0,
-
-        /** Modifies glyph outlines minimally to improve constrast.
-            With FreeType, this is equivalent in spirit to the
-            FT_LOAD_TARGET_LIGHT value supplied to FT_Load_Glyph. It chooses a
-            lighter hinting algorithm for non-monochrome modes.
-            Generated glyphs may be fuzzy but better resemble their original shape.
-        */
-        kSlight_Hinting = 1,
-
-        /** Modifies glyph outlines to improve constrast. This is the default.
-            With FreeType, this supplies FT_LOAD_TARGET_NORMAL to FT_Load_Glyph,
-            choosing the default hinting algorithm, which is optimized for standard
-            gray-level rendering.
-        */
-        kNormal_Hinting = 2,
-
-        /** Modifies glyph outlines for maxiumum constrast. With FreeType, this selects
-            FT_LOAD_TARGET_LCD or FT_LOAD_TARGET_LCD_V if kLCDRenderText_Flag is set.
-            FT_LOAD_TARGET_LCD is a variant of FT_LOAD_TARGET_NORMAL optimized for
-            horizontally decimated LCD displays; FT_LOAD_TARGET_LCD_V is a
-            variant of FT_LOAD_TARGET_NORMAL optimized for vertically decimated LCD displays.
-        */
-        kFull_Hinting   = 3,
+        kNo_Hinting     = 0, //!< glyph outlines unchanged
+        kSlight_Hinting = 1, //!< minimal modification to improve constrast
+        kNormal_Hinting = 2, //!< glyph outlines modified to improve constrast
+        kFull_Hinting   = 3, //!< modifies glyph outlines for maximum constrast
     };
 
     /** Returns level of glyph outline adjustment.
@@ -236,15 +210,13 @@ public:
         kEmbeddedBitmapText_Flag = 0x400,  //!< mask for setting font embedded bitmaps
         kAutoHinting_Flag        = 0x800,  //!< mask for setting auto-hinting
         kVerticalText_Flag       = 0x1000, //!< mask for setting vertical text
-
-        /** mask of all Flags, including private flags and flags reserved for future use */
-        kAllFlags                = 0xFFFF,
+        kAllFlags                = 0xFFFF, //!< mask of all Flags
     };
 
     #ifdef SK_BUILD_FOR_ANDROID_FRAMEWORK
     enum ReserveFlags {
-        kUnderlineText_ReserveFlag  = 0x08, //!< deprecated
-        kStrikeThruText_ReserveFlag = 0x10, //!< deprecated
+        kUnderlineText_ReserveFlag  = 0x08, //!< to be deprecated soon
+        kStrikeThruText_ReserveFlag = 0x10, //!< to be deprecated soon
     };
     #endif
 
@@ -444,20 +416,11 @@ public:
     */
     void setFakeBoldText(bool fakeBoldText);
 
-    /** Returns if character spacing may be adjusted by the hinting difference.
-
-        Equivalent to getFlags() masked with kDevKernText_Flag.
-
-        @return  kDevKernText_Flag state
+    /** Deprecated.
     */
     bool isDevKernText() const { return false; }
 
-    /** Requests, but does not require, to use hinting to adjust glyph spacing.
-
-        Sets kDevKernText_Flag if devKernText is true.
-        Clears kDevKernText_Flag if devKernText is false.
-
-        @param devKernText  setting for devKernText
+    /** Deprecated.
     */
     void setDevKernText(bool) { }
 
@@ -489,34 +452,12 @@ public:
         a fill draw.
     */
     enum Style {
-        /** Set to fill geometry.
-            Applies to SkRect, SkRegion, SkRRect, circles, ovals, SkPath, and text.
-            SkBitmap, SkImage, patches, SkRegion, sprites, and vertices are painted as if
-            kFill_Style is set, and ignore the set Style.
-            The FillType specifies additional rules to fill the area outside the path edge,
-            and to create an unfilled hole inside the shape.
-            Style is set to kFill_Style by default.
-        */
-        kFill_Style,
-
-        /** Set to stroke geometry.
-            Applies to SkRect, SkRegion, SkRRect, arcs, circles, ovals, SkPath, and text.
-            Arcs, lines, and points, are always drawn as if kStroke_Style is set,
-            and ignore the set Style.
-            The stroke construction is unaffected by the FillType.
-        */
-        kStroke_Style,
-
-        /** Set to stroke and fill geometry.
-            Applies to SkRect, SkRegion, SkRRect, circles, ovals, SkPath, and text.
-            SkPath is treated as if it is set to SkPath::kWinding_FillType,
-            and the set FillType is ignored.
-        */
-        kStrokeAndFill_Style,
+        kFill_Style,          //!< set to fill geometry
+        kStroke_Style,        //!< set to stroke geometry
+        kStrokeAndFill_Style, //!< sets to stroke and fill geometry
     };
 
-    /** The number of different Style values defined.
-        May be used to verify that Style is a legal value.
+    /** May be used to verify that SkPaint::Style is a legal value.
     */
     static constexpr int kStyleCount = kStrokeAndFill_Style + 1;
 
@@ -567,10 +508,10 @@ public:
     /** Sets color used when drawing solid fills. The color components range from 0 to 255.
         The color is unpremultiplied; alpha sets the transparency independent of RGB.
 
-        @param a  amount of color alpha, from fully transparent (0) to fully opaque (255)
-        @param r  amount of color rgb red, from no red (0) to full red (255)
-        @param g  amount of color rgb green, from no green (0) to full green (255)
-        @param b  amount of color rgb blue, from no blue (0) to full blue (255)
+        @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)
     */
     void setARGB(U8CPU a, U8CPU r, U8CPU g, U8CPU b);
 
@@ -607,28 +548,15 @@ public:
         Cap draws at the beginning and end of an open path contour.
     */
     enum Cap {
-        kButt_Cap,                  //!< Does not extend the stroke past the beginning or the end.
-
-        /** Adds a circle with a diameter equal to stroke width at the beginning
-            and end.
-        */
-        kRound_Cap,
-
-        /** Adds a square with sides equal to stroke width at the beginning
-            and end. The square sides are parallel to the initial and final direction
-            of the stroke.
-        */
-        kSquare_Cap,
-        kLast_Cap    = kSquare_Cap, //!< Equivalent to the largest value for Cap.
-
-        /** Equivalent to kButt_Cap.
-            Cap is set to kButt_Cap by default.
-        */
-        kDefault_Cap = kButt_Cap,
+        kButt_Cap,                  //!< no stroke extension
+        kRound_Cap,                 //!< adds circle
+        kSquare_Cap,                //!< adds square
+        kLast_Cap    = kSquare_Cap, //!< largest Cap value
+        kDefault_Cap = kButt_Cap,   //!< equivalent to kButt_Cap
     };
 
-    /** The number of different SkPaint::Cap values defined.
-        May be used to verify that SkPaint::Cap is a legal value.*/
+    /** May be used to verify that SkPaint::Cap is a legal value.
+    */
     static constexpr int kCapCount = kLast_Cap + 1;
 
     /** \enum SkPaint::Join
@@ -645,24 +573,15 @@ public:
         not necessarily include circles at each connected segment.
     */
     enum Join {
-        /** Extends the outside corner to the extent allowed by miter limit.
-            If the extension exceeds miter limit, kBevel_Join is used instead.
-        */
-        kMiter_Join,
-
-        /** Adds a circle with a diameter of stroke width at the sharp corner. */
-        kRound_Join,
-        kBevel_Join,                 //!< Connects the outside edges of the sharp corner.
-        kLast_Join    = kBevel_Join, //!< Equivalent to the largest value for Join.
-
-        /** Equivalent to kMiter_Join.
-            Join is set to kMiter_Join by default.
-        */
-        kDefault_Join = kMiter_Join,
+        kMiter_Join,                 //!< extends to miter limit
+        kRound_Join,                 //!< adds circle
+        kBevel_Join,                 //!< connects outside edges
+        kLast_Join    = kBevel_Join, //!< equivalent to the largest value for Join
+        kDefault_Join = kMiter_Join, //!< equivalent to kMiter_Join
     };
 
-    /** The number of different SkPaint::Join values defined.
-        May be used to verify that SkPaint::Join is a legal value.*/
+    /** May be used to verify that SkPaint::Join is a legal value.
+    */
     static constexpr int kJoinCount = kLast_Join + 1;
 
     /** The geometry drawn at the beginning and end of strokes.
@@ -930,21 +849,14 @@ public:
         Align defaults to kLeft_Align.
     */
     enum Align {
-        /** Leaves the glyph at the position computed by the font offset by the text position. */
-        kLeft_Align,
-
-        /** Moves the glyph half its width if Flags has kVerticalText_Flag clear, and
-            half its height if Flags has kVerticalText_Flag set.
-        */
-        kCenter_Align,
-
-        /** Moves the glyph by its width if Flags has kVerticalText_Flag clear,
-            and by its height if Flags has kVerticalText_Flag set.
-        */
-        kRight_Align,
+        kLeft_Align,   //!< positions glyph by computed font offset
+        kCenter_Align, //!< centers line of glyphs by its width or height
+        kRight_Align,  //!< moves lines of glyphs by its width or height
     };
 
-    static constexpr int kAlignCount = 3; //!< The number of different Align values defined.
+    /** May be used to verify that align is a legal value.
+    */
+    static constexpr int kAlignCount = 3;
 
     /** Returns SkPaint::Align.
         Returns kLeft_Align if SkPaint::Align has not been set.
@@ -1021,10 +933,10 @@ public:
         TextEncoding is set to kUTF8_TextEncoding by default.
     */
     enum TextEncoding {
-        kUTF8_TextEncoding,    //!< Uses bytes to represent UTF-8 or ASCII.
-        kUTF16_TextEncoding,   //!< Uses two byte words to represent most of Unicode.
-        kUTF32_TextEncoding,   //!< Uses four byte words to represent all of Unicode.
-        kGlyphID_TextEncoding, //!< Uses two byte words to represent glyph indices.
+        kUTF8_TextEncoding,    //!< uses bytes to represent UTF-8 or ASCII
+        kUTF16_TextEncoding,   //!< uses two byte words to represent most of Unicode
+        kUTF32_TextEncoding,   //!< uses four byte words to represent all of Unicode
+        kGlyphID_TextEncoding, //!< uses two byte words to represent glyph indices
     };
 
     /** Returns SkPaint::TextEncoding.
@@ -1069,95 +981,28 @@ public:
             Fonts with embedded bitmaps may not have valid underline or strikeout metrics.
         */
         enum FontMetricsFlags {
-            kUnderlineThicknessIsValid_Flag = 1 << 0, //!< Set if fUnderlineThickness is valid.
-            kUnderlinePositionIsValid_Flag  = 1 << 1, //!< Set if fUnderlinePosition is valid.
-            kStrikeoutThicknessIsValid_Flag = 1 << 2, //!< Set if fStrikeoutThickness is valid.
-            kStrikeoutPositionIsValid_Flag  = 1 << 3, //!< Set if fStrikeoutPosition is valid.
+            kUnderlineThicknessIsValid_Flag = 1 << 0, //!< set if fUnderlineThickness is valid
+            kUnderlinePositionIsValid_Flag  = 1 << 1, //!< set if fUnderlinePosition is valid
+            kStrikeoutThicknessIsValid_Flag = 1 << 2, //!< set if fStrikeoutThickness is valid
+            kStrikeoutPositionIsValid_Flag  = 1 << 3, //!< set if fStrikeoutPosition is valid
         };
 
-        uint32_t fFlags;              //!< fFlags is set when underline metrics are valid.
-
-        /** Greatest extent above the baseline for any glyph.
-            Typically less than zero.
-        */
-        SkScalar fTop;
-
-        /** Recommended distance above the baseline to reserve for a line of text.
-            Typically less than zero.
-        */
-        SkScalar fAscent;
-
-        /** Recommended distance below the baseline to reserve for a line of text.
-            Typically greater than zero.
-        */
-        SkScalar fDescent;
-
-        /** Greatest extent below the baseline for any glyph.
-            Typically greater than zero.
-        */
-        SkScalar fBottom;
-
-        /** Recommended distance to add between lines of text.
-            Typically greater than or equal to zero.
-        */
-        SkScalar fLeading;
-
-        /** Average character width, if it is available.
-            Zero if no average width is stored in the font.
-        */
-        SkScalar fAvgCharWidth;
-
-        SkScalar fMaxCharWidth;       //!< Maximum character width.
-
-        /** Minimum bounding box x value for all glyphs.
-            Typically less than zero.
-        */
-        SkScalar fXMin;
-
-        /** Maximum bounding box x value for all glyphs.
-            Typically greater than zero.
-        */
-        SkScalar fXMax;
-
-        /** Height of a lower-case 'x'.
-            May be zero if no lower-case height is stored in the font.
-        */
-        SkScalar fXHeight;
-
-        /** Height of an upper-case letter.
-            May be zero if no upper-case height is stored in the font.
-        */
-        SkScalar fCapHeight;
-
-        /** Underline thickness.
-
-            If the metric is valid, the kUnderlineThicknessIsValid_Flag is set in fFlags.
-            If kUnderlineThicknessIsValid_Flag is clear, fUnderlineThickness is zero.
-        */
-        SkScalar fUnderlineThickness;
-
-        /** Position of the top of the underline stroke relative to the baseline.
-            Typically positive when valid.
-
-            If the metric is valid, the kUnderlinePositionIsValid_Flag is set in fFlags.
-            If kUnderlinePositionIsValid_Flag is clear, fUnderlinePosition is zero.
-        */
-        SkScalar fUnderlinePosition;
-
-        /** Strikeout thickness.
-
-            If the metric is valid, the kStrikeoutThicknessIsValid_Flag is set in fFlags.
-            If kStrikeoutThicknessIsValid_Flag is clear, fStrikeoutThickness is zero.
-        */
-        SkScalar fStrikeoutThickness;
-
-        /** Position of the bottom of the strikeout stroke relative to the baseline.
-            Typically negative when valid.
-
-            If the metric is valid, the kStrikeoutPositionIsValid_Flag is set in fFlags.
-            If kStrikeoutPositionIsValid_Flag is clear, fStrikeoutPosition is zero.
-        */
-        SkScalar fStrikeoutPosition;
+        uint32_t fFlags;              //!< is set to FontMetricsFlags when metrics are valid
+        SkScalar fTop;                //!< extent above baseline
+        SkScalar fAscent;             //!< distance to reserve above baseline
+        SkScalar fDescent;            //!< distance to reserve below baseline
+        SkScalar fBottom;             //!< extent below baseline
+        SkScalar fLeading;            //!< distance to add between lines
+        SkScalar fAvgCharWidth;       //!< average character width
+        SkScalar fMaxCharWidth;       //!< maximum character width
+        SkScalar fXMin;               //!< minimum x
+        SkScalar fXMax;               //!< maximum x
+        SkScalar fXHeight;            //!< height of lower-case 'x'
+        SkScalar fCapHeight;          //!< height of an upper-case letter
+        SkScalar fUnderlineThickness; //!< underline thickness
+        SkScalar fUnderlinePosition;  //!< underline position relative to baseline
+        SkScalar fStrikeoutThickness; //!< strikeout thickness
+        SkScalar fStrikeoutPosition;  //!< strikeout position relative to baseline
 
         /** If SkPaint::FontMetrics has a valid underline thickness, return true, and set
             thickness to that value. If the underline thickness is not valid,
@@ -1515,7 +1360,7 @@ public:
     /** Returns true if SkPaint prevents all drawing;
         otherwise, the SkPaint may or may not allow drawing.
 
-        Returns true if, for example, SkBlendMode combined with color alpha computes a
+        Returns true if, for example, SkBlendMode combined with alpha computes a
         new alpha of zero.
 
         @return  true if SkPaint prevents all drawing
@@ -1542,15 +1387,14 @@ public:
         should not rely on storage being set to the result, but should always
         use the returned value. It is legal for orig and storage to be the same
         SkRect.
-            e.g.
-            if (paint.canComputeFastBounds()) {
-            SkRect r, storage;
-            path.computeBounds(&r, SkPath::kFast_BoundsType);
-            const SkRect& fastR = paint.computeFastBounds(r, &storage);
-            if (canvas->quickReject(fastR, ...)) {
-            // don't draw the path
-            }
+            For example:
+            if (!path.isInverseFillType() && paint.canComputeFastBounds()) {
+                SkRect storage;
+                if (canvas->quickReject(paint.computeFastBounds(path.getBounds(), &storage))) {
+                    return; // do not draw the path
+                }
             }
+            // draw the path
 
         @param orig     geometry modified by SkPaint when drawn
         @param storage  computed bounds of geometry; may not be nullptr