update dox

git-svn-id: http://skia.googlecode.com/svn/trunk@1318 2bbb7eff-a529-9590-31e7-b0007b416f81

diff --git a/include/core/SkRect.h b/include/core/SkRect.h
index eb8815c..68a51d1 100644 (file)
--- a/include/core/SkRect.h
+++ b/include/core/SkRect.h
@@ -460,9 +460,10 @@ struct SK_API SkRect {
     */
     bool intersect(SkScalar left, SkScalar top, SkScalar right, SkScalar bottom);
 
-    /** Return true if this rectangle is not empty, and the specified sides of
-        a rectangle are not empty, and they intersect.
-    */
+    /**
+     *  Return true if this rectangle is not empty, and the specified sides of
+     *  a rectangle are not empty, and they intersect.
+     */
     bool intersects(SkScalar left, SkScalar top, SkScalar right, SkScalar bottom) const {
         return // first check that both are not empty
                left < right && top < bottom &&
@@ -472,18 +473,20 @@ struct SK_API SkRect {
                fTop < bottom && top < fBottom;
     }
     
-    /** Return true if rectangles a and b are not empty and intersect.
-        */
+    /**
+     *  Return true if rectangles a and b are not empty and intersect.
+     */
     static bool Intersects(const SkRect& a, const SkRect& b) {
-        return  !a.isEmpty() && !b.isEmpty() &&             // check for empties
-        a.fLeft < b.fRight && b.fLeft < a.fRight &&
-        a.fTop < b.fBottom && b.fTop < a.fBottom;
+        return  !a.isEmpty() && !b.isEmpty() &&
+                a.fLeft < b.fRight && b.fLeft < a.fRight &&
+                a.fTop < b.fBottom && b.fTop < a.fBottom;
     }
     
-    /** Update this rectangle to enclose itself and the specified rectangle.
-        If this rectangle is empty, just set it to the specified rectangle. If the specified
-        rectangle is empty, do nothing.
-    */
+    /**
+     *  Update this rectangle to enclose itself and the specified rectangle.
+     *  If this rectangle is empty, just set it to the specified rectangle.
+     *  If the specified rectangle is empty, do nothing.
+     */
     void join(SkScalar left, SkScalar top, SkScalar right, SkScalar bottom);
 
     /** Update this rectangle to enclose itself and the specified rectangle.
@@ -496,6 +499,15 @@ struct SK_API SkRect {
     // alias for join()
     void growToInclude(const SkRect& r) { this->join(r); }
 
+    /**
+     *  Grow the rect to include the specified (x,y). After this call, the
+     *  following will be true: fLeft <= x <= fRight && fTop <= y <= fBottom.
+     *
+     *  This is close, but not quite the same contract as contains(), since
+     *  contains() treats the left and top different from the right and bottom.
+     *  contains(x,y) -> fLeft <= x < fRight && fTop <= y < fBottom. Also note
+     *  that contains(x,y) always returns false if the rect is empty.
+     */
     void growToInclude(SkScalar x, SkScalar y) {
         fLeft  = SkMinScalar(x, fLeft);
         fRight = SkMaxScalar(x, fRight);
@@ -503,60 +515,70 @@ struct SK_API SkRect {
         fBottom = SkMaxScalar(y, fBottom);
     }
     
-    /** Returns true if (p.fX,p.fY) is inside the rectangle. The left and top coordinates of
-        the rectangle are considered to be inside, while the right and bottom coordinates
-        are not. Thus for the rectangle (0, 0, 5, 10), the points (0,0) and (0,9) are inside,
-        while (-1,0) and (5,9) are not.
-        If this rectangle is empty, return false.
-    */
+    /**
+     *  Returns true if (p.fX,p.fY) is inside the rectangle, and the rectangle
+     *  is not empty.
+     *
+     *  Contains treats the left and top differently from the right and bottom.
+     *  The left and top coordinates of the rectangle are themselves considered
+     *  to be inside, while the right and bottom are not. Thus for the rectangle
+     *  {0, 0, 5, 10}, (0,0) is contained, but (0,10), (5,0) and (5,10) are not.
+     */
     bool contains(const SkPoint& p) const {
-        return  !this->isEmpty() &&
-                fLeft <= p.fX && p.fX < fRight &&
-                fTop <= p.fY && p.fY < fBottom;
+        return !this->isEmpty() &&
+               fLeft <= p.fX && p.fX < fRight && fTop <= p.fY && p.fY < fBottom;
     }
 
-    /** Returns true if (x,y) is inside the rectangle. The left and top coordinates of
-        the rectangle are considered to be inside, while the right and bottom coordinates
-        are not. Thus for the rectangle (0, 0, 5, 10), the points (0,0) and (0,9) are inside,
-        while (-1,0) and (5,9) are not.
-        If this rectangle is empty, return false.
-    */
+    /**
+     *  Returns true if (x,y) is inside the rectangle, and the rectangle
+     *  is not empty.
+     *
+     *  Contains treats the left and top differently from the right and bottom.
+     *  The left and top coordinates of the rectangle are themselves considered
+     *  to be inside, while the right and bottom are not. Thus for the rectangle
+     *  {0, 0, 5, 10}, (0,0) is contained, but (0,10), (5,0) and (5,10) are not.
+     */
     bool contains(SkScalar x, SkScalar y) const {
         return  !this->isEmpty() &&
-                fLeft <= x && x < fRight &&
-                fTop <= y && y < fBottom;
+                fLeft <= x && x < fRight && fTop <= y && y < fBottom;
     }
 
-    /** Return true if this rectangle contains r.
-        If either rectangle is empty, return false.
-    */
+    /**
+     *  Return true if this rectangle contains r, and if both rectangles are
+     *  not empty.
+     */
     bool contains(const SkRect& r) const {
-        return  !r.isEmpty() && !this->isEmpty() &&     // check for empties
+        return  !r.isEmpty() && !this->isEmpty() &&
                 fLeft <= r.fLeft && fTop <= r.fTop &&
                 fRight >= r.fRight && fBottom >= r.fBottom;
     }
 
-    /** Set the dst integer rectangle by rounding this rectangle's coordinates
-        to their nearest integer values.
-    */
+    /**
+     *  Set the dst rectangle by rounding this rectangle's coordinates to their
+     *  nearest integer values using SkScalarRound.
+     */
     void round(SkIRect* dst) const {
         SkASSERT(dst);
-        dst->set(SkScalarRound(fLeft), SkScalarRound(fTop), SkScalarRound(fRight), SkScalarRound(fBottom));
+        dst->set(SkScalarRound(fLeft), SkScalarRound(fTop),
+                 SkScalarRound(fRight), SkScalarRound(fBottom));
     }
 
-    /** Set the dst integer rectangle by rounding "out" this rectangle, choosing the floor of top and left,
-        and the ceiling of right and bototm.
-    */
+    /**
+     *  Set the dst rectangle by rounding "out" this rectangle, choosing the
+     *  SkScalarFloor of top and left, and the SkScalarCeil of right and bottom.
+     */
     void roundOut(SkIRect* dst) const {
         SkASSERT(dst);
-        dst->set(SkScalarFloor(fLeft), SkScalarFloor(fTop), SkScalarCeil(fRight), SkScalarCeil(fBottom));
+        dst->set(SkScalarFloor(fLeft), SkScalarFloor(fTop),
+                 SkScalarCeil(fRight), SkScalarCeil(fBottom));
     }
 
-    /** Swap top/bottom or left/right if there are flipped.
-        This can be called if the edges are computed separately,
-        and may have crossed over each other.
-        When this returns, left <= right && top <= bottom
-    */
+    /**
+     *  Swap top/bottom or left/right if there are flipped (i.e. if width()
+     *  or height() would have returned a negative value.) This should be called
+     *  if the edges are computed separately, and may have crossed over each
+     *  other. When this returns, left <= right && top <= bottom
+     */
     void sort();
 };