Documentation refresh

- add links to types within methods
- add check to see that all references and definitions match
- add style to tables to make them easier to read
- use https everywhere
- remove trailing spaces
- move overview inside class
- split class and struct in summary tables
- add missing #Line
- clean up SkImageInfo constant documentation
- work on SkColor documentation
- allow common phrases to take different parameters
- add more flexibility to generated tables
- tighten token parent requirements
- generalize deprecated and example interfaces
- detect inner constructors

R=caryclark@google.com
Docs-Preview: https://skia.org/?cl=121799
Bug: skia:6898
Change-Id: Ia75a23740b80259460916890b310e2a9f024962a
Reviewed-on: https://skia-review.googlesource.com/121799
Commit-Queue: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

1 files changed, 83 insertions, 61 deletions

diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index e07999a434..6fdf2a0e89 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -1,12 +1,6 @@
 #Topic Paint
 #Alias Paint_Reference
 
-#Subtopic Overview
-    #Subtopic Subtopic
-    #Populate
-    ##
-##
-
 #Class SkPaint
 
 Paint controls options applied when drawing and measuring. Paint collects all
@@ -35,6 +29,10 @@ Paint describes a single color, a single font, a single image quality, and so on
 Multiple colors are drawn either by using multiple paints or with objects like
 Shader attached to Paint.
 
+#Subtopic Overview
+#Populate
+##
+
 #Subtopic Related_Function
 #Populate
 ##
@@ -43,7 +41,7 @@ Shader attached to Paint.
 #Populate
 ##
 
-#Subtopic Class_or_Struct
+#Subtopic Struct
 #Populate
 ##
 
@@ -419,6 +417,7 @@ The four levels roughly control corresponding features on platforms that use Fre
 as the Font_Engine.
 
 #Const kNo_Hinting   0
+#Line # glyph outlines unchanged ##
     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
@@ -426,6 +425,7 @@ as the Font_Engine.
     to 26.6 fractional pixels.
 ##
 #Const kSlight_Hinting 1
+#Line # minimal modification to improve constrast ##
     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
@@ -433,12 +433,14 @@ as the Font_Engine.
     Generated Glyphs may be fuzzy but better resemble their original shape.
 ##
 #Const kNormal_Hinting 2
+#Line # glyph outlines modified to improve constrast ##
     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.
 ##
 #Const kFull_Hinting 3
+#Line # modifies glyph outlines for maxiumum constrast ##
     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
@@ -446,15 +448,11 @@ as the Font_Engine.
     variant of FT_LOAD_TARGET_NORMAL optimized for vertically decimated LCD displays.
 ##
 
-#Track
-#File SkFontHost_mac.cpp:1777,1806
-#Time 2013-03-03 07:16:29 +0000
 #Bug 915
 On OS_X and iOS, hinting controls whether Core_Graphics dilates the font outlines
 to account for LCD text. No hinting uses Core_Text gray scale output.
 Normal hinting uses Core_Text LCD output. If kLCDRenderText_Flag is clear,
 the LCD output is reduced to a single grayscale channel.
-#Track ##
 
 On Windows with DirectWrite, Hinting has no effect.
 
@@ -548,34 +546,34 @@ All flags can be read and written explicitly; Flags allows manipulating
 multiple settings at once.
 
     #Const kAntiAlias_Flag          0x0001
-        mask for setting Anti-alias
+    #Line # mask for setting Anti-alias ##
     ##
     #Const kDither_Flag             0x0004
-        mask for setting Dither
+    #Line # mask for setting Dither ##
     ##
-
     #Const kFakeBoldText_Flag       0x0020
-        mask for setting Fake_Bold
+    #Line # mask for setting Fake_Bold ##
     ##
     #Const kLinearText_Flag         0x0040
-        mask for setting Linear_Text
+    #Line # mask for setting Linear_Text ##
     ##
     #Const kSubpixelText_Flag       0x0080
-        mask for setting Subpixel_Text
+    #Line # mask for setting Subpixel_Text ##
     ##
     #Const kLCDRenderText_Flag      0x0200
-        mask for setting LCD_Text
+    #Line # mask for setting LCD_Text ##
     ##
     #Const kEmbeddedBitmapText_Flag 0x0400
-        mask for setting Font_Embedded_Bitmaps
+    #Line # mask for setting Font_Embedded_Bitmaps ##
     ##
     #Const kAutoHinting_Flag        0x0800
-        mask for setting Automatic_Hinting
+    #Line # mask for setting Automatic_Hinting ##
     ##
     #Const kVerticalText_Flag       0x1000
-        mask for setting Vertical_Text
+    #Line # mask for setting Vertical_Text ##
     ##
     #Const kAllFlags                0xFFFF
+    #Line # mask of all Flags ##
         mask of all Flags, including private flags and flags reserved for future use
     ##
 
@@ -652,6 +650,8 @@ All Flags members may be cleared, or one or more may be set.
 # ------------------------------------------------------------------------------
 #Subtopic Anti-alias
 #Alias Anti-alias  # permit hyphen in topic name, should probably not substitute hyphen with _
+#Alias Anti-aliased
+#Alias Anti-aliasing
 #In Related_Function
 #Line # approximating coverage with transparency ##
 
@@ -1342,7 +1342,7 @@ Skia can translate text character codes as a series of Glyphs, but does not impl
 font substitution,
 textual substitution, line layout, or contextual spacing like Kerning pairs. Use
 a text shaping engine like
-#A HarfBuzz # http://harfbuzz.org/ ##
+#A HarfBuzz # https://harfbuzz.org/ ##
  to translate text runs
 into glyph series.
 
@@ -1868,7 +1868,7 @@ Use kStrokeAndFill_Style to avoid hitting the same pixels twice with a stroke dr
 a fill draw.
 
 #Const  kFill_Style 0
-    Set to fill geometry.
+#Line # set to fill geometry ##
     Applies to Rect, Region, Round_Rect, Circles, Ovals, Path, and Text.
     Bitmap, Image, Patches, Region, Sprites, and Vertices are painted as if
     kFill_Style is set, and ignore the set Style.
@@ -1878,7 +1878,7 @@ a fill draw.
 ##
 
 #Const kStroke_Style 1
-    Set to stroke geometry.
+#Line # set to stroke geometry ##
     Applies to Rect, Region, Round_Rect, Arcs, Circles, Ovals, Path, and Text.
     Arcs, Lines, and points, are always drawn as if kStroke_Style is set,
     and ignore the set Style.
@@ -1886,14 +1886,14 @@ a fill draw.
 ##
 
 #Const kStrokeAndFill_Style 2
-    Set to stroke and fill geometry.
+#Line # sets to stroke and fill geometry ##
     Applies to Rect, Region, Round_Rect, Circles, Ovals, Path, and Text.
     Path is treated as if it is set to SkPath::kWinding_FillType,
     and the set Path_Fill_Type is ignored.
 ##
 
 #Const kStyleCount 3
-The number of different Style values defined.
+#Line # number of different Style values defined ##
 May be used to verify that Style is a legal value.
 ##
 
@@ -2200,27 +2200,31 @@ Here are some miter limits and the angles that triggers them.
 Stroke_Cap draws at the beginning and end of an open Path_Contour.
 
     #Const kButt_Cap 0
+    #Line # no stroke extension ##
         Does not extend the stroke past the beginning or the end.
     ##
     #Const kRound_Cap 1
+    #Line # adds circle ##
         Adds a circle with a diameter equal to Stroke_Width at the beginning
         and end.
     ##
     #Const kSquare_Cap 2
+    #Line # adds square ##
         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.
     ##
     #Const kLast_Cap 2
+    #Line # largest Stroke_Cap value ##
         Equivalent to the largest value for Stroke_Cap.
     ##
     #Const kDefault_Cap 0
-        Equivalent to kButt_Cap.
+    #Line # equivalent to kButt_Cap ##
         Stroke_Cap is set to kButt_Cap by default.
     ##
 
     #Const kCapCount 3
-        The number of different Stroke_Cap values defined.
+    #Line # number of different Stroke_Cap values defined ##
         May be used to verify that Stroke_Cap is a legal value.
     ##
 #Enum ##
@@ -2362,29 +2366,32 @@ not contain the actual join. For instance, a fill path constructed with round jo
 not necessarily include circles at each connected segment.
 
 #Const kMiter_Join 0
+#Line # extends to Miter_Limit ##
     Extends the outside corner to the extent allowed by Miter_Limit.
     If the extension exceeds Miter_Limit, kBevel_Join is used instead.
 ##
 
 #Const kRound_Join 1
+#Line # adds circle ##
     Adds a circle with a diameter of Stroke_Width at the sharp corner.
 ##
 
 #Const kBevel_Join 2
+#Line # connects outside edges ##
     Connects the outside edges of the sharp corner.
 ##
 
 #Const kLast_Join 2
-    Equivalent to the largest value for Stroke_Join.
+#Line # equivalent to the largest value for Stroke_Join ##
 ##
 
 #Const kDefault_Join 1
-    Equivalent to kMiter_Join.
+#Line # equivalent to kMiter_Join ##
     Stroke_Join is set to kMiter_Join by default.
 ##
 
 #Const kJoinCount 3
-    The number of different Stroke_Join values defined.
+#Line # number of different Stroke_Join values defined ##
     May be used to verify that Stroke_Join is a legal value.
 ##
 
@@ -3466,21 +3473,24 @@ using the metrics returned by the font.
 Align defaults to kLeft_Align.
 
 #Const kLeft_Align 0
+#Line # positions glyph by computed font offset ##
     Leaves the glyph at the position computed by the font offset by the text position.
 ##
 
 #Const kCenter_Align 1
+#Line # centers line of glyphs by its width or height ##
     Moves the glyph half its width if Flags has kVerticalText_Flag clear, and
     half its height if Flags has kVerticalText_Flag set.
 ##
 
 #Const kRight_Align 2
+#Line # moves lines of glyphs by its width or height ##
     Moves the glyph by its width if Flags has kVerticalText_Flag clear,
     and by its height if Flags has kVerticalText_Flag set.
 ##
 
 #Const kAlignCount 3
-    The number of different Text_Align values defined.
+#Line # number of different Text_Align values defined ##
 ##
 
 #Enum ##
@@ -3765,7 +3775,7 @@ Text_Skew_X defaults to 0.
 
 TextEncoding determines whether text specifies character codes and their encoded
 size, or glyph indices. Characters are encoded as specified by the
-#A Unicode standard # http://unicode.org/standard/standard.html ##
+#A Unicode standard # https://unicode.org/standard/standard.html ##
 .
 
 Character codes encoded size are specified by UTF-8, UTF-16, or UTF-32.
@@ -3778,7 +3788,7 @@ in the total storage required.
 #A UTF-16 (RFC 2781) # https://tools.ietf.org/html/rfc2781 ##
  encodes each character as one or two 16-bit words.
 
-#A UTF-32 # http://www.unicode.org/versions/Unicode5.0.0/ch03.pdf ##
+#A UTF-32 # https://www.unicode.org/versions/Unicode5.0.0/ch03.pdf ##
  encodes each character as one 32-bit word.
 
 Font_Manager uses font data to convert character code points into glyph indices.
@@ -3787,16 +3797,16 @@ A glyph index is a 16-bit word.
 TextEncoding is set to kUTF8_TextEncoding by default.
 
 #Const kUTF8_TextEncoding 0
-Uses bytes to represent UTF-8 or ASCII.
+#Line # uses bytes to represent UTF-8 or ASCII ##
 ##
 #Const kUTF16_TextEncoding 1
-Uses two byte words to represent most of Unicode.
+#Line # uses two byte words to represent most of Unicode ##
 ##
 #Const kUTF32_TextEncoding 2
-Uses four byte words to represent all of Unicode.
+#Line # uses four byte words to represent all of Unicode ##
 ##
 #Const kGlyphID_TextEncoding 3
-Uses two byte words to represent glyph indices.
+#Line # uses two byte words to represent glyph indices ##
 ##
 
 #Enum ##
@@ -3807,7 +3817,7 @@ Uses two byte words to represent glyph indices.
 First line is encoded in UTF-8.
 Second line is encoded in UTF-16.
 Third line is encoded in UTF-32.
-Fourth line has 16 bit glyph indices.
+Fourth line has 16-bit glyph indices.
 ##
 void draw(SkCanvas* canvas) {
     SkPaint paint;
@@ -3987,7 +3997,7 @@ void draw(SkCanvas* canvas) {
     are valid, since their value may be zero.
 
     #Enum FontMetricsFlags
-#Line # valid Font_Metrics ##
+    #Line # valid Font_Metrics ##
 
     #Code
         enum FontMetricsFlags {
@@ -4003,86 +4013,94 @@ void draw(SkCanvas* canvas) {
     Fonts with embedded bitmaps may not have valid underline or strikeout metrics.
 
         #Const kUnderlineThicknessIsValid_Flag 0x0001
-            Set if fUnderlineThickness is valid.
+        #Line # set if fUnderlineThickness is valid ##
         ##
         #Const kUnderlinePositionIsValid_Flag  0x0002
-            Set if fUnderlinePosition is valid.
+        #Line # set if fUnderlinePosition is valid ##
         ##
         #Const kStrikeoutThicknessIsValid_Flag 0x0004
-            Set if fStrikeoutThickness is valid.
+        #Line # set if fStrikeoutThickness is valid ##
         ##
         #Const kStrikeoutPositionIsValid_Flag  0x0008
-            Set if fStrikeoutPosition is valid.
+        #Line # set if fStrikeoutPosition is valid ##
         ##
 
     #Enum ##
 
     #Member uint32_t    fFlags
-        fFlags is set when underline metrics are valid.
+    #Line # is set to FontMetricsFlags when metrics are valid ##
     ##
 
     #Member SkScalar    fTop
+    #Line # extent above baseline ##
         Greatest extent above the baseline for any glyph.
         Typically less than zero.
     ##
 
     #Member SkScalar    fAscent
+    #Line # distance to reserve above baseline ##
         Recommended distance above the baseline to reserve for a line of text.
         Typically less than zero.
     ##
 
     #Member SkScalar    fDescent
+    #Line # distance to reserve below baseline ##
         Recommended distance below the baseline to reserve for a line of text.
         Typically greater than zero.
     ##
 
     #Member SkScalar    fBottom
+    #Line # extent below baseline ##
         Greatest extent below the baseline for any glyph.
         Typically greater than zero.
     ##
 
     #Member SkScalar    fLeading
+    #Line # distance to add between lines ##
         Recommended distance to add between lines of text.
         Typically greater than or equal to zero.
     ##
 
     #Member SkScalar    fAvgCharWidth
+    #Line # average character width ##
         Average character width, if it is available.
         Zero if no average width is stored in the font.
     ##
 
     #Member SkScalar    fMaxCharWidth
-        Maximum character width.
+    #Line # maximum character width ##
     ##
 
     #Member SkScalar    fXMin
-        Minimum bounding box x value for all Glyphs.
+    #Line # minimum x ##
+        Minimum bounding box x-value for all Glyphs.
         Typically less than zero.
     ##
 
     #Member SkScalar    fXMax
+    #Line # maximum x ##
         Maximum bounding box x value for all Glyphs.
         Typically greater than zero.
     ##
 
     #Member SkScalar    fXHeight
-        Height of a lower-case 'x'.
+    #Line # height of lower-case 'x' ##
         May be zero if no lower-case height is stored in the font.
     ##
 
     #Member SkScalar    fCapHeight
-        Height of an upper-case letter.
+    #Line # height of an upper-case letter ##
         May be zero if no upper-case height is stored in the font.
     ##
 
     #Member SkScalar    fUnderlineThickness
-        Underline thickness.
-
+    #Line # underline thickness ##
         If the metric is valid, the kUnderlineThicknessIsValid_Flag is set in fFlags.
         If kUnderlineThicknessIsValid_Flag is clear, fUnderlineThickness is zero.
     ##
 
     #Member SkScalar    fUnderlinePosition
+    #Line # underline position relative to baseline ##
        Position of the top of the underline stroke relative to the baseline.
        Typically positive when valid.
 
@@ -4091,13 +4109,14 @@ void draw(SkCanvas* canvas) {
     ##
 
     #Member SkScalar    fStrikeoutThickness
-        Strikeout thickness.
+    #Line # strikeout thickness ##
 
         If the metric is valid, the kStrikeoutThicknessIsValid_Flag is set in fFlags.
         If kStrikeoutThicknessIsValid_Flag is clear, fStrikeoutThickness is zero.
     ##
 
     #Member SkScalar    fStrikeoutPosition
+    #Line # strikeout position relative to baseline ##
         Position of the bottom of the strikeout stroke relative to the baseline.
         Typically negative when valid.
 
@@ -4106,6 +4125,7 @@ void draw(SkCanvas* canvas) {
     ##
 
     #Method bool hasUnderlineThickness(SkScalar* thickness) const
+    #Line # returns underline thickness if set ##
 
         If Font_Metrics has a valid underline thickness, return true, and set
         thickness to that value. If the underline thickness is not valid,
@@ -4120,6 +4140,7 @@ void draw(SkCanvas* canvas) {
     ##
 
     #Method bool hasUnderlinePosition(SkScalar* position) const
+    #Line # returns underline position if set ##
 
         If Font_Metrics has a valid underline position, return true, and set
         position to that value. If the underline position is not valid,
@@ -4134,6 +4155,7 @@ void draw(SkCanvas* canvas) {
     ##
 
     #Method bool hasStrikeoutThickness(SkScalar* thickness) const
+    #Line # returns strikeout thickness if set ##
 
         If Font_Metrics has a valid strikeout thickness, return true, and set
         thickness to that value. If the underline thickness is not valid,
@@ -4148,6 +4170,7 @@ void draw(SkCanvas* canvas) {
     ##
 
     #Method bool hasStrikeoutPosition(SkScalar* position) const
+    #Line # returns strikeout position if set ##
 
         If Font_Metrics has a valid strikeout position, return true, and set
         position to that value. If the underline position is not valid,
@@ -4985,7 +5008,7 @@ void draw(SkCanvas* canvas) {
     To be made private.
     ##
 
-Fast_Bounds methods conservatively outset a drawing bounds by additional area
+Fast_Bounds functions conservatively outset a drawing bounds by additional area
 Paint may draw to.
 
 #Method bool canComputeFastBounds() const
@@ -5023,15 +5046,14 @@ Paint may draw to.
     Rect.
 
     #Private
-    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; // don't draw the path
+        }
     }
+    // draw the path
     ##
 
     #Param orig     geometry modified by Paint when drawn ##