auto table generation

Replace manually entered summary tables with ones that are populated
and sorted by bookmaker. This introduces a slight regression for
anonymous enums but fixes a lot of bugs and omissions.

The format is

#Topic somethingTopical
#Populate
##

where somethingTopical is one of Subtopics, Constructors, Constants,
Classes_and_Structs, Members, Member_Functions, and Related_Functions.

Fix the bad formatting in SkCanvas reference. The #Error tag was
was corrupting the markdown table. Remove the tag and replace it
with #NoExample.

Next up: revise self-check to know about populated topics.

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

1 files changed, 47 insertions, 155 deletions

diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh
index 541bb83695..2225b205de 100644
--- a/docs/SkCanvas_Reference.bmh
+++ b/docs/SkCanvas_Reference.bmh
@@ -1,6 +1,12 @@
 #Topic Canvas
 #Alias Canvas_Reference
 
+#Subtopic Overview
+    #Subtopic Subtopics
+    #Populate
+    ##
+##
+
 #Class SkCanvas
 
 Canvas provides an interface for drawing, and how the drawing is clipped and transformed.
@@ -24,153 +30,29 @@ destination.
 Canvas can be constructed to draw to Bitmap without first creating Raster_Surface.
 This approach may be deprecated in the future.  
 
-#Topic Overview
-
-#Subtopic Subtopics
-#Table
-#Legend
-# name                  # description                                        ##
-#Legend ##
-# Classes_and_Structs   # embedded struct and class members                  ##
-# Constants             # enum and enum class, const values                  ##
-# Constructors          # functions that construct SkPath                    ##
-# Member_Functions      # static functions and member methods                ##
-#Table ##
-#Subtopic ##
+#Subtopic Related_Functions
+#Populate
+##
 
 #Subtopic Constants
-#Table
-#Legend
-# name                           # description                                 ##
-#Legend ##
-# Lattice::Flags                 # controls Lattice transparency ##
-# PointMode                      # sets drawPoints options ##
-# SaveLayerFlags                 # sets SaveLayerRec options ##
-# SrcRectConstraint              # sets drawImageRect options ##
-#Table ##
-#Subtopic ##
+#Populate
+##
 
 #Subtopic Classes_and_Structs
-#Table
-#Legend
-# name                           # description                                   ##
-#Legend ##
-# Lattice                        # divides Bitmap, Image into a rectangular grid ##
-# SaveLayerRec                   # contains state to create Layer                ##
-#Table ##
-#Subtopic ##
+#Populate
+##
 
 #Subtopic Constructors
 
 Create the desired type of Surface to obtain its Canvas when possible. Constructors are useful
 when no Surface is required, and some helpers implicitly create Raster_Surface.
 
-#Table
-#Legend
-# name                                                          # description                                    ##
-#Legend ##
-# MakeRasterDirect                                              # creates from SkImageInfo and Pixel_Storage     ##
-# MakeRasterDirectN32                                           # creates from image data and Pixel_Storage      ##
-# SkCanvas()                                                    # creates with no Surface, no dimensions         ##
-# SkCanvas(SkBaseDevice* device)                                # to be deprecated                               ##
-# SkCanvas(const SkBitmap& bitmap)                              # uses existing Bitmap                           ##
-# SkCanvas(const SkBitmap& bitmap, ColorBehavior behavior)      # Android framework only                         ##
-# SkCanvas(const SkBitmap& bitmap, const SkSurfaceProps& props) # uses existing Bitmap and Surface_Properties    ##
-# SkCanvas(int width, int height, const SkSurfaceProps* props = nullptr) # no Surface, set dimensions, Surface_Properties ##
-# ~SkCanvas()                                                   # draws saved Layers, frees resources            ##
-#Table ##
-#Subtopic ##
+#Populate
+##
 
 #Subtopic Member_Functions
-#Table
-#Legend
-# name                             # description                                                   ##
-#Legend ##
-# MakeRasterDirect                 # creates from SkImageInfo and Pixel_Storage ##
-# MakeRasterDirectN32              # creates from image data and Pixel_Storage ##
-# accessTopLayerPixels             # returns writable pixel access if available ##
-# accessTopRasterHandle            # returns context that tracks Clip and Matrix ##
-# androidFramework_setDeviceClipRestriction # for use by Android framework ##
-# clear()                          # fills Clip with Color ##
-# clipPath                         # combines Clip with Path ##
-# clipRRect                        # combines Clip with Round_Rect ##
-# clipRect                         # combines Clip with Rect ##
-# clipRegion                       # combines Clip with Region ##
-# concat()                         # multiplies Matrix by Matrix ##
-# discard()                        # makes Canvas contents undefined ##
-# drawAnnotation                   # associates a Rect with a key-value pair ##
-# drawArc                          # draws Arc using Clip, Matrix, and Paint ##
-# drawAtlas                        # draws sprites using Clip, Matrix, and Paint ##
-# drawBitmap                       # draws Bitmap at (x, y) position ##
-# drawBitmapLattice                # draws proportionally stretched Bitmap ##
-# drawBitmapNine                   # draws Nine_Patch Bitmap ##
-# drawBitmapRect                   # draws Bitmap, source Rect to destination Rect ##
-# drawCircle                       # draws Circle using Clip, Matrix, and Paint ##
-# drawColor                        # fills Clip with Color and Blend_Mode ##
-# drawDRRect                       # draws double Round_Rect stroked or filled ##
-# drawDrawable                     # draws Drawable, encapsulated drawing commands ##
-# drawIRect                        # draws IRect using Clip, Matrix, and Paint ##
-# drawImage                        # draws Image at (x, y) position ##
-# drawImageLattice                 # draws proportionally stretched Image ##
-# drawImageNine                    # draws Nine_Patch Image ##
-# drawImageRect                    # draws Image, source Rect to destination Rect ##
-# drawLine                         # draws line segment between two points ##
-# drawOval                         # draws Oval using Clip, Matrix, and Paint ##
-# drawPaint                        # fills Clip with Paint ##
-# drawPatch                        # draws Coons_Patch ##
-# drawPath                         # draws Path using Clip, Matrix, and Paint ##
-# drawPicture                      # draws Picture using Clip and Matrix ##
-# drawPoint                        # draws point at (x, y) position ##
-# drawPoints                       # draws array as points, lines, polygon ##
-# drawPosText                      # draws text at array of (x, y) positions ##
-# drawPosTextH                     # draws text at x positions with common baseline ##
-# drawRRect                        # draws Round_Rect using Clip, Matrix, and Paint ##
-# drawRect                         # draws Rect using Clip, Matrix, and Paint ##
-# drawRegion                       # draws Region using Clip, Matrix, and Paint ##
-# drawRoundRect                    # draws Round_Rect using Clip, Matrix, and Paint ##
-# drawString                       # draws null terminated string at (x, y) using font advance ##
-# drawText                         # draws text at (x, y), using font advance ##
-# drawTextBlob                     # draws text with arrays of positions and Paint ##
-# drawTextOnPath                   # draws text following Path contour ##
-# drawTextOnPathHV                 # draws text following Path with offsets ##
-# drawTextRSXform                  # draws text with array of RSXform ##
-# drawVertices                     # draws Vertices, a triangle mesh ##
-# flush()                          # triggers execution of all pending draw operations ##
-# getBaseLayerSize                 # returns size of base Layer in global coordinates ##
-# getDeviceClipBounds              # returns IRect bounds of Clip ##
-# getDrawFilter                    # legacy; to be deprecated ##
-# getGrContext                     # returns GPU_Context of the GPU_Surface ##
-# getLocalClipBounds               # returns Clip bounds in source coordinates ##
-# getMetaData                      # associates additional data with the canvas ##
-# getProps                         # copies Surface_Properties if available ##
-# getSaveCount                     # returns depth of stack containing Clip and Matrix ##
-# getTotalMatrix                   # returns Matrix ##
-# imageInfo                        # returns Image_Info for Canvas ##
-# isClipEmpty                      # returns if Clip is empty ##
-# isClipRect                       # returns if Clip is Rect and not empty ##
-# makeSurface                      # creates Surface matching SkImageInfo and SkSurfaceProps ##
-# peekPixels                       # returns if Canvas has direct access to its pixels ##
-# quickReject                      # returns if Rect is outside Clip ##
-# readPixels                       # copies and converts rectangle of pixels from Canvas ##
-# resetMatrix                      # resets Matrix to identity ##
-# restore()                        # restores changes to Clip and Matrix, pops save stack ##
-# restoreToCount                   # restores changes to Clip and Matrix to given depth ##
-# rotate()                         # rotates Matrix ##
-# save()                           # saves Clip and Matrix on stack ##
-# saveLayer                        # saves Clip and Matrix on stack; creates Layer ##
-# saveLayerAlpha                   # saves Clip and Matrix on stack; creates Layer; sets opacity ##
-# saveLayerPreserveLCDTextRequests # saves Clip and Matrix on stack; creates Layer for LCD text ##
-# scale()                          # scales Matrix ##
-# setAllowSimplifyClip             # experimental ##
-# setDrawFilter                    # legacy; to be deprecated ##
-# setMatrix                        # sets Matrix ##
-# skew()                           # skews Matrix ##
-# translate()                      # translates Matrix ##
-# writePixels                      # copies and converts rectangle of pixels to Canvas ##
-#Table ##
-#Subtopic ##
-
-#Topic Overview ##
+#Populate
+##
 
 # ------------------------------------------------------------------------------
 
@@ -424,10 +306,8 @@ Used by child classes of SkCanvas.
 
 #Return         Canvas that can be used to draw into device ##
 
-#Example
-#Error "Unsure how to create a meaningful example."
- SkPDFCanvas::SkPDFCanvas(const sk_sp<SkPDFDevice>& dev)
-    : SkCanvas(dev.get()) {}
+#ToDo  unsure how to create a meaningful example ##
+#NoExample
 ##
 
 #ToDo either remove doc or figure out a way to fiddle it ##
@@ -501,7 +381,7 @@ The actual output depends on the installed fonts.
 ##
 
 #EnumClass ColorBehavior
-
+#Line # Android framework only ##
 #Private
 Android framework only.
 ##
@@ -748,8 +628,8 @@ In an overview section on managing the GPU, include:
 for posterity: this doesn't show a difference: fiddle.skia.org/c/@flushfail
 ##
 
-#Example
-#Error "haven't thought of a useful example to put here"
+#ToDo haven't thought of a useful example to put here ##
+#NoExample
 ##
 
 #SeeAlso peekPixels SkSurface::flush() GrContext::flush() SkSurface::prepareForExternalIO GrContext::abandonContext()
@@ -1371,7 +1251,8 @@ void draw(SkCanvas* canvas) {
 ##
 
 # ------------------------------------------------------------------------------
-#Topic State_Stack
+#Subtopic State_Stack
+#Line # stack of state for hierarchical drawing ##
 
 Canvas maintains a stack of state that allows hierarchical drawing, commonly used
 to implement windows and views. The initial state has an identity matrix and and
@@ -1573,13 +1454,14 @@ depth = 1
 
 ##
 
-#Topic State_Stack ##
+#Subtopic State_Stack ##
 
 # ------------------------------------------------------------------------------
 
-#Topic Layer
+#Subtopic Layer
 #Substitute layer
 #Alias Layers
+#Line # temporary Bitmap to draw into ##
 
 Layer allocates a temporary Bitmap to draw into. When the drawing is
 complete, the Bitmap is drawn into the Canvas. 
@@ -1791,8 +1673,13 @@ Call restoreToCount with returned value to restore this and subsequent saves.
 
 ##
 
-#Enum
+#ToDo 
+add new markup to associate typedef SaveLayerFlags with Enum so that, for
+documentation purposes, this enum is named rather than anonymous
+##
 
+#Enum
+#Line # sets SaveLayerRec options ##
 #Code
     enum {
         kIsOpaque_SaveLayerFlag = 1 << 0,
@@ -1860,7 +1747,7 @@ void draw(SkCanvas* canvas) {
 ##
 
 #Struct SaveLayerRec
-
+#Line # contains the state used to create the Layer ##
 #Code
     struct SaveLayerRec {
         SaveLayerRec*(...
@@ -2096,10 +1983,11 @@ Outside of the circle the mandrill is brightened.
 
 ##
 
-#Topic Layer ##
+#Subtopic Layer ##
 
 # ------------------------------------------------------------------------------
-#Topic Matrix
+#Subtopic Matrix
+#Line # coordinate transformation ##
 
 #Method void translate(SkScalar dx, SkScalar dy)
 
@@ -2414,10 +2302,11 @@ This does not account for translation by Device or Surface.
 
 ##
 
-#Topic Matrix ##
+#Subtopic Matrix ##
 
 # ------------------------------------------------------------------------------
-#Topic Clip
+#Subtopic Clip
+#Line # stack of clipping Paths ##
 
 Clip is built from a stack of clipping paths. Each Path in the
 stack can be constructed from one or more Path_Contour elements. The 
@@ -3102,7 +2991,7 @@ Unlike getLocalClipBounds, bounds is not outset.
 
 ##
 
-#Topic Clip ##
+#Subtopic Clip ##
 
 # ------------------------------------------------------------------------------
 
@@ -3211,6 +3100,7 @@ void draw(SkCanvas* canvas) {
 # ------------------------------------------------------------------------------
 
 #Enum PointMode
+#Line # sets drawPoints options ##
 
 #Code
     enum PointMode {
@@ -3933,7 +3823,8 @@ void draw(SkCanvas* canvas) {
 ##
 
 # ------------------------------------------------------------------------------
-#Topic Draw_Image
+#Subtopic Draw_Image
+#Line # draws Image to Canvas ##
 
 drawImage, drawImageRect, and drawImageNine can be called with a bare pointer or
 a smart pointer as a convenience. The pairs of calls are otherwise identical.
@@ -4020,6 +3911,7 @@ void draw(SkCanvas* canvas) {
 # ------------------------------------------------------------------------------
 
 #Enum SrcRectConstraint
+#Line # sets drawImageRect options ##
 
 #Code
     enum SrcRectConstraint {
@@ -4833,7 +4725,7 @@ void draw(SkCanvas* canvas) {
 
 # ------------------------------------------------------------------------------
 #Struct Lattice
-
+#Line # divides Bitmap or Image into a rectangular grid ##
 #Code
     struct Lattice {
         enum RectType ...
@@ -5098,7 +4990,7 @@ void draw(SkCanvas* canvas) {
 
 ##
 
-#Topic Draw_Image ##
+#Subtopic Draw_Image ##
 
 # ------------------------------------------------------------------------------