generate include comments

- formalize how aliases and substitutions work together
- add constexpr, #define, typedef support
- check for correct description order
- write short enum, struct members

R=caryclark@google.com

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

16 files changed, 161 insertions, 125 deletions

diff --git a/docs/SkBitmap_Reference.bmh b/docs/SkBitmap_Reference.bmh
index 967b9d1ca9..8f241e3f85 100644
--- a/docs/SkBitmap_Reference.bmh
+++ b/docs/SkBitmap_Reference.bmh
@@ -1,6 +1,6 @@
 #Topic Bitmap
-#Alias Bitmaps
-#Alias Bitmap_Reference
+#Alias Bitmaps ##
+#Alias Bitmap_Reference ##
 
 #Class SkBitmap
 
@@ -11,7 +11,7 @@ Bitmap points to Pixel_Ref, which describes the physical array of pixels.
 Image_Info bounds may be located anywhere fully inside Pixel_Ref bounds.
 
 Bitmap can be drawn using Canvas. Bitmap can be a drawing destination for Canvas
-draw member functionss. Bitmap flexibility as a pixel container limits some
+draw member functions. Bitmap flexibility as a pixel container limits some
 optimizations available to the target platform.
 
 If pixel array is primarily read-only, use Image for better performance.
diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh
index 2990a8c48c..ddf081cb1f 100644
--- a/docs/SkCanvas_Reference.bmh
+++ b/docs/SkCanvas_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Canvas
-#Alias Canvas_Reference
+#Alias Canvas_Reference ##
 
 #Class SkCanvas
 
@@ -1463,6 +1463,8 @@ depth = 1
 #Subtopic Layer
 #Substitute layer
 #Alias Layers
+#Substitute layers
+##
 #Line # temporary Bitmap to draw into ##
 
 Layer allocates a temporary Bitmap to draw into. When the drawing is
@@ -1691,13 +1693,12 @@ Call restoreToCount with returned value to restore this and subsequent saves.
 
 #Typedef uint32_t SaveLayerFlags
 #Line # options for SaveLayerRec ##
+##
 
 SaveLayerFlags provides options that may be used in any combination in SaveLayerRec,
 defining how Layer allocated by saveLayer operates. It may be set to zero,
 kPreserveLCDText_SaveLayerFlag, kInitWithPrevious_SaveLayerFlag, or both flags.
 
-##
-
 #Const kPreserveLCDText_SaveLayerFlag 2
 #Line # creates Layer for LCD text ##
   Creates Layer for LCD text. Flag is ignored if Layer Paint contains
@@ -1751,8 +1752,6 @@ void draw(SkCanvas* canvas) {
 #Struct SaveLayerRec
 #Line # contains the state used to create the Layer ##
 
-SaveLayerRec contains the state used to create the Layer.
-
 #Code
     struct SaveLayerRec {
         SaveLayerRec*(...
@@ -1764,6 +1763,8 @@ SaveLayerRec contains the state used to create the Layer.
     };
 ##
 
+SaveLayerRec contains the state used to create the Layer.
+
 #Subtopic Overview
 #Populate
 ##
@@ -2502,7 +2503,7 @@ The clip restriction is not recorded in pictures.
 Pass an empty rect to disable maximum clip.
 
 #Private
-This is private API to be used only by Android framework.
+This private API is for use by Android framework only.
 ##
 
 #Param  rect   maximum allowed clip in device coordinates
@@ -4401,9 +4402,7 @@ are larger than dst; center and four sides are scaled to fit remaining space, if
 
 Additionally transform draw using Clip, Matrix, and optional Paint paint.
 
-If Paint paint is supplied, apply Color_Filter, Color_Alpha, Image_Filter,
-Blend_Mode, and Draw_Looper. If image is kAlpha_8_SkColorType, apply Shader.
-If paint contains Mask_Filter, generate mask from image bounds.
+#paint_as_used_by_draw_lattice_or_draw_nine(image)#
 
 If generated mask extends beyond image bounds, replicate image edge colors, just
 as Shader made from SkImage::makeShader with SkShader::kClamp_TileMode set
@@ -4690,7 +4689,7 @@ Blend_Mode, and Draw_Looper. If #bitmap_or_image# is kAlpha_8_SkColorType, apply
 If paint contains Mask_Filter, generate mask from #bitmap_or_image# bounds. If paint
 Filter_Quality set to kNone_SkFilterQuality, disable pixel filtering. For all
 other values of paint Filter_Quality, use kLow_SkFilterQuality to filter pixels.
-Any SkMaskFilter on the paint is ignored as is the paint's antialiasing state.
+Any SkMaskFilter on paint is ignored as is paint Anti_Aliasing state.
 ##
 
 #Method void drawBitmapNine(const SkBitmap& bitmap, const SkIRect& center, const SkRect& dst,
@@ -4767,14 +4766,6 @@ void draw(SkCanvas* canvas) {
 #Struct Lattice
 #Line # divides Bitmap or Image into a rectangular grid ##
 
-Lattice divides Bitmap or Image into a rectangular grid.
-Grid entries on even columns and even rows are fixed; these entries are
-always drawn at their original size if the destination is large enough.
-If the destination side is too small to hold the fixed entries, all fixed
-entries are proportionately scaled down to fit.
-The grid entries not on even columns and rows are scaled to fit the
-remaining space, if any.
-
 #Code
     struct Lattice {
         enum RectType ...
@@ -4789,6 +4780,14 @@ remaining space, if any.
     };
 ##
 
+Lattice divides Bitmap or Image into a rectangular grid.
+Grid entries on even columns and even rows are fixed; these entries are
+always drawn at their original size if the destination is large enough.
+If the destination side is too small to hold the fixed entries, all fixed
+entries are proportionately scaled down to fit.
+The grid entries not on even columns and rows are scaled to fit the
+remaining space, if any.
+
 #Subtopic Overview
 #Populate
 ##
@@ -5192,7 +5191,7 @@ Paint paint. The number of entries in pos array must match the number of Glyphs
 described by byteLength of text.
 
 text meaning depends on Paint_Text_Encoding; by default, text is encoded as
-UTF-8. pos elements' meaning depends on Paint_Text_Align and Paint_Vertical_Text;
+UTF-8. pos elements meaning depends on Paint_Vertical_Text;
 by default each glyph left side bearing is positioned at x and its
 baseline is positioned at y. Text size is affected by Matrix and
 Paint_Text_Size.
@@ -5238,7 +5237,7 @@ constY, using Clip, Matrix, and Paint paint. The number of entries in xpos array
 must match the number of Glyphs described by byteLength of text.
 
 text meaning depends on Paint_Text_Encoding; by default, text is encoded as
-UTF-8. xpos elements' meaning depends on Paint_Text_Align and Paint_Vertical_Text;
+UTF-8. xpos elements meaning depends on Paint_Vertical_Text;
 by default each glyph left side bearing is positioned at an xpos element and
 its baseline is positioned at constY. Text size is affected by Matrix and
 Paint_Text_Size.
@@ -5332,21 +5331,22 @@ filled 12 point black Glyphs.
 Draw text on Path path, using Clip, Matrix, and Paint paint.
 
 Origin of text is at beginning of path offset by matrix, if not nullptr.
-matrix also transforms text before text is mapped to path. If the path section
+matrix transforms text before text is mapped to path. If the path section
 corresponding the glyph advance is curved, the glyph is drawn curved to match;
 control points in the glyph are mapped to projected points parallel to the path.
 If the text advance is larger than the path length, the excess text is clipped.
 
+matrix does not effect paint Shader.
+
 text meaning depends on Paint_Text_Encoding; by default, text is encoded as
 UTF-8. Origin meaning depends on Paint_Text_Align and Paint_Vertical_Text; by
 default text positions the first glyph left side bearing at origin x and its
-baseline at origin y. Text size is affected by matrix parameter, Canvas_Matrix,
+baseline at origin y. Text size is affected by matrix parameter, Canvas Matrix,
 and Paint_Text_Size.
 
 All elements of paint: Path_Effect, Mask_Filter, Shader,
 Color_Filter, Image_Filter, and Draw_Looper; apply to text. By default, draws
-filled 12 point black Glyphs. Canvas Matrix does effect paint Shader, but
-matrix parameter does not.
+filled 12 point black Glyphs.
 
 #Param  text         character code points or Glyphs drawn ##
 #Param  byteLength   byte length of text array ##
@@ -5391,8 +5391,8 @@ matrix parameter does not.
 Draw text, transforming each glyph by the corresponding SkRSXform,
 using Clip, Matrix, and Paint paint.
 
-RSXform array specifies a separate square scale, rotation, and translation for
-each glyph.
+RSXform xform array specifies a separate square scale, rotation, and translation
+for each glyph. xform does not affect paint Shader.
 
 Optional Rect cullRect is a conservative bounds of text, taking into account
 RSXform and paint. If cullRect is outside of Clip, canvas can skip drawing.
diff --git a/docs/SkColor4f_Reference.bmh b/docs/SkColor4f_Reference.bmh
index a2c3b0ea2d..a23431e827 100644
--- a/docs/SkColor4f_Reference.bmh
+++ b/docs/SkColor4f_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Color4f
-#Alias Color4f_Reference
+#Alias Color4f_Reference ##
 
 #Struct SkColor4f
 
diff --git a/docs/SkColor_Reference.bmh b/docs/SkColor_Reference.bmh
index 67a47a297e..50b4eb5590 100644
--- a/docs/SkColor_Reference.bmh
+++ b/docs/SkColor_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Color
-#Alias Color_Reference
+#Alias Color_Reference ##
 
 #Subtopic Overview
 #Populate
@@ -36,7 +36,9 @@ floating point values. Unsigned integer Alpha ranges from zero, fully
 transparent, to all bits set, fully opaque. Floating point Alpha ranges from
 zero, fully transparent, to one, fully opaque.
 
-#Alias Alpha
+#Alias Alpha 
+#Substitute alpha
+##
 
 #Typedef uint8_t SkAlpha
 #Line # defines Alpha as eight bits ##
diff --git a/docs/SkIPoint_Reference.bmh b/docs/SkIPoint_Reference.bmh
index 61c7394aeb..2ed3b7b80c 100644
--- a/docs/SkIPoint_Reference.bmh
+++ b/docs/SkIPoint_Reference.bmh
@@ -1,6 +1,6 @@
 #Topic IPoint
-#Alias IPoints
-#Alias IPoint_Reference
+#Alias IPoints ##
+#Alias IPoint_Reference ##
 
 #Struct SkIPoint
 
@@ -454,15 +454,15 @@ Can also be used to add IVector to IVector, returning IVector.
 
 #Subtopic IVector
 #Line # alias for IPoint ##
-    #Alias IVector
-    #Alias IVectors
+    #Alias IVector ##
+    #Alias IVectors ##
     #Typedef SkIPoint SkIVector
     #Line # alias for IPoint ##
     #Code
     typedef SkIPoint SkIVector;
     ##
     SkIVector provides an alternative name for SkIPoint. SkIVector and SkIPoint
-    can be used interchangably for all purposes.
+    can be used interchangeably for all purposes.
     #Typedef ##
 ##
 
diff --git a/docs/SkIRect_Reference.bmh b/docs/SkIRect_Reference.bmh
index db8d4ad501..f3c269b294 100644
--- a/docs/SkIRect_Reference.bmh
+++ b/docs/SkIRect_Reference.bmh
@@ -1,6 +1,6 @@
 #Topic IRect
-#Alias IRects
-#Alias IRect_Reference
+#Alias IRects ##
+#Alias IRect_Reference ##
 
 #Struct SkIRect
 
diff --git a/docs/SkImageInfo_Reference.bmh b/docs/SkImageInfo_Reference.bmh
index 963bcd4181..02bdaf0c28 100644
--- a/docs/SkImageInfo_Reference.bmh
+++ b/docs/SkImageInfo_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Image_Info
-#Alias Image_Info_Reference
+#Alias Image_Info_Reference ##
 
 Image_Info specifies the dimensions and encoding of the pixels in a Bitmap.
 The dimensions are integral width and height. The encoding is how pixel
@@ -22,8 +22,8 @@ but Image and Surface may not contain Image_Info.
 # ------------------------------------------------------------------------------
 #Subtopic Alpha_Type
 #Line # encoding for pixel transparency ##
-#Alias Alpha_Type
-#Alias Alpha_Types
+#Alias Alpha_Type ##
+#Alias Alpha_Types ##
 
 #PhraseDef list_of_alpha_types
 kUnknown_SkAlphaType, kOpaque_SkAlphaType, kPremul_SkAlphaType,
@@ -224,8 +224,8 @@ opaque, then the result of drawing any pixel with a Color_Alpha value less than
 # ------------------------------------------------------------------------------
 #Subtopic Color_Type
 #Line # encoding for pixel color ##
-#Alias Color_Type
-#Alias Color_Types
+#Alias Color_Type ##
+#Alias Color_Types ##
 
 #PhraseDef list_of_color_types
 kUnknown_SkColorType, kAlpha_8_SkColorType, kRGB_565_SkColorType,
@@ -265,7 +265,7 @@ $$$#
 #Code ##
 
 Describes how pixel bits encode color. A pixel may be an alpha mask, a
-grayscale, RGB, or ARGB.
+Grayscale, RGB, or ARGB.
 
 kN32_SkColorType selects the native 32-bit ARGB format. On Little_Endian
 processors, pixels containing 8-bit ARGB components pack into 32-bit
@@ -335,7 +335,7 @@ kRGBA_8888_SkColorType.
 ##
 
 #Const kGray_8_SkColorType 9
-#Line # pixel with grayscale level in 8-bit byte ##
+#Line # pixel with Grayscale level in 8-bit byte ##
 #Details Gray_8
     Stores 8-bit byte pixel encoding that equivalent to equal values for red,
     blue, and green, representing colors from black to white.
@@ -355,7 +355,7 @@ kRGBA_8888_SkColorType.
 ##
 
 #Const kN32_SkColorType 4 or 6
-#Alias Native_Color_Type
+#Alias Native_Color_Type ##
 #NoJustify
 #Line # native ARGB 32-bit encoding ##
     Encodes ARGB as either kRGBA_8888_SkColorType or
@@ -733,8 +733,8 @@ kRGBA_8888_SkColorType.
 ##
 
 #Subtopic Gray_8
-#Line # encodes level of grayscale in 8 bits ##
-    kGray_8_SkColorType encodes grayscale level in eight bits that is equivalent
+#Line # encodes level of Grayscale in 8 bits ##
+    kGray_8_SkColorType encodes Grayscale level in eight bits that is equivalent
     to equal values for red, blue, and green, representing colors from black to
     white.  Pixels described by kGray_8_SkColorType are fully
     opaque as if its Color_Alpha was set to one, and should always be paired with
@@ -980,7 +980,8 @@ and return true if alphaType is not kUnknown_SkAlphaType.
 # ------------------------------------------------------------------------------
 #Subtopic YUV_ColorSpace
 #Line # color range of YUV pixels ##
-#Alias YUV_ColorSpace
+#Alias YUV_ColorSpace ##
+
 #Enum SkYUVColorSpace
 #Line # color range of YUV pixels ##
 
@@ -1037,7 +1038,6 @@ with studio range of 16 to 235 range for components.
 
 # ------------------------------------------------------------------------------
 
-
 #Struct SkImageInfo
 
 Describes pixel dimensions and encoding. Bitmap, Image, PixMap, and Surface
diff --git a/docs/SkImage_Reference.bmh b/docs/SkImage_Reference.bmh
index 614115cf01..3cdcd0513b 100644
--- a/docs/SkImage_Reference.bmh
+++ b/docs/SkImage_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Image
-#Alias Image_Reference
+#Alias Image_Reference ##
 
 #Class SkImage
 
@@ -19,7 +19,7 @@ include BMP, GIF, HEIF, ICO, JPEG, PNG, WBMP, WebP. Supported encoding details
 vary with platform.
 
 #Subtopic Raster_Image
-#Alias Raster_Image
+#Alias Raster_Image ##
 #Line # pixels decoded in Raster_Bitmap ##
 Raster_Image pixels are decoded in a Raster_Bitmap. These pixels may be read
 directly and in most cases written to, although edited pixels may not be drawn
diff --git a/docs/SkMatrix_Reference.bmh b/docs/SkMatrix_Reference.bmh
index e76accdb40..4ab498a2c8 100644
--- a/docs/SkMatrix_Reference.bmh
+++ b/docs/SkMatrix_Reference.bmh
@@ -1,6 +1,6 @@
 #Topic Matrix
-#Alias Matrices
-#Alias Matrix_Reference
+#Alias Matrices ##
+#Alias Matrix_Reference ##
 
 #Class SkMatrix
 
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index 057135414e..d7738582e7 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Paint
-#Alias Paint_Reference
+#Alias Paint_Reference ##
 
 #Class SkPaint
 
@@ -440,8 +440,8 @@ as the Font_Engine.
     gray-level rendering.
 ##
 #Const kFull_Hinting 3
-#Line # modifies glyph outlines for maxiumum constrast ##
-    Modifies glyph outlines for maxiumum constrast. With FreeType, this selects
+#Line # modifies glyph outlines for maximum constrast ##
+    Modifies glyph outlines for maximum 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
@@ -450,9 +450,9 @@ as the Font_Engine.
 
 #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.
+to account for LCD text. No hinting uses Core_Text Grayscale output.
 Normal hinting uses Core_Text LCD output. If kLCDRenderText_Flag is clear,
-the LCD output is reduced to a single grayscale channel.
+the LCD output is reduced to a single Grayscale channel.
 
 On Windows with DirectWrite, Hinting has no effect.
 
@@ -650,11 +650,14 @@ All Flags members may be cleared, or one or more may be set.
 # ------------------------------------------------------------------------------
 #Subtopic Anti_Alias
 #Alias Anti_Alias
-#Substitute Anti-alias
+#Substitute anti-alias
+##
 #Alias Anti_Aliased
-#Substitute Anti-aliased
+#Substitute anti-aliased
+##
 #Alias Anti_Aliasing
-#Substitute Anti-aliasing
+#Substitute anti-aliasing
+##
 #In Related_Function
 #Line # approximating coverage with transparency ##
 
@@ -948,7 +951,7 @@ kLCDRenderText_Flag or kSubpixelText_Flag (or both) at compile time.
 #Subtopic Device_Text ##
 
 #Subtopic Linear_Text
-#Alias Linear_Text
+#Alias Linear_Text ##
 #Line # selects text rendering as Glyph or Path ##
 
 Linear_Text selects whether text is rendered as a Glyph or as a Path.
@@ -1025,7 +1028,7 @@ If kLinearText_Flag is clear, it is the same as setting Hinting to kNo_Hinting.
 #Subtopic Linear_Text ##
 
 #Subtopic Subpixel_Text
-#Alias Subpixel_Text
+#Alias Subpixel_Text ##
 #Line # uses pixel transparency to represent fractional offset ##
 
 Flags kSubpixelText_Flag uses the pixel transparency to represent a fractional offset.
@@ -1085,9 +1088,12 @@ SkDebugf("paint.isSubpixelText() %c= !!(paint.getFlags() & SkPaint::kSubpixelTex
 #Subtopic Subpixel_Text ##
 
 #Subtopic LCD_Text
-#Substitute LCD text
 #Line # text relying on the order of RGB stripes ##
-#Alias LCD_Text # makes this a top level name, since it is under subtopic Device_Text
+
+# make this a top level name, since it is under subtopic Device_Text
+#Alias LCD_Text
+#Substitute LCD text
+##
 
 When set, Flags kLCDRenderText_Flag takes advantage of the organization of RGB stripes that
 create a color, and relies
@@ -1151,7 +1157,7 @@ SkDebugf("paint.isLCDRenderText() %c= !!(paint.getFlags() & SkPaint::kLCDRenderT
 # ------------------------------------------------------------------------------
 #Subtopic Font_Embedded_Bitmaps
 #Line # custom sized bitmap Glyphs ##
-#Alias Font_Embedded_Bitmaps # long-winded enough, alias so I don't type Paint_Font_...
+#Alias Font_Embedded_Bitmaps ## # long-winded enough, alias so I don't type Paint_Font_...
 
 Font_Embedded_Bitmaps allows selecting custom sized bitmap Glyphs.
 Flags kEmbeddedBitmapText_Flag when set chooses an embedded bitmap glyph over an outline contained
@@ -1515,7 +1521,7 @@ void draw(SkCanvas* canvas) {
 # ------------------------------------------------------------------------------
 #Subtopic Full_Hinting_Spacing
 #Line # glyph spacing affected by hinting ##
-#Alias Full_Hinting_Spacing # long winded enough -- maybe things with two underscores auto-aliased?
+#Alias Full_Hinting_Spacing ## # long winded enough -- maybe things with two underscores auto-aliased?
 
 if Hinting is set to kFull_Hinting, Full_Hinting_Spacing adjusts the character
 spacing by the difference of the hinted and Unhinted Left_Side_Bearing and
@@ -1834,7 +1840,7 @@ may have gaps, and if kAntiAlias_Flag is set, Color_Alpha will increase to visua
 
 #Subtopic Hairline
 #Line # lines and curves with minimal width ##
-#Alias Hairline # maybe should be Stroke_Hairline ?
+#Alias Hairline ## # maybe should be Stroke_Hairline ?
 
 Stroke_Width of zero has a special meaning and switches drawing to use Hairline.
 Hairline draws the thinnest continuous frame. If kAntiAlias_Flag is clear, adjacent pixels
@@ -3494,6 +3500,7 @@ Align defaults to kLeft_Align.
 
 #Const kAlignCount 3
 #Line # number of different Text_Align values defined ##
+May be used to verify that Align is a legal value.
 ##
 
 #Enum ##
@@ -5053,7 +5060,7 @@ Paint may draw to.
     if (!path.isInverseFillType() && paint.canComputeFastBounds()) {
         SkRect storage;
         if (canvas->quickReject(paint.computeFastBounds(path.getBounds(), &storage))) {
-            return; // don't draw the path
+            return; // do not draw the path
         }
     }
     // draw the path
diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh
index f43bd2b8e1..1b8f991c6a 100644
--- a/docs/SkPath_Reference.bmh
+++ b/docs/SkPath_Reference.bmh
@@ -1,6 +1,6 @@
 #Topic Path
-#Alias Path_Reference
-#Alias Paths
+#Alias Path_Reference ##
+#Alias Paths ##
 
 Path contains Lines and Curves which can be stroked or filled. Contour is
 composed of a series of connected Lines and Curves. Path may contain zero,
@@ -76,7 +76,7 @@ a new Path independent of the original. Internally, the copy does not duplicate
 its contents until it is edited, to reduce memory use and improve performance.
 
 #Subtopic Contour
-#Alias Contours
+#Alias Contours ##
 #Line # loop of lines and curves ##
 
 Contour contains one or more Verbs, and as many Points as
@@ -135,7 +135,7 @@ void draw(SkCanvas* canvas) {
 ##
 
 #Subtopic Zero_Length
-#Alias Zero_Length_Contour
+#Alias Zero_Length_Contour ##
 #Line # consideration when contour has no length ##
 Contour length is distance traveled from first Point to Last_Point,
 plus, if Contour is closed, distance from Last_Point to first Point.
@@ -214,7 +214,7 @@ SkPath::updateBoundsCache to make Path thread safe.
 ##
 
 #Subtopic Verb
-#Alias Verbs
+#Alias Verbs ##
 #Line # line and curve type ##
 #Enum Verb
 #Line # controls how Path Points are interpreted ##
@@ -326,7 +326,7 @@ verbs: kMove_Verb kLine_Verb kQuad_Verb kClose_Verb kMove_Verb kCubic_Verb kConi
 # ------------------------------------------------------------------------------
 #Subtopic Direction
 #Line # contour orientation, clockwise or counterclockwise ##
-#Alias Directions
+#Alias Directions ##
 
 #Enum Direction
 #Line # sets Contour clockwise or counterclockwise ##
@@ -2316,10 +2316,10 @@ void draw(SkCanvas* canvas) {
 
 # ------------------------------------------------------------------------------
 #Subtopic Quad
-#Alias Quad
-#Alias Quads
-#Alias Quadratic_Bezier
-#Alias Quadratic_Beziers
+#Alias Quad ##
+#Alias Quads ##
+#Alias Quadratic_Bezier ##
+#Alias Quadratic_Beziers ##
 #Line # curve described by second-order polynomial ##
 
 Quad describes a quadratic Bezier, a second-order curve identical to a section
@@ -2491,7 +2491,7 @@ void draw(SkCanvas* canvas) {
 
 #Subtopic Conic
 #Line # conic section defined by three points and a weight ##
-#Alias Conics
+#Alias Conics ##
 
 Conic describes a conical section: a piece of an ellipse, or a piece of a
 parabola, or a piece of a hyperbola. Conic begins at a start Point,
@@ -2502,8 +2502,8 @@ Each Conic in Path adds two Points and one Conic_Weight. Conic_Weights in Path
 may be inspected with Iter, or with RawIter.
 
 #Subtopic Weight
-#Alias Conic_Weights
-#Alias Weights
+#Alias Conic_Weights ##
+#Alias Weights ##
 #Line # strength of Conic control Point ##
 
 Weight determines both the strength of the control Point and the type of Conic.
@@ -2512,7 +2512,7 @@ have no effect; Conic is identical to a line segment from start Point to end
 point. If Weight is less than one, Conic follows an elliptical arc.
 If Weight is exactly one, then Conic is identical to Quad; Conic follows a
 parabolic arc. If Weight is greater than one, Conic follows a hyperbolic
-arc. If Weight is infinity, Conic is indentical to two line segments, connecting
+arc. If Weight is infinity, Conic is identical to two line segments, connecting
 start Point to control Point, and control Point to end Point.
 
 #Example
@@ -2788,10 +2788,10 @@ void draw(SkCanvas* canvas) {
 
 # ------------------------------------------------------------------------------
 #Subtopic Cubic
-#Alias Cubic
-#Alias Cubics
-#Alias Cubic_Bezier
-#Alias Cubic_Beziers
+#Alias Cubic ##
+#Alias Cubics ##
+#Alias Cubic_Bezier ##
+#Alias Cubic_Beziers ##
 #Line # curve described by third-order polynomial ##
 
 Cubic describes a Bezier_Curve segment described by a third-order polynomial.
@@ -5266,7 +5266,7 @@ length = 40; returned by readFromMemory = 36
 
 # ------------------------------------------------------------------------------
 #Subtopic Generation_ID
-#Alias Generation_IDs
+#Alias Generation_IDs ##
 #Line # value reflecting contents change ##
 Generation_ID provides a quick way to check if Verb_Array, Point_Array, or
 Conic_Weight has changed. Generation_ID is not a hash; identical Paths will
@@ -5339,10 +5339,6 @@ empty genID = 1
 #Class Iter
 #Line # data iterator ##
 
-Iterates through Verb_Array, and associated Point_Array and Conic_Weight.
-Provides options to treat open Contours as closed, and to ignore
-degenerate data.
-
 #Code
 class Iter {
 public:
@@ -5356,6 +5352,10 @@ public:
 };
 ##
 
+Iterates through Verb_Array, and associated Point_Array and Conic_Weight.
+Provides options to treat open Contours as closed, and to ignore
+degenerate data.
+
 #Example
 #Height 128
 #Description
@@ -5733,9 +5733,6 @@ with close(),    forceClose is true : isClosedContour returns true
 #Class RawIter
 #Line # raw data iterator ##
 
-Iterates through Verb_Array, and associated Point_Array and Conic_Weight.
-Verb_Array, Point_Array, and Conic_Weight are returned unaltered.
-
 #Code
     class RawIter {
     public:
@@ -5748,6 +5745,9 @@ Verb_Array, Point_Array, and Conic_Weight are returned unaltered.
     }
 ##
 
+Iterates through Verb_Array, and associated Point_Array and Conic_Weight.
+Verb_Array, Point_Array, and Conic_Weight are returned unaltered.
+
     #Method RawIter()
     #Line # constructs empty Path iterator ##
 
diff --git a/docs/SkPixmap_Reference.bmh b/docs/SkPixmap_Reference.bmh
index 03f2b714aa..432324e3e2 100644
--- a/docs/SkPixmap_Reference.bmh
+++ b/docs/SkPixmap_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Pixmap
-#Alias Pixmap_Reference
+#Alias Pixmap_Reference ##
 
 #Class SkPixmap
 
diff --git a/docs/SkPoint_Reference.bmh b/docs/SkPoint_Reference.bmh
index 0f98f19326..fe48cd185f 100644
--- a/docs/SkPoint_Reference.bmh
+++ b/docs/SkPoint_Reference.bmh
@@ -1,6 +1,6 @@
 #Topic Point
-#Alias Points
-#Alias Point_Reference
+#Alias Points ##
+#Alias Point_Reference ##
 
 #Struct SkPoint
 
@@ -1261,8 +1261,8 @@ Returns the dot product of Vector and Vector vec.
 
 #Subtopic Vector
 #Line # alias for Point ##
-    #Alias Vector
-    #Alias Vectors
+    #Alias Vector ##
+    #Alias Vectors ##
     #Typedef SkPoint SkVector
     #Line # alias for Point ##
     #Code
diff --git a/docs/SkRect_Reference.bmh b/docs/SkRect_Reference.bmh
index 40fcfb39ae..2d878ef36d 100644
--- a/docs/SkRect_Reference.bmh
+++ b/docs/SkRect_Reference.bmh
@@ -1,6 +1,6 @@
 #Topic Rect
-#Alias Rects
-#Alias Rect_Reference
+#Alias Rects ##
+#Alias Rect_Reference ##
 
 #Struct SkRect
 
diff --git a/docs/SkSurface_Reference.bmh b/docs/SkSurface_Reference.bmh
index b4faad3224..97ac249be6 100644
--- a/docs/SkSurface_Reference.bmh
+++ b/docs/SkSurface_Reference.bmh
@@ -1,5 +1,5 @@
 #Topic Surface
-#Alias Surface_Reference
+#Alias Surface_Reference ##
 
 #Class SkSurface
 
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index be0c1b5c2c..9e982e5d9a 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -2,7 +2,6 @@
 #External
  DirectWrite TrueType Windows Linux Android iOS __ANDROID_API__ AHardwareBuffer
  FreeType FreeType-based Harfbuzz
- Descenders Kerning Unhinted
  LCD RGB sRGB ARGB BGR YUV SDTV HDTV
  YUV_Component_Y YUV_Component_U YUV_Component_V
  Unicode Unicode5 UTF-8 UTF-16 UTF-32 ASCII Unichar
@@ -14,7 +13,7 @@
  RFC
  NaN NaNs
  Bezier_Curve Coons_Patch Cartesian_Coordinate Euclidean_Distance Euclidean_Space Mip_Map
- C C++ Destructor Subclasses
+ C C++ 
  CSS HTML
  HTML_Gray HTML_DarkGray HTML_LightGray HTML_Silver HTML_Lime HTML_Green HTML_Aqua HTML_Fuchsia
  SVG_lightgray SVG_darkgray
@@ -49,17 +48,49 @@ FT_Load_Glyph
 
 #External ##
 
+# this jargon requires a substitute to lower-case the word. The word is uppercase because
+# it is not a dictionary word. An alternative would be to put this in an exception list
+# in the spell checker
+#Topic Destructor
+#Substitute destructor
+##
+
+# see comment for Destructor above
+#Topic Subclasses
+#Substitute subclasses
+##
+
+# see comment for Destructor above
+#Topic Descenders
+#Substitute descenders
+##
+
+# see comment for Destructor above
+#Topic Grayscale
+#Substitute grayscale
+##
+
+# see comment for Destructor above
+#Topic Kerning
+#Substitute kerning
+##
+
+# see comment for Destructor above
+#Topic Unhinted
+#Substitute unhinted
+##
+
 #Topic Alias
-#Alias Aliased
-#Alias Aliasing
+#Alias Aliased ##
+#Alias Aliasing ##
 ##
 
 #Topic Arc
-#Alias Arcs
+#Alias Arcs ##
 #Topic ##
 
 #Topic Backend_Semaphore
-#Alias Backend_Semaphores
+#Alias Backend_Semaphores ##
 #Class GrBackendSemaphore
 ##
 ##
@@ -81,7 +112,7 @@ FT_Load_Glyph
 #Topic ##
 
 #Topic Circle
-#Alias Circles
+#Alias Circles ##
 #Topic ##
 
 #Topic Clip_Op
@@ -132,7 +163,7 @@ FT_Load_Glyph
 ##
 
 #Topic Curve
-#Alias Curves
+#Alias Curves ##
 ##
 
 #Topic Data
@@ -261,7 +292,7 @@ FT_Load_Glyph
 #Topic ##
 
 #Topic Glyph
-#Alias Glyphs
+#Alias Glyphs ##
 ##
 
 #Topic GPU_Context
@@ -309,7 +340,7 @@ FT_Load_Glyph
 ##
 
 #Topic Line
-#Alias Lines
+#Alias Lines ##
 #Topic ##
 
 # to be in Topic Malloc_Pixel_Ref
@@ -372,7 +403,7 @@ FT_Load_Glyph
     #Typedef uint16_t SkGlyphID
     #Typedef ##
     #Topic Scalar
-    #Alias Scalar
+    #Alias Scalar ##
     #Typedef float SkScalar
     #Typedef ##
     ##
@@ -420,7 +451,7 @@ FT_Load_Glyph
 ##
 
 #Topic Oval
-#Alias Ovals
+#Alias Ovals ##
 #Topic ##
 
 #Topic Paint_Defaults
@@ -435,7 +466,7 @@ FT_Load_Glyph
 #Topic ##
 
 #Topic Patch
-#Alias Patches
+#Alias Patches ##
 #Topic ##
 
 #Topic Path_Effect
@@ -495,10 +526,6 @@ FT_Load_Glyph
 #Enum SkPixelGeometry
 ##
 
-# Topic Point_Array
-# Substitute SkPoint arrays
-# Topic ##
-
 #Topic Point3
 #Struct SkPoint3
 ##
@@ -512,7 +539,7 @@ FT_Load_Glyph
 ##
 
 #Topic Premultiply
-#Alias Premultiplied
+#Alias Premultiplied ##
 ##
 
 #Topic Raster_Engine
@@ -597,7 +624,7 @@ FT_Load_Glyph
 ##
 
 #Topic Sprite
-#Alias Sprites
+#Alias Sprites ##
 #Topic ##
 
 #Topic Stream
@@ -693,7 +720,7 @@ FT_Load_Glyph
 # end of defined in types
 
 #Topic Unpremultiply
-#Alias Unpremultiplied
+#Alias Unpremultiplied ##
 ##
 
 #Topic Vertices