More GDK documentation tweaks

9 files changed, 333 insertions, 306 deletions

diff --git a/gdk/gdkcairo.c b/gdk/gdkcairo.c
index 0d4b8bde09..2ae8b09459 100644
--- a/gdk/gdkcairo.c
+++ b/gdk/gdkcairo.c
@@ -8,7 +8,7 @@
  *
  * This library is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.	 See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General Public
@@ -27,17 +27,18 @@
 
 /**
  * SECTION:cairo_interaction
- * @Short_description: Functions to support using Cairo
+ * @Short_description: Functions to support using cairo
  * @Title: Cairo Interaction
  *
  * <link href="http://cairographics.org">Cairo</link> is a graphics
  * library that supports vector graphics and image compositing that
- * can be used with GDK. GTK+ does all of its drawing using Cairo.
+ * can be used with GDK. GTK+ does all of its drawing using cairo.
  *
- * GDK does not wrap the Cairo API, instead it allows to create Cairo
+ * GDK does not wrap the cairo API, instead it allows to create cairo
  * contexts which can be used to draw on #GdkWindows. Additional
  * functions allow use #GdkRectangles with cairo and to use #GdkColors,
- * #GdkPixbufs and #GdkWindows as sources for drawing operations.
+ * #GdkRGBAs, #GdkPixbufs and #GdkWindows as sources for drawing
+ * operations.
  */
 
 
@@ -46,13 +47,13 @@
  * @cr: a cairo context
  * @rect: (out) (allow-none): return location for the clip, or %NULL
  *
- * This is a convenience function around cairo_clip_extents(). It rounds
- * the clip extents to integer coordinates and returns a boolean
- * indicating if a clip area exists.
+ * This is a convenience function around cairo_clip_extents().
+ * It rounds the clip extents to integer coordinates and returns
+ * a boolean indicating if a clip area exists.
  *
  * Returns: %TRUE if a clip rectangle exists, %FALSE if all of @cr is
- * clipped and all drawing can be skipped.
- **/
+ *     clipped and all drawing can be skipped
+ */
 gboolean
 gdk_cairo_get_clip_rectangle (cairo_t      *cr,
                               GdkRectangle *rect)
@@ -82,35 +83,35 @@ gdk_cairo_get_clip_rectangle (cairo_t      *cr,
 
 /**
  * gdk_cairo_set_source_color:
- * @cr: a #cairo_t
+ * @cr: a cairo context
  * @color: a #GdkColor
  *
  * Sets the specified #GdkColor as the source color of @cr.
  *
  * Since: 2.8
- **/
+ */
 void
 gdk_cairo_set_source_color (cairo_t        *cr,
-			    const GdkColor *color)
+                            const GdkColor *color)
 {
   g_return_if_fail (cr != NULL);
   g_return_if_fail (color != NULL);
     
   cairo_set_source_rgb (cr,
-			color->red / 65535.,
-			color->green / 65535.,
-			color->blue / 65535.);
+                        color->red / 65535.,
+                        color->green / 65535.,
+                        color->blue / 65535.);
 }
 
 /**
  * gdk_cairo_set_source_rgba:
- * @cr: a #cairo_t
+ * @cr: a cairo context
  * @rgba: a #GdkRGBA
  *
  * Sets the specified #GdkRGBA as the source color of @cr.
  *
  * Since: 3.0
- **/
+ */
 void
 gdk_cairo_set_source_rgba (cairo_t       *cr,
                            const GdkRGBA *rgba)
@@ -127,37 +128,37 @@ gdk_cairo_set_source_rgba (cairo_t       *cr,
 
 /**
  * gdk_cairo_rectangle:
- * @cr: a #cairo_t
+ * @cr: a cairo context
  * @rectangle: a #GdkRectangle
- * 
+ *
  * Adds the given rectangle to the current path of @cr.
  *
  * Since: 2.8
- **/
+ */
 void
 gdk_cairo_rectangle (cairo_t            *cr,
-		     const GdkRectangle *rectangle)
+                     const GdkRectangle *rectangle)
 {
   g_return_if_fail (cr != NULL);
   g_return_if_fail (rectangle != NULL);
 
   cairo_rectangle (cr,
-		   rectangle->x,     rectangle->y,
-		   rectangle->width, rectangle->height);
+                   rectangle->x,     rectangle->y,
+                   rectangle->width, rectangle->height);
 }
 
 /**
  * gdk_cairo_region:
- * @cr: a #cairo_t
+ * @cr: a cairo context
  * @region: a #cairo_region_t
- * 
+ *
  * Adds the given region to the current path of @cr.
  *
  * Since: 2.8
- **/
+ */
 void
 gdk_cairo_region (cairo_t         *cr,
-		  const cairo_region_t *region)
+                  const cairo_region_t *region)
 {
   cairo_rectangle_int_t box;
   gint n_boxes, i;
@@ -176,22 +177,23 @@ gdk_cairo_region (cairo_t         *cr,
 
 /**
  * gdk_cairo_set_source_pixbuf:
- * @cr: a #Cairo context
+ * @cr: a cairo context
  * @pixbuf: a #GdkPixbuf
  * @pixbuf_x: X coordinate of location to place upper left corner of @pixbuf
  * @pixbuf_y: Y coordinate of location to place upper left corner of @pixbuf
- * 
- * Sets the given pixbuf as the source pattern for the Cairo context.
+ *
+ * Sets the given pixbuf as the source pattern for @cr.
+ *
  * The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned
- * so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y
+ * so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y.
  *
  * Since: 2.8
- **/
+ */
 void
 gdk_cairo_set_source_pixbuf (cairo_t         *cr,
-			     const GdkPixbuf *pixbuf,
-			     double           pixbuf_x,
-			     double           pixbuf_y)
+                             const GdkPixbuf *pixbuf,
+                             gdouble          pixbuf_x,
+                             gdouble          pixbuf_y)
 {
   gint width = gdk_pixbuf_get_width (pixbuf);
   gint height = gdk_pixbuf_get_height (pixbuf);
@@ -217,7 +219,7 @@ gdk_cairo_set_source_pixbuf (cairo_t         *cr,
                                                  width, height, cairo_stride);
 
   cairo_surface_set_user_data (surface, &key,
-			       cairo_pixels, (cairo_destroy_func_t)g_free);
+                               cairo_pixels, (cairo_destroy_func_t)g_free);
 
   for (j = height; j; j--)
     {
@@ -225,51 +227,51 @@ gdk_cairo_set_source_pixbuf (cairo_t         *cr,
       guchar *q = cairo_pixels;
 
       if (n_channels == 3)
-	{
-	  guchar *end = p + 3 * width;
-	  
-	  while (p < end)
-	    {
+        {
+          guchar *end = p + 3 * width;
+
+          while (p < end)
+            {
 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
-	      q[0] = p[2];
-	      q[1] = p[1];
-	      q[2] = p[0];
-#else	  
-	      q[1] = p[0];
-	      q[2] = p[1];
-	      q[3] = p[2];
+              q[0] = p[2];
+              q[1] = p[1];
+              q[2] = p[0];
+#else
+              q[1] = p[0];
+              q[2] = p[1];
+              q[3] = p[2];
 #endif
-	      p += 3;
-	      q += 4;
-	    }
-	}
+              p += 3;
+              q += 4;
+            }
+        }
       else
-	{
-	  guchar *end = p + 4 * width;
-	  guint t1,t2,t3;
-	    
+        {
+          guchar *end = p + 4 * width;
+          guint t1,t2,t3;
+
 #define MULT(d,c,a,t) G_STMT_START { t = c * a + 0x7f; d = ((t >> 8) + t) >> 8; } G_STMT_END
 
-	  while (p < end)
-	    {
+          while (p < end)
+            {
 #if G_BYTE_ORDER == G_LITTLE_ENDIAN
-	      MULT(q[0], p[2], p[3], t1);
-	      MULT(q[1], p[1], p[3], t2);
-	      MULT(q[2], p[0], p[3], t3);
-	      q[3] = p[3];
-#else	  
-	      q[0] = p[3];
-	      MULT(q[1], p[0], p[3], t1);
-	      MULT(q[2], p[1], p[3], t2);
-	      MULT(q[3], p[2], p[3], t3);
+              MULT(q[0], p[2], p[3], t1);
+              MULT(q[1], p[1], p[3], t2);
+              MULT(q[2], p[0], p[3], t3);
+              q[3] = p[3];
+#else
+              q[0] = p[3];
+              MULT(q[1], p[0], p[3], t1);
+              MULT(q[2], p[1], p[3], t2);
+              MULT(q[3], p[2], p[3], t3);
 #endif
-	      
-	      p += 4;
-	      q += 4;
-	    }
-	  
+
+              p += 4;
+              q += 4;
+            }
+
 #undef MULT
-	}
+        }
 
       gdk_pixels += gdk_rowstride;
       cairo_pixels += cairo_stride;
@@ -281,12 +283,13 @@ gdk_cairo_set_source_pixbuf (cairo_t         *cr,
 
 /**
  * gdk_cairo_set_source_window:
- * @cr: a #Cairo context
+ * @cr: a cairo context
  * @window: a #GdkWindow
  * @x: X coordinate of location to place upper left corner of @window
  * @y: Y coordinate of location to place upper left corner of @window
  *
- * Sets the given window as the source pattern for the Cairo context.
+ * Sets the given window as the source pattern for @cr.
+ *
  * The pattern has an extend mode of %CAIRO_EXTEND_NONE and is aligned
  * so that the origin of @window is @x, @y. The window contains all its
  * subwindows when rendering.
@@ -299,11 +302,11 @@ gdk_cairo_set_source_pixbuf (cairo_t         *cr,
 void
 gdk_cairo_set_source_window (cairo_t   *cr,
                              GdkWindow *window,
-                             double     x,
-                             double     y)
+                             gdouble    x,
+                             gdouble    y)
 {
   cairo_surface_t *surface;
-  
+
   g_return_if_fail (cr != NULL);
   g_return_if_fail (GDK_IS_WINDOW (window));
 
@@ -312,23 +315,24 @@ gdk_cairo_set_source_window (cairo_t   *cr,
   cairo_surface_destroy (surface);
 }
 
-/**
+/*
  * _gdk_cairo_surface_extents:
  * @surface: surface to measure
  * @extents: (out): rectangle to put the extents
  *
  * Measures the area covered by @surface and puts it into @extents.
+ *
  * Note that this function respects device offsets set on @surface.
- * if @surface is unbounded, the resulting extents will be empty and
+ * If @surface is unbounded, the resulting extents will be empty and
  * not be a maximal sized rectangle. This is to avoid careless coding.
  * You must explicitly check the return value of you want to handle
  * that case.
  *
- * Returns: %TRUE if the extents fit in a #GdkRectangle, %FALSE if not.
- **/
+ * Returns: %TRUE if the extents fit in a #GdkRectangle, %FALSE if not
+ */
 gboolean
 _gdk_cairo_surface_extents (cairo_surface_t *surface,
-                            GdkRectangle *extents)
+                            GdkRectangle    *extents)
 {
   double x1, x2, y1, y2;
   cairo_t *cr;
@@ -346,7 +350,7 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
   y2 = ceil (y2);
   x2 -= x1;
   y2 -= y1;
-  
+
   if (x1 < G_MININT || x1 > G_MAXINT ||
       y1 < G_MININT || y1 > G_MAXINT ||
       x2 > G_MAXINT || y2 > G_MAXINT)
@@ -371,14 +375,15 @@ _gdk_cairo_surface_extents (cairo_surface_t *surface,
  */
 /**
  * gdk_cairo_region_create_from_surface:
- * @surface: A surface
+ * @surface: a cairo surface
  *
- * Creates region that describes covers the area where the given @surface
- * is more than 50% opaque. This function takes into account device
- * offsets that might be set with cairo_surface_set_device_offset().
+ * Creates region that describes covers the area where the given
+ * @surface is more than 50% opaque.
  *
- * Returns: A #cairo_region_t. This must be freed with cairo_region_destroy()
- *   when you are done.
+ * This function takes into account device offsets that might be
+ * set with cairo_surface_set_device_offset().
+ *
+ * Returns: A #cairo_region_t; must be freed with cairo_region_destroy()
  */
 cairo_region_t *
 gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
@@ -417,37 +422,36 @@ gdk_cairo_region_create_from_surface (cairo_surface_t *surface)
   for (y = 0; y < extents.height; y++)
     {
       for (x = 0; x < extents.width; x++)
-	{
-	  /* Search for a continuous range of "non transparent pixels"*/
-	  gint x0 = x;
-	  while (x < extents.width)
-	    {
-	      if (((data[x / 8] >> (x%8)) & 1) == 0)
-		/* This pixel is "transparent"*/
-		break;
-	      x++;
-	    }
-	  
-	  if (x > x0)
-	    {
-	      /* Add the pixels (x0, y) to (x, y+1) as a new rectangle
-	       * in the region
-	       */
+        {
+          /* Search for a continuous range of "non transparent pixels"*/
+          gint x0 = x;
+          while (x < extents.width)
+            {
+              if (((data[x / 8] >> (x%8)) & 1) == 0)
+                /* This pixel is "transparent"*/
+                break;
+              x++;
+            }
+
+          if (x > x0)
+            {
+              /* Add the pixels (x0, y) to (x, y+1) as a new rectangle
+               * in the region
+               */
               rect.x = x0;
               rect.width = x - x0;
               rect.y = y;
               rect.height = 1;
 
               cairo_region_union_rectangle (region, &rect);
-	    }
-	}
+            }
+        }
       data += stride;
     }
 
   cairo_surface_destroy (image);
-  
+
   cairo_region_translate (region, extents.x, extents.y);
 
   return region;
 }
-
diff --git a/gdk/gdkcairo.h b/gdk/gdkcairo.h
index 67e08aa933..f2cf7bd7e1 100644
--- a/gdk/gdkcairo.h
+++ b/gdk/gdkcairo.h
@@ -31,31 +31,31 @@
 
 G_BEGIN_DECLS
 
-cairo_t *gdk_cairo_create            (GdkWindow          *window);
-gboolean gdk_cairo_get_clip_rectangle(cairo_t            *cr,
-                                      GdkRectangle       *rect);
-
-void     gdk_cairo_set_source_color  (cairo_t            *cr,
-                                      const GdkColor     *color);
-void     gdk_cairo_set_source_rgba   (cairo_t            *cr,
-                                      const GdkRGBA      *rgba);
-void     gdk_cairo_set_source_pixbuf (cairo_t            *cr,
-                                      const GdkPixbuf    *pixbuf,
-                                      double              pixbuf_x,
-                                      double              pixbuf_y);
-void     gdk_cairo_set_source_window (cairo_t            *cr,
-                                      GdkWindow          *window,
-                                      double              x,
-                                      double              y);
-
-void     gdk_cairo_rectangle         (cairo_t            *cr,
-                                      const GdkRectangle *rectangle);
-void     gdk_cairo_region            (cairo_t            *cr,
-                                      const cairo_region_t    *region);
+cairo_t  * gdk_cairo_create             (GdkWindow          *window);
+gboolean   gdk_cairo_get_clip_rectangle (cairo_t            *cr,
+                                         GdkRectangle       *rect);
+
+void       gdk_cairo_set_source_color   (cairo_t              *cr,
+                                         const GdkColor       *color);
+void       gdk_cairo_set_source_rgba    (cairo_t              *cr,
+                                         const GdkRGBA        *rgba);
+void       gdk_cairo_set_source_pixbuf  (cairo_t              *cr,
+                                         const GdkPixbuf      *pixbuf,
+                                         gdouble               pixbuf_x,
+                                         gdouble               pixbuf_y);
+void       gdk_cairo_set_source_window  (cairo_t              *cr,
+                                         GdkWindow            *window,
+                                         gdouble               x,
+                                         gdouble               y);
+
+void       gdk_cairo_rectangle          (cairo_t              *cr,
+                                         const GdkRectangle   *rectangle);
+void       gdk_cairo_region             (cairo_t              *cr,
+                                         const cairo_region_t *region);
 
 cairo_region_t *
-         gdk_cairo_region_create_from_surface
-                                     (cairo_surface_t    *surface);
+           gdk_cairo_region_create_from_surface
+                                        (cairo_surface_t      *surface);
 
 G_END_DECLS
 
diff --git a/gdk/gdkcolor.c b/gdk/gdkcolor.c
index d4ab63cb28..ace91012e0 100644
--- a/gdk/gdkcolor.c
+++ b/gdk/gdkcolor.c
@@ -37,23 +37,29 @@
  * SECTION:colors
  * @Short_description: Manipulation of colors
  * @Title: Colors
+ *
+ * A #GdkColor represents a color.
+ *
+ * When working with cairo, it is often more convenient
+ * to use a #GdkRGBA instead.
  */
 
 
 /**
  * gdk_color_copy:
- * @color: a #GdkColor.
- * 
- * Makes a copy of a color structure. The result
- * must be freed using gdk_color_free().
- * 
- * Return value: a copy of @color.
- **/
+ * @color: a #GdkColor
+ *
+ * Makes a copy of a color structure.
+ *
+ * The result must be freed using gdk_color_free().
+ *
+ * Return value: a copy of @color
+ */
 GdkColor*
 gdk_color_copy (const GdkColor *color)
 {
   GdkColor *new_color;
-  
+
   g_return_val_if_fail (color != NULL, NULL);
 
   new_color = g_slice_new (GdkColor);
@@ -63,11 +69,10 @@ gdk_color_copy (const GdkColor *color)
 
 /**
  * gdk_color_free:
- * @color: a #GdkColor.
- * 
- * Frees a color structure created with 
- * gdk_color_copy().
- **/
+ * @color: a #GdkColor
+ *
+ * Frees a color structure created with gdk_color_copy().
+ */
 void
 gdk_color_free (GdkColor *color)
 {
@@ -78,41 +83,41 @@ gdk_color_free (GdkColor *color)
 
 /**
  * gdk_color_hash:
- * @colora: a #GdkColor.
- * 
+ * @color: a #GdkColor
+ *
  * A hash function suitable for using for a hash
- * table that stores #GdkColor's.
- * 
- * Return value: The hash function applied to @colora
- **/
+ * table that stores #GdkColors.
+ *
+ * Return value: The hash function applied to @color
+ */
 guint
-gdk_color_hash (const GdkColor *colora)
+gdk_color_hash (const GdkColor *color)
 {
-  return ((colora->red) +
-	  (colora->green << 11) +
-	  (colora->blue << 22) +
-	  (colora->blue >> 6));
+  return ((color->red) +
+          (color->green << 11) +
+          (color->blue << 22) +
+          (color->blue >> 6));
 }
 
 /**
  * gdk_color_equal:
- * @colora: a #GdkColor.
- * @colorb: another #GdkColor.
- * 
- * Compares two colors. 
- * 
+ * @colora: a #GdkColor
+ * @colorb: another #GdkColor
+ *
+ * Compares two colors.
+ *
  * Return value: %TRUE if the two colors compare equal
- **/
+ */
 gboolean
 gdk_color_equal (const GdkColor *colora,
-		 const GdkColor *colorb)
+                 const GdkColor *colorb)
 {
   g_return_val_if_fail (colora != NULL, FALSE);
   g_return_val_if_fail (colorb != NULL, FALSE);
 
   return ((colora->red == colorb->red) &&
-	  (colora->green == colorb->green) &&
-	  (colora->blue == colorb->blue));
+          (colora->green == colorb->green) &&
+          (colora->blue == colorb->blue));
 }
 
 G_DEFINE_BOXED_TYPE (GdkColor, gdk_color,
@@ -121,25 +126,28 @@ G_DEFINE_BOXED_TYPE (GdkColor, gdk_color,
 
 /**
  * gdk_color_parse:
- * @spec: the string specifying the color.
+ * @spec: the string specifying the color
  * @color: (out): the #GdkColor to fill in
  *
  * Parses a textual specification of a color and fill in the
  * <structfield>red</structfield>, <structfield>green</structfield>,
  * and <structfield>blue</structfield> fields of a #GdkColor
- * structure. The string can either one of a large set of standard
- * names. (Taken from the X11 <filename>rgb.txt</filename> file), or
+ * structure.
+ *
+ * The string can either one of a large set of standard names
+ * (taken from the X11 <filename>rgb.txt</filename> file), or
  * it can be a hex value in the form '&num;rgb' '&num;rrggbb'
- * '&num;rrrgggbbb' or '&num;rrrrggggbbbb' where 'r', 'g' and 'b' are
- * hex digits of the red, green, and blue components of the color,
- * respectively. (White in the four forms is '&num;fff' '&num;ffffff'
- * '&num;fffffffff' and '&num;ffffffffffff')
- * 
- * Return value: %TRUE if the parsing succeeded.
- **/
+ * '&num;rrrgggbbb' or '&num;rrrrggggbbbb' where 'r', 'g' and
+ * 'b' are hex digits of the red, green, and blue components
+ * of the color, respectively. (White in the four forms is
+ * '&num;fff', '&num;ffffff', '&num;fffffffff' and
+ * '&num;ffffffffffff').
+ *
+ * Return value: %TRUE if the parsing succeeded
+ */
 gboolean
 gdk_color_parse (const gchar *spec,
-		 GdkColor    *color)
+                 GdkColor    *color)
 {
   PangoColor pango_color;
 
@@ -164,10 +172,12 @@ gdk_color_parse (const gchar *spec,
  * <literal>g</literal> and <literal>b</literal> are hex digits
  * representing the red, green and blue components respectively.
  *
+ * The returned string can be parsed by gdk_color_parse().
+ *
  * Return value: a newly-allocated text string
  *
  * Since: 2.12
- **/
+ */
 gchar *
 gdk_color_to_string (const GdkColor *color)
 {
diff --git a/gdk/gdkcolor.h b/gdk/gdkcolor.h
index 4f9ee2af05..cab28a6453 100644
--- a/gdk/gdkcolor.h
+++ b/gdk/gdkcolor.h
@@ -39,16 +39,16 @@ G_BEGIN_DECLS
 
 /**
  * GdkColor:
- * @pixel: For allocated colors, the value used to
- *  draw this color on the screen.
+ * @pixel: For allocated colors, the pixel value used to
+ *     draw this color on the screen. Not used anymore.
  * @red: The red component of the color. This is
- *  a value between 0 and 65535, with 65535 indicating
- *  full intensitiy.
- * @green: The green component of the color.
- * @blue: The blue component of the color.
+ *     a value between 0 and 65535, with 65535 indicating
+ *     full intensitiy
+ * @green: The green component of the color
+ * @blue: The blue component of the color
  *
- * The #GdkColor structure is used to describe an
- * allocated or unallocated color.
+ * The #GdkColor structure is used to describe a color,
+ * similar to the XColor struct used in the X11 drawing API.
  */
 struct _GdkColor
 {
@@ -58,18 +58,20 @@ struct _GdkColor
   guint16 blue;
 };
 
-#define GDK_TYPE_COLOR                 (gdk_color_get_type ())
+#define GDK_TYPE_COLOR (gdk_color_get_type ())
+
+GType     gdk_color_get_type (void) G_GNUC_CONST;
 
 GdkColor *gdk_color_copy      (const GdkColor *color);
 void      gdk_color_free      (GdkColor       *color);
-gboolean  gdk_color_parse     (const gchar    *spec,
-			       GdkColor       *color);
-guint     gdk_color_hash      (const GdkColor *colora);
+
+guint     gdk_color_hash      (const GdkColor *color);
 gboolean  gdk_color_equal     (const GdkColor *colora,
-			       const GdkColor *colorb);
-gchar *   gdk_color_to_string (const GdkColor *color);
+                               const GdkColor *colorb);
 
-GType     gdk_color_get_type (void) G_GNUC_CONST;
+gboolean  gdk_color_parse     (const gchar    *spec,
+                               GdkColor       *color);
+gchar *   gdk_color_to_string (const GdkColor *color);
 
 
 G_END_DECLS
diff --git a/gdk/gdkpixbuf-drawable.c b/gdk/gdkpixbuf-drawable.c
index fd14b9e352..67d890c9b6 100644
--- a/gdk/gdkpixbuf-drawable.c
+++ b/gdk/gdkpixbuf-drawable.c
@@ -34,12 +34,14 @@
 
 /**
  * SECTION:pixbufs
- * @Short_description: Functions for rendering pixbufs on drawables
+ * @Short_description: Functions for obtaining pixbufs
  * @Title: Pixbufs
  *
- * These functions allow to render pixbufs on drawables. Pixbufs are
- * client-side images. For details on how to create and manipulate
- * pixbufs, see the #GdkPixbuf API documentation.
+ * Pixbufs are client-side images. For details on how to create
+ * and manipulate pixbufs, see the #GdkPixbuf API documentation.
+ *
+ * The functions described here allow to obtain pixbufs from
+ * #GdkWindows and cairo surfaces.
  */
 
 
@@ -55,7 +57,7 @@
  * representation inside a #GdkPixbuf. In other words, copies
  * image data from a server-side drawable to a client-side RGB(A) buffer.
  * This allows you to efficiently read individual pixels on the client side.
- * 
+ *
  * This function will create an RGB pixbuf with 8 bits per channel with
  * the same size specified by the @width and @height arguments. The pixbuf
  * will contain an alpha channel if the @window contains one.
@@ -78,16 +80,18 @@
  *  it returns %NULL; so check the return value.)
  *
  * Return value: (transfer full): A newly-created pixbuf with a reference
- * count of 1, or %NULL on error
- **/
+ *     count of 1, or %NULL on error
+ */
 GdkPixbuf *
-gdk_pixbuf_get_from_window (GdkWindow   *src,
-                            int src_x,  int src_y,
-                            int width,  int height)
+gdk_pixbuf_get_from_window (GdkWindow *src,
+                            gint       src_x,
+                            gint       src_y,
+                            gint       width,
+                            gint       height)
 {
   cairo_surface_t *surface;
   GdkPixbuf *dest;
-  
+
   g_return_val_if_fail (GDK_IS_WINDOW (src), NULL);
   g_return_val_if_fail (gdk_window_is_viewable (src), NULL);
 
@@ -99,7 +103,7 @@ gdk_pixbuf_get_from_window (GdkWindow   *src,
 
   return dest;
 }
-        
+
 static cairo_format_t
 gdk_cairo_format_for_content (cairo_content_t content)
 {
@@ -117,11 +121,11 @@ gdk_cairo_format_for_content (cairo_content_t content)
 
 static cairo_surface_t *
 gdk_cairo_surface_coerce_to_image (cairo_surface_t *surface,
-                                   cairo_content_t content,
-                                   int src_x,
-                                   int src_y,
-                                   int width,
-                                   int height)
+                                   cairo_content_t  content,
+                                   int              src_x,
+                                   int              src_y,
+                                   int              width,
+                                   int              height)
 {
   cairo_surface_t *copy;
   cairo_t *cr;
@@ -140,14 +144,14 @@ gdk_cairo_surface_coerce_to_image (cairo_surface_t *surface,
 }
 
 static void
-convert_alpha (guchar  *dest_data,
-               int      dest_stride,
-               guchar  *src_data,
-               int      src_stride,
-               int      src_x,
-               int      src_y,
-               int      width,
-               int      height)
+convert_alpha (guchar *dest_data,
+               int     dest_stride,
+               guchar *src_data,
+               int     src_stride,
+               int     src_x,
+               int     src_y,
+               int     width,
+               int     height)
 {
   int x, y;
 
@@ -180,14 +184,14 @@ convert_alpha (guchar  *dest_data,
 }
 
 static void
-convert_no_alpha (guchar  *dest_data,
-                  int      dest_stride,
-                  guchar  *src_data,
-                  int      src_stride,
-                  int      src_x,
-                  int      src_y,
-                  int      width,
-                  int      height)
+convert_no_alpha (guchar *dest_data,
+                  int     dest_stride,
+                  guchar *src_data,
+                  int     src_stride,
+                  int     src_x,
+                  int     src_y,
+                  int     width,
+                  int     height)
 {
   int x, y;
 
@@ -220,22 +224,22 @@ convert_no_alpha (guchar  *dest_data,
  * individual pixels from cairo surfaces. For #GdkWindows, use
  * gdk_pixbuf_get_from_window() instead.
  *
- * This function will create an RGB pixbuf with 8 bits per channel. The pixbuf
- * will contain an alpha channel if the @surface contains one.
+ * This function will create an RGB pixbuf with 8 bits per channel.
+ * The pixbuf will contain an alpha channel if the @surface contains one.
  *
- * Return value: (transfer full): A newly-created pixbuf with a reference count
- * of 1, or %NULL on error
- **/
+ * Return value: (transfer full): A newly-created pixbuf with a reference
+ *     count of 1, or %NULL on error
+ */
 GdkPixbuf *
 gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
-                              int              src_x,
-                              int              src_y,
-                              int              width,
-                              int              height)
+                              gint             src_x,
+                              gint             src_y,
+                              gint             width,
+                              gint             height)
 {
   cairo_content_t content;
   GdkPixbuf *dest;
-  
+
   /* General sanity checks */
   g_return_val_if_fail (surface != NULL, NULL);
   g_return_val_if_fail (width > 0 && height > 0, NULL);
@@ -246,7 +250,8 @@ gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
                          8,
                          width, height);
 
-  surface = gdk_cairo_surface_coerce_to_image (surface, content, src_x, src_y,
+  surface = gdk_cairo_surface_coerce_to_image (surface, content,
+                                               src_x, src_y,
                                                width, height);
   cairo_surface_flush (surface);
   if (cairo_surface_status (surface) || dest == NULL)
@@ -273,4 +278,3 @@ gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
   cairo_surface_destroy (surface);
   return dest;
 }
-
diff --git a/gdk/gdkpixbuf.h b/gdk/gdkpixbuf.h
index 61a1392d09..b7b09d2b48 100644
--- a/gdk/gdkpixbuf.h
+++ b/gdk/gdkpixbuf.h
@@ -37,18 +37,17 @@
 
 G_BEGIN_DECLS
 
-/* Fetching a region from a drawable */
-GdkPixbuf *gdk_pixbuf_get_from_window   (GdkWindow   *window,
-					 int          src_x,
-					 int          src_y,
-					 int          width,
-					 int          height);
-
-GdkPixbuf *gdk_pixbuf_get_from_surface  (cairo_surface_t *surface,
-					 int              src_x,
-					 int              src_y,
-					 int              width,
-					 int              height);
+GdkPixbuf *gdk_pixbuf_get_from_window  (GdkWindow       *window,
+                                        gint             src_x,
+                                        gint             src_y,
+                                        gint             width,
+                                        gint             height);
+
+GdkPixbuf *gdk_pixbuf_get_from_surface (cairo_surface_t *surface,
+                                        gint             src_x,
+                                        gint             src_y,
+                                        gint             width,
+                                        gint             height);
 
 G_END_DECLS
 
diff --git a/gdk/gdkrgba.c b/gdk/gdkrgba.c
index de06cb27c7..f5e20c5f3a 100644
--- a/gdk/gdkrgba.c
+++ b/gdk/gdkrgba.c
@@ -34,7 +34,7 @@
  * @Title: RGBA Colors
  *
  * The #GdkRGBA struct is a convenient way to pass rgba colors around.
- * It's based on cairo's way to deal with colors and mirros its behavior.
+ * It's based on cairo's way to deal with colors and mirrors its behavior.
  * All values are in the range from 0.0 to 1.0 inclusive. So the color
  * (0.0, 0.0, 0.0, 0.0) represents transparent black and
  * (1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped
@@ -46,28 +46,28 @@ G_DEFINE_BOXED_TYPE (GdkRGBA, gdk_rgba,
 
 /**
  * GdkRGBA:
- * @red: The intensity of the red channel from 0.0 to 1.0 inclusive.
- * @green: The intensity of the green channel from 0.0 to 1.0 inclusive.
- * @blue: The intensity of the blue channel from 0.0 to 1.0 inclusive.
+ * @red: The intensity of the red channel from 0.0 to 1.0 inclusive
+ * @green: The intensity of the green channel from 0.0 to 1.0 inclusive
+ * @blue: The intensity of the blue channel from 0.0 to 1.0 inclusive
  * @alpha: The opacity of the color from 0.0 for completely translucent to
- *   1.0 for opaque.
+ *   1.0 for opaque
  *
- * The GdkRGBA structure is used to pass around color data. When using it
- * as struct members or on the stack, you want to use the struct directly
- * and not allocate it.
+ * The GdkRGBA structure is used to represent a (possibly translucent)
+ * color, in a way that is compatible with cairos notion of color.
  */
 
 /**
  * gdk_rgba_copy:
  * @rgba: a #GdkRGBA
  *
- * Makes a copy of a #GdkRGBA structure, the result must be freed
- * through gdk_rgba_free().
+ * Makes a copy of a #GdkRGBA structure.
  *
- * Returns: A newly allocated #GdkRGBA
+ * The result must be freed through gdk_rgba_free().
+ *
+ * Returns: A newly allocated #GdkRGBA, with the same contents as @rgba
  *
  * Since: 3.0
- **/
+ */
 GdkRGBA *
 gdk_rgba_copy (const GdkRGBA *rgba)
 {
@@ -89,7 +89,7 @@ gdk_rgba_copy (const GdkRGBA *rgba)
  * Frees a #GdkRGBA struct created with gdk_rgba_copy()
  *
  * Since: 3.0
- **/
+ */
 void
 gdk_rgba_free (GdkRGBA *rgba)
 {
@@ -111,7 +111,7 @@ gdk_rgba_free (GdkRGBA *rgba)
  */
 static double
 parse_rgb_value (const char  *str,
-		 char       **endp)
+                 char       **endp)
 {
   double number;
   const char *p;
@@ -168,7 +168,7 @@ parse_rgb_value (const char  *str,
  * Returns: %TRUE if the parsing succeeded
  *
  * Since: 3.0
- **/
+ */
 gboolean
 gdk_rgba_parse (GdkRGBA     *rgba,
                 const gchar *spec)
@@ -193,7 +193,8 @@ gdk_rgba_parse (GdkRGBA     *rgba,
       PangoColor pango_color;
 
       /* Resort on PangoColor for rgb.txt color
-       * map and '#' prefixed colors */
+       * map and '#' prefixed colors
+       */
       if (pango_color_parse (&pango_color, str))
         {
           if (rgba)
@@ -272,37 +273,37 @@ gdk_rgba_parse (GdkRGBA     *rgba,
 
 /**
  * gdk_rgba_hash:
- * @p: (type GdkRGBA): a #GdkRGBA pointer.
+ * @p: (type GdkRGBA): a #GdkRGBA pointer
  *
  * A hash function suitable for using for a hash
- * table that stores #GdkRGBA<!-- -->s.
+ * table that stores #GdkRGBAs.
  *
- * Return value: The hash function applied to @p
+ * Return value: The hash value for @p
  *
  * Since: 3.0
- **/
+ */
 guint
 gdk_rgba_hash (gconstpointer p)
 {
   const GdkRGBA *rgba = p;
 
   return ((guint) (rgba->red * 65535) +
-	  ((guint) (rgba->green * 65535) << 11) +
-	  ((guint) (rgba->blue * 65535) << 22) +
-	  ((guint) (rgba->alpha * 65535) >> 6));
+          ((guint) (rgba->green * 65535) << 11) +
+          ((guint) (rgba->blue * 65535) << 22) +
+          ((guint) (rgba->alpha * 65535) >> 6));
 }
 
 /**
  * gdk_rgba_equal:
- * @p1: (type GdkRGBA): a #GdkRGBA pointer.
- * @p2: (type GdkRGBA): another #GdkRGBA pointer.
+ * @p1: (type GdkRGBA): a #GdkRGBA pointer
+ * @p2: (type GdkRGBA): another #GdkRGBA pointer
  *
  * Compares two RGBA colors.
  *
  * Return value: %TRUE if the two colors compare equal
  *
  * Since: 3.0
- **/
+ */
 gboolean
 gdk_rgba_equal (gconstpointer p1,
                 gconstpointer p2)
@@ -325,27 +326,35 @@ gdk_rgba_equal (gconstpointer p1,
  * gdk_rgba_to_string:
  * @rgba: a #GdkRGBA
  *
- * Returns a textual specification of @rgba in the form <literal>rgb
- * (r, g, b)</literal> or <literal>rgba (r, g, b, a)</literal>,
- * where 'r', 'g', 'b' and 'a' represent the red, green, blue and alpha values
- * respectively. r, g, and b are integers in the range 0 to 255, and a
- * is a floating point value in the range 0 to 1.
+ * Returns a textual specification of @rgba in the form
+ * <literal>rgb (r, g, b)</literal> or
+ * <literal>rgba (r, g, b, a)</literal>,
+ * where 'r', 'g', 'b' and 'a' represent the red, green,
+ * blue and alpha values respectively. r, g, and b are
+ * represented as integers in the range 0 to 255, and a
+ * is represented as floating point value in the range 0 to 1.
  *
- * (These string forms are string forms those supported by the CSS3 colors module)
+ * These string forms are string forms those supported by
+ * the CSS3 colors module, and can be parsed by gdk_rgba_parse().
+ *
+ * Note that this string representation may loose some
+ * precision, since r, g and b are represented as 8-bit
+ * integers. If this is a concern, you should use a
+ * different representation.
  *
  * Returns: A newly allocated text string
  *
  * Since: 3.0
- **/
+ */
 gchar *
 gdk_rgba_to_string (const GdkRGBA *rgba)
 {
   if (rgba->alpha > 0.999)
     {
       return g_strdup_printf ("rgb(%d,%d,%d)",
-			      (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
-			      (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
-			      (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.));
+                              (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
+                              (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
+                              (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.));
     }
   else
     {
@@ -354,9 +363,9 @@ gdk_rgba_to_string (const GdkRGBA *rgba)
       g_ascii_dtostr (alpha, G_ASCII_DTOSTR_BUF_SIZE, CLAMP (rgba->alpha, 0, 1));
 
       return g_strdup_printf ("rgba(%d,%d,%d,%s)",
-			      (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
-			      (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
-			      (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.),
-			      alpha);
+                              (int)(0.5 + CLAMP (rgba->red, 0., 1.) * 255.),
+                              (int)(0.5 + CLAMP (rgba->green, 0., 1.) * 255.),
+                              (int)(0.5 + CLAMP (rgba->blue, 0., 1.) * 255.),
+                              alpha);
     }
 }
diff --git a/gdk/gdkrgba.h b/gdk/gdkrgba.h
index d0d1286c7b..e5f26687d2 100644
--- a/gdk/gdkrgba.h
+++ b/gdk/gdkrgba.h
@@ -45,20 +45,19 @@ struct _GdkRGBA
 
 #define GDK_TYPE_RGBA (gdk_rgba_get_type ())
 
-GdkRGBA * gdk_rgba_copy (const GdkRGBA *rgba);
-void      gdk_rgba_free (GdkRGBA *rgba);
+GType     gdk_rgba_get_type  (void) G_GNUC_CONST;
 
-gboolean  gdk_rgba_parse (GdkRGBA     *rgba,
-                          const gchar *spec);
+GdkRGBA * gdk_rgba_copy      (const GdkRGBA *rgba);
+void      gdk_rgba_free      (GdkRGBA       *rgba);
 
-guint     gdk_rgba_hash  (gconstpointer p);
-gboolean  gdk_rgba_equal (gconstpointer p1,
-                          gconstpointer p2);
+guint     gdk_rgba_hash      (gconstpointer  p);
+gboolean  gdk_rgba_equal     (gconstpointer  p1,
+                              gconstpointer  p2);
 
+gboolean  gdk_rgba_parse     (GdkRGBA       *rgba,
+                              const gchar   *spec);
 gchar *   gdk_rgba_to_string (const GdkRGBA *rgba);
 
-GType     gdk_rgba_get_type (void) G_GNUC_CONST;
-
 
 G_END_DECLS
 
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index e53fdd07fa..af702a462e 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -51,12 +51,12 @@
  * @Short_description: Onscreen display areas in the target window system
  * @Title: Windows
  *
- * A #GdkWindow is a rectangular region on the screen. It's a low-level object,
- * used to implement high-level objects such as #GtkWidget and #GtkWindow on the
- * GTK+ level. A #GtkWindow is a toplevel window, the thing a user might think
- * of as a "window" with a titlebar and so on; a #GtkWindow may contain many
- * #GdkWindow<!-- -->s. For example, each #GtkButton has a #GdkWindow associated
- * with it.
+ * A #GdkWindow is a (usually) rectangular region on the screen.
+ * It's a low-level object, used to implement high-level objects such as
+ * #GtkWidget and #GtkWindow on the GTK+ level. A #GtkWindow is a toplevel
+ * window, the thing a user might think of as a "window" with a titlebar and
+ * so on; a #GtkWindow may contain many #GdkWindows. For example, each
+ * #GtkButton has a #GdkWindow associated with it.
  *
  * <refsect2 id="COMPOSITED-WINDOWS">
  * <title>Composited Windows</title>