self check and corrections

Add self-checking code that looks to see that overview is populated
and alphabetized. Eventually, this will self-check to see if
methods are collected into subtopics and have reciprocal 'see also'
data.

Standardize phrases so that they don't start with a capital or end
with a period.

Self-check is a work in progress, so it is not yet run by the
bookmaker bots. The self-check should run cleanly, however. To run
it:

./out/skia/bookmaker -b docs -k

The expected output is doc stats. Self-check errors such as missing
methods in the overview would be reported here if there are any.

TBR=caryclark@google.com
Docs-Preview: https://skia.org/?cl=93621
Bug: skia:6898
Change-Id: I8f1f817a7b083b13138ee33d1aa090445e9304c6
Reviewed-on: https://skia-review.googlesource.com/93621
Reviewed-by: Cary Clark <caryclark@skia.org>
Commit-Queue: Cary Clark <caryclark@skia.org>

1 files changed, 178 insertions, 166 deletions

diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 31031e76fa..801df43109 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -32,208 +32,220 @@ Shader attached to Paint.
 #Topic Overview
 
 #Subtopic Subtopics
-#ToDo not all methods are in topics ##
-#ToDo subtopics are not in topics ##
 #Table
 #Legend
-# topics                 # description                                 ##
+# name                   # description                                 ##
 #Legend ##
-# Initializers           # Constructors and initialization.            ##
-# Destructor             # Paint termination.                          ##
-# Management             # Paint copying, moving, comparing.           ##
-# Hinting                # Glyph outline adjustment.                   ##
-# Flags                  # Attributes represented by single bits.      ##
-# Anti-alias             # Approximating coverage with transparency.   ##
-# Dither                 # Distributing color error.                   ##
-# Device_Text            # Increase precision of glyph position.       ##
-# Font_Embedded_Bitmaps  # Custom sized bitmap Glyphs.                 ##
-# Automatic_Hinting      # Always adjust glyph paths.                  ##
-# Vertical_Text          # Orient text from top to bottom.             ##
-# Fake_Bold              # Approximate font styles.                    ##
-# Full_Hinting_Spacing   # Glyph spacing affected by hinting.          ##
-# Filter_Quality_Methods # Get and set Filter_Quality.                 ##
-# Color_Methods          # Get and set Color.                          ##
-# Style                  # Geometry filling, stroking.                 ##
-# Stroke_Width           # Thickness perpendicular to geometry.        ##
-# Miter_Limit            # Maximum length of stroked corners.          ##
-# Stroke_Cap             # Decorations at ends of open strokes.        ##
-# Stroke_Join            # Decoration at corners of strokes.           ##
-# Fill_Path              # Make Path from Path_Effect, stroking.       ##
-# Shader_Methods         # Get and set Shader.                         ##
-# Color_Filter_Methods   # Get and set Color_Filter.                   ##
-# Blend_Mode_Methods     # Get and set Blend_Mode.                     ##
-# Path_Effect_Methods    # Get and set Path_Effect.                    ##
-# Mask_Filter_Methods    # Get and set Mask_Filter.                    ##
-# Typeface_Methods       # Get and set Typeface.                       ##
-# Image_Filter_Methods   # Get and set Image_Filter.                   ##
-# Draw_Looper_Methods    # Get and set Draw_Looper.                    ##
-# Text_Align             # Text placement relative to position.        ##
-# Text_Size              # Overall height in points.                   ##
-# Text_Scale_X           # Text horizontal scale.                      ##
-# Text_Skew_X            # Text horizontal slant.                      ##
-# Text_Encoding          # Text encoded as characters or Glyphs.       ##
-# Font_Metrics           # Common glyph dimensions.                    ##
-# Measure_Text           # Width, height, bounds of text.              ##
-# Text_Path              # Geometry of Glyphs.                         ##
-# Text_Intercepts        # Advanced underline, strike through.         ##
-# Fast_Bounds            # Approximate area required by Paint.         ##
+# Classes_and_Structs    # embedded struct and class members           ##
+# Constants              # enum and enum class, const values           ##
+# Constructors           # list of functions that construct SkPath     ##
+# Member_Functions       # list of static functions and member methods ##
+# Operators              # operator overloading methods                ##
+# Related_Functions      # similar methods grouped together            ##
+#Table ##
+#Subtopic ##
+
+#Subtopic Related_Functions
+#Table
+#Legend
+# name                   # description                                ##
+#Legend ##
+# Anti-alias             # approximating coverage with transparency   ##
+# Automatic_Hinting      # always adjust glyph paths                  ##
+# Blend_Mode_Methods     # get and set Blend_Mode                     ##
+# Color_Filter_Methods   # get and set Color_Filter                   ##
+# Color_Methods          # get and set Color                          ##
+# Destructor             # paint termination                          ##
+# Device_Text            # increase precision of glyph position       ##
+# Dither                 # distributing color error                   ##
+# Draw_Looper_Methods    # get and set Draw_Looper                    ##
+# Fake_Bold              # approximate font styles                    ##
+# Fast_Bounds            # approximate area required by Paint         ##
+# Fill_Path              # make Path from Path_Effect, stroking       ##
+# Filter_Quality_Methods # get and set Filter_Quality                 ##
+# Flags                  # attributes represented by single bits      ##
+# Font_Embedded_Bitmaps  # custom sized bitmap Glyphs                 ##
+# Font_Metrics           # common glyph dimensions                    ##
+# Full_Hinting_Spacing   # glyph spacing affected by hinting          ##
+# Hinting                # glyph outline adjustment                   ##
+# Image_Filter_Methods   # get and set Image_Filter                   ##
+# Initializers           # constructors and initialization            ##
+# Management             # paint copying, moving, comparing           ##
+# Mask_Filter_Methods    # get and set Mask_Filter                    ##
+# Measure_Text           # width, height, bounds of text              ##
+# Miter_Limit            # maximum length of stroked corners          ##
+# Path_Effect_Methods    # get and set Path_Effect                    ##
+# Shader_Methods         # get and set Shader                         ##
+# Stroke_Cap             # decorations at ends of open strokes        ##
+# Stroke_Join            # decoration at corners of strokes           ##
+# Stroke_Width           # thickness perpendicular to geometry        ##
+# Style                  # geometry filling, stroking                 ##
+# Text_Align             # text placement relative to position        ##
+# Text_Encoding          # text encoded as characters or Glyphs       ##
+# Text_Intercepts        # advanced underline, strike through         ##
+# Text_Path              # geometry of Glyphs                         ##
+# Text_Scale_X           # text horizontal scale                      ##
+# Text_Size              # overall height in points                   ##
+# Text_Skew_X            # text horizontal slant                      ##
+# Typeface_Methods       # get and set Typeface                       ##
+# Vertical_Text          # orient text from top to bottom             ##
 #Table ##
 #Subtopic ##
 
 #Subtopic Constants
 #Table
 #Legend
-# constants                      # description                                 ##
+# name                           # description                                 ##
 #Legend ##
-# Align                          # Glyph locations relative to text position.  ##
-# Cap                            # Start and end geometry on stroked shapes.   ##
-# Flags                          # Values described by bits and masks.         ##
-# FontMetrics::FontMetricsFlags  # Valid Font_Metrics.                         ##
-# Hinting                        # Level of glyph outline adjustment.          ##
-# Join                           # Corner geometry on stroked shapes.          ##
-# Style                          # Stroke, fill, or both.                      ##
-# TextEncoding                   # Character or glyph encoded size.            ##
+# Align                          # glyph locations relative to text position  ##
+# Cap                            # start and end geometry on stroked shapes   ##
+# Flags                          # values described by bits and masks         ##
+# FontMetrics::FontMetricsFlags  # valid Font_Metrics                         ##
+# Hinting                        # level of glyph outline adjustment          ##
+# Join                           # corner geometry on stroked shapes          ##
+# Style                          # stroke, fill, or both                      ##
+# TextEncoding                   # character or glyph encoded size            ##
 #Table ##
 #Subtopic ##
 
-#Subtopic Structs
+#Subtopic Classes_and_Structs
 #Table
 #Legend
-# struct                         # description                                 ##
+# name                           # description                                ##
 #Legend ##
-# FontMetrics                    # Typeface values.                            ##
+# FontMetrics                    # typeface values                            ##
 #Table ##
 #Subtopic ##
 
 #Subtopic Constructors
 #Table
 #Legend
-#                                # description                                 ##
+# name                           # description                                ##
 #Legend ##
-# SkPaint()                      # Constructs with default values.             ##
-# SkPaint(const SkPaint& paint)  # Makes a shallow copy.                       ##
-# SkPaint(SkPaint&& paint)       # Moves paint without copying it.             ##
-# ~SkPaint()                     # Decreases Reference_Count of owned objects. ##
+# SkPaint()                      # constructs with default values             ##
+# SkPaint(SkPaint&& paint)       # moves paint without copying it             ##
+# SkPaint(const SkPaint& paint)  # makes a shallow copy                       ##
+# ~SkPaint()                     # decreases Reference_Count of owned objects ##
 #Table ##
 #Subtopic ##
 
 #Subtopic Operators
 #Table
 #Legend
-# operator                                       # description                      ##
+# name                                          # description                      ##
 #Legend ##
-# operator=(const SkPaint& paint)                # Makes a shallow copy.            ##
-# operator=(SkPaint&& paint)                     # Moves paint without copying it.  ##
-# operator==(const SkPaint& a, const SkPaint& b) # Compares paints for equality.    ##
-# operator!=(const SkPaint& a, const SkPaint& b) # Compares paints for inequality.  ##
+# operator!=(const SkPaint& a, const SkPaint& b) # compares paints for inequality  ##
+# operator=(SkPaint&& paint)                     # moves paint without copying it  ##
+# operator=(const SkPaint& paint)                # makes a shallow copy            ##
+# operator==(const SkPaint& a, const SkPaint& b) # compares paints for equality    ##
 #Table ##
 #Subtopic ##
 
 #Subtopic Member_Functions
 #Table
 #Legend
-# function              # description                                           ##
+# name                  # description                                          ##
 #Legend ##
-# breakText             # Returns text that fits in a width.                    ##
-# canComputeFastBounds  # Returns true if settings allow for fast bounds computation. ##
-# computeFastBounds     # Returns fill bounds for quick reject tests.           ##
-# computeFastStrokeBounds # Returns stroke bounds for quick reject tests.       ##
-# containsText          # Returns if all text corresponds to Glyphs.            ##
-# countText             # Returns number of Glyphs in text.                     ##
-# doComputeFastBounds   # Returns bounds for quick reject tests.                ##
-# flatten()             # Serializes into a buffer.                             ##
-# getAlpha              # Returns Color_Alpha, color opacity.                   ##
-# getBlendMode          # Returns Blend_Mode, how colors combine with Device.   ##
-# getColor              # Returns Color_Alpha and Color_RGB, one drawing color. ##
-# getColorFilter        # Returns Color_Filter, how colors are altered.         ##
-# getDrawLooper         # Returns Draw_Looper, multiple layers.                 ##
-# getFillPath           # Returns fill path equivalent to stroke.               ##
-# getFilterQuality      # Returns Filter_Quality, image filtering level.        ##
-# getFlags              # Returns Flags stored in a bit field.                  ##
-# getFontBounds         # Returns union all glyph bounds.                       ##
-# getFontMetrics        # Returns Typeface metrics scaled by text size.         ##
-# getFontSpacing        # Returns recommended spacing between lines.            ##
-# getHash               # Returns a shallow hash for equality checks.           ##
-# getHinting            # Returns Hinting, glyph outline adjustment level.      ##
-# getImageFilter        # Returns Image_Filter, alter pixels; blur.             ##
-# getMaskFilter         # Returns Mask_Filter, alterations to Mask_Alpha.       ##
-# getPathEffect         # Returns Path_Effect, modifications to path geometry; dashing. ##
-# getPosTextPath        # Returns Path equivalent to positioned text.           ##
-# getPosTextIntercepts  # Returns where lines intersect positioned text; underlines. ##
-# getPosTextHIntercepts # Returns where lines intersect horizontally positioned text; underlines. ##
-# getShader             # Returns Shader, multiple drawing colors; gradients.   ##
-# getStrokeCap          # Returns Cap, the area drawn at path ends.             ##
-# getStrokeJoin         # Returns Join, geometry on path corners.               ##
-# getStrokeMiter        # Returns Miter_Limit, angles with sharp corners.       ##
-# getStrokeWidth        # Returns thickness of the stroke.                      ##
-# getStyle              # Returns Style: stroke, fill, or both.                 ##
-# getTextAlign          # Returns Align: left, center, or right.                ##
-# getTextBlobIntercepts # Returns where lines intersect Text_Blob; underlines.  ##
-# getTextEncoding       # Returns character or glyph encoded size.    b         ##
-# getTextIntercepts     # Returns where lines intersect text; underlines.       ##
-# getTextPath           # Returns Path equivalent to text.                      ##
-# getTextScaleX         # Returns the text horizontal scale; condensed text.    ##
-# getTextSkewX          # Returns the text horizontal skew; oblique text.       ##
-# getTextSize           # Returns text size in points.                          ##
-# getTextWidths         # Returns advance and bounds for each glyph in text.    ##
-# getTypeface           # Returns Typeface, font description.                   ##
-# glyphsToUnichars      # Converts Glyphs into text.                            ##
-# isAntiAlias           # Returns true if Anti-alias is set.                    ##
-# isAutohinted          # Returns true if Glyphs are always hinted.             ##
-# isDevKernText         # Returns true if Full_Hinting_Spacing is set.          ##
-# isDither              # Returns true if Dither is set.                        ##
-# isEmbeddedBitmapText  # Returns true if Font_Embedded_Bitmaps is set.         ##
-# isFakeBoldText        # Returns true if Fake_Bold is set.                     ##
-# isLCDRenderText       # Returns true if LCD_Text is set.                      ##
-# isSrcOver             # Returns true if Blend_Mode is SkBlendMode::kSrcOver.   ##
-# isSubpixelText        # Returns true if Subpixel_Text is set.                 ##
-# isVerticalText        # Returns true if Vertical_Text is set.                 ##
-# measureText           # Returns advance width and bounds of text.             ##
-# nothingToDraw         # Returns true if Paint prevents all drawing.           ##
-# refColorFilter        # References Color_Filter, how colors are altered.      ##
-# refDrawLooper         # References Draw_Looper, multiple layers.              ##
-# refImageFilter        # References Image_Filter, alter pixels; blur.          ##
-# refMaskFilter         # References Mask_Filter, alterations to Mask_Alpha.    ##
-# refPathEffect         # References Path_Effect, modifications to path geometry; dashing. ##
-# refShader             # References Shader, multiple drawing colors; gradients. ##
-# refTypeface           # References Typeface, font description.                ##
-# reset()               # Sets to default values.                               ##
-# setAlpha              # Sets Color_Alpha, color opacity.                      ##
-# setAntiAlias          # Sets or clears Anti-alias.                            ##
-# setARGB               # Sets color by component.                              ##
-# setAutohinted         # Sets Glyphs to always be hinted.                      ##
-# setBlendMode          # Sets Blend_Mode, how colors combine with destination. ##
-# setColor              # Sets Color_Alpha and Color_RGB, one drawing color.    ##
-# setColorFilter        # Sets Color_Filter, alters color.                      ##
-# setDevKernText        # Sets or clears Full_Hinting_Spacing.                  ##
-# setDither             # Sets or clears Dither.                                ##
-# setDrawLooper         # Sets Draw_Looper, multiple layers.                    ##
-# setEmbeddedBitmapText # Sets or clears Font_Embedded_Bitmaps.                 ##
-# setFakeBoldText       # Sets or clears Fake_Bold.                             ##
-# setFilterQuality      # Sets Filter_Quality, the image filtering level.       ##
-# setFlags              # Sets multiple Flags in a bit field.                   ##
-# setHinting            # Sets Hinting, glyph outline adjustment level.         ##
-# setLCDRenderText      # Sets or clears LCD_Text.                              ##
-# setMaskFilter         # Sets Mask_Filter, alterations to Mask_Alpha.          ##
-# setPathEffect         # Sets Path_Effect, modifications to path geometry; dashing. ##
-# setImageFilter        # Sets Image_Filter, alter pixels; blur.                ##
-# setShader             # Sets Shader, multiple drawing colors; gradients.      ##  
-# setStrokeCap          # Sets Cap, the area drawn at path ends.                ##
-# setStrokeJoin         # Sets Join, geometry on path corners.                  ##
-# setStrokeMiter        # Sets Miter_Limit, angles with sharp corners.          ##
-# setStrokeWidth        # Sets thickness of the stroke.                         ##
-# setStyle              # Sets Style: stroke, fill, or both.                    ##
-# setSubpixelText       # Sets or clears Subpixel_Text.                         ##
-# setTextAlign          # Sets Align: left, center, or right.                   ##
-# setTextEncoding       # Sets character or glyph encoded size.                 ##
-# setTextScaleX         # Sets the text horizontal scale; condensed text.       ##
-# setTextSkewX          # Sets the text horizontal skew; oblique text.          ##
-# setTextSize           # Sets text size in points.                             ##
-# setTypeface           # Sets Typeface, font description.                      ##
-# setVerticalText       # Sets or clears Vertical_Text.                         ##
-# textToGlyphs          # Converts text into glyph indices.                     ##
-# toString              # Converts Paint to machine readable form.              ##
-# unflatten()           # Populates from a serialized stream.                   ##
+# breakText             # returns text that fits in a width                    ##
+# canComputeFastBounds  # returns true if settings allow for fast bounds computation ##
+# computeFastBounds     # returns fill bounds for quick reject tests           ##
+# computeFastStrokeBounds # returns stroke bounds for quick reject tests       ##
+# containsText          # returns if all text corresponds to Glyphs            ##
+# countText             # returns number of Glyphs in text                     ##
+# doComputeFastBounds   # returns bounds for quick reject tests                ##
+# flatten()             # serializes into a buffer                             ##
+# getAlpha              # returns Color_Alpha, color opacity                   ##
+# getBlendMode          # returns Blend_Mode, how colors combine with Device   ##
+# getColor              # returns Color_Alpha and Color_RGB, one drawing color ##
+# getColorFilter        # returns Color_Filter, how colors are altered         ##
+# getDrawLooper         # returns Draw_Looper, multiple layers                 ##
+# getFillPath           # returns fill path equivalent to stroke               ##
+# getFilterQuality      # returns Filter_Quality, image filtering level        ##
+# getFlags              # returns Flags stored in a bit field                  ##
+# getFontBounds         # returns union all glyph bounds                       ##
+# getFontMetrics        # returns Typeface metrics scaled by text size         ##
+# getFontSpacing        # returns recommended spacing between lines            ##
+# getHash               # returns a shallow hash for equality checks           ##
+# getHinting            # returns Hinting, glyph outline adjustment level      ##
+# getImageFilter        # returns Image_Filter, alter pixels; blur             ##
+# getMaskFilter         # returns Mask_Filter, alterations to Mask_Alpha       ##
+# getPathEffect         # returns Path_Effect, modifications to path geometry; dashing ##
+# getPosTextHIntercepts # returns where lines intersect horizontally positioned text; underlines ##
+# getPosTextIntercepts  # returns where lines intersect positioned text; underlines ##
+# getPosTextPath        # returns Path equivalent to positioned text           ##
+# getShader             # returns Shader, multiple drawing colors; gradients   ##
+# getStrokeCap          # returns Cap, the area drawn at path ends             ##
+# getStrokeJoin         # returns Join, geometry on path corners               ##
+# getStrokeMiter        # returns Miter_Limit, angles with sharp corners       ##
+# getStrokeWidth        # returns thickness of the stroke                      ##
+# getStyle              # returns Style: stroke, fill, or both                 ##
+# getTextAlign          # returns Align: left, center, or right                ##
+# getTextBlobIntercepts # returns where lines intersect Text_Blob; underlines  ##
+# getTextEncoding       # returns character or glyph encoded size              ##
+# getTextIntercepts     # returns where lines intersect text; underlines       ##
+# getTextPath           # returns Path equivalent to text                      ##
+# getTextScaleX         # returns the text horizontal scale; condensed text    ##
+# getTextSize           # returns text size in points                          ##
+# getTextSkewX          # returns the text horizontal skew; oblique text       ##
+# getTextWidths         # returns advance and bounds for each glyph in text    ##
+# getTypeface           # returns Typeface, font description                   ##
+# glyphsToUnichars      # converts Glyphs into text                            ##
+# isAntiAlias           # returns true if Anti-alias is set                    ##
+# isAutohinted          # returns true if Glyphs are always hinted             ##
+# isDevKernText         # returns true if Full_Hinting_Spacing is set          ##
+# isDither              # returns true if Dither is set                        ##
+# isEmbeddedBitmapText  # returns true if Font_Embedded_Bitmaps is set         ##
+# isFakeBoldText        # returns true if Fake_Bold is set                     ##
+# isLCDRenderText       # returns true if LCD_Text is set                      ##
+# isSrcOver             # returns true if Blend_Mode is SkBlendMode::kSrcOver   ##
+# isSubpixelText        # returns true if Subpixel_Text is set                 ##
+# isVerticalText        # returns true if Vertical_Text is set                 ##
+# measureText           # returns advance width and bounds of text             ##
+# nothingToDraw         # returns true if Paint prevents all drawing           ##
+# refColorFilter        # references Color_Filter, how colors are altered      ##
+# refDrawLooper         # references Draw_Looper, multiple layers              ##
+# refImageFilter        # references Image_Filter, alter pixels; blur          ##
+# refMaskFilter         # references Mask_Filter, alterations to Mask_Alpha    ##
+# refPathEffect         # references Path_Effect, modifications to path geometry; dashing ##
+# refShader             # references Shader, multiple drawing colors; gradients ##
+# refTypeface           # references Typeface, font description                ##
+# reset()               # sets to default values                               ##
+# setARGB               # sets color by component                              ##
+# setAlpha              # sets Color_Alpha, color opacity                      ##
+# setAntiAlias          # sets or clears Anti-alias                            ##
+# setAutohinted         # sets Glyphs to always be hinted                      ##
+# setBlendMode          # sets Blend_Mode, how colors combine with destination ##
+# setColor              # sets Color_Alpha and Color_RGB, one drawing color    ##
+# setColorFilter        # sets Color_Filter, alters color                      ##
+# setDevKernText        # sets or clears Full_Hinting_Spacing                  ##
+# setDither             # sets or clears Dither                                ##
+# setDrawLooper         # sets Draw_Looper, multiple layers                    ##
+# setEmbeddedBitmapText # sets or clears Font_Embedded_Bitmaps                 ##
+# setFakeBoldText       # sets or clears Fake_Bold                             ##
+# setFilterQuality      # sets Filter_Quality, the image filtering level       ##
+# setFlags              # sets multiple Flags in a bit field                   ##
+# setHinting            # sets Hinting, glyph outline adjustment level         ##
+# setImageFilter        # sets Image_Filter, alter pixels; blur                ##
+# setLCDRenderText      # sets or clears LCD_Text                              ##
+# setMaskFilter         # sets Mask_Filter, alterations to Mask_Alpha          ##
+# setPathEffect         # sets Path_Effect, modifications to path geometry; dashing ##
+# setShader             # sets Shader, multiple drawing colors; gradients      ##
+# setStrokeCap          # sets Cap, the area drawn at path ends                ##
+# setStrokeJoin         # sets Join, geometry on path corners                  ##
+# setStrokeMiter        # sets Miter_Limit, angles with sharp corners          ##
+# setStrokeWidth        # sets thickness of the stroke                         ##
+# setStyle              # sets Style: stroke, fill, or both                    ##
+# setSubpixelText       # sets or clears Subpixel_Text                         ##
+# setTextAlign          # sets Align: left, center, or right                   ##
+# setTextEncoding       # sets character or glyph encoded size                 ##
+# setTextScaleX         # sets the text horizontal scale; condensed text       ##
+# setTextSize           # sets text size in points                             ##
+# setTextSkewX          # sets the text horizontal skew; oblique text          ##
+# setTypeface           # sets Typeface, font description                      ##
+# setVerticalText       # sets or clears Vertical_Text                         ##
+# textToGlyphs          # converts text into glyph indices                     ##
+# toString              # converts Paint to machine readable form              ##
+# unflatten()           # populates from a serialized stream                   ##
 #Table ##
 #Subtopic ##
 
@@ -582,7 +594,7 @@ by the client.
 
 #Param buffer  serialized data describing Paint content ##
 
-#Return false if the buffer contained invalid data for initializing the paint. ##
+#Return false if the buffer contains invalid data ##
 
 # why is unflatten() public? 
 #Bug 6172 ##