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, 122 insertions, 0 deletions

diff --git a/docs/SkAutoCanvasRestore_Reference.bmh b/docs/SkAutoCanvasRestore_Reference.bmh
new file mode 100644
index 0000000000..a01aa793c7
--- /dev/null
+++ b/docs/SkAutoCanvasRestore_Reference.bmh
@@ -0,0 +1,122 @@
+#Topic Automatic_Canvas_Restore
+
+#Class SkAutoCanvasRestore
+
+Stack helper class calls SkCanvas::restoreToCount() when SkAutoCanvasRestore
+goes out of scope. Use this to guarantee that the canvas is restored to a known
+state.
+
+#Topic Overview
+
+#Subtopic Subtopics
+#ToDo manually add subtopics ##
+#Table
+#Legend
+# name             # description                                   ##
+#Legend ##
+# Constructors     # functions that construct SkAutoCanvasRestore  ##
+# Member_Functions # static functions and member methods           ##
+#Table ##
+#Subtopic ##
+
+#Subtopic Constructors
+#Table
+#Legend
+# name                                               # description                     ##
+#Legend ##
+# SkAutoCanvasRestore(SkCanvas* canvas, bool doSave) # Preserves Canvas save count.    ##
+# ~SkAutoCanvasRestore()                             # Restores Canvas to saved state. ##
+#Table ##
+#Subtopic ##
+
+#Subtopic Member_Functions
+#Table
+#Legend
+# name                             # description                     ##
+#Legend ##
+# restore()                        # Restores Canvas to saved state. ##
+#Table ##
+#Subtopic ##
+
+#Topic Overview ##
+
+#Method SkAutoCanvasRestore(SkCanvas* canvas, bool doSave)
+
+Preserves Canvas save count. Optionally saves Canvas_Clip and Canvas_Matrix.
+
+#Param canvas  Canvas to guard ##
+#Param doSave  call SkCanvas::save() ##
+
+#Return utility to restore Canvas state on destructor ##
+
+#Example
+#Height 128
+    SkPaint p;
+    p.setAntiAlias(true);
+    p.setTextSize(64);
+    for (SkScalar sx : { -1, 1 } ) {
+        for (SkScalar sy : { -1, 1 } ) {
+            SkAutoCanvasRestore autoRestore(canvas, true);
+            SkMatrix m = SkMatrix::MakeAll(sx, 1, 96,    0, sy, 64,   0, 0, 1);
+            canvas->concat(m);
+            canvas->drawString("R", 0, 0, p);
+        }
+    }
+##
+
+#SeeAlso SkCanvas::save SkCanvas::restore
+
+##
+
+#Method ~SkAutoCanvasRestore()
+
+Restores Canvas to saved state. Destructor is called when container goes out of
+scope.
+
+#NoExample
+##
+
+#SeeAlso SkCanvas::save SkCanvas::restore
+
+##
+
+#Method void restore()
+
+Restores Canvas to saved state immediately. Subsequent calls and
+~SkAutoCanvasRestore have no effect.
+
+#Example
+for (bool callRestore : { false, true } ) {
+    for (bool saveCanvas : {false, true} ) {
+        SkAutoCanvasRestore autoRestore(canvas, saveCanvas);
+        if (!saveCanvas) {
+            canvas->save();
+        }
+        SkDebugf("saveCanvas: %s  before restore: %d\n",
+               saveCanvas ? "true" : "false", canvas->getSaveCount());
+        if (callRestore) autoRestore.restore();
+        SkDebugf("saveCanvas: %s  after restore: %d\n",
+               saveCanvas ? "true" : "false", canvas->getSaveCount());
+    }
+}
+SkDebugf("final count: %d\n", canvas->getSaveCount());
+#StdOut
+saveCanvas: false  before restore: 2
+saveCanvas: false  after restore: 2
+saveCanvas: true  before restore: 2
+saveCanvas: true  after restore: 2
+saveCanvas: false  before restore: 2
+saveCanvas: false  after restore: 1
+saveCanvas: true  before restore: 2
+saveCanvas: true  after restore: 1
+final count: 1
+##
+##
+
+#SeeAlso SkCanvas::save SkCanvas::restore
+
+##
+
+#Class SkAutoCanvasRestore ##
+
+#Topic Automatic_Canvas_Restore ##