[libdazzle: 2/5] docs: dzl-cairo

[Christian Hergert <chergert src gnome org>]

commit b350746496f25a1618427c0497757ff592092a7e
Author: FlyingPiMonster <flyingpimonster flyingpimonster net>
Date:   Mon Dec 17 17:51:29 2018 -0600

    docs: dzl-cairo

 src/util/dzl-cairo.c | 24 ++++++++++++++++++++++++
 src/util/dzl-cairo.h | 32 ++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
---
diff --git a/src/util/dzl-cairo.c b/src/util/dzl-cairo.c
index fcc390c..c88bd97 100644
--- a/src/util/dzl-cairo.c
+++ b/src/util/dzl-cairo.c
@@ -22,6 +22,21 @@
 
 #include "dzl-cairo.h"
 
+/**
+ * SECTION:dzl-cairo
+ * @title: Cairo Utilities
+ * @short_description: Some utility functions to use with the Cairo graphics library
+ *
+ * [Cairo](https://cairographics.org) is the graphics library that GTK uses to draw widgets.
+ * This section contains functions for commonly used calculations with Cairo objects.
+ */
+
+/**
+ * dzl_cairo_region_create_from_clip_extents:
+ * @cr a cairo context
+ *
+ * Creates a region from the extents of the context's current clip area.
+ */
 cairo_region_t *
 dzl_cairo_region_create_from_clip_extents (cairo_t *cr)
 {
@@ -39,6 +54,15 @@ dzl_cairo_region_create_from_clip_extents (cairo_t *cr)
   return cairo_region_create_rectangle (&crect);
 }
 
+/**
+ * dzl_cairo_rounded_rectangle:
+ * @cr: a cairo context
+ * @rect: a #GdkRectangle to draw
+ * @x_radius: the radius of the corners on the X axis
+ * @y_radius: the radius of the corners on the Y axis
+ *
+ * Adds a rounded rectangle to @cr's current path.
+ */
 void
 dzl_cairo_rounded_rectangle (cairo_t            *cr,
                             const GdkRectangle *rect,
diff --git a/src/util/dzl-cairo.h b/src/util/dzl-cairo.h
index 03b70c5..cb7cd95 100644
--- a/src/util/dzl-cairo.h
+++ b/src/util/dzl-cairo.h
@@ -33,30 +33,62 @@ void            dzl_cairo_rounded_rectangle               (cairo_t            *c
                                                            gint                x_radius,
                                                            gint                y_radius);
 
+/**
+ * dzl_cairo_rectangle_x2:
+ * @rect: the cairo rectangle to find the right side of
+ *
+ * Finds the X coordinate of the right side of a rectangle.
+ */
 static inline gint
 dzl_cairo_rectangle_x2 (const cairo_rectangle_int_t *rect)
 {
   return rect->x + rect->width;
 }
 
+/**
+ * dzl_cairo_rectangle_y2:
+ * @rect: the cairo rectangle to find the bottom of
+ *
+ * Finds the Y coordinate of the bottom of a rectangle.
+ */
 static inline gint
 dzl_cairo_rectangle_y2 (const cairo_rectangle_int_t *rect)
 {
   return rect->y + rect->height;
 }
 
+/**
+ * dzl_cairo_rectangle_center:
+ * @rect: the cairo rectangle to find the center of
+ *
+ * Finds the X coordinate of the center of a rectangle.
+ */
 static inline gint
 dzl_cairo_rectangle_center (const cairo_rectangle_int_t *rect)
 {
   return rect->x + (rect->width/2);
 }
 
+/**
+ * dzl_cairo_rectangle_middle:
+ * @rect: the cairo rectangle to find the center of
+ *
+ * Finds the Y coordinate of the center of a rectangle.
+ */
 static inline gint
 dzl_cairo_rectangle_middle (const cairo_rectangle_int_t *rect)
 {
   return rect->y + (rect->height/2);
 }
 
+/**
+ * dzl_cairo_rectangle_contains_rectangle:
+ * @a: the outer rectangle
+ * @b: the inner rectangle
+ *
+ * Determines whether rectangle @a completely contains rectangle @b.
+ * @b may share edges with @a and still be considered contained.
+ */
 static inline cairo_bool_t
 dzl_cairo_rectangle_contains_rectangle (const cairo_rectangle_int_t *a,
                                         const cairo_rectangle_int_t *b)