add --deprecated-guards

2001-02-19  Havoc Pennington  <hp@pobox.com>

	* gdk/Makefile.am (SCAN_OPTIONS): add --deprecated-guards

	* gdk/gdk-sections.txt: update

	* gdk/gdk-docs.sgml: update

2001-02-19  Havoc Pennington  <hp@pobox.com>

	* gdk/gdkwindow.c: docs

	* gdk/gdkrgb.c: docs

	* gdk/gdkregion-generic.c: docs

	* gdk/gdkgc.c (gdk_gc_set_values): docs

	* gdk/gdkdraw.c: docs

	* gdk/gdkdrawable.h: deprecate drawable get/set data

ChangeLog

@@ -1,3 +1,17 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/gdkwindow.c: docs
+
+	* gdk/gdkrgb.c: docs
+
+	* gdk/gdkregion-generic.c: docs
+
+	* gdk/gdkgc.c (gdk_gc_set_values): docs
+
+	* gdk/gdkdraw.c: docs
+
+	* gdk/gdkdrawable.h: deprecate drawable get/set data
+
 Mon Feb 19 20:37:35 2001  Jonathan Blandford  <jrb@redhat.com>
 
 	* demos/gtk-demo/dialog.c: Add simple new demo.

ChangeLog.pre-2-0

@@ -1,3 +1,17 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/gdkwindow.c: docs
+
+	* gdk/gdkrgb.c: docs
+
+	* gdk/gdkregion-generic.c: docs
+
+	* gdk/gdkgc.c (gdk_gc_set_values): docs
+
+	* gdk/gdkdraw.c: docs
+
+	* gdk/gdkdrawable.h: deprecate drawable get/set data
+
 Mon Feb 19 20:37:35 2001  Jonathan Blandford  <jrb@redhat.com>
 
 	* demos/gtk-demo/dialog.c: Add simple new demo.

ChangeLog.pre-2-10

@@ -1,3 +1,17 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/gdkwindow.c: docs
+
+	* gdk/gdkrgb.c: docs
+
+	* gdk/gdkregion-generic.c: docs
+
+	* gdk/gdkgc.c (gdk_gc_set_values): docs
+
+	* gdk/gdkdraw.c: docs
+
+	* gdk/gdkdrawable.h: deprecate drawable get/set data
+
 Mon Feb 19 20:37:35 2001  Jonathan Blandford  <jrb@redhat.com>
 
 	* demos/gtk-demo/dialog.c: Add simple new demo.

ChangeLog.pre-2-2

@@ -1,3 +1,17 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/gdkwindow.c: docs
+
+	* gdk/gdkrgb.c: docs
+
+	* gdk/gdkregion-generic.c: docs
+
+	* gdk/gdkgc.c (gdk_gc_set_values): docs
+
+	* gdk/gdkdraw.c: docs
+
+	* gdk/gdkdrawable.h: deprecate drawable get/set data
+
 Mon Feb 19 20:37:35 2001  Jonathan Blandford  <jrb@redhat.com>
 
 	* demos/gtk-demo/dialog.c: Add simple new demo.

ChangeLog.pre-2-4

@@ -1,3 +1,17 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/gdkwindow.c: docs
+
+	* gdk/gdkrgb.c: docs
+
+	* gdk/gdkregion-generic.c: docs
+
+	* gdk/gdkgc.c (gdk_gc_set_values): docs
+
+	* gdk/gdkdraw.c: docs
+
+	* gdk/gdkdrawable.h: deprecate drawable get/set data
+
 Mon Feb 19 20:37:35 2001  Jonathan Blandford  <jrb@redhat.com>
 
 	* demos/gtk-demo/dialog.c: Add simple new demo.

ChangeLog.pre-2-6

@@ -1,3 +1,17 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/gdkwindow.c: docs
+
+	* gdk/gdkrgb.c: docs
+
+	* gdk/gdkregion-generic.c: docs
+
+	* gdk/gdkgc.c (gdk_gc_set_values): docs
+
+	* gdk/gdkdraw.c: docs
+
+	* gdk/gdkdrawable.h: deprecate drawable get/set data
+
 Mon Feb 19 20:37:35 2001  Jonathan Blandford  <jrb@redhat.com>
 
 	* demos/gtk-demo/dialog.c: Add simple new demo.

ChangeLog.pre-2-8

@@ -1,3 +1,17 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/gdkwindow.c: docs
+
+	* gdk/gdkrgb.c: docs
+
+	* gdk/gdkregion-generic.c: docs
+
+	* gdk/gdkgc.c (gdk_gc_set_values): docs
+
+	* gdk/gdkdraw.c: docs
+
+	* gdk/gdkdrawable.h: deprecate drawable get/set data
+
 Mon Feb 19 20:37:35 2001  Jonathan Blandford  <jrb@redhat.com>
 
 	* demos/gtk-demo/dialog.c: Add simple new demo.

docs/reference/ChangeLog

@@ -1,3 +1,11 @@
+2001-02-19  Havoc Pennington  <hp@pobox.com>
+
+	* gdk/Makefile.am (SCAN_OPTIONS): add --deprecated-guards
+
+	* gdk/gdk-sections.txt: update
+
+	* gdk/gdk-docs.sgml: update
+
 2001-02-18  Havoc Pennington  <hp@pobox.com>
 
 	* gdk-pixbuf/Makefile.am (IGNORE_HFILES): add gdk-pixbuf-marshal.h

docs/reference/gdk/Makefile.am

@@ -10,7 +10,7 @@ DOC_MAIN_SGML_FILE=gdk-docs.sgml
 DOC_SOURCE_DIR=$(top_srcdir)/gdk
 
 # Extra options to supply to gtkdoc-scan
-SCAN_OPTIONS=
+SCAN_OPTIONS=--deprecated-guards="GDK_ENABLE_BROKEN|GDK_DISABLE_DEPRECATED"
 
 # Extra options to supply to gtkdoc-mkdb
 MKDB_OPTIONS=

docs/reference/gdk/gdk-docs.sgml

@@ -15,11 +15,9 @@
 <!entity gdk-Input-Methods SYSTEM "sgml/input_methods.sgml">
 <!entity gdk-Pango-Interaction SYSTEM "sgml/pango_interaction.sgml">
 <!entity gdk-Input-Contexts SYSTEM "sgml/input_contexts.sgml">
-<!entity gdk-Color-Contexts SYSTEM "sgml/color_contexts.sgml">
 <!entity gdk-Points-Rectangles-and-Regions SYSTEM "sgml/regions.sgml">
 <!entity gdk-Threads SYSTEM "sgml/threads.sgml">
-<!entity gdk-Key-Values SYSTEM "sgml/keys.sgml">
+<!entity gdk-Keys SYSTEM "sgml/keys.sgml">
-<!entity gdk-Keyboard-Handling SYSTEM "sgml/gdkkeys.sgml">
 <!entity gdk-Input-Devices SYSTEM "sgml/input_devices.sgml">
 <!entity gdk-Events SYSTEM "sgml/events.sgml">
 <!entity gdk-Event-Structures SYSTEM "sgml/event_structs.sgml">
@@ -48,7 +46,6 @@
     &gdk-Pixbufs;
 
     &gdk-Colormaps-and-Colors;
-    &gdk-Color-Contexts;
     &gdk-Visuals;
 
     &gdk-Fonts;
@@ -59,6 +56,8 @@
     &gdk-Events;
     &gdk-Event-Structures;
 
+    &gdk-Keys;
+
     &gdk-Selections;
     &gdk-Drag-and-Drop;
 
@@ -70,8 +69,6 @@
 
     &gdk-Input-Devices;
 
-    &gdk-Keyboard-Handling;
-
     &gdk-Pango-Interaction;
     &gdk-Input-Methods;
     &gdk-Input-Contexts;

docs/reference/gdk/gdk-sections.txt

@@ -6,9 +6,9 @@
 <FILE>general</FILE>
 gdk_init
 gdk_init_check
-gdk_exit
 gdk_set_locale
 gdk_set_sm_client_id
+gdk_exit
 
 <SUBSECTION>
 gdk_get_display
@@ -32,10 +32,6 @@ gdk_pointer_is_grabbed
 gdk_keyboard_grab
 gdk_keyboard_ungrab
 
-<SUBSECTION>
-gdk_key_repeat_disable
-gdk_key_repeat_restore
-
 <SUBSECTION>
 gdk_beep
 
@@ -273,8 +269,9 @@ gdk_draw_arc
 gdk_draw_polygon
 gdk_draw_glyphs
 gdk_draw_layout_line
+gdk_draw_layout_line_with_colors
 gdk_draw_layout
-
+gdk_draw_layout_with_colors
 <SUBSECTION>
 gdk_draw_string
 gdk_draw_text
@@ -423,6 +420,7 @@ gdk_window_freeze_updates
 gdk_window_thaw_updates
 gdk_window_process_all_updates
 gdk_window_process_updates
+gdk_window_set_debug_updates
 
 <SUBSECTION>
 gdk_window_set_user_data
@@ -547,6 +545,12 @@ GDK_HAVE_WCTYPE_H
 <FILE>pango_interaction</FILE>
 gdk_pango_context_get
 gdk_pango_context_set_colormap
+GdkPangoAttrEmbossed
+GdkPangoAttrStipple
+gdk_pango_attr_embossed_new
+gdk_pango_attr_stipple_new
+gdk_pango_layout_get_clip_region
+gdk_pango_layout_line_get_clip_region
 </SECTION>
 
 <SECTION>
@@ -567,28 +571,6 @@ gdk_ic_attr_new
 gdk_ic_attr_destroy
 </SECTION>
 
-<SECTION>
-<TITLE>Color Contexts</TITLE>
-<FILE>color_contexts</FILE>
-GdkColorContext
-GdkColorContextDither
-GdkColorContextMode
-
-gdk_color_context_new
-gdk_color_context_new_mono
-gdk_color_context_free
-gdk_color_context_get_pixel
-gdk_color_context_get_pixels
-gdk_color_context_get_pixels_incremental
-gdk_color_context_query_color
-gdk_color_context_query_colors
-gdk_color_context_add_palette
-gdk_color_context_init_dither
-gdk_color_context_free_dither
-gdk_color_context_get_pixel_from_palette
-gdk_color_context_get_index_from_palette
-</SECTION>
-
 <SECTION>
 <TITLE>Points, Rectangles and Regions</TITLE>
 <FILE>regions</FILE>

docs/reference/gdk/tmpl/drawing.sgml

@@ -122,6 +122,24 @@ more information.
 @height: 
 
 
+<!-- ##### FUNCTION gdk_drawable_get_clip_region ##### -->
+<para>
+
+</para>
+
+@drawable: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_drawable_get_visible_region ##### -->
+<para>
+
+</para>
+
+@drawable: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gdk_draw_point ##### -->
 <para>
 Draws a point, using the foreground color and other attributes of the #GdkGC.
@@ -279,6 +297,20 @@ polygon.
 @line: 
 
 
+<!-- ##### FUNCTION gdk_draw_layout_line_with_colors ##### -->
+<para>
+
+</para>
+
+@drawable: 
+@gc: 
+@x: 
+@y: 
+@line: 
+@foreground: 
+@background: 
+
+
 <!-- ##### FUNCTION gdk_draw_layout ##### -->
 <para>
 
@@ -291,6 +323,20 @@ polygon.
 @layout: 
 
 
+<!-- ##### FUNCTION gdk_draw_layout_with_colors ##### -->
+<para>
+
+</para>
+
+@drawable: 
+@gc: 
+@x: 
+@y: 
+@layout: 
+@foreground: 
+@background: 
+
+
 <!-- ##### FUNCTION gdk_draw_string ##### -->
 <para>
 Draws a string of characters in the given font or fontset.

docs/reference/gdk/tmpl/event_structs.sgml

@@ -95,6 +95,8 @@ example, it is these characters which should be added to the input buffer.
 When using <link linkend="gdk-Input-Methods"> Input Methods</link> to support
 internationalized text input, the composed characters appear here after the
 pre-editing has been completed.
+@hardware_keycode: 
+@group: 
 
 <!-- ##### STRUCT GdkEventButton ##### -->
 <para>

docs/reference/gdk/tmpl/events.sgml

@@ -226,6 +226,16 @@ Gets the timestamp from a #GdkEvent.
 no timestamp.
 
 
+<!-- ##### FUNCTION gdk_event_get_state ##### -->
+<para>
+
+</para>
+
+@event: 
+@state: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gdk_event_get_axis ##### -->
 <para>
 

docs/reference/gdk/tmpl/general.sgml

@@ -53,20 +53,6 @@ by GTK+ applications.
 @Returns: TRUE if initialization succeeded.
 
 
-<!-- ##### FUNCTION gdk_exit ##### -->
-<para>
-Exits the application using the exit() system call.
-</para>
-<para>
-This routine is provided mainly for backwards compatability, since it used to
-perform tasks necessary to exit the application cleanly. Those tasks are now
-performed in a function which is automatically called on exit (via the use
-of g_atexit()).
-</para>
-
-@error_code: the error code to pass to the exit() call.
-
-
 <!-- ##### FUNCTION gdk_set_locale ##### -->
 <para>
 Initializes the support for internationalization by calling the setlocale()
@@ -113,6 +99,20 @@ part of the X Windows distribution.)
 connection was opened, or NULL to remove the property.
 
 
+<!-- ##### FUNCTION gdk_exit ##### -->
+<para>
+Exits the application using the exit() system call.
+</para>
+<para>
+This routine is provided mainly for backwards compatability, since it used to
+perform tasks necessary to exit the application cleanly. Those tasks are now
+performed in a function which is automatically called on exit (via the use
+of g_atexit()).
+</para>
+
+@error_code: the error code to pass to the exit() call.
+
+
 <!-- ##### FUNCTION gdk_get_display ##### -->
 <para>
 Gets the name of the display, which usually comes from the DISPLAY
@@ -274,22 +274,6 @@ Ungrabs the keyboard, if it is grabbed by this application.
 available.
 
 
-<!-- ##### FUNCTION gdk_key_repeat_disable ##### -->
-<para>
-Disables the keyboard auto-repeat mode.
-This should be used with care as it may affect other applications.
-</para>
-
-
-
-<!-- ##### FUNCTION gdk_key_repeat_restore ##### -->
-<para>
-Restores the keyboard auto-repeat mode to its state when the application was
-started.
-</para>
-
-
-
 <!-- ##### FUNCTION gdk_beep ##### -->
 <para>
 Emits a short beep.

docs/reference/gdk/tmpl/keys.sgml

@@ -29,6 +29,96 @@ using gdk_keyval_to_upper() and gdk_keyval_to_lower().
 
 </para>
 
+<!-- ##### STRUCT GdkKeymap ##### -->
+<para>
+
+</para>
+
+@parent_instance: 
+
+<!-- ##### STRUCT GdkKeymapClass ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### STRUCT GdkKeymapKey ##### -->
+<para>
+
+</para>
+
+@keycode: 
+@group: 
+@level: 
+
+<!-- ##### STRUCT GdkKeyInfo ##### -->
+<para>
+
+</para>
+
+@keycode: 
+@group: 
+@level: 
+
+<!-- ##### FUNCTION gdk_keymap_get_default ##### -->
+<para>
+
+</para>
+
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_keymap_lookup_key ##### -->
+<para>
+
+</para>
+
+@keymap: 
+@key: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_keymap_translate_keyboard_state ##### -->
+<para>
+
+</para>
+
+@keymap: 
+@hardware_keycode: 
+@state: 
+@group: 
+@keyval: 
+@effective_group: 
+@level: 
+@unused_modifiers: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_keymap_get_entries_for_keyval ##### -->
+<para>
+
+</para>
+
+@keymap: 
+@keyval: 
+@keys: 
+@n_keys: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_keymap_get_entries_for_keycode ##### -->
+<para>
+
+</para>
+
+@keymap: 
+@hardware_keycode: 
+@keys: 
+@keyvals: 
+@n_entries: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gdk_keyval_name ##### -->
 <para>
 Converts a key value into a symbolic name.

docs/reference/gdk/tmpl/pango_interaction.sgml

@@ -31,3 +31,63 @@ Pango Interaction
 @colormap: 
 
 
+<!-- ##### STRUCT GdkPangoAttrEmbossed ##### -->
+<para>
+
+</para>
+
+@attr: 
+@embossed: 
+
+<!-- ##### STRUCT GdkPangoAttrStipple ##### -->
+<para>
+
+</para>
+
+@attr: 
+@stipple: 
+
+<!-- ##### FUNCTION gdk_pango_attr_embossed_new ##### -->
+<para>
+
+</para>
+
+@embossed: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_pango_attr_stipple_new ##### -->
+<para>
+
+</para>
+
+@bitmap: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_pango_layout_get_clip_region ##### -->
+<para>
+
+</para>
+
+@layout: 
+@x_origin: 
+@y_origin: 
+@index_ranges: 
+@n_ranges: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_pango_layout_line_get_clip_region ##### -->
+<para>
+
+</para>
+
+@line: 
+@x_origin: 
+@y_origin: 
+@index_ranges: 
+@n_ranges: 
+@Returns: 
+
+

docs/reference/gdk/tmpl/regions.sgml

@@ -270,3 +270,34 @@ Returns the union of a region and a rectangle.
 @source2: 
 
 
+<!-- ##### STRUCT GdkSpan ##### -->
+<para>
+
+</para>
+
+@x: 
+@y: 
+@width: 
+
+<!-- ##### USER_FUNCTION GdkSpanFunc ##### -->
+<para>
+
+</para>
+
+@span: 
+@data: 
+
+
+<!-- ##### FUNCTION gdk_region_spans_intersect_foreach ##### -->
+<para>
+
+</para>
+
+@region: 
+@spans: 
+@n_spans: 
+@sorted: 
+@function: 
+@data: 
+
+

docs/reference/gdk/tmpl/windows.sgml

@@ -443,6 +443,14 @@ Windows
 @update_children: 
 
 
+<!-- ##### FUNCTION gdk_window_set_debug_updates ##### -->
+<para>
+
+</para>
+
+@setting: 
+
+
 <!-- ##### FUNCTION gdk_window_set_user_data ##### -->
 <para>
 

gdk/gdkcursor.c

@@ -27,6 +27,14 @@
 #include "gdkcursor.h"
 #include "gdkinternals.h"
 
+/**
+ * gdk_cursor_ref:
+ * @cursor: a #GdkCursor
+ * 
+ * Adds a reference to @cursor.
+ * 
+ * Return value: Same @cursor that was passed in
+ **/
 GdkCursor*
 gdk_cursor_ref (GdkCursor *cursor)
 {
@@ -38,6 +46,14 @@ gdk_cursor_ref (GdkCursor *cursor)
   return cursor;
 }
 
+/**
+ * gdk_cursor_unref:
+ * @cursor: a #GdkCursor
+ *
+ * Removes a reference from @cursor, deallocating the cursor
+ * if no references remain.
+ * 
+ **/
 void
 gdk_cursor_unref (GdkCursor *cursor)
 {

gdk/gdkdraw.c

@@ -79,6 +79,17 @@ gdk_drawable_class_init (GdkDrawableClass *klass)
 /* Manipulation of drawables
  */
 
+/**
+ * gdk_drawable_set_data:
+ * @drawable: a #GdkDrawable
+ * @key: name to store the data under
+ * @data: arbitrary data
+ * @destroy_func: function to free @data, or %NULL
+ *
+ * This function is equivalent to g_object_set_data(),
+ * the #GObject variant should be used instead.
+ * 
+ **/
 void          
 gdk_drawable_set_data (GdkDrawable   *drawable,
 		       const gchar   *key,
@@ -93,6 +104,16 @@ gdk_drawable_set_data (GdkDrawable   *drawable,
                            destroy_func);
 }
 
+/**
+ * gdk_drawable_get_data:
+ * @drawable: a #GdkDrawable
+ * @key: name the data was stored under
+ * 
+ * Equivalent to g_object_get_data(); the #GObject variant should be
+ * used instead.
+ * 
+ * Return value: the data stored at @key
+ **/
 gpointer
 gdk_drawable_get_data (GdkDrawable   *drawable,
 		       const gchar   *key)
@@ -103,6 +124,16 @@ gdk_drawable_get_data (GdkDrawable   *drawable,
                              g_quark_try_string (key));
 }
 
+/**
+ * gdk_drawable_get_size:
+ * @drawable: a #GdkDrawable
+ * @width: location to store drawable's width, or %NULL
+ * @height: location to store drawable's height, or %NULL
+ *
+ * Fills *@width and *@height with the size of @drawable.
+ * @width or @height can be %NULL if you only want the other one.
+ * 
+ **/
 void
 gdk_drawable_get_size (GdkDrawable *drawable,
 		       gint        *width,
@@ -113,6 +144,14 @@ gdk_drawable_get_size (GdkDrawable *drawable,
   GDK_DRAWABLE_GET_CLASS (drawable)->get_size (drawable, width, height);  
 }
 
+/**
+ * gdk_drawable_get_visual:
+ * @drawable: a #GdkDrawable
+ * 
+ * Gets the #GdkVisual describing the pixel format of @drawable.
+ * 
+ * Return value: a #GdkVisual
+ **/
 GdkVisual*
 gdk_drawable_get_visual (GdkDrawable *drawable)
 {
@@ -121,6 +160,16 @@ gdk_drawable_get_visual (GdkDrawable *drawable)
   return GDK_DRAWABLE_GET_CLASS (drawable)->get_visual (drawable);
 }
 
+/**
+ * gdk_drawable_get_depth:
+ * @drawable: a #GdkDrawable
+ * 
+ * Obtains the bit depth of the drawable, that is, the number of bits
+ * that make up a pixel in the drawable's visual. Examples are 8 bits
+ * per pixel, 24 bits per pixel, etc.
+ * 
+ * Return value: number of bits per pixel
+ **/
 gint
 gdk_drawable_get_depth (GdkDrawable *drawable)
 {
@@ -129,6 +178,21 @@ gdk_drawable_get_depth (GdkDrawable *drawable)
   return GDK_DRAWABLE_GET_CLASS (drawable)->get_depth (drawable);
 }
 
+/**
+ * gdk_drawable_set_colormap:
+ * @drawable: a #GdkDrawable
+ * @colormap: a #GdkColormap
+ *
+ * Sets the colormap associated with @drawable. Normally this will
+ * happen automatically when the drawable is created; you only need to
+ * use this function if the drawable-creating function did not have a
+ * way to determine the colormap, and you then use drawable operations
+ * that require a colormap. The colormap for all drawables and
+ * graphics contexts you intend to use together should match. i.e.
+ * when using a #GdkGC to draw to a drawable, or copying one drawable
+ * to another, the colormaps should match.
+ * 
+ **/
 void
 gdk_drawable_set_colormap (GdkDrawable *drawable,
                            GdkColormap *cmap)
@@ -138,6 +202,15 @@ gdk_drawable_set_colormap (GdkDrawable *drawable,
   GDK_DRAWABLE_GET_CLASS (drawable)->set_colormap (drawable, cmap);
 }
 
+/**
+ * gdk_drawable_get_colormap:
+ * @drawable: a #GdkDrawable
+ * 
+ * Gets the colormap for @drawable, if one is set; returns
+ * %NULL otherwise.
+ * 
+ * Return value: the colormap, or %NULL
+ **/
 GdkColormap*
 gdk_drawable_get_colormap (GdkDrawable *drawable)
 {
@@ -146,12 +219,28 @@ gdk_drawable_get_colormap (GdkDrawable *drawable)
   return GDK_DRAWABLE_GET_CLASS (drawable)->get_colormap (drawable);
 }
 
+/**
+ * gdk_drawable_ref:
+ * @drawable: a #GdkDrawable
+ * 
+ * Deprecated equivalent of calling g_object_ref() on @drawable.
+ * (Drawables were not objects in previous versions of GDK.)
+ * 
+ * Return value: the same @drawable passed in
+ **/
 GdkDrawable*
 gdk_drawable_ref (GdkDrawable *drawable)
 {
   return (GdkDrawable *) g_object_ref (G_OBJECT (drawable));
 }
 
+/**
+ * gdk_drawable_unref:
+ * @drawable: a #GdkDrawable
+ * 
+ * Deprecated equivalent of calling g_object_unref() on @drawable.
+ * 
+ **/
 void
 gdk_drawable_unref (GdkDrawable *drawable)
 {
@@ -475,6 +564,42 @@ gdk_draw_glyphs (GdkDrawable      *drawable,
 }
 
 
+/**
+ * gdk_drawable_get_image:
+ * @drawable: a #GdkDrawable
+ * @x: x coordinate on @drawable
+ * @y: y coordinate on @drawable
+ * @width: width of region to get
+ * @height: height or region to get
+ * 
+ * A #GdkImage stores client-side image data (pixels). In contrast,
+ * #GdkPixmap and #GdkWindow are server-side
+ * objects. gdk_drawable_get_image() obtains the pixels from a
+ * server-side drawable as a client-side #GdkImage.  The format of a
+ * #GdkImage depends on the #GdkVisual of the current display, which
+ * makes manipulating #GdkImage extremely difficult; therefore, in
+ * most cases you should use gdk_pixbuf_get_from_drawable() instead of
+ * this lower-level function. A #GdkPixbuf contains image data in a
+ * canonicalized RGB format, rather than a display-dependent format.
+ * Of course, there's a convenience vs. speed tradeoff here, so you'll
+ * want to think about what makes sense for your application.
+ *
+ * @x, @y, @width, and @height define the region of @drawable to
+ * obtain as an image.
+ *
+ * You would usually copy image data to the client side if you intend
+ * to examine the values of individual pixels, for example to darken
+ * an image or add a red tint. It would be prohibitively slow to
+ * make a round-trip request to the windowing system for each pixel,
+ * so instead you get all of them at once, modify them, then copy
+ * them all back at once.
+ *
+ * If the X server or other windowing system backend is on the local
+ * machine, this function may use shared memory to avoid copying
+ * the image data.
+ * 
+ * Return value: a #GdkImage containing the contents of @drawable
+ **/
 GdkImage*
 gdk_drawable_get_image (GdkDrawable *drawable,
                         gint         x,

gdk/gdkdrawable.h

@@ -138,12 +138,14 @@ GType           gdk_drawable_get_type     (void);
 /* Manipulation of drawables
  */
 
+#ifndef GDK_DISABLE_DEPRECATED
 void            gdk_drawable_set_data     (GdkDrawable    *drawable,
 					   const gchar    *key,
 					   gpointer	  data,
 					   GDestroyNotify  destroy_func);
 gpointer        gdk_drawable_get_data     (GdkDrawable    *drawable,
 					   const gchar    *key);
+#endif /* GDK_DISABLE_DEPRECATED */
 
 void            gdk_drawable_get_size     (GdkDrawable	  *drawable,
 					   gint	          *width,

gdk/gdkgc.c

@@ -144,6 +144,19 @@ gdk_gc_get_values (GdkGC       *gc,
   GDK_GC_GET_CLASS (gc)->get_values (gc, values);
 }
 
+/**
+ * gdk_gc_set_values:
+ * @gc: a #GdkGC
+ * @values: struct containing the new values
+ * @values_mask: mask indicating which struct fields are to be used
+ *
+ * Sets attributes of a graphics context in bulk. For each flag set in
+ * @values_mask, the corresponding field will be read from @values and
+ * set as the new value for @gc. If you're only setting a few values
+ * on @gc, calling individual "setter" functions is likely more
+ * convenient.
+ * 
+ **/
 void
 gdk_gc_set_values (GdkGC           *gc,
 		   GdkGCValues	   *values,

gdk/gdkregion-generic.c

@@ -123,6 +123,14 @@ gdk_region_new ()
   return temp;
 }
 
+/**
+ * gdk_region_rectangle:
+ * @rectangle: a #GdkRectangle
+ * 
+ * Creates a new region containing the area @rectangle.
+ * 
+ * Return value: a new region
+ **/
 GdkRegion *
 gdk_region_rectangle (GdkRectangle *rectangle)
 {
@@ -144,6 +152,14 @@ gdk_region_rectangle (GdkRectangle *rectangle)
   return temp;
 }
 
+/**
+ * gdk_region_copy:
+ * @region: a #GdkRegion
+ * 
+ * Copies @region, creating an identical new region.
+ * 
+ * Return value: a new region identical to @region
+ **/
 GdkRegion *
 gdk_region_copy (GdkRegion *region)
 {
@@ -456,6 +472,16 @@ miIntersectO (GdkRegion    *pReg,
     }
 }
 
+/**
+ * gdk_region_intersect:
+ * @source1: a #GdkRegion
+ * @source2: another #GdkRegion
+ *
+ * Converts @source1 into the intersection between @source1 and @source2.
+ * That is, after calling this function @source2 will be unchanged and
+ * @source1 will be the areas the two regions have in common.
+ * 
+ **/
 void
 gdk_region_intersect (GdkRegion *region,
 		      GdkRegion *other)
@@ -1311,20 +1337,14 @@ miSubtractO (GdkRegion    *pReg,
     }
 }
 
-/*-
+/**
- *-----------------------------------------------------------------------
+ * gdk_region_subtract:
- * gdk_region_subtract --
+ * @source1: a #GdkRegion
- *	Subtract other from region and leave the result in region.
+ * @source2: another #GdkRegion
  *
- * Results:
+ * Subtracts any area in @source2 from the area in @source1.
- *	TRUE.
  * 
- * Side Effects:
+ **/
- *	region is overwritten.
- *
- *-----------------------------------------------------------------------
- */
-
 void
 gdk_region_subtract (GdkRegion *region,
 		     GdkRegion *other)
@@ -1346,6 +1366,17 @@ gdk_region_subtract (GdkRegion *region,
   miSetExtents (region);
 }
 
+/**
+ * gdk_region_xor:
+ * @source1: a #GdkRegion
+ * @source2: another #GdkRegion
+ *
+ * XORs the two regions, placing the result in @source1.  The XOR of two
+ * regions contains all areas which were not overlapping.  That is,
+ * it's the union of the regions minus the intersection of the
+ * regions.
+ * 
+ **/
 void
 gdk_region_xor (GdkRegion *sra,
 		GdkRegion *srb)

gdk/gdkrgb.c

@@ -917,6 +917,27 @@ gdk_rgb_gc_set_background (GdkGC *gc, guint32 rgb)
   gdk_gc_set_background (gc, &color);
 }
 
+/**
+ * gdk_rgb_find_color:
+ * @colormap: a #GdkColormap
+ * @color: a #GdkColor
+ *
+ * @colormap should be the colormap for the graphics context and
+ * drawable you're using to draw. If you're drawing to a #GtkWidget,
+ * call gtk_widget_get_colormap().
+ *
+ * @color should have its %red, %green, and %blue fields initialized;
+ * gdk_rgb_find_color() will fill in the %pixel field with the best
+ * matching pixel from a color cube. The color is then ready to be
+ * used for drawing, e.g. you can call gdk_gc_set_foreground() which
+ * expects %pixel to be initialized.
+ *
+ * In many cases, you can avoid this whole issue by calling
+ * gdk_gc_set_rgb_fg_color() or gdk_gc_set_rgb_bg_color(), which
+ * do not expect %pixel to be initialized in advance. If you use those
+ * functions, there's no need for gdk_rgb_find_color().
+ * 
+ **/
 void
 gdk_rgb_find_color (GdkColormap *colormap, GdkColor *color)
 {
@@ -3522,6 +3543,17 @@ gdk_rgb_ditherable (void)
   return gdk_rgb_colormap_ditherable (gdk_rgb_get_colormap ());
 }
 
+/**
+ * gdk_rgb_get_colormap:
+ * 
+ * Returns the preferred colormap for rendering image data.  Not a
+ * very useful function; historically, GDK could only render RGB image
+ * data to one colormap and visual, but in the current version it can
+ * render to any colormap and visual. So there's no need to call this
+ * function.
+ * 
+ * Return value: the preferred colormap
+ **/
 GdkColormap *
 gdk_rgb_get_colormap (void)
 {

gdk/gdkwindow.c

@@ -614,6 +614,16 @@ gdk_window_is_viewable (GdkWindow *window)
   return TRUE;
 }
 
+/**
+ * gdk_window_begin_paint_rect:
+ * @window: a #GdkWindow
+ * @rectangle: rectangle you intend to draw to
+ *
+ * A convenience wrapper around gdk_window_begin_paint_region() which
+ * creates a rectangular region for you. See
+ * gdk_window_begin_paint_region() for details.
+ * 
+ **/
 void
 gdk_window_begin_paint_rect (GdkWindow    *window,
 			     GdkRectangle *rectangle)
@@ -684,6 +694,51 @@ gdk_window_paint_init_bg (GdkWindow      *window,
 #include "x11/gdkx.h"
 #endif
 
+/**
+ * gdk_window_begin_paint_region:
+ * @window: a #GdkWindow
+ * @region: region you intend to draw to
+ *
+ * Indicates that you are beginning the process of redrawing @region.
+ * A backing store (offscreen buffer) large enough to contain @region
+ * will be created. The backing store will be initialized with the
+ * background color or background pixmap for @window. Then, all
+ * drawing operations performed on @window will be diverted to the
+ * backing store.  When you call gdk_window_end_paint(), the backing
+ * store will be copied to @window, making it visible onscreen. Only
+ * the part of window contained in @region will be modified; that is,
+ * drawing operations are clipped to @region.
+ *
+ * The net result of all this is to remove flicker, because the user
+ * sees the finished product appear all at once when you call
+ * gdk_window_end_paint(). If you draw to @window directly without
+ * calling gdk_window_begin_paint_region(), the user may see flicker
+ * as individual drawing operations are performed in sequence.  The
+ * clipping and background-initializing features of
+ * gdk_window_begin_paint_region() are conveniences for the
+ * programmer, so you can avoid doing that work yourself.
+ *
+ * When using GTK+, the widget system automatically places calls to
+ * gdk_window_begin_paint_region() and gdk_window_end_paint() around
+ * emissions of the expose_event signal. That is, if you're writing an
+ * expose event handler, you can assume that the exposed area in
+ * #GdkEventExpose has already been cleared to the window background,
+ * is already set as the clip region, and already has a backing store.
+ * Therefore in most cases, application code need not call
+ * gdk_window_begin_paint_region(). (You can disable the automatic
+ * calls around expose events on a widget-by-widget basis by calling
+ * gtk_widget_set_double_buffered().)
+ *
+ * If you call this function multiple times before calling the
+ * matching gdk_window_end_paint(), the backing stores are pushed onto
+ * a stack. gdk_window_end_paint() copies the topmost backing store
+ * onscreen, subtracts the topmost region from all other regions in
+ * the stack, and pops the stack. All drawing operations affect only
+ * the topmost backing store in the stack. One matching call to
+ * gdk_window_end_paint() is required for each call to
+ * gdk_window_begin_paint_region().
+ * 
+ **/
 void	      
 gdk_window_begin_paint_region (GdkWindow *window,
 			       GdkRegion *region)
@@ -783,6 +838,19 @@ gdk_window_begin_paint_region (GdkWindow *window,
 #endif /* USE_BACKING_STORE */
 }
 
+/**
+ * gdk_window_end_paint:
+ * @window: a #GdkWindow
+ *
+ * Indicates that the backing store created by the most recent call to
+ * gdk_window_begin_paint_region() should be copied onscreen and
+ * deleted, leaving the next-most-recent backing store or no backing
+ * store at all as the active paint region. See
+ * gdk_window_begin_paint_region() for full details. It is an error to
+ * call this function without a matching
+ * gdk_window_begin_paint_region() first.
+ * 
+ **/
 void
 gdk_window_end_paint (GdkWindow *window)
 {
@@ -799,7 +867,11 @@ gdk_window_end_paint (GdkWindow *window)
   if (GDK_WINDOW_DESTROYED (window))
     return;
 
-  g_return_if_fail (private->paint_stack != NULL);
+  if (private->paint_stack == NULL)
+    {
+      g_warning (G_STRLOC": no preceding call to gdk_window_begin_paint_region(), see documentation");
+      return;
+    }
 
   paint = private->paint_stack->data;
   private->paint_stack = g_slist_delete_link (private->paint_stack, private->paint_stack);
@@ -1694,6 +1766,13 @@ gdk_window_process_updates_internal (GdkWindow *window)
     }
 }
 
+/**
+ * gdk_window_process_all_updates:
+ *
+ * Calls gdk_window_process_updates() for all windows (see #GdkWindow)
+ * in the application.
+ * 
+ **/
 void
 gdk_window_process_all_updates (void)
 {
@@ -1725,6 +1804,21 @@ gdk_window_update_idle (gpointer data)
   return FALSE;
 }
 
+/**
+ * gdk_window_process_updates:
+ * @window: a #GdkWindow
+ * @update_children: whether to also process updates for child windows
+ *
+ * Sends one or more expose events to @window. The areas in each 
+ * expose event will cover the entire update area for the window (see
+ * gdk_window_invalidate_region() for details). Normally GDK calls
+ * gdk_window_process_all_updates() on your behalf, so there's no
+ * need to call this function unless you want to force expose events
+ * to be delivered immediately and synchronously (vs. the usual
+ * case, where GDK delivers them in an idle handler). Occasionally
+ * this is useful to produce nicer scrolling behavior, for example.
+ * 
+ **/
 void
 gdk_window_process_updates (GdkWindow *window,
 			    gboolean   update_children)
@@ -1751,6 +1845,17 @@ gdk_window_process_updates (GdkWindow *window,
     }
 }
 
+/**
+ * gdk_window_invalidate_rect:
+ * @window: a #GdkWindow
+ * @rect: rectangle to invalidate
+ * @invalidate_children: whether to also invalidate child windows
+ *
+ * A convenience wrapper around gdk_window_invalidate_region() which
+ * invalidates a rectangular region. See
+ * gdk_window_invalidate_region() for details.
+ * 
+ **/
 void
 gdk_window_invalidate_rect   (GdkWindow    *window,
 			      GdkRectangle *rect,
@@ -1784,6 +1889,30 @@ gdk_window_invalidate_rect   (GdkWindow    *window,
   gdk_region_destroy (region);
 }
 
+/**
+ * gdk_window_invalidate_region:
+ * @window: a #GdkWindow
+ * @region: a #GdkRegion
+ * @invalidate_children: %TRUE to also invalidate child windows 
+ *
+ * Adds @region to the update area for @window. The update area is the
+ * region that needs to be redrawn, or "dirty region." The call
+ * gdk_window_process_updates() sends one or more expose events to the
+ * window, which together cover the entire update area. An
+ * application would normally redraw the contents of @window in
+ * response to those expose events.
+ *
+ * GDK will call gdk_window_process_all_updates() on your behalf
+ * whenever your program returns to the main loop and becomes idle, so
+ * normally there's no need to do that manually, you just need to
+ * invalidate regions that you know should be redrawn.
+ *
+ * The @invalidate_children parameter controls whether the region of
+ * each child window that intersects @region will also be invalidated.
+ * If %FALSE, then the update area for child windows will remain
+ * unaffected.
+ *
+ **/
 void
 gdk_window_invalidate_region (GdkWindow *window,
 			      GdkRegion *region,
@@ -1874,6 +2003,19 @@ gdk_window_invalidate_region (GdkWindow *window,
   gdk_region_destroy (visible_region);
 }
 
+/**
+ * gdk_window_get_update_area:
+ * @window: a #GdkWindow
+ * 
+ * Transfers ownership of the update area from @window to the caller
+ * of the function. That is, after calling this function, @window will
+ * no longer have an invalid/dirty region; the update area is removed
+ * from @window and handed to you. If a window has no update area,
+ * gdk_window_get_update_area() returns %NULL. You are responsible for
+ * calling gdk_region_destroy() on the returned region if it's non-%NULL.
+ * 
+ * Return value: the update area for @window
+ **/
 GdkRegion *
 gdk_window_get_update_area (GdkWindow *window)
 {
@@ -1946,8 +2088,34 @@ gdk_window_thaw_updates (GdkWindow *window)
 				   gdk_window_update_idle, NULL, NULL);
 }
 
+/**
+ * gdk_window_set_debug_updates:
+ * @setting: %TRUE to turn on update debugging
+ *
+ * With update debugging enabled, calls to
+ * gdk_window_invalidate_region() clear the invalidated region of the
+ * screen to a noticeable color, and GDK pauses for a short time
+ * before sending exposes to windows during
+ * gdk_window_process_updates().  The net effect is that you can see
+ * the invalid region for each window and watch redraws as they
+ * occur. This allows you to diagnose inefficiencies in your application.
+ *
+ * In essence, because the GDK rendering model prevents all flicker,
+ * if you are redrawing the same region 400 times you may never
+ * notice, aside from noticing a speed problem. Enabling update
+ * debugging causes GTK to flicker slowly and noticeably, so you can
+ * see exactly what's being redrawn when, in what order.
+ *
+ * The --gtk-debug=updates command line option passed to GTK+ programs
+ * enables this debug option at application startup time. That's
+ * usually more useful than calling gdk_window_set_debug_updates()
+ * yourself, though you might want to use this function to enable
+ * updates sometime after application startup time.
+ * 
+ **/
 void
 gdk_window_set_debug_updates (gboolean setting)
 {
   debug_updates = setting;
 }
+