Documentation refresh

- add links to types within methods
- add check to see that all references and definitions match
- add style to tables to make them easier to read
- use https everywhere
- remove trailing spaces
- move overview inside class
- split class and struct in summary tables
- add missing #Line
- clean up SkImageInfo constant documentation
- work on SkColor documentation
- allow common phrases to take different parameters
- add more flexibility to generated tables
- tighten token parent requirements
- generalize deprecated and example interfaces
- detect inner constructors

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

1 files changed, 76 insertions, 69 deletions

diff --git a/docs/SkMatrix_Reference.bmh b/docs/SkMatrix_Reference.bmh
index ba3cf79a1d..b079cb5632 100644
--- a/docs/SkMatrix_Reference.bmh
+++ b/docs/SkMatrix_Reference.bmh
@@ -2,12 +2,6 @@
 #Alias Matrices
 #Alias Matrix_Reference
 
-#Subtopic Overview
-    #Subtopic Subtopic
-    #Populate
-    ##
-##
-
 #Class SkMatrix
 
 Matrix holds a 3x3 matrix for transforming coordinates. This allows mapping
@@ -19,9 +13,13 @@ so it must be explicitly initialized. setIdentity initializes Matrix
 so it has no effect. setTranslate, setScale, setSkew, setRotate, set9 and setAll
 initializes all Matrix elements with the corresponding mapping.
 
-Matrix includes a hidden variable that classifies the type of matrix to 
+Matrix includes a hidden variable that classifies the type of matrix to
 improve performance. Matrix is not thread safe unless getType is called first.
 
+#Subtopic Overview
+#Populate
+##
+
 #Subtopic Member_Function
 #Populate
 ##
@@ -173,7 +171,7 @@ Sets Matrix to:
 # ------------------------------------------------------------------------------
 
 #Enum TypeMask
-
+#Line # bit field for Matrix complexity ##
 #Code
     enum TypeMask {
         kIdentity_Mask = 0,
@@ -188,18 +186,23 @@ Enum of bit fields for mask returned by getType.
 Used to identify the complexity of Matrix, to optimize performance.
 
 #Const kIdentity_Mask 0
+#Line # identity Matrix; all bits clear ##
 all bits clear if Matrix is identity
 ##
 #Const kTranslate_Mask 1
+#Line # translation Matrix ##
 set if Matrix has translation
 ##
 #Const kScale_Mask 2
+#Line # scale Matrix ##
 set if Matrix has x or y scale
 ##
 #Const kAffine_Mask 4
+#Line # skew or rotate Matrix ##
 set if Matrix skews or rotates
 ##
 #Const kPerspective_Mask 8
+#Line # perspective Matrix ##
 set if Matrix has perspective
 ##
 
@@ -226,10 +229,10 @@ SkPoint polys[][4] = {{{0, 0}, {0, 1}, {1, 1}, {1, 0}}, {{0, 0}, {0, 1}, {2, 1},
 matrix.setPolyToPoly(polys[0], polys[1], 4);
 debugster("setPolyToPoly", matrix);
 #StdOut
-after reset: kIdentity_Mask 
-after postTranslate: kTranslate_Mask 
-after postScale: kTranslate_Mask kScale_Mask 
-after postScale: kTranslate_Mask kScale_Mask kAffine_Mask 
+after reset: kIdentity_Mask
+after postTranslate: kTranslate_Mask
+after postScale: kTranslate_Mask kScale_Mask
+after postScale: kTranslate_Mask kScale_Mask kAffine_Mask
 after setPolyToPoly: kTranslate_Mask kScale_Mask kAffine_Mask kPerspective_Mask
 ##
 ##
@@ -253,7 +256,7 @@ false positives. For example, when kPerspective_Mask is set, all
 other bits are set.
 
 #Return  kIdentity_Mask, or combinations of: kTranslate_Mask, kScale_Mask,
-         kAffine_Mask, kPerspective_Mask 
+         kAffine_Mask, kPerspective_Mask
 ##
 
 #Example
@@ -492,7 +495,7 @@ Returns true if the matrix contains perspective elements. Matrix form is:
 | perspective-x  perspective-y  perspective-scale |
 ##
 
-where perspective-x or perspective-y is non-zero, or perspective-scale is 
+where perspective-x or perspective-y is non-zero, or perspective-scale is
 not one. All other elements may have any value.
 
 #Return  true if Matrix is in most general form ##
@@ -527,7 +530,7 @@ uniform scale.
 Returns false if Matrix contains different scales, skewing, perspective, or
 degenerate forms that collapse to a line or point.
 
-Describes that the Matrix makes rendering with and without the matrix are 
+Describes that the Matrix makes rendering with and without the matrix are
 visually alike; a transformed circle remains a circle. Mathematically, this is
 referred to as similarity of a Euclidean_Space, or a similarity transformation.
 
@@ -555,7 +558,7 @@ with isSimilarity false reveals the pair not visible through the matrix.
             {
                 SkAutoCanvasRestore autoRestore(canvas, true);
                 canvas->concat(m);
-                canvas->drawString(str, 0, 0, p);    
+                canvas->drawString(str, 0, 0, p);
             }
             if (!isSimilarity) {
                 canvas->drawString(str, 40, below, p);
@@ -576,7 +579,7 @@ with isSimilarity false reveals the pair not visible through the matrix.
 #Line # returns if mapped 90 angle remains 90 degrees ##
 Returns true if Matrix contains only translation, rotation, reflection, and
 scale. Scale may differ along rotated axes.
-Returns false if Matrix skewing, perspective, or degenerate forms that collapse 
+Returns false if Matrix skewing, perspective, or degenerate forms that collapse
 to a line or point.
 
 Preserves right angles, but not requiring that the arms of the angle
@@ -607,7 +610,7 @@ for (SkScalar sx : { 1, 2 } ) {
                     preservesRightAngles ? "right" : "");
         SkAutoCanvasRestore autoRestore(canvas, true);
         canvas->concat(m);
-        canvas->drawString(str, 0, pos, p);    
+        canvas->drawString(str, 0, pos, p);
         pos += 20;
     }
 }
@@ -639,31 +642,31 @@ Matrix organizes its values in row order. These members correspond to
 each value in Matrix.
 
 #Const kMScaleX 0
-horizontal scale factor
+#Line # horizontal scale factor ##
 ##
 #Const kMSkewX 1
-horizontal skew factor
+#Line # horizontal skew factor ##
 ##
 #Const kMTransX 2
-horizontal translation
+#Line # horizontal translation ##
 ##
 #Const kMSkewY 3
-vertical skew factor
+#Line # vertical skew factor ##
 ##
 #Const kMScaleY 4
-vertical scale factor
+#Line # vertical scale factor ##
 ##
 #Const kMTransY 5
-vertical translation
+#Line # vertical translation ##
 ##
 #Const kMPersp0 6
-input x perspective factor
+#Line # input x perspective factor ##
 ##
 #Const kMPersp1 7
-input y perspective factor
+#Line # input y perspective factor ##
 ##
 #Const kMPersp2 8
-perspective bias
+#Line # perspective bias ##
 ##
 
 #Example
@@ -710,22 +713,22 @@ Affine arrays are in column major order to match the matrix used by
 PDF and XPS.
 
 #Const kAScaleX 0
-horizontal scale factor
+#Line # horizontal scale factor ##
 ##
 #Const kASkewY 1
-vertical skew factor
+#Line # vertical skew factor ##
 ##
 #Const kASkewX 2
-horizontal skew factor
+#Line # horizontal skew factor ##
 ##
 #Const kAScaleY 3
-vertical scale factor
+#Line # vertical scale factor ##
 ##
 #Const kATransX 4
-horizontal translation
+#Line # horizontal translation ##
 ##
 #Const kATransY 5
-vertical translation
+#Line # vertical translation ##
 ##
 
 #NoExample
@@ -943,7 +946,7 @@ matrix.getTranslateY() == 24
 #Method SkScalar getPerspX() const
 #In Property
 #Line # returns input x perspective factor ##
-Returns factor scaling input x relative to input y. 
+Returns factor scaling input x relative to input y.
 
 #Return  input x perspective factor ##
 
@@ -975,7 +978,7 @@ Returns factor scaling input x relative to input y.
 #In Property
 #Line # returns input y perspective factor ##
 
-Returns factor scaling input y relative to input x. 
+Returns factor scaling input y relative to input x.
 
 #Return  input y perspective factor ##
 
@@ -1044,7 +1047,7 @@ after dirty cache:    x = 66
 # ------------------------------------------------------------------------------
 #Subtopic Set
 #Populate
-#Line # set one or more matrix values ##
+#Line # sets one or more matrix values ##
 ##
 
 #Method void set(int index, SkScalar value)
@@ -1082,7 +1085,7 @@ after 2nd skew x mod: x = 66
 #Method void setScaleX(SkScalar v)
 #In Set
 #Line # sets horizontal scale factor ##
-Sets horizontal scale factor. 
+Sets horizontal scale factor.
 
 #Param v  horizontal scale factor to store ##
 
@@ -1108,7 +1111,7 @@ canvas->drawString("x scale", 0, 48, paint);
 #Method void setScaleY(SkScalar v)
 #In Set
 #Line # sets vertical scale factor ##
-Sets vertical scale factor. 
+Sets vertical scale factor.
 
 #Param v  vertical scale factor to store ##
 
@@ -1134,7 +1137,7 @@ canvas->drawString("y scale", 12, 48, paint);
 #Method void setSkewY(SkScalar v)
 #In Set
 #Line # sets vertical skew factor ##
-Sets vertical skew factor. 
+Sets vertical skew factor.
 
 #Param v  vertical skew factor to store ##
 
@@ -1160,7 +1163,7 @@ canvas->drawString("y skew", 12, 48, paint);
 #Method void setSkewX(SkScalar v)
 #In Set
 #Line # sets horizontal skew factor ##
-Sets horizontal skew factor. 
+Sets horizontal skew factor.
 
 #Param v  horizontal skew factor to store ##
 
@@ -1352,13 +1355,13 @@ SkMatrix matrix = SkMatrix::MakeRectToRect({0, 0, 1, 1}, {3, 4, 7, 9},
                                            SkMatrix::kFill_ScaleToFit);
 SkScalar b[9];
 matrix.get9(b);
-SkDebugf("{%g, %g, %g},\n{%g, %g, %g},\n{%g, %g, %g}\n", b[0], b[1], b[2], 
+SkDebugf("{%g, %g, %g},\n{%g, %g, %g},\n{%g, %g, %g}\n", b[0], b[1], b[2],
          b[3], b[4], b[5], b[6], b[7], b[8]);
 #StdOut
 {4, 0, 3},
 {0, 5, 4},
 {0, 0, 1}
-##    
+##
 ##
 
 #SeeAlso set9
@@ -1650,7 +1653,7 @@ Positive degrees rotates clockwise.
 #In Set
 #Line # sets to rotate and scale about a point ##
 
-Sets Matrix to rotate by sinValue and cosValue, about a pivot point at (px, py). 
+Sets Matrix to rotate by sinValue and cosValue, about a pivot point at (px, py).
 The pivot point is unchanged when mapped with Matrix.
 
 Vector (sinValue, cosValue) describes the angle of rotation relative to (0, 1).
@@ -1683,7 +1686,7 @@ Vector length specifies scale.
 
 #Method void setSinCos(SkScalar sinValue, SkScalar cosValue)
 
-Sets Matrix to rotate by sinValue and cosValue, about a pivot point at (0, 0). 
+Sets Matrix to rotate by sinValue and cosValue, about a pivot point at (0, 0).
 
 Vector (sinValue, cosValue) describes the angle of rotation relative to (0, 1).
 Vector length specifies scale.
@@ -1901,7 +1904,7 @@ Matrix * T(dx, dy) = | D E F | | 0 1 dy | = | D E D*dx+E*dy+F |
     for (int i = 0; i < 2; ++i ) {
         SkMatrix matrix;
         i == 0 ? matrix.reset(): matrix.setRotate(25, rect.centerX(), 320);
-        { 
+        {
             SkAutoCanvasRestore acr(canvas, true);
             canvas->concat(matrix);
             paint.setColor(SK_ColorGRAY);
@@ -1940,7 +1943,7 @@ Matrix = | D E F |,  S(sx, sy, px, py) = |  0 sy dy |
          | G H I |                       |  0  0  1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2043,7 +2046,7 @@ Matrix = | D E F |,  R(degrees, px, py) = | s  c dy |
          | G H I |                        | 0  0  1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2100,7 +2103,7 @@ Matrix = | D E F |,  R(degrees, px, py) = | s  c 0 |
          | G H I |                        | 0  0 1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2153,7 +2156,7 @@ Matrix = | D E F |,  K(kx, ky, px, py) = | ky  1 dy |
          | G H I |                       |  0  0  1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2324,7 +2327,7 @@ Compare with preTranslate example.
     for (int i = 0; i < 2; ++i ) {
         SkMatrix matrix;
         i == 0 ? matrix.reset(): matrix.setRotate(25, rect.centerX(), 320);
-        { 
+        {
             SkAutoCanvasRestore acr(canvas, true);
             canvas->concat(matrix);
             paint.setColor(SK_ColorGRAY);
@@ -2340,7 +2343,7 @@ Compare with preTranslate example.
     }
 ##
 
-#SeeAlso preTranslate setTranslate MakeTrans 
+#SeeAlso preTranslate setTranslate MakeTrans
 
 #Method ##
 
@@ -2363,7 +2366,7 @@ Matrix = | M N O |,  S(sx, sy, px, py) = |  0 sy dy |
          | P Q R |                       |  0  0  1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2467,7 +2470,7 @@ Matrix = | M N O |,  I(divx, divy) = |  0 sy  0 |
          | P Q R |                   |  0  0  1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2525,7 +2528,7 @@ Matrix = | M N O |,  R(degrees, px, py) = | s  c dy |
          | P Q R |                        | 0  0  1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2582,7 +2585,7 @@ Matrix = | M N O |,  R(degrees, px, py) = | s  c 0 |
          | P Q R |                        | 0  0 1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2635,7 +2638,7 @@ Matrix = | M N O |,  K(kx, ky, px, py) = | ky  1 dy |
          | P Q R |                       |  0  0  1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -2764,7 +2767,7 @@ canvas->drawBitmap(source, 0, 0);
 # ------------------------------------------------------------------------------
 
 #Enum ScaleToFit
-
+#Line # options to map Rects ##
 #Code
     enum ScaleToFit {
         kFill_ScaleToFit,
@@ -2780,21 +2783,25 @@ or may restrict Matrix to square scaling. If restricted, ScaleToFit specifies
 how Matrix maps to the side or center of the destination Rect.
 
 #Const kFill_ScaleToFit 0
+#Line # scales in x and y to fill destination Rect ##
     Computes Matrix that scales in x and y independently, so that source Rect is
     mapped to completely fill destination Rect. The aspect ratio of source Rect
     may change.
 ##
 #Const kStart_ScaleToFit 1
+#Line # scales and aligns to left and top ##
     Computes Matrix that maintains source Rect aspect ratio, mapping source Rect
     width or height to destination Rect. Aligns mapping to left and top edges
     of destination Rect.
 ##
 #Const kCenter_ScaleToFit 2
+#Line # scales and aligns to center ##
     Computes Matrix that maintains source Rect aspect ratio, mapping source Rect
     width or height to destination Rect. Aligns mapping to center of destination
     Rect.
 ##
 #Const kEnd_ScaleToFit 3
+#Line # scales and aligns to right and bottom ##
     Computes Matrix that maintains source Rect aspect ratio, mapping source Rect
     width or height to destination Rect. Aligns mapping to right and bottom
     edges of destination Rect.
@@ -2879,7 +2886,7 @@ src: 1, 2, 3, 4  dst: 5, 6, 8, 9  success: true
 ##
 ##
 
-#SeeAlso MakeRectToRect ScaleToFit setPolyToPoly SkRect::isEmpty 
+#SeeAlso MakeRectToRect ScaleToFit setPolyToPoly SkRect::isEmpty
 
 ##
 
@@ -2947,7 +2954,7 @@ If count is zero, sets Matrix to identity and returns true.
 If count is one, sets Matrix to translate and returns true.
 If count is two or more, sets Matrix to map Points if possible; returns false
 if Matrix cannot be constructed. If count is four, Matrix may include
-perspective. 
+perspective.
 
 #Param src  Points to map from ##
 #Param dst  Points to map to ##
@@ -3091,7 +3098,7 @@ if (matrix.asAffine(affine)) {
     SkDebugf("\n");
 }
 #StdOut
-ScaleX: 2 SkewY: 5 SkewX: 3 ScaleY: 6 TransX: 4 TransY: 7 
+ScaleX: 2 SkewY: 5 SkewX: 3 ScaleY: 6 TransX: 4 TransY: 7
 ##
 ##
 
@@ -3140,7 +3147,7 @@ if (matrix.asAffine(affine)) {
     matrix.dump();
 }
 #StdOut
-ScaleX: 2 SkewY: 5 SkewX: 3 ScaleY: 6 TransX: 4 TransY: 7 
+ScaleX: 2 SkewY: 5 SkewX: 3 ScaleY: 6 TransX: 4 TransY: 7
 [  2.0000   3.0000   4.0000][  5.0000   6.0000   7.0000][  0.0000   0.0000   1.0000]
 ##
 ##
@@ -3168,7 +3175,7 @@ Matrix = | D E F |,  pt = | y |
          | G H I |        | 1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -3227,7 +3234,7 @@ Matrix = | D E F |,  pt = | y |
          | G H I |        | 1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -3436,7 +3443,7 @@ Matrix = | D E 0 |,  src = | y |
          | G H I |         | 1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -3497,7 +3504,7 @@ Matrix = | D E 0 |,  vec = | y |
          | G H I |         | 1 |
 ##
 
-where 
+where
 
 #Code
 #Literal
@@ -3711,7 +3718,7 @@ Returned value is the same as calling rectStaysRect.
 Maps four corners of rect to dst. Points are mapped by multiplying each
 rect corner by Matrix. rect corner is processed in this order:
 (rect.fLeft, rect.fTop), (rect.fRight, rect.fTop), (rect.fRight, rect.fBottom),
-(rect.fLeft, rect.fBottom). 
+(rect.fLeft, rect.fBottom).
 
 rect may be empty: rect.fLeft may be greater than or equal to rect.fRight;
 rect.fTop may be greater than or equal to rect.fBottom.
@@ -4162,7 +4169,7 @@ matrix.getMaxScale() 42
 #Method bool SK_WARN_UNUSED_RESULT getMinMaxScales(SkScalar scaleFactors[2]) const
 #In Property
 #Line # returns minimum and maximum scaling, if possible ##
-Sets scaleFactors[0] to the minimum scaling factor, and scaleFactors[1] to the 
+Sets scaleFactors[0] to the minimum scaling factor, and scaleFactors[1] to the
 maximum scaling factor. Scaling factors are computed by decomposing
 the Matrix scaling and skewing elements.
 
@@ -4205,7 +4212,7 @@ to determine if Matrix can be decomposed without computing remainder.
 
 Returns true if scale components are found. scale and remaining are
 unchanged if Matrix contains perspective; scale factors are not finite, or
-are nearly zero. 
+are nearly zero.
 
 On success
 
@@ -4362,7 +4369,7 @@ canvas->drawBitmap(source, 0, 0);
 #Method void dirtyMatrixTypeCache()
 #In Utility
 #Line # sets internal cache to unknown state ##
-Sets internal cache to unknown state. Use to force update after repeated 
+Sets internal cache to unknown state. Use to force update after repeated
 modifications to Matrix element reference returned by operator[](int index).
 
 #Example