fix bugs exposed by documenting SkImageInfo

- More rigorous symbol identification creates additional
links, and finds spurious errors like unnecessary
parentheses.

- Fixed code to allow preprocessor directives in
#Code blocks (still more to do).

- Fixed examples waiting on fiddle updates.

- Make SkImageInfo officially documented (update in status.json).

- Fixed enum indentation.



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

7 files changed, 26 insertions, 33 deletions

diff --git a/docs/SkAutoCanvasRestore_Reference.bmh b/docs/SkAutoCanvasRestore_Reference.bmh
index e4d559da41..fc0f988c2c 100644
--- a/docs/SkAutoCanvasRestore_Reference.bmh
+++ b/docs/SkAutoCanvasRestore_Reference.bmh
@@ -8,7 +8,7 @@
 
 #Class SkAutoCanvasRestore
 
-Stack helper class calls SkCanvas::restoreToCount() when 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.
 
diff --git a/docs/SkBitmap_Reference.bmh b/docs/SkBitmap_Reference.bmh
index 584672af3f..192896acc6 100644
--- a/docs/SkBitmap_Reference.bmh
+++ b/docs/SkBitmap_Reference.bmh
@@ -1475,8 +1475,8 @@ until the pixels are written to. The actual behavior depends on the platform
 implementation of malloc(), if flags is zero, and calloc(), if flags is
 kZeroPixels_AllocFlag.
 
-Passing kZeroPixels_AllocFlag is usually faster than separately calling
-eraseColor(SK_ColorTRANSPARENT).
+flags set to kZeroPixels_AllocFlag offers equal or better performance than
+subsequently calling eraseColor with SK_ColorTRANSPARENT.
 
 #Param info  contains width, height, Alpha_Type, Color_Type, Color_Space ##
 #Param flags  kZeroPixels_AllocFlag, or zero ##
@@ -1519,8 +1519,8 @@ until the pixels are written to. The actual behavior depends on the platform
 implementation of malloc(), if flags is zero, and calloc(), if flags is
 kZeroPixels_AllocFlag.
 
-Passing kZeroPixels_AllocFlag is usually faster than separately calling
-eraseColor(SK_ColorTRANSPARENT).
+flags set to kZeroPixels_AllocFlag offers equal or better performance than
+subsequently calling eraseColor with SK_ColorTRANSPARENT.
 
 #Param info  contains width, height, Alpha_Type, Color_Type, Color_Space ##
 #Param flags  kZeroPixels_AllocFlag, or zero ##
diff --git a/docs/SkIRect_Reference.bmh b/docs/SkIRect_Reference.bmh
index 45b636082d..1e59578310 100644
--- a/docs/SkIRect_Reference.bmh
+++ b/docs/SkIRect_Reference.bmh
@@ -420,11 +420,9 @@ overflow in its calculation.
 
 #Return fRight minus fLeft cast to int64_t ##
 
-#Bug 7489
-# width64 is not yet visible to fiddle
-#NoExample
+#Example
 SkIRect large = { -2147483647, 1, 2147483644, 2 };
-SkDebugf("width: %d wdith64: %lld\n", large.width(), large.width64());
+SkDebugf("width: %d width64: %lld\n", large.width(), large.width64());
 #StdOut
 width: -5 width64: 4294967291
 ##
@@ -472,9 +470,7 @@ overflow in its calculation.
 
 #Return fBottom minus fTop cast to int64_t ##
 
-#Bug 7489
-# height64 not yet visible to fiddle
-#NoExample
+#Example
 SkIRect large = { 1, -2147483647, 2, 2147483644 };
 SkDebugf("height: %d height64: %lld\n", large.height(), large.height64());
 #StdOut
@@ -623,16 +619,14 @@ width64() or height64().
 
 #Return true if width64() or height64() are zero or negative ##
 
-#Bug 7489
-# isEmpty64 not yet visible to fiddle
-#NoExample
+#Example
 SkIRect tests[] = {{20, 40, 10, 50}, {20, 40, 20, 50}};
 for (auto rect : tests) {
-SkDebugf("rect: {%d, %d, %d, %d} is" "%s empty\n", rect.left(), rect.top(), rect.right(),
-rect.bottom(), isEmpty64() ? "" : " not");
-rect.sort();
-SkDebugf("sorted: {%d, %d, %d, %d} is" "%s empty\n", rect.left(), rect.top(), rect.right(),
-rect.bottom(), isEmpty64() ? "" : " not");
+    SkDebugf("rect: {%d, %d, %d, %d} is" "%s empty\n", rect.left(), rect.top(), rect.right(),
+            rect.bottom(), rect.isEmpty64() ? "" : " not");
+    rect.sort();
+    SkDebugf("sorted: {%d, %d, %d, %d} is" "%s empty\n", rect.left(), rect.top(), rect.right(),
+            rect.bottom(), rect.isEmpty64() ? "" : " not");
 }
 #StdOut
 rect: {20, 40, 10, 50} is empty
diff --git a/docs/SkImageInfo_Reference.bmh b/docs/SkImageInfo_Reference.bmh
index 516de4e35f..f8b3f208eb 100644
--- a/docs/SkImageInfo_Reference.bmh
+++ b/docs/SkImageInfo_Reference.bmh
@@ -227,7 +227,6 @@ kGray_8_SkColorType, kRGBA_F16_SkColorType
 #Line # encoding for pixel color ##
 
 #Code
-###$
     enum SkColorType {
         kUnknown_SkColorType,
         kAlpha_8_SkColorType,
@@ -242,7 +241,7 @@ kGray_8_SkColorType, kRGBA_F16_SkColorType
         kRGBA_F16_SkColorType,
 
         kLastEnum_SkColorType = kRGBA_F16_SkColorType,
-
+###$
     #if SK_PMCOLOR_BYTE_ORDER(B,G,R,A)
         kN32_SkColorType = kBGRA_8888_SkColorType,
     #elif SK_PMCOLOR_BYTE_ORDER(R,G,B,A)
@@ -250,9 +249,9 @@ kGray_8_SkColorType, kRGBA_F16_SkColorType
     #else
         #error "SK_*32_SHIFT values must correspond to BGRA or RGBA byte order"
     #endif
-    };
 $$$#
-##
+    };
+#Code ##
 
 Describes how pixel bits encode color. A pixel may be an alpha mask, a
 gray level, Color_RGB, or Color_ARGB. 
@@ -263,7 +262,7 @@ kBGRA_8888_SkColorType. On Big_Endian processors, pixels pack into 32-bit
 kRGBA_8888_SkColorType.
 
 #Const kUnknown_SkColorType 0
-
+    Color_Type is uninitialized; encoding format and size is unknown.
 ##
 #Const kAlpha_8_SkColorType 1
     Encodes Color_Alpha as Alpha_8 pixel in an 8-bit byte.
diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh
index 869e72e5fd..8aecf01728 100644
--- a/docs/SkPath_Reference.bmh
+++ b/docs/SkPath_Reference.bmh
@@ -4077,8 +4077,6 @@ Oval is upright ellipse bounded by Rect oval with radii equal to half oval width
 and half oval height. Oval begins at (oval.fRight, oval.centerY()) and continues
 clockwise if dir is kCW_Direction, counterclockwise if dir is kCCW_Direction.
 
-This form is identical to addOval(oval, dir, 1).
-
 #Param oval  bounds of ellipse added ##
 #Param dir   Direction to wind ellipse ##
 
@@ -4839,7 +4837,7 @@ Last_Point can be read and written directly with getLastPt and setLastPt.
 #In Last_Point
 #Line # replaces Last_Point ##
     Set Last_Point to (x, y). If Point_Array is empty, append kMove_Verb to
-    Verb_Array and (x, y) to Point_Array.
+    Verb_Array and append (x, y) to Point_Array.
 
     #Param x  set x-coordinate of Last_Point ##
     #Param y  set y-coordinate of Last_Point ##
@@ -4860,8 +4858,8 @@ Last_Point can be read and written directly with getLastPt and setLastPt.
 
 #Method void setLastPt(const SkPoint& p) 
 
-    Set the last point on the path. If no points have been added, moveTo(p)
-    is automatically called.
+    Set the last point on the path. If Point_Array is empty, append kMove_Verb to
+    Verb_Array and append p to Point_Array.
 
     #Param p  set value of Last_Point ##
 
@@ -5129,7 +5127,7 @@ path is equal to copy
 ##
 ##
 
-#SeeAlso dump SkRect::dumpHex() SkRRect::dumpHex() writeToMemory
+#SeeAlso dump SkRect::dumpHex SkRRect::dumpHex writeToMemory
 
 ##
 
diff --git a/docs/status.json b/docs/status.json
index eaa80b4189..8ac5f03298 100644
--- a/docs/status.json
+++ b/docs/status.json
@@ -5,6 +5,7 @@
                 "SkBitmap.h",
                 "SkCanvas.h",
                 "SkImage.h",
+                "SkImageInfo.h",
                 "SkMatrix.h",
                 "SkPaint.h",
                 "SkPath.h",
@@ -22,6 +23,7 @@
             "SkPoint_Reference.bmh",
             "SkIRect_Reference.bmh",
             "SkImage_Reference.bmh",
+            "SkImageInfo_Reference.bmh",
             "SkPath_Reference.bmh",
             "SkRect_Reference.bmh",
             "SkBitmap_Reference.bmh",
@@ -36,11 +38,9 @@
     "InProgress": {
         "include": {
             "core": [
-                "SkImageInfo.h"
             ]
         },
         "docs": [
-            "SkImageInfo_Reference.bmh",
             "overview.bmh",
             "usingBookmaker.bmh"
         ]
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index da8b9fceee..f59b5daf8b 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -125,6 +125,8 @@ FT_Load_Glyph
     ##
     #Const SK_ColorWHITE 0xFFFFFFFF 
     ##
+    #Const SK_ColorTRANSPARENT 0x00000000
+    ##
     #Subtopic Alpha
         #Alias Alpha
     #Subtopic ##