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>
diff --git a/docs/SkRect_Reference.bmh b/docs/SkRect_Reference.bmh
index d3ba4c3..73225fc 100644
--- a/docs/SkRect_Reference.bmh
+++ b/docs/SkRect_Reference.bmh
@@ -2,16 +2,10 @@
#Alias Rects
#Alias Rect_Reference
-#Subtopic Overview
- #Subtopic Subtopic
- #Populate
- ##
-##
-
#Struct SkRect
SkRect holds four SkScalar coordinates describing the upper and
-lower bounds of a rectangle. SkRect may be created from outer bounds or
+lower bounds of a rectangle. SkRect may be created from outer bounds or
from position, width, and height. SkRect describes an area; if its right
is less than or equal to its left, or if its bottom is less than or equal to
its top, it is considered empty.
@@ -20,9 +14,13 @@
SkRect can be constructed from int values to avoid compiler warnings that
integer input cannot convert to SkScalar without loss of precision.
+#Subtopic Overview
+#Populate
+##
+
#Subtopic Related_Function
#Populate
-#Subtopic ##
+##
#Subtopic Member_Function
#Populate
@@ -70,7 +68,7 @@
Many other rectangles are empty; if left is equal to or greater than right,
or if top is equal to or greater than bottom. Setting all members to zero
is a convenience, but does not designate a special empty rectangle.
-
+
#Return bounds (0, 0, 0, 0) ##
#Example
@@ -274,7 +272,7 @@
#In Constructor
#Line # constructs from ISize returning (0, 0, width, height) ##
-Returns constructed IRect set to (0, 0, size.width(), size.height()).
+Returns constructed IRect set to (0, 0, size.width(), size.height()).
Does not validate input; size.width() or size.height() may be negative.
#Param size integer values for Rect width and height ##
@@ -399,7 +397,7 @@
#In Property
#Line # returns true if no member is infinite or NaN ##
Returns true if all values in the rectangle are finite: SK_ScalarMin or larger,
-and SK_ScalarMax or smaller.
+and SK_ScalarMax or smaller.
#Return true if no member is infinite or NaN ##
@@ -700,7 +698,7 @@
#In Operator
#Line # returns true if members are equal ##
-Returns true if all members in a: fLeft, fTop, fRight, and fBottom; are
+Returns true if all members in a: fLeft, fTop, fRight, and fBottom; are
equal to the corresponding members in b.
a and b are not equal if either contain NaN. a and b are equal if members
@@ -731,7 +729,7 @@
tests are equal
{0, 0, 2, 2} == {-0, -0, 2, 2} and are numerically equal
{0, 0, 2, 2} == {-0, -0, 2, 2} and are numerically equal
-{0, 0, 2, 2} == {-0, -0, 2, 2} and are numerically equal
+{0, 0, 2, 2} == {-0, -0, 2, 2} and are numerically equal
##
##
@@ -745,7 +743,7 @@
#In Operator
#Line # returns true if members are unequal ##
-Returns true if any in a: fLeft, fTop, fRight, and fBottom; does not
+Returns true if any in a: fLeft, fTop, fRight, and fBottom; does not
equal the corresponding members in b.
a and b are not equal if either contain NaN. a and b are equal if members
@@ -760,7 +758,7 @@
SkRect test = {0, 0, 2, SK_ScalarNaN};
SkDebugf("test with NaN is %s" "equal to itself\n", test == test ? "" : "not ");
#StdOut
-test with NaN is not equal to itself
+test with NaN is not equal to itself
##
##
@@ -782,10 +780,10 @@
#In As_Points
#Line # returns four corners as Point ##
Returns four points in quad that enclose Rect ordered as: top-left, top-right,
-bottom-right, bottom-left.
+bottom-right, bottom-left.
#Private
-Consider adding param to control whether quad is CW or CCW.
+Consider adding param to control whether quad is clockwise or counterclockwise.
##
#Param quad storage for corners of Rect ##
@@ -802,7 +800,7 @@
SkDebugf("\n");
#StdOut
rect: {1, 2, 3, 4}
-corners: {1, 2} {3, 2} {3, 4} {1, 4}
+corners: {1, 2} {3, 2} {3, 4} {1, 4}
##
##
@@ -937,7 +935,7 @@
#In Set
#Line # sets to SkScalar input (left, top, right, bottom) and others ##
Sets Rect to src, promoting src members from integer to Scalar.
-Very large values in src may lose precision.
+Very large values in src may lose precision.
#Param src integer Rect ##
@@ -1071,7 +1069,7 @@
#Example
#Description
-p0 and p1 may be swapped and have the same effect unless one contains NaN.
+p0 and p1 may be swapped and have the same effect unless one contains NaN.
##
SkPoint point1 = {SK_ScalarNaN, 8};
SkPoint point2 = {3, 4};
@@ -1092,7 +1090,7 @@
#In Set
#Line # sets to SkScalar input (x, y, width, height) ##
-Sets Rect to
+Sets Rect to
#Formula
(x, y, x + width, y + height)
##
@@ -1155,7 +1153,7 @@
#Subtopic Set ##
#Subtopic From_Integers
-#Line # set Scalar values from integer input ##
+#Line # sets Scalar values from integer input ##
#Populate
@@ -1238,7 +1236,7 @@
If dx is negative, Rect returned is moved to the left.
If dx is positive, Rect returned is moved to the right.
If dy is negative, Rect returned is moved upward.
-If dy is positive, Rect returned is moved downward.
+If dy is positive, Rect returned is moved downward.
#Param dx added to fLeft and fRight ##
#Param dy added to fTop and fBottom ##
@@ -1273,7 +1271,7 @@
If dx is negative, Rect returned is wider.
If dx is positive, Rect returned is narrower.
If dy is negative, Rect returned is taller.
-If dy is positive, Rect returned is shorter.
+If dy is positive, Rect returned is shorter.
#Param dx added to fLeft and subtracted from fRight ##
#Param dy added to fTop and subtracted from fBottom ##
@@ -1308,7 +1306,7 @@
If dx is negative, Rect returned is narrower.
If dx is positive, Rect returned is wider.
If dy is negative, Rect returned is shorter.
-If dy is positive, Rect returned is taller.
+If dy is positive, Rect returned is taller.
#Param dx subtracted to fLeft and added from fRight ##
#Param dy subtracted to fTop and added from fBottom ##
@@ -1343,7 +1341,7 @@
If dx is negative, moves Rect to the left.
If dx is positive, moves Rect to the right.
If dy is negative, moves Rect upward.
-If dy is positive, moves Rect downward.
+If dy is positive, moves Rect downward.
#Param dx offset added to fLeft and fRight ##
#Param dy offset added to fTop and fBottom ##
@@ -1372,7 +1370,7 @@
If delta.fX is negative, moves Rect to the left.
If delta.fX is positive, moves Rect to the right.
If delta.fY is negative, moves Rect upward.
-If delta.fY is positive, moves Rect downward.
+If delta.fY is positive, moves Rect downward.
#Param delta added to Rect ##
@@ -1475,9 +1473,9 @@
#Subtopic Inset_Outset_Offset ##
#Subtopic Intersection
-#Line # set to shared bounds ##
+#Line # sets to shared bounds ##
-Rects intersect when they enclose a common area. To intersect, each of the pair
+Rects intersect when they enclose a common area. To intersect, each of the pair
must describe area; fLeft is less than fRight, and fTop is less than fBottom;
empty() returns false. The intersection of Rect pair can be described by:
@@ -1618,11 +1616,11 @@
SkRect leftRect = { 10, 40, 50, 80 };
SkRect rightRect = { 30, 60, 70, 90 };
SkDebugf("%s intersection: ", leftRect.intersect(rightRect) ? "" : "no ");
- SkDebugf("%g, %g, %g, %g\n", leftRect.left(), leftRect.top(),
+ SkDebugf("%g, %g, %g, %g\n", leftRect.left(), leftRect.top(),
leftRect.right(), leftRect.bottom());
#StdOut
intersection: 30, 60, 50, 80
-##
+##
##
#SeeAlso intersects Intersects join SkIRect::intersect
@@ -1657,11 +1655,11 @@
##
SkRect leftRect = { 10, 40, 50, 80 };
SkDebugf("%s intersection: ", leftRect.intersect(30, 60, 70, 90) ? "" : "no ");
- SkDebugf("%g, %g, %g, %g\n", leftRect.left(), leftRect.top(),
+ SkDebugf("%g, %g, %g, %g\n", leftRect.left(), leftRect.top(),
leftRect.right(), leftRect.bottom());
#StdOut
intersection: 30, 60, 50, 80
-##
+##
##
#SeeAlso intersects Intersects join SkIRect::intersect
@@ -1690,7 +1688,7 @@
result.left(), result.top(), result.right(), result.bottom());
#StdOut
intersection: 30, 60, 50, 80
-##
+##
##
#SeeAlso intersects Intersects join SkIRect::intersect
@@ -1721,7 +1719,7 @@
SkDebugf("%s intersection", rect.intersects(30, 60, 70, 90) ? "" : "no ");
#StdOut
intersection
-##
+##
##
#SeeAlso intersect Intersects SkIRect::Intersects
@@ -1745,7 +1743,7 @@
SkDebugf("%s intersection", rect.intersects({30, 60, 70, 90}) ? "" : "no ");
#StdOut
intersection
-##
+##
##
#SeeAlso intersect Intersects SkIRect::Intersects
@@ -1770,7 +1768,7 @@
SkDebugf("%s intersection", SkRect::Intersects({10, 40, 50, 80}, {30, 60, 70, 90}) ? "" : "no ");
#StdOut
intersection
-##
+##
##
#SeeAlso intersect intersects SkIRect::Intersects
@@ -1780,7 +1778,7 @@
#Subtopic Intersection ##
#Subtopic Join
-#Line # set to union of bounds ##
+#Line # sets to union of bounds ##
#Populate
@@ -1809,7 +1807,7 @@
SkDebugf("join: %g, %g, %g, %g\n", rect.fLeft, rect.fTop, rect.fRight, rect.fBottom);
#StdOut
join: 10, 20, 55, 65
-##
+##
##
#SeeAlso joinNonEmptyArg joinPossiblyEmptyRect SkIRect::join
@@ -1834,7 +1832,7 @@
SkDebugf("join: %g, %g, %g, %g\n", rect.fLeft, rect.fTop, rect.fRight, rect.fBottom);
#StdOut
join: 10, 20, 55, 65
-##
+##
##
#SeeAlso joinNonEmptyArg joinPossiblyEmptyRect SkIRect::join
@@ -1870,7 +1868,7 @@
#StdOut
rect: 50, 60, 55, 65
sorted: 10, 0, 55, 100
-##
+##
##
#SeeAlso join joinPossiblyEmptyRect SkIRect::join
@@ -1882,7 +1880,7 @@
#Method void joinPossiblyEmptyRect(const SkRect& r)
#In Join
-#Line # sets to union of bounds. Skips empty check for both ##
+#Line # sets to union of bounds; skips empty check for both ##
Sets Rect to the union of itself and the construction.
May produce incorrect results if Rect or r is empty.
@@ -1903,7 +1901,7 @@
#StdOut
rect: 10, 60, 55, 65
sorted: 10, 0, 55, 100
-##
+##
##
#SeeAlso joinNonEmptyArg join SkIRect::join
@@ -1977,7 +1975,7 @@
# ------------------------------------------------------------------------------
-#Method void roundOut(SkRect* dst) const
+#Method void roundOut(SkRect* dst) const
#In Rounding
Sets Rect by discarding the fractional portion of fLeft and fTop; and
@@ -2129,7 +2127,7 @@
#In Sorting
#In Constructor
-#Line # constructs, ordering sides from smaller to larger ##
+#Line # constructs Rect, ordering sides from smaller to larger ##
Returns Rect with fLeft and fRight swapped if fLeft is greater than fRight; and
with fTop and fBottom swapped if fTop is greater than fBottom. Result may be empty;
and width() and height() will be zero or positive.
@@ -2180,7 +2178,7 @@
#Method void dump(bool asHex) const
#In Property
#Line # sends text representation to standard output using floats ##
-Writes text representation of Rect to standard output. Set asHex to true to
+Writes text representation of Rect to standard output. Set asHex to true to
generate exact binary representations of floating point numbers.
#Param asHex true if SkScalar values are written as hexadecimal ##
@@ -2239,8 +2237,8 @@
in hexadecimal to preserve their exact bit pattern. The output reconstructs the
original Rect.
-Use instead of dump() when submitting
-#A bug reports against Skia # http://bug.skia.org ##
+Use instead of dump() when submitting
+#A bug reports against Skia # https://bug.skia.org ##
.
#Example