[region] Add documentation for all the new region methods.

1 files changed, 229 insertions, 31 deletions

diff --git a/src/cairo-region.c b/src/cairo-region.c
index aec1bdf1..e162321b 100644
--- a/src/cairo-region.c
+++ b/src/cairo-region.c
@@ -76,6 +76,19 @@ cairo_region_set_error (cairo_region_t *region,
     return _cairo_error (status);
 }
 
+/**
+ * cairo_region_create:
+ *
+ * Allocates a new empty region object.
+ * 
+ * Return value: A newly allocated #cairo_region_t. Free with
+ *   cairo_region_destroy(). This function always returns a
+ *   valid pointer; if memory cannot be allocated, then a special
+ *   error object is returned where all operations on the object do nothing.
+ *   You can check for this with cairo_region_status().
+ * 
+ * Since: 1.10
+ **/
 cairo_region_t *
 cairo_region_create (void)
 {
@@ -91,8 +104,22 @@ cairo_region_create (void)
     return region;
 }
 
+/**
+ * cairo_region_create_rectangle:
+ * @rectangle: a #cairo_rectangle_int_t
+ *
+ * Allocates a new region object containing @rectangle.
+ * 
+ * Return value: A newly allocated #cairo_region_t. Free with
+ *   cairo_region_destroy(). This function always returns a
+ *   valid pointer; if memory cannot be allocated, then a special
+ *   error object is returned where all operations on the object do nothing.
+ *   You can check for this with cairo_region_status().
+ * 
+ * Since: 1.10
+ **/
 cairo_region_t *
-cairo_region_create_rectangle (cairo_rectangle_int_t *rect)
+cairo_region_create_rectangle (cairo_rectangle_int_t *rectangle)
 {
     cairo_region_t *region = _cairo_malloc (sizeof (cairo_region_t));
 
@@ -102,22 +129,26 @@ cairo_region_create_rectangle (cairo_rectangle_int_t *rect)
     region->status = CAIRO_STATUS_SUCCESS;
     
     pixman_region32_init_rect (&region->rgn,
-			       rect->x, rect->y,
-			       rect->width, rect->height);
+			       rectangle->x, rectangle->y,
+			       rectangle->width, rectangle->height);
 
     return region;
 }
 
-void
-cairo_region_destroy (cairo_region_t *region)
-{
-    if (region->status)
-	return;
-    
-    pixman_region32_fini (&region->rgn);
-    free (region);
-}
-
+/**
+ * cairo_region_copy:
+ * @original: a #cairo_region_t
+ * 
+ * Allocates a new region object copying the area from @original.
+ * 
+ * Return value: A newly allocated #cairo_region_t. Free with
+ *   cairo_region_destroy(). This function always returns a
+ *   valid pointer; if memory cannot be allocated, then a special
+ *   error object is returned where all operations on the object do nothing.
+ *   You can check for this with cairo_region_status().
+ * 
+ * Since: 1.10
+ **/
 cairo_region_t *
 cairo_region_copy (cairo_region_t *original)
 {
@@ -139,6 +170,36 @@ cairo_region_copy (cairo_region_t *original)
     return copy;
 }
 
+/**
+ * cairo_region_destroy:
+ * @region: a #cairo_region_t
+ * 
+ * Destroys a #cairo_region_t object created with
+ * cairo_region_create(), cairo_region_copy(), or
+ * or cairo_region_create_rectangle().
+ * 
+ * Since: 1.10
+ **/
+void
+cairo_region_destroy (cairo_region_t *region)
+{
+    if (region->status)
+	return;
+    
+    pixman_region32_fini (&region->rgn);
+    free (region);
+}
+
+/**
+ * cairo_region_num_rectangles:
+ * @region: a #cairo_region_t
+ * 
+ * Returns the number of rectangles contained in @region.
+ * 
+ * Return value: The number of rectangles contained in @region.
+ * 
+ * Since: 1.10
+ **/
 int
 cairo_region_num_rectangles (cairo_region_t *region)
 {
@@ -148,30 +209,42 @@ cairo_region_num_rectangles (cairo_region_t *region)
     return pixman_region32_n_rects (&region->rgn);
 }
 
+/**
+ * cairo_region_get_rectangle:
+ * @region: a #cairo_region_t
+ * @nth: a number indicating which rectangle should be returned
+ * @rectangle: return location for a #cairo_rectangle_int_t
+ * 
+ * Stores the @nth rectangle from the region in @rectangle.
+ * 
+ * Since: 1.10
+ **/
 void
 cairo_region_get_rectangle (cairo_region_t *region,
-			    int nth_box,
-			    cairo_rectangle_int_t *rect)
+			    int nth,
+			    cairo_rectangle_int_t *rectangle)
 {
     pixman_box32_t *pbox;
 
     if (region->status)
 	return;
     
-    pbox = pixman_region32_rectangles (&region->rgn, NULL) + nth_box;
+    pbox = pixman_region32_rectangles (&region->rgn, NULL) + nth;
 
-    rect->x = pbox->x1;
-    rect->y = pbox->y1;
-    rect->width = pbox->x2 - pbox->x1;
-    rect->height = pbox->y2 - pbox->y1;
+    rectangle->x = pbox->x1;
+    rectangle->y = pbox->y1;
+    rectangle->width = pbox->x2 - pbox->x1;
+    rectangle->height = pbox->y2 - pbox->y1;
 }
 
 /**
  * cairo_region_get_extents:
  * @region: a #cairo_region_t
- * @rect: rectangle into which to store the extents
+ * @rectangle: rectangle into which to store the extents
  *
- * Gets the bounding box of a region as a #cairo_rectangle_int_t
+ * Gets the bounding rectangle of @region as a #cairo_rectangle_int_t
+ *
+ * Since: 1.10
  **/
 void
 cairo_region_get_extents (cairo_region_t *region,
@@ -190,12 +263,34 @@ cairo_region_get_extents (cairo_region_t *region,
     extents->height = pextents->y2 - pextents->y1;
 }
 
+/**
+ * cairo_region_status:
+ * @region: a #cairo_region_t
+ * 
+ * Checks whether an error has previous occured for this
+ * region object.
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ * 
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_region_status (cairo_region_t *region)
 {
     return region->status;
 }
 
+/**
+ * cairo_region_subtract:
+ * @dst: a #cairo_region_t 
+ * @other: another #cairo_region_t
+ * 
+ * Subtracts @other from @dst and places the result in @dst
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ * 
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_region_subtract (cairo_region_t *dst, cairo_region_t *other)
 {
@@ -211,6 +306,17 @@ cairo_region_subtract (cairo_region_t *dst, cairo_region_t *other)
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_region_subtract_rectangle:
+ * @dst: a #cairo_region_t
+ * @rectangle: a #cairo_rectangle_int_t
+ *
+ * Subtracts @rectangle from @dst and places the result in @dst
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ * 
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_region_subtract_rectangle (cairo_region_t *dst,
 				 cairo_rectangle_int_t *rectangle)
@@ -233,6 +339,17 @@ cairo_region_subtract_rectangle (cairo_region_t *dst,
     return status;
 }
 
+/**
+ * cairo_region_intersect:
+ * @dst: a #cairo_region_t
+ * @other: another #cairo_region_t
+ * 
+ * Computes the intersection of @dst with @other and places the result in @dst
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ * 
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_region_intersect (cairo_region_t *dst, cairo_region_t *other)
 {
@@ -248,9 +365,20 @@ cairo_region_intersect (cairo_region_t *dst, cairo_region_t *other)
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_region_intersect_rectangle:
+ * @dst: a #cairo_region_t
+ * @rectangle: a #cairo_rectangle_int_t
+ * 
+ * Computes the intersection of @dst with @rectangle and places the result in @dst
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ * 
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_region_intersect_rectangle (cairo_region_t *dst,
-				  const cairo_rectangle_int_t *rect)
+				  const cairo_rectangle_int_t *rectangle)
 {
     cairo_status_t status = CAIRO_STATUS_SUCCESS;
     pixman_region32_t region;
@@ -259,7 +387,8 @@ cairo_region_intersect_rectangle (cairo_region_t *dst,
 	return dst->status;
     
     pixman_region32_init_rect (&region,
-			       rect->x, rect->y, rect->width, rect->height);
+			       rectangle->x, rectangle->y,
+			       rectangle->width, rectangle->height);
 
     if (!pixman_region32_intersect (&dst->rgn, &dst->rgn, &region))
 	status = cairo_region_set_error (dst, CAIRO_STATUS_NO_MEMORY);
@@ -269,6 +398,17 @@ cairo_region_intersect_rectangle (cairo_region_t *dst,
     return status;
 }
 
+/**
+ * cairo_region_union:
+ * @dst: a #cairo_region_t
+ * @other: another #cairo_region_t
+ * 
+ * Computes the union of @dst with @other and places the result in @dst
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ * 
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_region_union (cairo_region_t *dst,
 		    cairo_region_t *other)
@@ -285,15 +425,27 @@ cairo_region_union (cairo_region_t *dst,
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_region_union_rectangle:
+ * @dst: a #cairo_region_t
+ * @rectangle: a #cairo_rectangle_int_t
+ * 
+ * Computes the union of @dst with @rectangle and places the result in @dst.
+ * 
+ * Return value: %CAIRO_STATUS_SUCCESS or %CAIRO_STATUS_NO_MEMORY
+ * 
+ * Since: 1.10
+ **/
 cairo_status_t
 cairo_region_union_rectangle (cairo_region_t *dst,
-			      const cairo_rectangle_int_t *rect)
+			      const cairo_rectangle_int_t *rectangle)
 {
     cairo_status_t status = CAIRO_STATUS_SUCCESS;
     pixman_region32_t region;
 
     pixman_region32_init_rect (&region,
-			       rect->x, rect->y, rect->width, rect->height);
+			       rectangle->x, rectangle->y,
+			       rectangle->width, rectangle->height);
     
     if (!pixman_region32_union (&dst->rgn, &dst->rgn, &region))
 	status = cairo_region_set_error (dst, CAIRO_STATUS_NO_MEMORY);
@@ -303,6 +455,16 @@ cairo_region_union_rectangle (cairo_region_t *dst,
     return status;
 }
 
+/**
+ * cairo_region_empty:
+ * @region: a #cairo_region_t
+ * 
+ * Checks whether @region is empty.
+ * 
+ * Return value: %TRUE if @region is empty, %FALSE if it isn't.
+ * 
+ * Since: 1.10
+ **/
 cairo_bool_t
 cairo_region_empty (cairo_region_t *region)
 {
@@ -312,6 +474,16 @@ cairo_region_empty (cairo_region_t *region)
     return !pixman_region32_not_empty (&region->rgn);
 }
 
+/**
+ * cairo_region_translate:
+ * @region: a #cairo_region_t
+ * @dx: Amount to translate in the x direction
+ * @dy: Amount to translate in the y direction
+ * 
+ * Translates @region by (@dx, @dy).
+ * 
+ * Since: 1.10
+ **/
 void
 cairo_region_translate (cairo_region_t *region,
 			int dx, int dy)
@@ -322,19 +494,33 @@ cairo_region_translate (cairo_region_t *region,
     pixman_region32_translate (&region->rgn, dx, dy);
 }
 
+/**
+ * cairo_region_contains_rectangle:
+ * @region: a #cairo_region_t
+ * @rectangle: a #cairo_rectangle_int_t
+ * 
+ * Checks whether @rectangle is inside, outside or partially contained in @region
+ * 
+ * Return value:
+ *   %CAIRO_REGION_OVERLAP_IN if @rectangle is entirely inside @region,
+ *   %CAIRO_REGION_OVERLAP_OUT if @rectangle is entirely outside @region, or
+ *   %CAIRO_REGION_OVERLAP_PART if @rectangle is partially inside and partially outside @region.
+ * 
+ * Since: 1.10
+ **/
 cairo_region_overlap_t
 cairo_region_contains_rectangle (cairo_region_t *region,
-				 const cairo_rectangle_int_t *rect)
+				 const cairo_rectangle_int_t *rectangle)
 {
     pixman_box32_t pbox;
     pixman_region_overlap_t poverlap;
 
     if (!region->status)
     {
-	pbox.x1 = rect->x;
-	pbox.y1 = rect->y;
-	pbox.x2 = rect->x + rect->width;
-	pbox.y2 = rect->y + rect->height;
+	pbox.x1 = rectangle->x;
+	pbox.y1 = rectangle->y;
+	pbox.x2 = rectangle->x + rectangle->width;
+	pbox.y2 = rectangle->y + rectangle->height;
 	
 	poverlap = pixman_region32_contains_rectangle (&region->rgn, &pbox);
 	
@@ -354,6 +540,18 @@ cairo_region_contains_rectangle (cairo_region_t *region,
     return CAIRO_REGION_OVERLAP_OUT;
 }
 
+/**
+ * cairo_region_contains_point:
+ * @region: a #cairo_region_t
+ * @x: the x coordinate of a point
+ * @y: the y coordinate of a point
+ * 
+ * Checks whether (@x, @y) is contained in @region.
+ * 
+ * Return value: %TRUE if (@x, @y) is contained in @region, %FALSE if it is not.
+ * 
+ * Since: 1.10
+ **/
 cairo_bool_t
 cairo_region_contains_point (cairo_region_t *region,
 			     int x, int y)