fix paint docs

quick and dirty edit to get the bots green.
Larger edit is in the works to bring docs
related to these changes up to date.

TBR=reed@google.com

Docs-Preview: https://skia.org/?cl=168923
Bug: skia:
Change-Id: I38af409e75e46439288e94de2758b34094d0e08f
Reviewed-on: https://skia-review.googlesource.com/c/168923
Commit-Queue: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

2 files changed, 171 insertions, 233 deletions

diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 49c8f65d4a..b9cd32c063 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -3232,242 +3232,14 @@ void draw(SkCanvas* canvas) {
 
 ##
 
+#Typedef typedef SkFontMetrics FontMetrics
+##
+
 #Subtopic Text_Encoding ##
 # ------------------------------------------------------------------------------
 #Subtopic Font_Metrics
-#Line # common glyph dimensions ##
-
-Font_Metrics describe dimensions common to the Glyphs in Typeface.
-The dimensions are computed by Font_Manager from font data and do not take
-Paint settings other than Text_Size into account.
-
-Font dimensions specify the anchor to the left of the glyph at baseline as the origin.
-X-axis values to the left of the glyph are negative, and to the right of the left glyph edge
-are positive.
-Y-axis values above the baseline are negative, and below the baseline are positive.
-
-#Example
-#Width 512
-void draw(SkCanvas* canvas) {
-    SkPaint paint;
-    paint.setAntiAlias(true);
-    paint.setTextSize(120);
-    SkPaint::FontMetrics fm;
-    SkScalar lineHeight = paint.getFontMetrics(&fm);
-    SkPoint pt = { 70, 180 };
-    canvas->drawString("M", pt.fX, pt.fY, paint);
-    canvas->drawLine(pt.fX, pt.fY, pt.fX, pt.fY + fm.fTop, paint);
-    SkScalar ascent = pt.fY + fm.fAscent;
-    canvas->drawLine(pt.fX - 25, ascent, pt.fX - 25, ascent + lineHeight, paint);
-    canvas->drawLine(pt.fX - 50, pt.fY, pt.fX - 50, pt.fY + fm.fDescent, paint);
-    canvas->drawLine(pt.fX + 100, pt.fY, pt.fX + 100, pt.fY + fm.fAscent, paint);
-    canvas->drawLine(pt.fX + 125, pt.fY, pt.fX + 125, pt.fY - fm.fXHeight, paint);
-    canvas->drawLine(pt.fX + 150, pt.fY, pt.fX + 150, pt.fY - fm.fCapHeight, paint);
-    canvas->drawLine(pt.fX + 5, pt.fY, pt.fX + 5, pt.fY + fm.fBottom, paint);
-    SkScalar xmin = pt.fX + fm.fXMin;
-    canvas->drawLine(xmin, pt.fY + 60, xmin + fm.fMaxCharWidth, pt.fY + 60, paint);
-    canvas->drawLine(xmin, pt.fY - 145, pt.fX, pt.fY - 145, paint);
-    canvas->drawLine(pt.fX + fm.fXMax, pt.fY - 160, pt.fX, pt.fY - 160, paint);
-    SkScalar upos = pt.fY + fm.fUnderlinePosition;
-    canvas->drawLine(pt.fX + 25, upos, pt.fX + 160, upos, paint);
-    SkScalar ut = fm.fUnderlineThickness;
-    canvas->drawLine(pt.fX + 130, upos + ut, pt.fX + 160, upos + ut, paint);
-    paint.setTextSize(12);
-    canvas->drawString("x-min",          pt.fX - 50, pt.fY - 148, paint);
-    canvas->drawString("x-max",          pt.fX + 140, pt.fY - 150, paint);
-    canvas->drawString("max char width", pt.fX + 120, pt.fY + 57, paint);
-    canvas->drawString("underline position", pt.fX + 30, pt.fY + 22, paint);
-    canvas->drawString("underline thickness", pt.fX + 162, pt.fY + 13, paint);
-    canvas->rotate(-90);
-    canvas->drawString("descent",     -pt.fY - 30, pt.fX - 54,  paint);
-    canvas->drawString("line height", -pt.fY,      pt.fX - 29,  paint);
-    canvas->drawString("top",         -pt.fY + 30, pt.fX - 4,   paint);
-    canvas->drawString("ascent",      -pt.fY,      pt.fX + 110, paint);
-    canvas->drawString("x-height",    -pt.fY,      pt.fX + 135, paint);
-    canvas->drawString("cap-height",  -pt.fY,      pt.fX + 160, paint);
-    canvas->drawString("bottom",      -pt.fY - 50, pt.fX + 15,  paint);
-}
-##
-
-#Struct FontMetrics
-#Line # values computed by Font_Manager using Typeface ##
-
-#Code
-#Populate
-##
-
-    FontMetrics is filled out by getFontMetrics. FontMetrics contents reflect the values
-    computed by Font_Manager using Typeface. Values are set to zero if they are
-    not available.
-
-    All vertical values are relative to the baseline, on a y-axis pointing down.
-    Zero is on the baseline, negative values are above the baseline, and positive
-    values are below the baseline.
-
-    fUnderlineThickness and fUnderlinePosition have a bit set in fFlags if their values
-    are valid, since their value may be zero.
-
-    fStrikeoutThickness and fStrikeoutPosition have a bit set in fFlags if their values
-    are valid, since their value may be zero.
-
-    #Enum FontMetricsFlags
-    #Line # valid Font_Metrics ##
-
-    #Code
-    #Populate
-    ##
-
-    FontMetricsFlags are set in fFlags when underline and strikeout metrics are valid;
-    the underline or strikeout metric may be valid and zero.
-    Fonts with embedded bitmaps may not have valid underline or strikeout metrics.
-
-        #Const kUnderlineThicknessIsValid_Flag 0x0001
-        #Line # set if fUnderlineThickness is valid ##
-        ##
-        #Const kUnderlinePositionIsValid_Flag  0x0002
-        #Line # set if fUnderlinePosition is valid ##
-        ##
-        #Const kStrikeoutThicknessIsValid_Flag 0x0004
-        #Line # set if fStrikeoutThickness is valid ##
-        ##
-        #Const kStrikeoutPositionIsValid_Flag  0x0008
-        #Line # set if fStrikeoutPosition is valid ##
-        ##
-
-    #Enum ##
-
-    #Member uint32_t    fFlags
-    #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
-    #Line # maximum character width ##
-    ##
-
-    #Member SkScalar    fXMin
-    #Line # minimum x ##
-        Minimum bounding box x-axis value for all Glyphs.
-        Typically less than zero.
-    ##
-
-    #Member SkScalar    fXMax
-    #Line # maximum x ##
-        Maximum bounding box x-axis value for all Glyphs.
-        Typically greater than zero.
-    ##
-
-    #Member SkScalar    fXHeight
-    #Line # height of lower-case 'x' ##
-        May be zero if no lower-case height is stored in the font.
-    ##
-
-    #Member SkScalar    fCapHeight
-    #Line # height of an upper-case letter ##
-        May be zero if no upper-case height is stored in the font.
-    ##
-
-    #Member SkScalar    fUnderlineThickness
-    #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.
-
-       If the metric is valid, the kUnderlinePositionIsValid_Flag is set in fFlags.
-       If kUnderlinePositionIsValid_Flag is clear, fUnderlinePosition is zero.
-    ##
-
-    #Member SkScalar    fStrikeoutThickness
-    #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.
-
-        If the metric is valid, the kStrikeoutPositionIsValid_Flag is set in fFlags.
-        If kStrikeoutPositionIsValid_Flag is clear, fStrikeoutPosition is zero.
-    ##
-
-    #Method bool hasUnderlineThickness(SkScalar* thickness) const
-    #Line # returns underline thickness if set ##
-#Populate
-
-#NoExample
-        ##
-    ##
-
-    #Method bool hasUnderlinePosition(SkScalar* position) const
-    #Line # returns underline position if set ##
-#Populate
-
-#NoExample
-        ##
-    ##
-
-    #Method bool hasStrikeoutThickness(SkScalar* thickness) const
-    #Line # returns strikeout thickness if set ##
-#Populate
-
-#NoExample
-        ##
-    ##
-
-    #Method bool hasStrikeoutPosition(SkScalar* position) const
-    #Line # returns strikeout position if set ##
-#Populate
-
-#NoExample
-        ##
-    ##
-
-#Struct ##
 
-#Method SkScalar getFontMetrics(FontMetrics* metrics) const
+#Method SkScalar getFontMetrics(SkFontMetrics* metrics) const
 
 #In Font_Metrics
 #Line # returns Typeface metrics scaled by text size ##
@@ -3521,7 +3293,7 @@ void draw(SkCanvas* canvas) {
 
 #Example
     SkPaint paint;
-    SkPaint::FontMetrics fm;
+    SkFontMetrics fm;
     paint.getFontMetrics(&fm);
     SkRect fb = paint.getFontBounds();
     SkDebugf("metrics bounds = { %g, %g, %g, %g }\n", fm.fXMin, fm.fTop, fm.fXMax, fm.fBottom );
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index 216373d212..1bb21e631e 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -354,6 +354,172 @@ FT_Load_Glyph
 #Const kFull_SkFontHinting 3
 ##
 ##
+#Struct SkFontMetrics
+#Line # values computed by Font_Manager using Typeface ##
+
+    SkFontMetrics is filled out by SkPaint::getFontMetrics. SkFontMetrics contents
+    reflect the values
+    computed by Font_Manager using Typeface. Values are set to zero if they are
+    not available.
+
+    All vertical values are relative to the baseline, on a y-axis pointing down.
+    Zero is on the baseline, negative values are above the baseline, and positive
+    values are below the baseline.
+
+    fUnderlineThickness and fUnderlinePosition have a bit set in fFlags if their values
+    are valid, since their value may be zero.
+
+    fStrikeoutThickness and fStrikeoutPosition have a bit set in fFlags if their values
+    are valid, since their value may be zero.
+
+    #Enum FontMetricsFlags
+    #Line # valid Font_Metrics ##
+
+    FontMetricsFlags are set in fFlags when underline and strikeout metrics are valid;
+    the underline or strikeout metric may be valid and zero.
+    Fonts with embedded bitmaps may not have valid underline or strikeout metrics.
+
+        #Const kUnderlineThicknessIsValid_Flag 0x0001
+        #Line # set if fUnderlineThickness is valid ##
+        ##
+        #Const kUnderlinePositionIsValid_Flag  0x0002
+        #Line # set if fUnderlinePosition is valid ##
+        ##
+        #Const kStrikeoutThicknessIsValid_Flag 0x0004
+        #Line # set if fStrikeoutThickness is valid ##
+        ##
+        #Const kStrikeoutPositionIsValid_Flag  0x0008
+        #Line # set if fStrikeoutPosition is valid ##
+        ##
+
+    #Enum ##
+
+    #Member uint32_t    fFlags
+    #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
+    #Line # maximum character width ##
+    ##
+
+    #Member SkScalar    fXMin
+    #Line # minimum x ##
+        Minimum bounding box x-axis value for all Glyphs.
+        Typically less than zero.
+    ##
+
+    #Member SkScalar    fXMax
+    #Line # maximum x ##
+        Maximum bounding box x-axis value for all Glyphs.
+        Typically greater than zero.
+    ##
+
+    #Member SkScalar    fXHeight
+    #Line # height of lower-case 'x' ##
+        May be zero if no lower-case height is stored in the font.
+    ##
+
+    #Member SkScalar    fCapHeight
+    #Line # height of an upper-case letter ##
+        May be zero if no upper-case height is stored in the font.
+    ##
+
+    #Member SkScalar    fUnderlineThickness
+    #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.
+
+       If the metric is valid, the kUnderlinePositionIsValid_Flag is set in fFlags.
+       If kUnderlinePositionIsValid_Flag is clear, fUnderlinePosition is zero.
+    ##
+
+    #Member SkScalar    fStrikeoutThickness
+    #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.
+
+        If the metric is valid, the kStrikeoutPositionIsValid_Flag is set in fFlags.
+        If kStrikeoutPositionIsValid_Flag is clear, fStrikeoutPosition is zero.
+    ##
+
+    #Method bool hasUnderlineThickness(SkScalar* thickness) const
+    #Line # returns underline thickness if set ##
+
+#NoExample
+        ##
+    ##
+
+    #Method bool hasUnderlinePosition(SkScalar* position) const
+    #Line # returns underline position if set ##
+
+#NoExample
+        ##
+    ##
+
+    #Method bool hasStrikeoutThickness(SkScalar* thickness) const
+    #Line # returns strikeout thickness if set ##
+
+#NoExample
+        ##
+    ##
+
+    #Method bool hasStrikeoutPosition(SkScalar* position) const
+    #Line # returns strikeout position if set ##
+
+#NoExample
+        ##
+    ##
+
+#Struct ##
 #Topic ##
 
 #Topic Font_Manager