Doc updates.

ChangeLog

@@ -1,10 +1,17 @@
 2004-06-22  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkgc-x11.c: 
+	* gdk/gdkgc.c: Move function docs inline, add hints about 
+	obtaining rgb colors from gcs.  (#144688, Steve Chaplin)
+
+	* gtk/gtktreestore.c (gtk_tree_store_swap): Make this work
+	for children of the root.  (#139785, Jean-François Wauthy,
+	patch by John Finlay)
+
 	* gtk/gtkicontheme.h (GTK_ICON_THEME_GET_CLASS): Typo
 	fix.  (#144750, Jeff Franks) 
 
 2004-06-21  Michael Natterer  <mitch@gimp.org>
-
 	Merge from stable:
 
 	* gdk/x11/gdkdrawable-x11.[ch]: made convert_format() utility

ChangeLog.pre-2-10

@@ -1,10 +1,17 @@
 2004-06-22  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkgc-x11.c: 
+	* gdk/gdkgc.c: Move function docs inline, add hints about 
+	obtaining rgb colors from gcs.  (#144688, Steve Chaplin)
+
+	* gtk/gtktreestore.c (gtk_tree_store_swap): Make this work
+	for children of the root.  (#139785, Jean-François Wauthy,
+	patch by John Finlay)
+
 	* gtk/gtkicontheme.h (GTK_ICON_THEME_GET_CLASS): Typo
 	fix.  (#144750, Jeff Franks) 
 
 2004-06-21  Michael Natterer  <mitch@gimp.org>
-
 	Merge from stable:
 
 	* gdk/x11/gdkdrawable-x11.[ch]: made convert_format() utility

ChangeLog.pre-2-6

@@ -1,10 +1,17 @@
 2004-06-22  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkgc-x11.c: 
+	* gdk/gdkgc.c: Move function docs inline, add hints about 
+	obtaining rgb colors from gcs.  (#144688, Steve Chaplin)
+
+	* gtk/gtktreestore.c (gtk_tree_store_swap): Make this work
+	for children of the root.  (#139785, Jean-François Wauthy,
+	patch by John Finlay)
+
 	* gtk/gtkicontheme.h (GTK_ICON_THEME_GET_CLASS): Typo
 	fix.  (#144750, Jeff Franks) 
 
 2004-06-21  Michael Natterer  <mitch@gimp.org>
-
 	Merge from stable:
 
 	* gdk/x11/gdkdrawable-x11.[ch]: made convert_format() utility

ChangeLog.pre-2-8

@@ -1,10 +1,17 @@
 2004-06-22  Matthias Clasen  <mclasen@redhat.com>
 
+	* gdk/x11/gdkgc-x11.c: 
+	* gdk/gdkgc.c: Move function docs inline, add hints about 
+	obtaining rgb colors from gcs.  (#144688, Steve Chaplin)
+
+	* gtk/gtktreestore.c (gtk_tree_store_swap): Make this work
+	for children of the root.  (#139785, Jean-François Wauthy,
+	patch by John Finlay)
+
 	* gtk/gtkicontheme.h (GTK_ICON_THEME_GET_CLASS): Typo
 	fix.  (#144750, Jeff Franks) 
 
 2004-06-21  Michael Natterer  <mitch@gimp.org>
-
 	Merge from stable:
 
 	* gdk/x11/gdkdrawable-x11.[ch]: made convert_format() utility

docs/reference/ChangeLog

@@ -1,3 +1,7 @@
+2004-06-22  Matthias Clasen  <mclasen@redhat.com>
+
+	* gdk/tmpl/gcs.sgml: Move function docs inline.
+
 Mon Jun 21 00:46:20 2004  Matthias Clasen  <maclas@gmx.de>
 
 	* gdk-pixbuf/gdk-pixbuf-sections.txt: Add 

docs/reference/gdk/tmpl/gcs.sgml

@@ -44,8 +44,10 @@ The #GdkGCValues structure holds a set of values used
 to create or modify a graphics context.
 </para>
 
-@foreground: the foreground color.
+@foreground: the foreground color. Note that gdk_gc_get_values()
-@background: the background color.
+  only sets the pixel value.
+@background: the background color. Note that gdk_gc_get_values()
+  only sets the pixel value.
 @font: the default font.
 @function: the bitwise operation used when drawing.
 @fill: the fill style.
@@ -117,25 +119,21 @@ useful. For bitmaps, %GDK_AND and %GDK_OR are also useful.
 
 <!-- ##### FUNCTION gdk_gc_new ##### -->
 <para>
-Create a new graphics context with default values. 
 </para>
 
-@drawable: a #GdkDrawable. The created GC must always be used
+@drawable: 
- with drawables of the same depth as this one.
+@Returns:
-@Returns: the new graphics context.
 
 
 <!-- ##### FUNCTION gdk_gc_new_with_values ##### -->
 <para>
-Create a new GC with the given initial values.
+
 </para>
 
-@drawable: a #GdkDrawable. The created GC must always be used
+@drawable: 
- with drawables of the same depth as this one.
+@values: 
-@values: a structure containing initial values for the GC.
+@values_mask:
-@values_mask: a bit mask indicating which fields in @values
+@Returns: 
-   are set.
-@Returns: the new graphics context.
 
 
 <!-- ##### FUNCTION gdk_gc_get_screen ##### -->
@@ -166,13 +164,12 @@ Create a new GC with the given initial values.
 
 <!-- ##### MACRO gdk_gc_destroy ##### -->
 <para>
-Identical to gdk_gc_unref(). This function is obsolete
+This function is obsolete and should not be used.
-and should not be used.
 </para>
 
 <!-- # Unused Parameters # -->
 @gc: a #GdkGC.
-
+@Deprecated: Use gdk_object_unref() instead
 
 <!-- ##### FUNCTION gdk_gc_set_values ##### -->
 <para>
@@ -186,29 +183,29 @@ and should not be used.
 
 <!-- ##### FUNCTION gdk_gc_get_values ##### -->
 <para>
-Retrieves the current values from a graphics context.
+
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@values: the #GdkGCValues structure in which to store the results.
+@values:
 
 
 <!-- ##### FUNCTION gdk_gc_set_foreground ##### -->
 <para>
-Sets the foreground color for a graphics context.
+
 </para>
 
-@gc: a #GdkGC.
+@gc: 
-@color: the new foreground color.
+@color: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_background ##### -->
 <para>
-Sets the background color for a graphics context.
+
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@color: the new background color.
+@color:
 
 
 <!-- ##### FUNCTION gdk_gc_set_rgb_fg_color ##### -->
@@ -231,34 +228,29 @@ Sets the background color for a graphics context.
 
 <!-- ##### FUNCTION gdk_gc_set_font ##### -->
 <para>
-Sets the font for a graphics context. (Note that
+
-all text-drawing functions in GDK take a @font
-argument; the value set here is used when that
-argument is %NULL.)
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@font: the new font.
+@font:
 
 
 <!-- ##### FUNCTION gdk_gc_set_function ##### -->
 <para>
-Determines how the current pixel values and the
+
-pixel values being drawn are combined to produce
-the final pixel values.
 </para>
 
-@gc: a #GdkGC.
+@gc:
 @function: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_fill ##### -->
 <para>
-Set the fill mode for a graphics context.
+
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@fill: the new fill mode.
+@fill:
 
 
 <!-- ##### ENUM GdkFill ##### -->
@@ -279,93 +271,75 @@ Determines how primitives are drawn.
 
 <!-- ##### FUNCTION gdk_gc_set_tile ##### -->
 <para>
-Set a tile pixmap for a graphics context.
+
-This will only be used if the fill mode
-is %GDK_TILED.
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@tile: the new tile pixmap.
+@tile:
 
 
 <!-- ##### FUNCTION gdk_gc_set_stipple ##### -->
 <para>
-Set the stipple bitmap for a graphics context. The
+
-stipple will only be used if the fill mode is
-%GDK_STIPPLED or %GDK_OPAQUE_STIPPLED.
 </para>
 
-@gc: a #GdkGC.
+@gc: 
-@stipple: the new stipple bitmap.
+@stipple: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_ts_origin ##### -->
 <para>
-Set the origin when using tiles or stipples with
+
-the GC. The tile or stipple will be aligned such
-that the upper left corner of the tile or stipple
-will coincide with this point.
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@x: the x-coordinate of the origin.
+@x: 
-@y: the y-coordinate of the origin.
+@y: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_origin ##### -->
 <para>
-Sets the origin of the clip mask. The coordinates are
+
-interpreted relative to the upper-left corner of
-the destination drawable of the current operation.
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@x: the x-coordinate of the origin.
+@x: 
-@y: the y-coordinate of the origin.
+@y: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_mask ##### -->
 <para>
-Sets the clip mask for a graphics context from a bitmap.
+
-The clip mask is interpreted relative to the clip
-origin. (See gdk_gc_set_clip_origin()).
 </para>
 
-@gc: the #GdkGC.
+@gc: 
-@mask: a bitmap.
+@mask: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_rectangle ##### -->
 <para>
-Sets the clip mask for a graphics context from a
-rectangle. The clip mask is interpreted relative to the clip
-origin. (See gdk_gc_set_clip_origin()).
-
 </para>
 
-@gc: a #GdkGC.
+@gc: 
-@rectangle: the rectangle to clip to.
+@rectangle: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_clip_region ##### -->
 <para>
-Sets the clip mask for a graphics context from a region structure.
+
-The clip mask is interpreted relative to the clip origin. (See
-gdk_gc_set_clip_origin()).
 </para>
 
-@gc: a #GdkGC.
+@gc:
-@region: the #GdkRegion.
+@region: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_subwindow ##### -->
 <para>
-Sets how drawing with this GC on a window will affect child
+
-windows of that window. 
 </para>
 
-@gc: a #GdkGC.
+@gc: 
-@mode: the subwindow mode.
+@mode: 
 
 
 <!-- ##### ENUM GdkSubwindowMode ##### -->
@@ -379,28 +353,23 @@ windows of that window.
 
 <!-- ##### FUNCTION gdk_gc_set_exposures ##### -->
 <para>
-Sets whether copying non-visible portions of a drawable
+
-using this graphics context generate exposure events
-for the corresponding regions of the destination
-drawable. (See gdk_draw_drawable()).
 </para>
 
-@gc: a #GdkGC.
+@gc: 
-@exposures: if %TRUE, exposure events will be generated.
+@exposures: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_line_attributes ##### -->
 <para>
-Sets various attributes of how lines are drawn. See
+
-the corresponding members of #GdkGCValues for full
-explanations of the arguments.
 </para>
 
-@gc: a #GdkGC.
+@gc: 
-@line_width: the width of lines.
+@line_width: 
-@line_style: the dash-style for lines.
+@line_style: 
-@cap_style: the manner in which the ends of lines are drawn.
+@cap_style: 
-@join_style: the in which lines are joined together.
+@join_style:
 
 
 <!-- ##### ENUM GdkLineStyle ##### -->
@@ -440,32 +409,22 @@ Determines how the joins between segments of a polygon are drawn.
 
 <!-- ##### FUNCTION gdk_gc_set_dashes ##### -->
 <para>
-Sets the way dashed-lines are drawn. Lines will be
+
-drawn with alternating on and off segments of the
-lengths specified in @dash_list. The manner in
-which the on and off segments are drawn is determined
-by the @line_style value of the GC. (This can
-be changed with gdk_gc_set_line_attributes().)
-</para>
-<para>
-The @dash_offset defines the phase of the pattern, specifying how many
-pixels into the dash-list the pattern should actually begin.
 </para>
 
-@gc: a #GdkGC.
+@gc: 
-@dash_offset: the phase of the dash pattern.
+@dash_offset: 
-@dash_list: an array of dash lengths.
+@dash_list: 
-@n: the number of elements in @dash_list.
+@n: 
 
 
 <!-- ##### FUNCTION gdk_gc_copy ##### -->
 <para>
-Copy the set of values from one graphics context
+
-onto another graphics context.
 </para>
 
-@dst_gc: the destination graphics context.
+@dst_gc:
-@src_gc: the source graphics context.
+@src_gc: 
 
 
 <!-- ##### FUNCTION gdk_gc_set_colormap ##### -->

gdk/gdkgc.c

@@ -73,6 +73,16 @@ gdk_gc_class_init (GObjectClass *class)
   class->finalize = gdk_gc_finalize;
 }
 
+
+/**
+ * gdk_gc_new:
+ * @drawable: a #GdkDrawable. The created GC must always be used
+ *   with drawables of the same depth as this one.
+ *
+ * Create a new graphics context with default values. 
+ *
+ * Returns: the new graphics context.
+ **/
 GdkGC*
 gdk_gc_new (GdkDrawable *drawable)
 {
@@ -81,6 +91,18 @@ gdk_gc_new (GdkDrawable *drawable)
   return gdk_gc_new_with_values (drawable, NULL, 0);
 }
 
+/**
+ * gdk_gc_new_with_values:
+ * @drawable: a #GdkDrawable. The created GC must always be used
+ *   with drawables of the same depth as this one.
+ * @values: a structure containing initial values for the GC.
+ * @values_mask: a bit mask indicating which fields in @values
+ *   are set.
+ * 
+ * Create a new GC with the given initial values.
+ * 
+ * Return value: the new graphics context.
+ **/
 GdkGC*
 gdk_gc_new_with_values (GdkDrawable	*drawable,
 			GdkGCValues	*values,
@@ -148,7 +170,9 @@ gdk_gc_ref (GdkGC *gc)
  * gdk_gc_unref:
  * @gc: a #GdkGC
  *
- * Deprecated function; use g_object_unref() instead.
+ * Decrement the reference count of @gc.
+ *
+ * Deprecated: Use g_object_unref() instead.
  **/
 void
 gdk_gc_unref (GdkGC *gc)
@@ -156,6 +180,16 @@ gdk_gc_unref (GdkGC *gc)
   g_object_unref (gc);
 }
 
+/**
+ * gdk_gc_get_values:
+ * @gc:  a #GdkGC.
+ * @values: the #GdkGCValues structure in which to store the results.
+ * 
+ * Retrieves the current values from a graphics context. Note that 
+ * only the pixel values of the @values->foreground and @values->background
+ * are filled, use gdk_colormap_query_color() to obtain the rgb values
+ * if you need them.
+ **/
 void
 gdk_gc_get_values (GdkGC       *gc,
 		   GdkGCValues *values)
@@ -199,6 +233,16 @@ gdk_gc_set_values (GdkGC           *gc,
   GDK_GC_GET_CLASS (gc)->set_values (gc, values, values_mask);
 }
 
+/**
+ * gdk_gc_set_foreground:
+ * @gc: a #GdkGC.
+ * @color: the new foreground color.
+ * 
+ * Sets the foreground color for a graphics context.
+ * Note that this function uses @color->pixel, use 
+ * gdk_gc_set_rgb_fg_color() to specify the foreground 
+ * color as red, green, blue components.
+ **/
 void
 gdk_gc_set_foreground (GdkGC	      *gc,
 		       const GdkColor *color)
@@ -212,6 +256,16 @@ gdk_gc_set_foreground (GdkGC	      *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_FOREGROUND);
 }
 
+/**
+ * gdk_gc_set_background:
+ * @gc: a #GdkGC.
+ * @color: the new background color.
+ * 
+ * Sets the background color for a graphics context.
+ * Note that this function uses @color->pixel, use 
+ * gdk_gc_set_rgb_bg_color() to specify the background 
+ * color as red, green, blue components.
+ **/
 void
 gdk_gc_set_background (GdkGC	      *gc,
 		       const GdkColor *color)
@@ -225,6 +279,16 @@ gdk_gc_set_background (GdkGC	      *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_BACKGROUND);
 }
 
+/**
+ * gdk_gc_set_font:
+ * @gc: a #GdkGC.
+ * @font: the new font. 
+ * 
+ * Sets the font for a graphics context. (Note that
+ * all text-drawing functions in GDK take a @font
+ * argument; the value set here is used when that
+ * argument is %NULL.)
+ **/
 void
 gdk_gc_set_font (GdkGC	 *gc,
 		 GdkFont *font)
@@ -238,6 +302,15 @@ gdk_gc_set_font (GdkGC	 *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_FONT);
 }
 
+/**
+ * gdk_gc_set_function:
+ * @gc: a #GdkGC.
+ * @function: the #GdkFunction to use
+ * 
+ * Determines how the current pixel values and the
+ * pixel values being drawn are combined to produce
+ * the final pixel values.
+ **/
 void
 gdk_gc_set_function (GdkGC	 *gc,
 		     GdkFunction  function)
@@ -250,6 +323,13 @@ gdk_gc_set_function (GdkGC	 *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_FUNCTION);
 }
 
+/**
+ * gdk_gc_set_fill:
+ * @gc: a #GdkGC.
+ * @fill: the new fill mode.
+ * 
+ * Set the fill mode for a graphics context.
+ **/
 void
 gdk_gc_set_fill (GdkGC	 *gc,
 		 GdkFill  fill)
@@ -262,6 +342,15 @@ gdk_gc_set_fill (GdkGC	 *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_FILL);
 }
 
+/**
+ * gdk_gc_set_tile:
+ * @gc:  a #GdkGC.
+ * @tile:  the new tile pixmap.
+ * 
+ * Set a tile pixmap for a graphics context.
+ * This will only be used if the fill mode
+ * is %GDK_TILED.
+ **/
 void
 gdk_gc_set_tile (GdkGC	   *gc,
 		 GdkPixmap *tile)
@@ -274,6 +363,15 @@ gdk_gc_set_tile (GdkGC	   *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_TILE);
 }
 
+/**
+ * gdk_gc_set_stipple:
+ * @gc: a #GdkGC.
+ * @stipple: the new stipple bitmap.
+ * 
+ * Set the stipple bitmap for a graphics context. The
+ * stipple will only be used if the fill mode is
+ * %GDK_STIPPLED or %GDK_OPAQUE_STIPPLED.
+ **/
 void
 gdk_gc_set_stipple (GdkGC     *gc,
 		    GdkPixmap *stipple)
@@ -286,6 +384,17 @@ gdk_gc_set_stipple (GdkGC     *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_STIPPLE);
 }
 
+/**
+ * gdk_gc_set_ts_origin:
+ * @gc:  a #GdkGC.
+ * @x: the x-coordinate of the origin.
+ * @y: the y-coordinate of the origin.
+ * 
+ * Set the origin when using tiles or stipples with
+ * the GC. The tile or stipple will be aligned such
+ * that the upper left corner of the tile or stipple
+ * will coincide with this point.
+ **/
 void
 gdk_gc_set_ts_origin (GdkGC *gc,
 		      gint   x,
@@ -302,6 +411,16 @@ gdk_gc_set_ts_origin (GdkGC *gc,
 		     GDK_GC_TS_X_ORIGIN | GDK_GC_TS_Y_ORIGIN);
 }
 
+/**
+ * gdk_gc_set_clip_origin:
+ * @gc: a #GdkGC.
+ * @x: the x-coordinate of the origin.
+ * @y: the y-coordinate of the origin.
+ * 
+ * Sets the origin of the clip mask. The coordinates are
+ * interpreted relative to the upper-left corner of
+ * the destination drawable of the current operation.
+ **/
 void
 gdk_gc_set_clip_origin (GdkGC *gc,
 			gint   x,
@@ -318,6 +437,15 @@ gdk_gc_set_clip_origin (GdkGC *gc,
 		     GDK_GC_CLIP_X_ORIGIN | GDK_GC_CLIP_Y_ORIGIN);
 }
 
+/**
+ * gdk_gc_set_clip_mask:
+ * @gc: the #GdkGC.
+ * @mask: a bitmap.
+ * 
+ * Sets the clip mask for a graphics context from a bitmap.
+ * The clip mask is interpreted relative to the clip
+ * origin. (See gdk_gc_set_clip_origin()).
+ **/
 void
 gdk_gc_set_clip_mask (GdkGC	*gc,
 		      GdkBitmap *mask)
@@ -331,6 +459,14 @@ gdk_gc_set_clip_mask (GdkGC	*gc,
 }
 
 
+/**
+ * gdk_gc_set_subwindow:
+ * @gc: a #GdkGC.
+ * @mode: the subwindow mode.
+ * 
+ * Sets how drawing with this GC on a window will affect child
+ * windows of that window. 
+ **/
 void
 gdk_gc_set_subwindow (GdkGC	       *gc,
 		      GdkSubwindowMode	mode)
@@ -343,6 +479,16 @@ gdk_gc_set_subwindow (GdkGC	       *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_SUBWINDOW);
 }
 
+/**
+ * gdk_gc_set_exposures:
+ * @gc: a #GdkGC.
+ * @exposures: if %TRUE, exposure events will be generated.
+ * 
+ * Sets whether copying non-visible portions of a drawable
+ * using this graphics context generate exposure events
+ * for the corresponding regions of the destination
+ * drawable. (See gdk_draw_drawable()).
+ **/
 void
 gdk_gc_set_exposures (GdkGC     *gc,
 		      gboolean   exposures)
@@ -355,6 +501,18 @@ gdk_gc_set_exposures (GdkGC     *gc,
   gdk_gc_set_values (gc, &values, GDK_GC_EXPOSURES);
 }
 
+/**
+ * gdk_gc_set_line_attributes:
+ * @gc: a #GdkGC.
+ * @line_width: the width of lines.
+ * @line_style: the dash-style for lines.
+ * @cap_style: the manner in which the ends of lines are drawn.
+ * @join_style: the in which lines are joined together.
+ * 
+ * Sets various attributes of how lines are drawn. See
+ * the corresponding members of #GdkGCValues for full
+ * explanations of the arguments.
+ **/
 void
 gdk_gc_set_line_attributes (GdkGC	*gc,
 			    gint	 line_width,
@@ -376,6 +534,24 @@ gdk_gc_set_line_attributes (GdkGC	*gc,
 		     GDK_GC_JOIN_STYLE);
 }
 
+/**
+ * gdk_gc_set_dashes:
+ * @gc: a #GdkGC.
+ * @dash_offset: the phase of the dash pattern.
+ * @dash_list: an array of dash lengths.
+ * @n: the number of elements in @dash_list.
+ * 
+ * Sets the way dashed-lines are drawn. Lines will be
+ * drawn with alternating on and off segments of the
+ * lengths specified in @dash_list. The manner in
+ * which the on and off segments are drawn is determined
+ * by the @line_style value of the GC. (This can
+ * be changed with gdk_gc_set_line_attributes().)
+ *
+ * The @dash_offset defines the phase of the pattern, 
+ * specifying how many pixels into the dash-list the pattern 
+ * should actually begin.
+ **/
 void
 gdk_gc_set_dashes (GdkGC *gc,
 		   gint	  dash_offset,
@@ -457,7 +633,7 @@ gdk_gc_set_colormap (GdkGC       *gc,
  * has a colormap, or if a colormap was set explicitely with
  * gdk_gc_set_colormap.
  * 
- * Return value: 
+ * Return value: the colormap of @gc, or %NULL if @gc doesn't have one.
  **/
 GdkColormap *
 gdk_gc_get_colormap (GdkGC *gc)

gdk/x11/gdkgc-x11.c

@@ -644,6 +644,15 @@ gdk_x11_gc_values_to_xvalues (GdkGCValues    *values,
 
 }
 
+/**
+ * gdk_gc_set_clip_rectangle:
+ * @gc: a #GdkGC.
+ * @rectangle: the rectangle to clip to.
+ * 
+ * Sets the clip mask for a graphics context from a
+ * rectangle. The clip mask is interpreted relative to the clip
+ * origin. (See gdk_gc_set_clip_origin()).
+ **/
 void
 gdk_gc_set_clip_rectangle (GdkGC	*gc,
 			   GdkRectangle *rectangle)
@@ -681,6 +690,15 @@ gdk_gc_set_clip_rectangle (GdkGC	*gc,
   x11_gc->dirty_mask |= GDK_GC_DIRTY_CLIP;
 }
 
+/**
+ * gdk_gc_set_clip_region:
+ * @gc: a #GdkGC.
+ * @region: the #GdkRegion. 
+ * 
+ * Sets the clip mask for a graphics context from a region structure.
+ * The clip mask is interpreted relative to the clip origin. (See
+ * gdk_gc_set_clip_origin()).
+ **/
 void
 gdk_gc_set_clip_region (GdkGC	  *gc,
 			GdkRegion *region)
@@ -719,6 +737,14 @@ gdk_gc_set_clip_region (GdkGC	  *gc,
 }
 
 
+/**
+ * gdk_gc_copy:
+ * @dst_gc: the destination graphics context.
+ * @src_gc: the source graphics context.
+ * 
+ * Copy the set of values from one graphics context
+ * onto another graphics context.
+ **/
 void
 gdk_gc_copy (GdkGC *dst_gc, GdkGC *src_gc)
 {