CVS is doing its broken pipe thing, this is more of the previous commit

2001-02-02  Havoc Pennington  <hp@redhat.com>

51 files changed, 2122 insertions, 257 deletions

diff --git a/gtk/gtkcellrenderer.c b/gtk/gtkcellrenderer.c
index d7724f49ab..0b69d98bcd 100644
--- a/gtk/gtkcellrenderer.c
+++ b/gtk/gtkcellrenderer.c
@@ -198,17 +198,23 @@ gtk_cell_renderer_set_property (GObject      *object,
     }
 }
 
+/**
+ * gtk_cell_renderer_get_size:
+ * @cell: a #GtkCellRenderer
+ * @widget: the widget the renderer is rendering to
+ * @width: location to return width needed to render a cell, or %NULL
+ * @height: location to return height needed to render a cell, or %NULL
+ * 
+ * Obtains the width and height needed to render the cell. Used by
+ * view widgets to determine the appropriate size for the cell_area
+ * passed to gtk_cell_renderer_render().
+ **/
 void
 gtk_cell_renderer_get_size (GtkCellRenderer *cell,
 			    GtkWidget *widget,
 			    gint      *width,
 			    gint      *height)
 {
-  /* It's actually okay to pass in a NULL cell, as we run into that
-   * a lot
-   */
-  if (cell == NULL)
-    return;
   g_return_if_fail (GTK_IS_CELL_RENDERER (cell));
   g_return_if_fail (GTK_CELL_RENDERER_GET_CLASS (cell)->get_size != NULL);
 
@@ -262,6 +268,22 @@ gtk_cell_renderer_render (GtkCellRenderer     *cell,
 					      flags);
 }
 
+/**
+ * gtk_cell_renderer_event:
+ * @cell: a #GtkCellRenderer
+ * @event: a #GdkEvent
+ * @widget: widget that received the event
+ * @path: widget-dependent string representation of the event location; e.g. for #GtkTreeView, a string representation of #GtkTreePath
+ * @background_area: background area as passed to gtk_cell_renderer_render()
+ * @cell_area: cell area as passed to gtk_cell_renderer_render()
+ * @flags: render flags
+ * 
+ * Passes an event to the cell renderer for possible processing.  Some
+ * cell renderers may use events; for example, #GtkCellRendererToggle
+ * toggles when it gets a mouse click.
+ * 
+ * Return value: %TRUE if the event was consumed/handled
+ **/
 gint
 gtk_cell_renderer_event (GtkCellRenderer     *cell,
 			 GdkEvent            *event,
diff --git a/gtk/gtkcellrendererpixbuf.c b/gtk/gtkcellrendererpixbuf.c
index 61a5572370..f3a434e37b 100644
--- a/gtk/gtkcellrendererpixbuf.c
+++ b/gtk/gtkcellrendererpixbuf.c
@@ -153,6 +153,19 @@ gtk_cell_renderer_pixbuf_set_property (GObject      *object,
     }
 }
 
+/**
+ * gtk_cell_renderer_pixbuf_new:
+ * 
+ * Creates a new #GtkCellRendererPixbuf. Adjust rendering
+ * parameters using object properties. Object properties can be set
+ * globally (with g_object_set()). Also, with #GtkTreeViewColumn, you
+ * can bind a property to a value in a #GtkTreeModel. For example, you
+ * can bind the "pixbuf" property on the cell renderer to a pixbuf value
+ * in the model, thus rendering a different image in each row of the
+ * #GtkTreeView.
+ * 
+ * Return value: the new cell renderer
+ **/
 GtkCellRenderer *
 gtk_cell_renderer_pixbuf_new (void)
 {
diff --git a/gtk/gtkcellrenderertext.c b/gtk/gtkcellrenderertext.c
index e98e6fd098..751659fc5c 100644
--- a/gtk/gtkcellrenderertext.c
+++ b/gtk/gtkcellrenderertext.c
@@ -331,6 +331,19 @@ gtk_cell_renderer_text_set_property (GObject      *object,
     }
 }
 
+/**
+ * gtk_cell_renderer_text_new:
+ * 
+ * Creates a new #GtkCellRendererText. Adjust how text is drawn using
+ * object properties. Object properties can be
+ * set globally (with g_object_set()). Also, with #GtkTreeViewColumn,
+ * you can bind a property to a value in a #GtkTreeModel. For example,
+ * you can bind the "text" property on the cell renderer to a string
+ * value in the model, thus rendering a different string in each row
+ * of the #GtkTreeView
+ * 
+ * Return value: the new cell renderer
+ **/
 GtkCellRenderer *
 gtk_cell_renderer_text_new (void)
 {
diff --git a/gtk/gtkcellrenderertextpixbuf.c b/gtk/gtkcellrenderertextpixbuf.c
index 8d8fe804bb..2f007dcc42 100644
--- a/gtk/gtkcellrenderertextpixbuf.c
+++ b/gtk/gtkcellrenderertextpixbuf.c
@@ -217,7 +217,6 @@ gtk_cell_renderer_text_pixbuf_get_property (GObject     *object,
     }
 }
 
-
 static void
 gtk_cell_renderer_text_pixbuf_set_property (GObject      *object,
 					    guint         param_id,
@@ -263,6 +262,19 @@ gtk_cell_renderer_text_pixbuf_set_property (GObject      *object,
     }
 }
 
+/**
+ * gtk_cell_renderer_text_pixbuf_new:
+ * 
+ * Creates a new #GtkCellRendererTextPixbuf. Adjust rendering
+ * parameters using object properties. Object properties can be set
+ * globally (with g_object_set()). Also, with #GtkTreeViewColumn, you
+ * can bind a property to a value in a #GtkTreeModel. For example, you
+ * can bind the "text" property on the cell renderer to a string value
+ * in the model, thus rendering a different string in each row of the
+ * #GtkTreeView
+ * 
+ * Return value: the new cell renderer
+ **/
 GtkCellRenderer *
 gtk_cell_renderer_text_pixbuf_new (void)
 {
diff --git a/gtk/gtkcellrenderertoggle.c b/gtk/gtkcellrenderertoggle.c
index 4ff6c7e520..2213f3c16b 100644
--- a/gtk/gtkcellrenderertoggle.c
+++ b/gtk/gtkcellrenderertoggle.c
@@ -184,7 +184,7 @@ gtk_cell_renderer_toggle_set_property (GObject      *object,
   switch (param_id)
     {
     case PROP_ACTIVE:
-      gtk_cell_renderer_toggle_set_active (celltoggle, g_value_get_boolean (value));
+      celltoggle->active = g_value_get_boolean (value);
       break;
     case PROP_RADIO:
       celltoggle->radio = g_value_get_boolean (value);
@@ -195,6 +195,19 @@ gtk_cell_renderer_toggle_set_property (GObject      *object,
     }
 }
 
+/**
+ * gtk_cell_renderer_toggle_new:
+ * 
+ * Creates a new #GtkCellRendererToggle. Adjust rendering
+ * parameters using object properties. Object properties can be set
+ * globally (with g_object_set()). Also, with #GtkTreeViewColumn, you
+ * can bind a property to a value in a #GtkTreeModel. For example, you
+ * can bind the "active" property on the cell renderer to a boolean value
+ * in the model, thus causing the check button to reflect the state of
+ * the model.
+ * 
+ * Return value: the new cell renderer
+ **/
 GtkCellRenderer *
 gtk_cell_renderer_toggle_new (void)
 {
@@ -299,35 +312,38 @@ gtk_cell_renderer_toggle_event (GtkCellRenderer *cell,
   return retval;
 }
 
+/**
+ * gtk_cell_renderer_toggle_set_radio:
+ * @toggle: a #GtkCellRendererToggle
+ * @radio: %TRUE to make the toggle look like a radio button
+ * 
+ * If @radio is %TRUE, the cell renderer renders a radio toggle
+ * (i.e. a toggle in a group of mutually-exclusive toggles).
+ * If %FALSE, it renders a check toggle (a standalone boolean option).
+ * This can be set globally for the cell renderer, or changed just
+ * before rendering each cell in the model (for #GtkTreeView, you set
+ * up a per-row setting using #GtkTreeViewColumn to associate model
+ * columns with cell renderer properties).
+ **/
 void
 gtk_cell_renderer_toggle_set_radio (GtkCellRendererToggle *toggle,
 				    gboolean               radio)
 {
-  g_return_if_fail (toggle != NULL);
   g_return_if_fail (GTK_IS_CELL_RENDERER_TOGGLE (toggle));
 
   toggle->radio = radio;
 }
 
+/**
+ * gtk_cell_renderer_toggle_get_radio:
+ * @toggle: a #GtkCellRendererToggle
+ * 
+ * Return value: %TRUE if we're rendering radio toggles rather than checkboxes
+ **/
 gboolean
-gtk_cell_renderer_toggle_get_active (GtkCellRendererToggle *toggle)
+gtk_cell_renderer_toggle_get_radio (GtkCellRendererToggle *toggle)
 {
   g_return_val_if_fail (GTK_IS_CELL_RENDERER_TOGGLE (toggle), FALSE);
 
-  return toggle->active;
-}
-
-void
-gtk_cell_renderer_toggle_set_active (GtkCellRendererToggle *toggle,
-                                     gboolean               setting)
-{
-  g_return_if_fail (GTK_IS_CELL_RENDERER_TOGGLE (toggle));
-
-  setting = !! setting;
-
-  if (toggle->active != setting)
-    {
-      toggle->active = setting;
-      g_object_notify (G_OBJECT (toggle), "active");
-    }
+  return toggle->radio;
 }
diff --git a/gtk/gtkclist.h b/gtk/gtkclist.h
index 3c41ed98ea..568c31f32f 100644
--- a/gtk/gtkclist.h
+++ b/gtk/gtkclist.h
@@ -25,6 +25,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTK_CLIST_H__
 #define __GTK_CLIST_H__
 
@@ -785,3 +787,5 @@ PangoLayout *_gtk_clist_create_cell_layout (GtkCList       *clist,
 #endif				/* __cplusplus */
 
 #endif				/* __GTK_CLIST_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 5f04910f95..d32eb52978 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -684,6 +684,20 @@ gtk_container_get_arg (GtkObject    *object,
     }
 }
 
+/**
+ * gtk_container_set_border_width:
+ * @container: a #GtkContainer
+ * @border_width: amount of blank space to leave <emphasis>outside</emphasis> the container
+ *
+ * The border width of a container is the amount of space to leave
+ * around the outside of the container. The only exception to this is
+ * #GtkWindow; because toplevel windows can't leave space outside,
+ * they leave the space inside. The border is added on all sides of
+ * the container. To add space to only one side, one approach is to
+ * create a #GtkAlignment widget, call gtk_widget_set_usize() to give
+ * it a size, and place it on the side of the container as a spacer.
+ * 
+ **/
 void
 gtk_container_set_border_width (GtkContainer *container,
 				guint         border_width)
@@ -700,6 +714,20 @@ gtk_container_set_border_width (GtkContainer *container,
     }
 }
 
+/**
+ * gtk_container_add:
+ * @container: a #GtkContainer
+ * @widget: a widget to be placed inside @container
+ * 
+ * Adds @widget to @container. Typically used for simple containers
+ * such as #GtkWindow, #GtkFrame, or #GtkButton; for more complicated
+ * layout containers such as #GtkBox or #GtkTable, this function will
+ * pick default packing parameters that may not be correct.  So
+ * consider functions such as gtk_box_pack_start() and
+ * gtk_table_attach() as an alternative to gtk_container_add() in
+ * those cases. A widget may be added to only one container at a time;
+ * you can't place the same widget inside two different containers.
+ **/
 void
 gtk_container_add (GtkContainer *container,
 		   GtkWidget    *widget)
@@ -708,11 +736,32 @@ gtk_container_add (GtkContainer *container,
   g_return_if_fail (GTK_IS_CONTAINER (container));
   g_return_if_fail (widget != NULL);
   g_return_if_fail (GTK_IS_WIDGET (widget));
-  g_return_if_fail (widget->parent == NULL);
+
+  if (widget->parent != NULL)
+    {
+      g_warning ("Attempting to add a widget with type %s to a container of "
+                 "type %s, but the widget is already inside a container of type %s",
+                 g_type_name (G_TYPE_FROM_INSTANCE (widget)),
+                 g_type_name (G_TYPE_FROM_INSTANCE (container)),
+                 g_type_name (G_TYPE_FROM_INSTANCE (widget->parent)));
+      return;
+    }
 
   gtk_signal_emit (GTK_OBJECT (container), container_signals[ADD], widget);
 }
 
+/**
+ * gtk_container_remove:
+ * @container: a #GtkContainer
+ * @widget: a current child of @container
+ * 
+ * Removes @widget from @container. @widget must be inside @container.
+ * Note that @container will own a reference to @widget, and that this
+ * may be the last reference held; so removing a widget from its
+ * container can destroy that widget. If you want to use @widget
+ * again, you need to add a reference to it while it's not inside
+ * a container, using g_object_ref().
+ **/
 void
 gtk_container_remove (GtkContainer *container,
 		      GtkWidget    *widget)
@@ -1087,6 +1136,19 @@ gtk_container_resize_children (GtkContainer *container)
   g_slist_free (resize_containers);
 }
 
+/**
+ * gtk_container_forall:
+ * @container: a #GtkContainer
+ * @callback: a callback
+ * @callback_data: callback user data
+ * 
+ * Invokes @callback on each child of @container, including children
+ * that are considered "internal" (implementation details of the
+ * container). "Internal" children generally weren't added by the user
+ * of the container, but were added by the container implementation
+ * itself.  Most applications should use gtk_container_foreach(),
+ * rather than gtk_container_forall().
+ **/
 void
 gtk_container_forall (GtkContainer *container,
 		      GtkCallback   callback,
@@ -1104,6 +1166,17 @@ gtk_container_forall (GtkContainer *container,
     class->forall (container, TRUE, callback, callback_data);
 }
 
+/**
+ * gtk_container_foreach:
+ * @container: a #GtkContainer
+ * @callback: a callback
+ * @callback_data: callback user data
+ * 
+ * Invokes @callback on each non-internal child of @container.  See
+ * gtk_container_forall() for details on what constitutes an
+ * "internal" child.  Most applications should use
+ * gtk_container_foreach(), rather than gtk_container_forall().
+ **/
 void
 gtk_container_foreach (GtkContainer *container,
 		       GtkCallback   callback,
diff --git a/gtk/gtkctree.h b/gtk/gtkctree.h
index b2dd4f39aa..69cc0b9821 100644
--- a/gtk/gtkctree.h
+++ b/gtk/gtkctree.h
@@ -28,6 +28,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTK_CTREE_H__
 #define __GTK_CTREE_H__
 
@@ -434,3 +436,5 @@ void gtk_ctree_sort_recursive                    (GtkCTree     *ctree,
 #endif				/* __cplusplus */
 
 #endif				/* __GTK_CTREE_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtkcurve.h b/gtk/gtkcurve.h
index ba0235156e..027a86c5e3 100644
--- a/gtk/gtkcurve.h
+++ b/gtk/gtkcurve.h
@@ -24,6 +24,16 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/*
+ * NOTE this widget is considered too specialized/little-used for
+ * GTK+, and will in the future be moved to some other package.  If
+ * your application needs this widget, feel free to use it, as the
+ * widget does work and is useful in some applications; it's just not
+ * of general interest. However, we are not accepting new features for
+ * the widget, and it will eventually move out of the GTK+
+ * distribution.
+ */
+
 #ifndef __GTK_CURVE_H__
 #define __GTK_CURVE_H__
 
diff --git a/gtk/gtkdrawingarea.h b/gtk/gtkdrawingarea.h
index 8ba240f451..72e713b4bb 100644
--- a/gtk/gtkdrawingarea.h
+++ b/gtk/gtkdrawingarea.h
@@ -63,9 +63,12 @@ struct _GtkDrawingAreaClass
 
 GtkType    gtk_drawing_area_get_type   (void) G_GNUC_CONST;
 GtkWidget* gtk_drawing_area_new        (void);
+
+#ifndef GTK_DISABLE_DEPRECATED
 void       gtk_drawing_area_size       (GtkDrawingArea      *darea,
 					gint                 width,
 					gint                 height);
+#endif /* GTK_DISABLE_DEPRECATED */
 
 
 #ifdef __cplusplus
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index a74589936b..dfc9a81665 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -2578,6 +2578,20 @@ gtk_entry_set_visibility (GtkEntry *entry,
   gtk_entry_recompute (entry);
 }
 
+/**
+ * gtk_entry_set_invisible_char:
+ * @entry: a #GtkEntry
+ * @ch: a Unicode character
+ * 
+ * Sets the character to use in place of the actual text when
+ * gtk_entry_set_visibility() has been called to set text visibility
+ * to %FALSE. i.e. this is the character used in "password mode" to
+ * show the user how many characters have been typed. The default
+ * invisible char is an asterisk ('*').  If you set the invisible char
+ * to 0, then the user will get no feedback at all; there will be
+ * no text on the screen as they type.
+ * 
+ **/
 void
 gtk_entry_set_invisible_char (GtkEntry *entry,
                               gunichar  ch)
diff --git a/gtk/gtkgamma.h b/gtk/gtkgamma.h
index 4875df82a9..931860e6eb 100644
--- a/gtk/gtkgamma.h
+++ b/gtk/gtkgamma.h
@@ -24,6 +24,16 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/*
+ * NOTE this widget is considered too specialized/little-used for
+ * GTK+, and will in the future be moved to some other package.  If
+ * your application needs this widget, feel free to use it, as the
+ * widget does work and is useful in some applications; it's just not
+ * of general interest. However, we are not accepting new features for
+ * the widget, and it will eventually move out of the GTK+
+ * distribution.
+ */
+
 #ifndef __GTK_GAMMA_CURVE_H__
 #define __GTK_GAMMA_CURVE_H__
 
diff --git a/gtk/gtkhruler.h b/gtk/gtkhruler.h
index 1c482331b6..829665c626 100644
--- a/gtk/gtkhruler.h
+++ b/gtk/gtkhruler.h
@@ -24,6 +24,16 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/*
+ * NOTE this widget is considered too specialized/little-used for
+ * GTK+, and will in the future be moved to some other package.  If
+ * your application needs this widget, feel free to use it, as the
+ * widget does work and is useful in some applications; it's just not
+ * of general interest. However, we are not accepting new features for
+ * the widget, and it will eventually move out of the GTK+
+ * distribution.
+ */
+
 #ifndef __GTK_HRULER_H__
 #define __GTK_HRULER_H__
 
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index ff724d4549..56d2fccc27 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -103,12 +103,49 @@ gtk_icon_factory_finalize (GObject *object)
   G_OBJECT_CLASS (parent_class)->finalize (object);
 }
 
+/**
+ * gtk_icon_factory_new:
+ *
+ * Creates a new #GtkIconFactory. An icon factory manages a collection
+ * of #GtkIconSet; a #GtkIconSet manages a set of variants of a
+ * particular icon (i.e. a #GtkIconSet contains variants for different
+ * sizes and widget states). Icons in an icon factory are named by a
+ * stock ID, which is a simple string identifying the icon. Each
+ * #GtkStyle has a list of #GtkIconFactory derived from the current
+ * theme; those icon factories are consulted first when searching for
+ * an icon. If the theme doesn't set a particular icon, GTK+ looks for
+ * the icon in a list of default icon factories, maintained by
+ * gtk_icon_factory_add_default() and
+ * gtk_icon_factory_remove_default(). Applications with icons should
+ * add a default icon factory with their icons, which will allow
+ * themes to override the icons for the application.
+ * 
+ * Return value: a new #GtkIconFactory
+ **/
 GtkIconFactory*
 gtk_icon_factory_new (void)
 {
   return GTK_ICON_FACTORY (g_object_new (GTK_TYPE_ICON_FACTORY, NULL));
 }
 
+/**
+ * gtk_icon_factory_add:
+ * @factory: a #GtkIconFactory
+ * @stock_id: icon name
+ * @icon_set: icon set
+ *
+ * Adds the given @icon_set to the icon factory, under the name
+ * @stock_id.  @stock_id should be namespaced for your application,
+ * e.g. "myapp-whatever-icon".  Normally applications create a
+ * #GtkIconFactory, then add it to the list of default factories with
+ * gtk_icon_factory_add_default(). Then they pass the @stock_id to
+ * widgets such as #GtkImage to display the icon. Themes can provide
+ * an icon with the same name (such as "myapp-whatever-icon") to
+ * override your application's default icons. If an icon already
+ * existed in @factory for @stock_id, it is unreferenced and replaced
+ * with the new @icon_set.
+ * 
+ **/
 void
 gtk_icon_factory_add (GtkIconFactory *factory,
                       const gchar    *stock_id,
@@ -139,6 +176,19 @@ gtk_icon_factory_add (GtkIconFactory *factory,
     gtk_icon_set_unref (old_value);
 }
 
+/**
+ * gtk_icon_factory_lookup:
+ * @factory: a #GtkIconFactory
+ * @stock_id: an icon name
+ * 
+ * Looks up @stock_id in the icon factory, returning an icon set
+ * if found, otherwise %NULL. For display to the user, you should
+ * use gtk_style_lookup_icon_set() on the #GtkStyle for the
+ * widget that will display the icon, instead of using this
+ * function directly, so that themes are taken into account.
+ * 
+ * Return value: icon set of @stock_id.
+ **/
 GtkIconSet *
 gtk_icon_factory_lookup (GtkIconFactory *factory,
                          const gchar    *stock_id)
@@ -152,6 +202,18 @@ gtk_icon_factory_lookup (GtkIconFactory *factory,
 static GtkIconFactory *gtk_default_icons = NULL;
 static GSList *default_factories = NULL;
 
+/**
+ * gtk_icon_factory_add_default:
+ * @factory: a #GtkIconFactory
+ * 
+ * Adds an icon factory to the list of icon factories searched by
+ * gtk_style_lookup_icon_set(). This means that, for example,
+ * gtk_image_new_from_stock() will be able to find icons in @factory.
+ * There will normally be an icon factory added for each library or
+ * application that comes with icons. The default icon factories
+ * can be overridden by themes.
+ * 
+ **/
 void
 gtk_icon_factory_add_default (GtkIconFactory *factory)
 {
@@ -162,6 +224,15 @@ gtk_icon_factory_add_default (GtkIconFactory *factory)
   default_factories = g_slist_prepend (default_factories, factory);
 }
 
+/**
+ * gtk_icon_factory_remove_default:
+ * @factory: a #GtkIconFactory previously added with gtk_icon_factory_add_default()
+ *
+ * Removes an icon factory from the list of default icon
+ * factories. Not normally used; you might use it for a library that
+ * can be unloaded or shut down.
+ * 
+ **/
 void
 gtk_icon_factory_remove_default (GtkIconFactory  *factory)
 {
@@ -172,6 +243,19 @@ gtk_icon_factory_remove_default (GtkIconFactory  *factory)
   g_object_unref (G_OBJECT (factory));
 }
 
+/**
+ * gtk_icon_factory_lookup_default:
+ * @stock_id: an icon name
+ *
+ * Looks for an icon in the list of default icon factories.  For
+ * display to the user, you should use gtk_style_lookup_icon_set() on
+ * the #GtkStyle for the widget that will display the icon, instead of
+ * using this function directly, so that themes are taken into
+ * account.
+ * 
+ * 
+ * Return value: a #GtkIconSet, or %NULL
+ **/
 GtkIconSet *
 gtk_icon_factory_lookup_default (const gchar *stock_id)
 {
@@ -428,6 +512,22 @@ init_icon_sizes (void)
     }
 }
 
+/**
+ * gtk_icon_size_lookup:
+ * @alias: name of an icon size
+ * @width: location to store icon width
+ * @height: location to store icon height
+ *
+ * Obtains the pixel size of an icon, normally @alias would be
+ * #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_BUTTON, etc.  This function
+ * isn't normally needed, gtk_widget_render_icon() is the usual
+ * way to get an icon for rendering, then just look at the size of
+ * the rendered pixbuf. The rendered pixbuf may not even correspond to
+ * the width/height returned by gtk_icon_size_lookup(), because themes
+ * are free to render the pixbuf however they like.
+ * 
+ * Return value: %TRUE if @alias was known.
+ **/
 gboolean
 gtk_icon_size_lookup (const gchar *alias,
                       gint        *widthp,
@@ -453,6 +553,16 @@ gtk_icon_size_lookup (const gchar *alias,
   return TRUE;
 }
 
+/**
+ * gtk_icon_size_register:
+ * @alias: name of the icon size
+ * @width: the icon width
+ * @height: the icon height
+ *
+ * Registers a new icon size, along the same lines as #GTK_ICON_SIZE_MENU,
+ * etc.
+ * 
+ **/
 void
 gtk_icon_size_register (const gchar *alias,
                         gint         width,
@@ -467,6 +577,15 @@ gtk_icon_size_register (const gchar *alias,
   icon_size_add (alias, width, height);
 }
 
+/**
+ * gtk_icon_size_register_alias:
+ * @alias: an alias for @target
+ * @target: an existing icon size name
+ *
+ * Registers @alias as another name for @target, usable when calling
+ * gtk_icon_size_lookup().
+ * 
+ **/
 void
 gtk_icon_size_register_alias (const gchar *alias,
                               const gchar *target)
@@ -523,6 +642,21 @@ struct _GtkIconSet
 
 static guint cache_serial = 0;
 
+/**
+ * gtk_icon_set_new:
+ * 
+ * Creates a new #GtkIconSet. A #GtkIconSet represents a single icon
+ * in various sizes and widget states. It can provide a #GdkPixbuf
+ * for a given size and state on request, and automatically caches
+ * some of the rendered #GdkPixbuf objects.
+ *
+ * Normally you would use gtk_widget_render_icon() instead of
+ * using #GtkIconSet directly. The one case where you'd use
+ * #GtkIconSet is to create application-specific icon sets to place in
+ * a #GtkIconFactory.
+ * 
+ * Return value: a new #GtkIconSet
+ **/
 GtkIconSet*
 gtk_icon_set_new (void)
 {
@@ -539,6 +673,14 @@ gtk_icon_set_new (void)
   return icon_set;
 }
 
+/**
+ * gtk_icon_set_ref:
+ * @icon_set: a #GtkIconSet
+ * 
+ * Increments the reference count on @icon_set
+ * 
+ * Return value: @icon_set is returned
+ **/
 GtkIconSet*
 gtk_icon_set_ref (GtkIconSet *icon_set)
 {
@@ -550,6 +692,13 @@ gtk_icon_set_ref (GtkIconSet *icon_set)
   return icon_set;
 }
 
+/**
+ * gtk_icon_set_unref:
+ * @icon_set: a #GtkIconSet
+ * 
+ * Decrements the reference count on @icon_set, and frees memory
+ * if the reference count reaches 0.
+ **/
 void
 gtk_icon_set_unref (GtkIconSet *icon_set)
 {
@@ -574,6 +723,14 @@ gtk_icon_set_unref (GtkIconSet *icon_set)
     }
 }
 
+/**
+ * gtk_icon_set_copy:
+ * @icon_set: a #GtkIconSet
+ * 
+ * Copies @icon_set by value. 
+ * 
+ * Return value: a new #GtkIconSet identical to the first.
+ **/
 GtkIconSet*
 gtk_icon_set_copy (GtkIconSet *icon_set)
 {
@@ -693,6 +850,24 @@ find_and_prep_icon_source (GtkIconSet       *icon_set,
   return source;
 }
 
+/**
+ * gtk_icon_set_render_icon:
+ * @icon_set: a #GtkIconSet
+ * @style: a #GtkStyle associated with @widget, or %NULL
+ * @direction: text direction
+ * @state: widget state
+ * @size: icon size
+ * @widget: widget that will display the icon, or %NULL
+ * @detail: detail to pass to the theme engine, or %NULL
+ * 
+ * Renders an icon using gtk_style_render_icon(). In most cases,
+ * gtk_widget_render_icon() is better, since it automatically
+ * provides most of the arguments from the current widget settings.
+ * A %NULL return value is possible if an icon file fails to load
+ * or the like.
+ * 
+ * Return value: a #GdkPixbuf to be displayed, or %NULL
+ **/
 GdkPixbuf*
 gtk_icon_set_render_icon (GtkIconSet        *icon_set,
                           GtkStyle          *style,
@@ -780,6 +955,19 @@ icon_source_compare (gconstpointer ap, gconstpointer bp)
     return 0;
 }
 
+/**
+ * gtk_icon_set_add_source:
+ * @icon_set: a #GtkIconSet
+ * @source: a #GtkIconSource
+ *
+ * Icon sets have a list of #GtkIconSource, which they use as base
+ * icons for rendering icons in different states and sizes. Icons are
+ * scaled, made to look insensitive, etc. in
+ * gtk_icon_set_render_icon(), but #GtkIconSet needs base images to
+ * work with. The base images and when to use them are described by
+ * #GtkIconSource.
+ * 
+ **/
 void
 gtk_icon_set_add_source (GtkIconSet *icon_set,
                          const GtkIconSource *source)
@@ -799,7 +987,15 @@ gtk_icon_set_add_source (GtkIconSet *icon_set,
                                              icon_source_compare);
 }
 
-GtkIconSource *
+/**
+ * gtk_icon_source_copy:
+ * @source: a #GtkIconSource
+ * 
+ * Creates a copy of @source; mostly useful for language bindings.
+ * 
+ * Return value: a new #GtkIconSource
+ **/
+GtkIconSource*
 gtk_icon_source_copy (const GtkIconSource *source)
 {
   GtkIconSource *copy;
@@ -818,6 +1014,13 @@ gtk_icon_source_copy (const GtkIconSource *source)
   return copy;
 }
 
+/**
+ * gtk_icon_source_free:
+ * @source: a #GtkIconSource
+ * 
+ * Frees a dynamically-allocated icon source, along with its
+ * filename, size, and pixbuf fields if those are not %NULL.
+ **/
 void
 gtk_icon_source_free (GtkIconSource *source)
 {
diff --git a/gtk/gtkimage.c b/gtk/gtkimage.c
index c44ad0fe31..53ea859d38 100644
--- a/gtk/gtkimage.c
+++ b/gtk/gtkimage.c
@@ -105,6 +105,19 @@ gtk_image_destroy (GtkObject *object)
 }
 
 
+/**
+ * gtk_image_new_from_pixmap:
+ * @pixmap: a #GdkPixmap, or %NULL
+ * @mask: a #GdkBitmap, or %NULL
+ * 
+ * Creates a #GtkImage widget displaying @pixmap with a @mask.
+ * A #GdkImage is a server-side image buffer in the pixel format of the
+ * current display. The #GtkImage does not assume a reference to the
+ * pixmap or mask; you still need to unref them if you own references.
+ * #GtkImage will add its own reference rather than adopting yours.
+ * 
+ * Return value: a new #GtkImage
+ **/
 GtkWidget*
 gtk_image_new_from_pixmap (GdkPixmap *pixmap,
                            GdkBitmap *mask)
@@ -118,6 +131,20 @@ gtk_image_new_from_pixmap (GdkPixmap *pixmap,
   return GTK_WIDGET (image);
 }
 
+/**
+ * gtk_image_new_from_image:
+ * @image: a #GdkImage, or %NULL
+ * @mask: a #GdkBitmap, or %NULL 
+ * 
+ * Creates a #GtkImage widget displaying a @image with a @mask.
+ * A #GdkImage is a client-side image buffer in the pixel format of the
+ * current display.
+ * The #GtkImage does not assume a reference to the
+ * image or mask; you still need to unref them if you own references.
+ * #GtkImage will add its own reference rather than adopting yours.
+ * 
+ * Return value: a new #GtkImage
+ **/
 GtkWidget*
 gtk_image_new_from_image  (GdkImage  *gdk_image,
                            GdkBitmap *mask)
@@ -131,6 +158,18 @@ gtk_image_new_from_image  (GdkImage  *gdk_image,
   return GTK_WIDGET (image);
 }
 
+/**
+ * gtk_image_new_from_file:
+ * @filename: a filename
+ * 
+ * Creates a new #GtkImage displaying the file @filename. If the
+ * file isn't found or can't be loaded, the #GtkImage will display
+ * a "broken image" icon. If you need to detect failures to load
+ * the file, use gdk_pixbuf_new_from_file() to load the file yourself,
+ * then create the #GtkImage from the pixbuf.
+ * 
+ * Return value: a new #GtkImage
+ **/
 GtkWidget*
 gtk_image_new_from_file   (const gchar *filename)
 {
@@ -143,6 +182,17 @@ gtk_image_new_from_file   (const gchar *filename)
   return GTK_WIDGET (image);
 }
 
+/**
+ * gtk_image_new_from_pixbuf:
+ * @pixbuf: a #GdkPixbuf, or %NULL
+ * 
+ * Creates a new #GtkImage displaying @pixbuf.
+ * The #GtkImage does not assume a reference to the
+ * pixbuf; you still need to unref it if you own references.
+ * #GtkImage will add its own reference rather than adopting yours.
+ * 
+ * Return value: a new #GtkImage
+ **/
 GtkWidget*
 gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf)
 {
@@ -155,6 +205,18 @@ gtk_image_new_from_pixbuf (GdkPixbuf *pixbuf)
   return GTK_WIDGET (image);  
 }
 
+/**
+ * gtk_image_new_from_stock:
+ * @stock_id: a stock icon name
+ * @size: a stock icon size
+ * 
+ * Creates a #GtkImage displaying a stock icon. Sample stock icon
+ * names are #GTK_STOCK_ICON_OPEN, #GTK_STOCK_ICON_EXIT. Sample stock sizes
+ * are #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. If the stock
+ * icon name isn't known, a "broken image" icon will be displayed instead.
+ * 
+ * Return value: a new #GtkImage displaying the stock icon
+ **/
 GtkWidget*
 gtk_image_new_from_stock (const gchar    *stock_id,
                           const gchar    *size)
@@ -168,6 +230,26 @@ gtk_image_new_from_stock (const gchar    *stock_id,
   return GTK_WIDGET (image);
 }
 
+/**
+ * gtk_image_new_from_icon_set:
+ * @icon_set: a #GtkIconSet
+ * @size: a stock icon size
+ *
+ * Creates a #GtkImage displaying an icon set. Sample stock sizes are
+ * #GTK_ICON_SIZE_MENU, #GTK_ICON_SIZE_SMALL_TOOLBAR. Instead of using
+ * this function, usually it's better to create a #GtkIconFactory, put
+ * your icon sets in the icon factory, add the icon factory to the
+ * list of default factories with gtk_icon_factory_add_default(), and
+ * then use gtk_image_new_from_stock(). This will allow themes to
+ * override the icon you ship with your application.
+ *
+ * The #GtkImage does not assume a reference to the
+ * icon set; you still need to unref it if you own references.
+ * #GtkImage will add its own reference rather than adopting yours.
+ * 
+ * 
+ * Return value: a new #GtkImage
+ **/
 GtkWidget*
 gtk_image_new_from_icon_set (GtkIconSet     *icon_set,
                              const gchar    *size)
@@ -181,6 +263,15 @@ gtk_image_new_from_icon_set (GtkIconSet     *icon_set,
   return GTK_WIDGET (image);
 }
 
+/**
+ * gtk_image_set_from_pixmap:
+ * @image: a #GtkImage
+ * @pixmap: a #GdkPixmap or %NULL
+ * @mask: a #GdkBitmap or %NULL
+ *
+ * See gtk_image_new_from_pixmap() for details.
+ * 
+ **/
 void
 gtk_image_set_from_pixmap (GtkImage  *image,
                            GdkPixmap *pixmap,
@@ -222,6 +313,15 @@ gtk_image_set_from_pixmap (GtkImage  *image,
     }
 }
 
+/**
+ * gtk_image_set_from_image:
+ * @image: a #GtkImage
+ * @gdk_image: a #GdkImage or %NULL
+ * @mask: a #GdkBitmap or %NULL
+ *
+ * See gtk_image_new_from_image() for details.
+ * 
+ **/
 void
 gtk_image_set_from_image  (GtkImage  *image,
                            GdkImage  *gdk_image,
@@ -259,6 +359,14 @@ gtk_image_set_from_image  (GtkImage  *image,
     }
 }
 
+/**
+ * gtk_image_set_from_file:
+ * @image: a #GtkImage
+ * @filename: a filename or %NULL
+ *
+ * See gtk_image_new_from_file() for details.
+ * 
+ **/
 void
 gtk_image_set_from_file   (GtkImage    *image,
                            const gchar *filename)
@@ -283,6 +391,14 @@ gtk_image_set_from_file   (GtkImage    *image,
   g_object_unref (G_OBJECT (pixbuf));
 }
 
+/**
+ * gtk_image_set_from_pixbuf:
+ * @image: a #GtkImage
+ * @pixbuf: a #GdkPixbuf or %NULL
+ *
+ * See gtk_image_new_from_pixbuf() for details. 
+ * 
+ **/
 void
 gtk_image_set_from_pixbuf (GtkImage  *image,
                            GdkPixbuf *pixbuf)
@@ -308,6 +424,15 @@ gtk_image_set_from_pixbuf (GtkImage  *image,
     }
 }
 
+/**
+ * gtk_image_set_from_stock:
+ * @image: a #GtkImage
+ * @stock_id: a stock icon name
+ * @size: a stock icon size
+ *
+ * See gtk_image_new_from_stock for details.
+ * 
+ **/
 void
 gtk_image_set_from_stock  (GtkImage       *image,
                            const gchar    *stock_id,
@@ -331,6 +456,15 @@ gtk_image_set_from_stock  (GtkImage       *image,
     }
 }
 
+/**
+ * gtk_image_set_from_icon_set:
+ * @image: a #GtkImage
+ * @icon_set: a #GtkIconSet
+ * @size: a stock icon size
+ *
+ * See gtk_image_new_from_icon_set() for details.
+ * 
+ **/
 void
 gtk_image_set_from_icon_set  (GtkImage       *image,
                               GtkIconSet     *icon_set,
@@ -356,6 +490,16 @@ gtk_image_set_from_icon_set  (GtkImage       *image,
     }
 }
 
+/**
+ * gtk_image_get_storage_type:
+ * @image: a #GtkImage
+ * 
+ * Gets the type of representation being used by the #GtkImage
+ * to store image data. If the #GtkImage has no image data,
+ * the return value will be %GTK_IMAGE_EMPTY.
+ * 
+ * Return value: image representation being used
+ **/
 GtkImageType
 gtk_image_get_storage_type (GtkImage *image)
 {
@@ -364,6 +508,19 @@ gtk_image_get_storage_type (GtkImage *image)
   return image->storage_type;
 }
 
+/**
+ * gtk_image_get_pixmap:
+ * @image: a #GtkImage
+ * @pixmap: location to store the pixmap, or %NULL
+ * @mask: location to store the mask, or %NULL
+ *
+ * Gets the pixmap and mask being displayed by the #GtkImage.
+ * The storage type of the image must be %GTK_IMAGE_EMPTY or
+ * %GTK_IMAGE_PIXMAP (see gtk_image_get_storage_type()).
+ * The caller of this function does not own a reference to the
+ * returned pixmap and mask.
+ * 
+ **/
 void
 gtk_image_get_pixmap (GtkImage   *image,
                       GdkPixmap **pixmap,
@@ -380,6 +537,18 @@ gtk_image_get_pixmap (GtkImage   *image,
     *mask = image->data.pixmap.mask;
 }
 
+/**
+ * gtk_image_get_image:
+ * @image: a #GtkImage
+ * @gdk_image: return location for a #GtkImage
+ * @mask: return location for a #GdkBitmap
+ * 
+ * Gets the #GdkImage and mask being displayed by the #GtkImage.
+ * The storage type of the image must be %GTK_IMAGE_EMPTY or
+ * %GTK_IMAGE_IMAGE (see gtk_image_get_storage_type()).
+ * The caller of this function does not own a reference to the
+ * returned image and mask.
+ **/
 void
 gtk_image_get_image  (GtkImage   *image,
                       GdkImage  **gdk_image,
@@ -396,6 +565,19 @@ gtk_image_get_image  (GtkImage   *image,
     *mask = image->data.image.mask;
 }
 
+/**
+ * gtk_image_get_pixbuf:
+ * @image: a #GtkImage
+ *
+ *
+ * Gets the #GdkPixbuf being displayed by the #GtkImage.
+ * The storage type of the image must be %GTK_IMAGE_EMPTY or
+ * %GTK_IMAGE_PIXBUF (see gtk_image_get_storage_type()).
+ * The caller of this function does not own a reference to the
+ * returned pixbuf.
+ * 
+ * Return value: the displayed pixbuf, or %NULL if the image is empty
+ **/
 GdkPixbuf*
 gtk_image_get_pixbuf (GtkImage *image)
 {
@@ -409,6 +591,19 @@ gtk_image_get_pixbuf (GtkImage *image)
   return image->data.pixbuf.pixbuf;
 }
 
+/**
+ * gtk_image_get_stock:
+ * @image: a #GtkImage
+ * @stock_id: place to store a stock icon name
+ * @size: place to store a stock icon size
+ *
+ * Gets the stock icon name and size being displayed by the #GtkImage.
+ * The storage type of the image must be %GTK_IMAGE_EMPTY or
+ * %GTK_IMAGE_STOCK (see gtk_image_get_storage_type()).
+ * The returned strings are owned by the #GtkImage and should not
+ * be freed.
+ * 
+ **/
 void
 gtk_image_get_stock  (GtkImage        *image,
                       gchar          **stock_id,
@@ -422,12 +617,25 @@ gtk_image_get_stock  (GtkImage        *image,
     image->data.stock.stock_id = NULL;
   
   if (stock_id)
-    *stock_id = g_strdup (image->data.stock.stock_id);
+    *stock_id = image->data.stock.stock_id;
 
   if (size)
     *size = image->data.stock.size;
 }
 
+/**
+ * gtk_image_get_icon_set:
+ * @image: a #GtkImage
+ * @icon_set: location to store a #GtkIconSet
+ * @size: location to store a stock icon size
+ *
+ * Gets the icon set and size being displayed by the #GtkImage.
+ * The storage type of the image must be %GTK_IMAGE_EMPTY or
+ * %GTK_IMAGE_ICON_SET (see gtk_image_get_storage_type()).
+ * The returned size string is owned by the #GtkImage and should not
+ * be freed.
+ * 
+ **/
 void
 gtk_image_get_icon_set  (GtkImage        *image,
                          GtkIconSet     **icon_set,
@@ -441,7 +649,7 @@ gtk_image_get_icon_set  (GtkImage        *image,
     *icon_set = image->data.icon_set.icon_set;
 
   if (size)
-    *size = g_strdup (image->data.icon_set.size);
+    *size = image->data.icon_set.size;
 }
 
 GtkWidget*
@@ -534,10 +742,10 @@ gtk_image_expose (GtkWidget      *widget,
           break;
 
         case GTK_IMAGE_STOCK:
-          stock_pixbuf = gtk_widget_render_stock_icon (widget,
-                                                       image->data.stock.stock_id,
-                                                       image->data.stock.size,
-                                                       NULL);
+          stock_pixbuf = gtk_widget_render_icon (widget,
+                                                 image->data.stock.stock_id,
+                                                 image->data.stock.size,
+                                                 NULL);
           if (stock_pixbuf)
             {              
               image_bound.width = gdk_pixbuf_get_width (stock_pixbuf);
@@ -741,10 +949,10 @@ gtk_image_size_request (GtkWidget      *widget,
   switch (image->storage_type)
     {
     case GTK_IMAGE_STOCK:
-      pixbuf = gtk_widget_render_stock_icon (GTK_WIDGET (image),
-                                             image->data.stock.stock_id,
-                                             image->data.stock.size,
-                                             NULL);
+      pixbuf = gtk_widget_render_icon (GTK_WIDGET (image),
+                                       image->data.stock.stock_id,
+                                       image->data.stock.size,
+                                       NULL);
       break;
 
     case GTK_IMAGE_ICON_SET:
diff --git a/gtk/gtkimage.h b/gtk/gtkimage.h
index 266d032e67..0c5da6db62 100644
--- a/gtk/gtkimage.h
+++ b/gtk/gtkimage.h
@@ -160,7 +160,7 @@ void       gtk_image_get_icon_set (GtkImage         *image,
                                    gchar           **size);
 
 
-
+#ifndef GTK_DISABLE_DEPRECATED
 /* These three are deprecated */
 
 GtkWidget* gtk_image_new      (GdkImage   *val,
@@ -171,7 +171,7 @@ void       gtk_image_set      (GtkImage   *image,
 void       gtk_image_get      (GtkImage   *image,
 			       GdkImage  **val,
 			       GdkBitmap **mask);
-
+#endif /* GTK_DISABLE_DEPRECATED */
 
 #ifdef __cplusplus
 }
diff --git a/gtk/gtkinputdialog.h b/gtk/gtkinputdialog.h
index e7a7f8131e..a661c0b106 100644
--- a/gtk/gtkinputdialog.h
+++ b/gtk/gtkinputdialog.h
@@ -24,6 +24,16 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/*
+ * NOTE this widget is considered too specialized/little-used for
+ * GTK+, and will in the future be moved to some other package.  If
+ * your application needs this widget, feel free to use it, as the
+ * widget does work and is useful in some applications; it's just not
+ * of general interest. However, we are not accepting new features for
+ * the widget, and it will eventually move out of the GTK+
+ * distribution.
+ */
+
 #ifndef __GTK_INPUTDIALOG_H__
 #define __GTK_INPUTDIALOG_H__
 
diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 1a0939a37c..95facb2a7b 100644
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -308,7 +308,7 @@ gtk_label_set_markup (GtkLabel    *label,
 }
 
 /**
- * gtk_label_set_markup:
+ * gtk_label_set_markup_with_accel:
  * @label: a #GtkLabel
  * @str: a markup string (see <link linkend="PangoMarkupFormat">Pango markup format</link>)
  * 
@@ -318,6 +318,8 @@ gtk_label_set_markup (GtkLabel    *label,
  * indicating that they represent a keyboard accelerator, and the GDK
  * keyval for the first underlined accelerator is returned. If there are
  * no underlines in the text, GDK_VoidSymbol will be returned.
+ *
+ * Return value: GDK keyval for accelerator
  **/
 guint
 gtk_label_set_markup_with_accel (GtkLabel    *label,
diff --git a/gtk/gtklabel.h b/gtk/gtklabel.h
index 04c579c4cb..787ffed50f 100644
--- a/gtk/gtklabel.h
+++ b/gtk/gtklabel.h
@@ -47,8 +47,6 @@ extern "C" {
 typedef struct _GtkLabel       GtkLabel;
 typedef struct _GtkLabelClass  GtkLabelClass;
 
-typedef struct _GtkLabelWord   GtkLabelWord;
-
 struct _GtkLabel
 {
   GtkMisc misc;
@@ -101,9 +99,11 @@ guint       gtk_label_parse_uline   (GtkLabel         *label,
 #  define gtk_label_set				gtk_label_set_text
 #endif	/* GTK_DISABLE_COMPAT_H */
 
+#ifndef GTK_DISABLE_DEPRECATED
 /* Deprecated */
 void       gtk_label_get           (GtkLabel          *label,
                                     char             **str);
+#endif /* GTK_DISABLE_DEPRECATED */
 
 #ifdef __cplusplus
 }
diff --git a/gtk/gtklayout.h b/gtk/gtklayout.h
index 54aa39e714..b0f2004aff 100644
--- a/gtk/gtklayout.h
+++ b/gtk/gtklayout.h
@@ -106,6 +106,8 @@ void           gtk_layout_set_hadjustment (GtkLayout     *layout,
 void           gtk_layout_set_vadjustment (GtkLayout     *layout,
 					   GtkAdjustment *adjustment);
 
+
+#ifndef GTK_DISABLE_DEPRECATED
 /* These disable and enable moving and repainting the scrolling window
  * of the GtkLayout, respectively.  If you want to update the layout's
  * offsets but do not want it to repaint itself, you should use these
@@ -116,6 +118,7 @@ void           gtk_layout_set_vadjustment (GtkLayout     *layout,
  */
 void           gtk_layout_freeze          (GtkLayout     *layout);
 void           gtk_layout_thaw            (GtkLayout     *layout);
+#endif /* GTK_DISABLE_DEPRECATED */
 
 #ifdef __cplusplus
 }
diff --git a/gtk/gtklist.h b/gtk/gtklist.h
index 027930e3a5..e4e15bd94b 100644
--- a/gtk/gtklist.h
+++ b/gtk/gtklist.h
@@ -24,6 +24,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTK_LIST_H__
 #define __GTK_LIST_H__
 
@@ -142,3 +144,5 @@ void       gtk_list_end_drag_selection    (GtkList          *list);
 
 
 #endif /* __GTK_LIST_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 2191146157..619594894e 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -235,12 +235,37 @@ gtk_list_store_init (GtkListStore *list_store)
   list_store->length = 0;
 }
 
+/**
+ * gtk_list_store_new:
+ *
+ * Creates a new #GtkListStore. A #GtkListStore implements the
+ * #GtkTreeModel interface, and stores a linked list of
+ * rows; each row can have any number of columns. Columns are of uniform type,
+ * i.e. all cells in a column have the same type such as #G_TYPE_STRING or
+ * #GDK_TYPE_PIXBUF. Use #GtkListStore to store data to be displayed in a
+ * #GtkTreeView.
+ * 
+ * Return value: a new #GtkListStore
+ **/
 GtkListStore *
 gtk_list_store_new (void)
 {
   return GTK_LIST_STORE (gtk_type_new (gtk_list_store_get_type ()));
 }
 
+/**
+ * gtk_list_store_new_with_types:
+ * @n_columns: number of columns in the list store
+ * @Varargs: pairs of column number and #GType
+ *
+ * Creates a new list store as with gtk_list_store_new(),
+ * simultaneously setting up the columns and column types as with
+ * gtk_list_store_set_n_columns() and
+ * gtk_list_store_set_column_type().
+ * 
+ * 
+ * Return value: a new #GtkListStore
+ **/
 GtkListStore *
 gtk_list_store_new_with_types (gint n_columns,
 			       ...)
@@ -264,6 +289,14 @@ gtk_list_store_new_with_types (gint n_columns,
   return retval;
 }
 
+/**
+ * gtk_list_store_set_n_columns:
+ * @store: a #GtkListStore
+ * @n_columns: number of columns
+ *
+ * Sets the number of columns in the #GtkListStore.
+ * 
+ **/
 void
 gtk_list_store_set_n_columns (GtkListStore *list_store,
 			      gint          n_columns)
@@ -293,6 +326,18 @@ gtk_list_store_set_n_columns (GtkListStore *list_store,
   list_store->n_columns = n_columns;
 }
 
+/**
+ * gtk_list_store_set_column_type:
+ * @store: a #GtkListStore
+ * @column: column number
+ * @type: type of the data stored in @column
+ *
+ * Supported types include: %G_TYPE_UINT, %G_TYPE_INT, %G_TYPE_UCHAR,
+ * %G_TYPE_CHAR, %G_TYPE_BOOLEAN, %G_TYPE_POINTER, %G_TYPE_FLOAT, %G_TYPE_STRING,
+ * %G_TYPE_OBJECT, and %G_TYPE_BOXED, along with subclasses of those types such
+ * as %GDK_TYPE_PIXBUF.
+ * 
+ **/
 void
 gtk_list_store_set_column_type (GtkListStore *list_store,
 				gint          column,
@@ -504,6 +549,19 @@ gtk_list_store_iter_parent (GtkTreeModel *tree_model,
 /* This is a somewhat inelegant function that does a lot of list
  * manipulations on it's own.
  */
+
+/**
+ * gtk_list_store_set_cell:
+ * @store: a #GtkListStore
+ * @iter: iterator for the row you're modifying
+ * @column: column number to modify
+ * @value: new value for the cell
+ *
+ * Sets the data in the cell specified by @iter and @column.
+ * The type of @value must be convertible to the type of the
+ * column.
+ * 
+ **/
 void
 gtk_list_store_set_cell (GtkListStore *list_store,
 			 GtkTreeIter  *iter,
@@ -560,10 +618,20 @@ gtk_list_store_set_cell (GtkListStore *list_store,
 			   NULL, iter);
 }
 
+/**
+ * gtk_list_store_set_valist:
+ * @list_store: a #GtkListStore
+ * @iter: row to set data for
+ * @var_args: va_list of column/value pairs
+ *
+ * See gtk_list_store_set(); this version takes a va_list for
+ * use by language bindings.
+ * 
+ **/
 void
 gtk_list_store_set_valist (GtkListStore *list_store,
                            GtkTreeIter  *iter,
-                           va_list	var_args)
+                           va_list	 var_args)
 {
   gint column;
 
@@ -614,7 +682,7 @@ gtk_list_store_set_valist (GtkListStore *list_store,
  * 
  * Sets the value of one or more cells in the row referenced by @iter.
  * The variable argument list should contain integer column numbers,
- * each column number followed by the value to be set. For example,
+ * each column number followed by the value to be set.
  * The list is terminated by a -1. For example, to set column 0 with type
  * %G_TYPE_STRING to "Foo", you would write gtk_list_store_set (store, iter,
  * 0, "Foo", -1).
@@ -633,6 +701,16 @@ gtk_list_store_set (GtkListStore *list_store,
   va_end (var_args);
 }
 
+/**
+ * gtk_list_store_get_valist:
+ * @list_store: a #GtkListStore
+ * @iter: a row in @list_store
+ * @var_args: va_list of column/return location pairs
+ *
+ * See gtk_list_store_get(), this version takes a va_list for
+ * language bindings to use.
+ * 
+ **/
 void
 gtk_list_store_get_valist (GtkListStore *list_store,
                            GtkTreeIter  *iter,
@@ -675,6 +753,22 @@ gtk_list_store_get_valist (GtkListStore *list_store,
     }
 }
 
+/**
+ * gtk_list_store_get:
+ * @list_store: a #GtkListStore
+ * @iter: a row in @list_store
+ * @Varargs: pairs of column number and value return locations, terminated by -1
+ *
+ * Gets the value of one or more cells in the row referenced by @iter.
+ * The variable argument list should contain integer column numbers,
+ * each column number followed by a place to store the value being
+ * retrieved.  The list is terminated by a -1. For example, to get a
+ * value from column 0 with type %G_TYPE_STRING, you would
+ * write: gtk_list_store_set (store, iter, 0, &place_string_here, -1),
+ * where place_string_here is a gchar* to be filled with the string.
+ * If appropriate, the returned values have to be freed or unreferenced.
+ * 
+ **/
 void
 gtk_list_store_get (GtkListStore *list_store,
 		    GtkTreeIter  *iter,
@@ -751,6 +845,15 @@ gtk_list_store_remove_silently (GtkListStore *list_store,
   list_store->stamp ++;
 }
 
+/**
+ * gtk_list_store_remove:
+ * @store: a #GtkListStore
+ * @iter: a row in @list_store
+ *
+ * Removes the given row from the list store, emitting the
+ * "deleted" signal on #GtkTreeModel.
+ * 
+ **/
 void
 gtk_list_store_remove (GtkListStore *list_store,
 		       GtkTreeIter  *iter)
@@ -794,6 +897,17 @@ insert_after (GtkListStore *list_store,
   list_store->length += 1;
 }
 
+/**
+ * gtk_list_store_insert:
+ * @store: a #GtkListStore
+ * @iter: iterator to initialize with the new row
+ * @position: position to insert the new row
+ *
+ * Creates a new row at @position, initializing @iter to point to the
+ * new row, and emitting the "inserted" signal from the #GtkTreeModel
+ * interface.
+ * 
+ **/
 void
 gtk_list_store_insert (GtkListStore *list_store,
 		       GtkTreeIter  *iter,
@@ -839,6 +953,17 @@ gtk_list_store_insert (GtkListStore *list_store,
   gtk_tree_path_free (path);
 }
 
+/**
+ * gtk_list_store_insert_before:
+ * @store: a #GtkListStore
+ * @iter: iterator to initialize with the new row
+ * @sibling: an existing row
+ *
+ * Inserts a new row before @sibling, initializing @iter to point to
+ * the new row, and emitting the "inserted" signal from the
+ * #GtkTreeModel interface.
+ * 
+ **/
 void
 gtk_list_store_insert_before (GtkListStore *list_store,
 			      GtkTreeIter  *iter,
@@ -909,6 +1034,17 @@ gtk_list_store_insert_before (GtkListStore *list_store,
   gtk_tree_path_free (path);
 }
 
+/**
+ * gtk_list_store_insert_after:
+ * @store: a #GtkListStore
+ * @iter: iterator to initialize with the new row
+ * @sibling: an existing row
+ *
+ * Inserts a new row after @sibling, initializing @iter to point to
+ * the new row, and emitting the "inserted" signal from the
+ * #GtkTreeModel interface.
+ * 
+ **/
 void
 gtk_list_store_insert_after (GtkListStore *list_store,
 			     GtkTreeIter  *iter,
@@ -952,6 +1088,16 @@ gtk_list_store_insert_after (GtkListStore *list_store,
   gtk_tree_path_free (path);
 }
 
+/**
+ * gtk_list_store_prepend:
+ * @store: a #GtkListStore
+ * @iter: iterator to initialize with new row
+ *
+ * Prepends a row to @store, initializing @iter to point to the
+ * new row, and emitting the "inserted" signal on the #GtkTreeModel
+ * interface for the @store.
+ * 
+ **/
 void
 gtk_list_store_prepend (GtkListStore *list_store,
 			GtkTreeIter  *iter)
@@ -983,6 +1129,16 @@ gtk_list_store_prepend (GtkListStore *list_store,
   gtk_tree_path_free (path);
 }
 
+/**
+ * gtk_list_store_append:
+ * @store: a #GtkListStore
+ * @iter: iterator to initialize with the new row
+ *
+ * Appends a row to @store, initializing @iter to point to the
+ * new row, and emitting the "inserted" signal on the #GtkTreeModel
+ * interface for the @store.
+ * 
+ **/
 void
 gtk_list_store_append (GtkListStore *list_store,
 		       GtkTreeIter  *iter)
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index ebb324efb0..a6695a34ec 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -540,6 +540,17 @@ gtk_set_locale (void)
   return gdk_set_locale ();
 }
 
+/**
+ * gtk_get_default_language:
+ *
+ * Returns the ISO language code for the default language currently in
+ * effect. (Note that this can change over the life of an
+ * application.)  The default language is derived from the current
+ * locale. It determines, for example, whether GTK+ uses the
+ * right-to-left or left-to-right text direction.
+ * 
+ * Return value: the default language as an allocated string, must be freed
+ **/
 gchar*
 gtk_get_default_language (void)
 {
@@ -1304,6 +1315,17 @@ gtk_invoke_input (gpointer	    data,
   closure->marshal (NULL, closure->data, 2, args);
 }
 
+/**
+ * gtk_get_current_event:
+ * 
+ * Obtains a copy of the event currently being processed by GTK+.  For
+ * example, if you get a "clicked" signal from #GtkButton, the current
+ * event will be the #GdkEventButton that triggered the "clicked"
+ * signal. The returned event must be freed with gdk_event_free().
+ * If there is no current event, the function returns %NULL.
+ * 
+ * Return value: a copy of the current event, or %NULL if no current event.
+ **/
 GdkEvent*
 gtk_get_current_event (void)
 {
@@ -1330,6 +1352,16 @@ gtk_get_current_event_time (void)
     return GDK_CURRENT_TIME;
 }
 
+/**
+ * gtk_get_current_event_state:
+ * @state: a location to store the state of the current event
+ * 
+ * If there is a current event and it has a state field, place
+ * that state field in @state and return %TRUE, otherwise return
+ * %FALSE.
+ * 
+ * Return value: %TRUE if there was a current event and it had a state field
+ **/
 gboolean
 gtk_get_current_event_state (GdkModifierType *state)
 {
@@ -1344,6 +1376,16 @@ gtk_get_current_event_state (GdkModifierType *state)
     }
 }
 
+/**
+ * gtk_get_event_widget:
+ * @event: a #GdkEvent
+ *
+ * If @event is %NULL or the event was not associated with any widget,
+ * returns %NULL, otherwise returns the widget that received the event
+ * originally.
+ * 
+ * Return value: the widget that originally received @event, or %NULL
+ **/
 GtkWidget*
 gtk_get_event_widget (GdkEvent *event)
 {
@@ -1386,6 +1428,29 @@ gtk_quit_invoke_function (GtkQuitFunction *quitf)
     }
 }
 
+/**
+ * gtk_propagate_event:
+ * @widget: a #GtkWidget
+ * @event: an event
+ *
+ * Sends an event to a widget, propagating the event to parent widgets
+ * if the event remains unhandled. Events received by GTK+ from GDK
+ * normally begin in gtk_main_do_event(). Depending on the type of
+ * event, existence of modal dialogs, grabs, etc., the event may be
+ * propagated; if so, this function is used. gtk_propagate_event()
+ * calls gtk_widget_event() on each widget it decides to send the
+ * event to.  So gtk_widget_event() is the lowest-level function; it
+ * simply emits the "event" and possibly an event-specific signal on a
+ * widget.  gtk_propagate_event() is a bit higher-level, and
+ * gtk_main_do_event() is the highest level.
+ *
+ * All that said, you most likely don't want to use any of these
+ * functions; synthesizing events is rarely needed. Consider asking on
+ * the mailing list for better ways to achieve your goals. For
+ * example, use gdk_window_invalidate_rect() or
+ * gtk_widget_queue_draw() instead of making up expose events.
+ * 
+ **/
 void
 gtk_propagate_event (GtkWidget *widget,
 		     GdkEvent  *event)
diff --git a/gtk/gtkmain.h b/gtk/gtkmain.h
index 0f7651edb1..5701588ea7 100644
--- a/gtk/gtkmain.h
+++ b/gtk/gtkmain.h
@@ -103,7 +103,9 @@ gboolean gtk_init_check_abi_check (int	  *argc,
 
 #endif
 
+#ifndef GTK_DISABLE_DEPRECATED
 void     gtk_exit                 (gint    error_code);
+#endif /* GTK_DISABLE_DEPRECATED */
 gchar*   gtk_set_locale           (void);
 gchar*   gtk_get_default_language (void);
 gint     gtk_events_pending       (void);
diff --git a/gtk/gtkoldeditable.h b/gtk/gtkoldeditable.h
index 5736539477..702332331e 100644
--- a/gtk/gtkoldeditable.h
+++ b/gtk/gtkoldeditable.h
@@ -24,6 +24,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTK_OLD_EDITABLE_H__
 #define __GTK_OLD_EDITABLE_H__
 
@@ -140,3 +142,5 @@ void       gtk_old_editable_changed         (GtkOldEditable *old_editable);
 
 
 #endif /* __GTK_OLD_EDITABLE_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtkoptionmenu.c b/gtk/gtkoptionmenu.c
index 65802151b2..9d9a259968 100644
--- a/gtk/gtkoptionmenu.c
+++ b/gtk/gtkoptionmenu.c
@@ -256,6 +256,15 @@ gtk_option_menu_set_history (GtkOptionMenu *option_menu,
     }
 }
 
+/**
+ * gtk_option_menu_get_history:
+ * @option_menu: a #GtkOptionMenu
+ * 
+ * Retrieves the index of the currently selected menu item. The menu
+ * items are numbered from top to bottom, starting with 0. 
+ * 
+ * Return value: index of the selected menu item, or -1 if there are no menu items
+ **/
 gint
 gtk_option_menu_get_history (GtkOptionMenu *option_menu)
 {
diff --git a/gtk/gtkpacker.h b/gtk/gtkpacker.h
index a483c9da6d..130e35418f 100644
--- a/gtk/gtkpacker.h
+++ b/gtk/gtkpacker.h
@@ -27,6 +27,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTK_PACKER_H__
 #define __GTK_PACKER_H__
 
@@ -171,3 +173,5 @@ void       gtk_packer_set_default_ipad	       (GtkPacker	*packer,
 
 
 #endif /* __GTK_PACKER_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index 483084702b..dba1ebf584 100644
--- a/gtk/gtkpaned.c
+++ b/gtk/gtkpaned.c
@@ -480,6 +480,14 @@ gtk_paned_forall (GtkContainer *container,
     (*callback) (paned->child2, callback_data);
 }
 
+/**
+ * gtk_paned_get_position:
+ * @paned: a #GtkPaned widget
+ * 
+ * Obtains the position of the divider between the two panes.
+ * 
+ * Return value: position of the divider
+ **/
 gint
 gtk_paned_get_position (GtkPaned  *paned)
 {
@@ -489,6 +497,13 @@ gtk_paned_get_position (GtkPaned  *paned)
   return paned->child1_size;
 }
 
+/**
+ * gtk_paned_set_position:
+ * @paned: a #GtkPaned widget
+ * @position: pixel position of divider
+ * 
+ * Sets the position of the divider between the two panes.
+ **/
 void
 gtk_paned_set_position (GtkPaned *paned,
 			gint      position)
diff --git a/gtk/gtkpixmap.h b/gtk/gtkpixmap.h
index 3e386179ba..652457a416 100644
--- a/gtk/gtkpixmap.h
+++ b/gtk/gtkpixmap.h
@@ -24,6 +24,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTK_PIXMAP_H__
 #define __GTK_PIXMAP_H__
 
@@ -85,3 +87,5 @@ void       gtk_pixmap_set_build_insensitive (GtkPixmap *pixmap,
 
 
 #endif /* __GTK_PIXMAP_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtkpreview.h b/gtk/gtkpreview.h
index 224ddfce07..0dd5d7fdeb 100644
--- a/gtk/gtkpreview.h
+++ b/gtk/gtkpreview.h
@@ -24,6 +24,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTK_PREVIEW_H__
 #define __GTK_PREVIEW_H__
 
@@ -141,3 +143,5 @@ void            gtk_preview_reset              (void);
 
 
 #endif /* __GTK_PREVIEW_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtkprogress.h b/gtk/gtkprogress.h
index 0764262c5c..00c398c625 100644
--- a/gtk/gtkprogress.h
+++ b/gtk/gtkprogress.h
@@ -37,6 +37,7 @@
 extern "C" {
 #endif /* __cplusplus */
 
+#ifndef GTK_DISABLE_DEPRECATED
 
 #define GTK_TYPE_PROGRESS            (gtk_progress_get_type ())
 #define GTK_PROGRESS(obj)            (GTK_CHECK_CAST ((obj), GTK_TYPE_PROGRESS, GtkProgress))
@@ -45,6 +46,7 @@ extern "C" {
 #define GTK_IS_PROGRESS_CLASS(klass) (GTK_CHECK_CLASS_TYPE ((klass), GTK_TYPE_PROGRESS))
 #define GTK_PROGRESS_GET_CLASS(obj)  (GTK_CHECK_GET_CLASS ((obj), GTK_TYPE_PROGRESS, GtkProgressClass))
 
+#endif /* GTK_DISABLE_DEPRECATED */
 
 typedef struct _GtkProgress       GtkProgress;
 typedef struct _GtkProgressClass  GtkProgressClass;
@@ -78,6 +80,8 @@ struct _GtkProgressClass
  * directly.
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 GtkType    gtk_progress_get_type            (void) G_GNUC_CONST;
 void       gtk_progress_set_show_text       (GtkProgress   *progress,
 					     gint           show_text);
@@ -106,6 +110,7 @@ gfloat     gtk_progress_get_current_percentage (GtkProgress *progress);
 gfloat     gtk_progress_get_percentage_from_value (GtkProgress *progress,
 						   gfloat       value);
 
+#endif /* GTK_DISABLE_DEPRECATED */
 
 #ifdef __cplusplus
 }
diff --git a/gtk/gtkprogressbar.h b/gtk/gtkprogressbar.h
index 71d5713642..b4252960e3 100644
--- a/gtk/gtkprogressbar.h
+++ b/gtk/gtkprogressbar.h
@@ -115,7 +115,7 @@ GtkWidget* gtk_progress_bar_new                  (void);
  * rest deprecated. However, the changes are 100% backward-compatible and
  * should break no existing code.
  *
- * The following 5 functions are the new programming interface. 
+ * The following 9 functions are the new programming interface. 
  */
 void       gtk_progress_bar_pulse                (GtkProgressBar *pbar);
 void       gtk_progress_bar_set_text             (GtkProgressBar *pbar,
@@ -135,6 +135,8 @@ gfloat gtk_progress_bar_get_pulse_step (GtkProgressBar *pbar);
 GtkProgressBarOrientation gtk_progress_bar_get_orientation (GtkProgressBar *pbar);
 
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 /* Everything below here is deprecated */
 GtkWidget* gtk_progress_bar_new_with_adjustment  (GtkAdjustment  *adjustment);
 void       gtk_progress_bar_set_bar_style        (GtkProgressBar *pbar,
@@ -152,6 +154,8 @@ void       gtk_progress_bar_set_activity_blocks  (GtkProgressBar *pbar,
 void       gtk_progress_bar_update               (GtkProgressBar *pbar,
 						  gfloat          percentage);
 
+#endif /* GTK_DISABLE_DEPRECATED */
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/gtk/gtkruler.h b/gtk/gtkruler.h
index 2adb80cdb8..f9d4b20892 100644
--- a/gtk/gtkruler.h
+++ b/gtk/gtkruler.h
@@ -24,6 +24,16 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/*
+ * NOTE this widget is considered too specialized/little-used for
+ * GTK+, and will in the future be moved to some other package.  If
+ * your application needs this widget, feel free to use it, as the
+ * widget does work and is useful in some applications; it's just not
+ * of general interest. However, we are not accepting new features for
+ * the widget, and it will eventually move out of the GTK+
+ * distribution.
+ */
+
 #ifndef __GTK_RULER_H__
 #define __GTK_RULER_H__
 
diff --git a/gtk/gtkscrolledwindow.c b/gtk/gtkscrolledwindow.c
index af5d485140..8ffd505e82 100644
--- a/gtk/gtkscrolledwindow.c
+++ b/gtk/gtkscrolledwindow.c
@@ -470,6 +470,15 @@ gtk_scrolled_window_set_placement (GtkScrolledWindow *scrolled_window,
     }
 }
 
+/**
+ * gtk_scrolled_window_set_shadow_type:
+ * @scrolled_window: a #GtkScrolledWindow
+ * @type: kind of shadow to draw around scrolled window contents
+ *
+ * Changes the type of shadow drawn around the contents of
+ * @scrolled_window.
+ * 
+ **/
 void
 gtk_scrolled_window_set_shadow_type (GtkScrolledWindow *scrolled_window,
 				     GtkShadowType      type)
diff --git a/gtk/gtkstatusbar.c b/gtk/gtkstatusbar.c
index 1c0d343775..9f2be1b62f 100644
--- a/gtk/gtkstatusbar.c
+++ b/gtk/gtkstatusbar.c
@@ -30,6 +30,14 @@
 #include "gtksignal.h"
 #include "gtkstatusbar.h"
 
+typedef struct _GtkStatusbarMsg GtkStatusbarMsg;
+
+struct _GtkStatusbarMsg
+{
+  gchar *text;
+  guint context_id;
+  guint message_id;
+};
 
 enum
 {
diff --git a/gtk/gtkstatusbar.h b/gtk/gtkstatusbar.h
index ccfc2c244e..e29d796b60 100644
--- a/gtk/gtkstatusbar.h
+++ b/gtk/gtkstatusbar.h
@@ -45,7 +45,6 @@ extern "C" {
 
 typedef struct _GtkStatusbar      GtkStatusbar;
 typedef struct _GtkStatusbarClass GtkStatusbarClass;
-typedef struct _GtkStatusbarMsg GtkStatusbarMsg;
 
 struct _GtkStatusbar
 {
@@ -75,12 +74,6 @@ struct _GtkStatusbarClass
 			 const gchar	*text);
 };
 
-struct _GtkStatusbarMsg
-{
-  gchar *text;
-  guint context_id;
-  guint message_id;
-};
 
 GtkType    gtk_statusbar_get_type     	(void) G_GNUC_CONST;
 GtkWidget* gtk_statusbar_new          	(void);
diff --git a/gtk/gtkstock.c b/gtk/gtkstock.c
index 64700232aa..60f3e9d6a8 100644
--- a/gtk/gtkstock.c
+++ b/gtk/gtkstock.c
@@ -65,6 +65,19 @@ real_add (const GtkStockItem *items,
     }
 }
 
+/**
+ * gtk_stock_add:
+ * @items: a #GtkStockItem or array of items
+ * @n_items: number of #GtkStockItem in @items
+ *
+ * Registers each of the stock items in @items. If an item already
+ * exists with the same stock ID as one of the @items, the old item
+ * gets replaced. The stock items are copied, so GTK+ does not hold
+ * any pointer into @items and @items can be freed. Use
+ * gtk_stock_add_static() if @items is persistent and GTK+ need not
+ * copy the array.
+ * 
+ **/
 void
 gtk_stock_add (const GtkStockItem *items,
                guint               n_items)
@@ -74,6 +87,15 @@ gtk_stock_add (const GtkStockItem *items,
   real_add (items, n_items, TRUE);
 }
 
+/**
+ * gtk_stock_add_static:
+ * @items: a #GtkStockItem or array of #GtkStockItem
+ * @n_items: number of items
+ *
+ * Same as gtk_stock_add(), but doesn't copy @items, so
+ * @items must persist until application exit.
+ * 
+ **/
 void
 gtk_stock_add_static (const GtkStockItem *items,
                       guint               n_items)
@@ -83,6 +105,17 @@ gtk_stock_add_static (const GtkStockItem *items,
   real_add (items, n_items, FALSE);
 }
 
+/**
+ * gtk_stock_lookup:
+ * @stock_id: a stock item name
+ * @item: stock item to initialize with values
+ * 
+ * Fills @item with the registered values for @stock_id, returning %TRUE
+ * if @stock_id was known.
+ * 
+ * 
+ * Return value: %TRUE if @item was initialized
+ **/
 gboolean
 gtk_stock_lookup (const gchar  *stock_id,
                   GtkStockItem *item)
@@ -124,6 +157,15 @@ g_hash_table_get_values (GHashTable *table)
   return list;
 }
 
+/**
+ * gtk_stock_list_items:
+ * 
+ * Retrieves a list of all known #GtkStockItem. The items are not copied;
+ * they should not be freed. However, the list itself must be freed
+ * with g_slist_free().
+ * 
+ * Return value: a list of registered stock items
+ **/
 GSList *
 gtk_stock_list_items (void)
 {
@@ -132,6 +174,14 @@ gtk_stock_list_items (void)
   return g_hash_table_get_values (stock_hash);
 }
 
+/**
+ * gtk_stock_item_copy:
+ * @item: a #GtkStockItem
+ * 
+ * Copies a stock item, mostly useful for language bindings and not in applications.
+ * 
+ * Return value: a new #GtkStockItem
+ **/
 GtkStockItem *
 gtk_stock_item_copy (const GtkStockItem *item)
 {
@@ -150,6 +200,15 @@ gtk_stock_item_copy (const GtkStockItem *item)
   return copy;
 }
 
+/**
+ * gtk_stock_item_free:
+ * @item: a #GtkStockItem
+ *
+ * Frees a stock item allocated on the heap, such as one returned by
+ * gtk_stock_item_copy(). Also frees the fields inside the stock item,
+ * if they are not %NULL.
+ * 
+ **/
 void
 gtk_stock_item_free (GtkStockItem *item)
 {
diff --git a/gtk/gtkstock.h b/gtk/gtkstock.h
index a11fa95154..d40cb95602 100644
--- a/gtk/gtkstock.h
+++ b/gtk/gtkstock.h
@@ -45,9 +45,9 @@ struct _GtkStockItem
   gchar *translation_domain;
 };
 
-void     gtk_stock_add        (const GtkStockItem  *item,
+void     gtk_stock_add        (const GtkStockItem  *items,
                                guint                n_items);
-void     gtk_stock_add_static (const GtkStockItem  *item,
+void     gtk_stock_add_static (const GtkStockItem  *items,
                                guint                n_items);
 gboolean gtk_stock_lookup     (const gchar         *stock_id,
                                GtkStockItem        *item);
diff --git a/gtk/gtkstyle.h b/gtk/gtkstyle.h
index fff657cd71..d52248ae4d 100644
--- a/gtk/gtkstyle.h
+++ b/gtk/gtkstyle.h
@@ -461,12 +461,14 @@ void gtk_draw_diamond    (GtkStyle        *style,
 			  gint             y,
 			  gint             width,
 			  gint             height);
+#ifndef GTK_DISABLE_DEPRECATED
 void gtk_draw_string     (GtkStyle        *style,
 			  GdkWindow       *window,
 			  GtkStateType     state_type,
 			  gint             x,
 			  gint             y,
 			  const gchar     *string);
+#endif /* GTK_DISABLE_DEPRECATED */
 void gtk_draw_box        (GtkStyle        *style,
 			  GdkWindow       *window,
 			  GtkStateType     state_type,
@@ -638,6 +640,7 @@ void gtk_paint_diamond    (GtkStyle        *style,
 			   gint             y,
 			   gint             width,
 			   gint             height);
+#ifndef GTK_DISABLE_DEPRECATED
 void gtk_paint_string     (GtkStyle        *style,
 			   GdkWindow       *window,
 			   GtkStateType     state_type,
@@ -647,6 +650,7 @@ void gtk_paint_string     (GtkStyle        *style,
 			   gint             x,
 			   gint             y,
 			   const gchar     *string);
+#endif /* GTK_DISABLE_DEPRECATED */
 void gtk_paint_box        (GtkStyle        *style,
 			   GdkWindow       *window,
 			   GtkStateType     state_type,
diff --git a/gtk/gtktextbtree.c b/gtk/gtktextbtree.c
index 3e9d1648fb..db30bd9b5c 100644
--- a/gtk/gtktextbtree.c
+++ b/gtk/gtktextbtree.c
@@ -2705,6 +2705,18 @@ _gtk_text_btree_get_mark_by_name (GtkTextBTree *tree,
   return seg ? seg->body.mark.obj : NULL;
 }
 
+/**
+ * gtk_text_mark_set_visible:
+ * @mark: a #GtkTextMark
+ * @setting: visibility of mark
+ * 
+ * Sets the visibility of @mark; the insertion point is normally
+ * visible, i.e. you can see it as a vertical bar. Also, the text
+ * widget uses a visible mark to indicate where a drop will occur when
+ * dragging-and-dropping text. Most other marks are not visible.
+ * Marks are not visible by default.
+ * 
+ **/
 void
 gtk_text_mark_set_visible (GtkTextMark       *mark,
                            gboolean           setting)
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index a2c13ac0d3..1a4ccdb1f0 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -1394,6 +1394,22 @@ gtk_text_buffer_real_insert_pixbuf (GtkTextBuffer     *buffer,
   g_signal_emit (G_OBJECT (buffer), signals[CHANGED], 0);
 }
 
+/**
+ * gtk_text_buffer_insert_pixbuf:
+ * @buffer: a #GtkTextBuffer
+ * @iter: location to insert the pixbuf
+ * @pixbuf: a #GdkPixbuf
+ *
+ * Inserts an image into the text buffer at @iter. The image will be
+ * counted as one character in character counts, and when obtaining
+ * the buffer contents as a string, will be represented by the Unicode
+ * "object replacement character" 0xFFFC. Note that the "slice"
+ * variants for obtaining portions of the buffer as a string include
+ * this character for pixbufs, but the "text" variants do
+ * not. e.g. see gtk_text_buffer_get_slice() and
+ * gtk_text_buffer_get_text().
+ * 
+ **/
 void
 gtk_text_buffer_insert_pixbuf         (GtkTextBuffer      *buffer,
                                        GtkTextIter        *iter,
@@ -1889,6 +1905,18 @@ gtk_text_buffer_emit_tag (GtkTextBuffer *buffer,
 }
 
 
+/**
+ * gtk_text_buffer_apply_tag:
+ * @buffer: a #GtkTextBuffer
+ * @tag: a #GtkTextTag
+ * @start: one bound of range to be tagged
+ * @end: other bound of range to be tagged
+ *
+ * Emits the "apply_tag" signal on @buffer. The default
+ * handler for the signal applies @tag to the given range.
+ * @start and @end do not have to be in order.
+ * 
+ **/
 void
 gtk_text_buffer_apply_tag (GtkTextBuffer *buffer,
                            GtkTextTag    *tag,
@@ -1903,6 +1931,18 @@ gtk_text_buffer_apply_tag (GtkTextBuffer *buffer,
   gtk_text_buffer_emit_tag (buffer, tag, TRUE, start, end);
 }
 
+/**
+ * gtk_text_buffer_remove_tag:
+ * @buffer: a #GtkTextBuffer
+ * @tag: a #GtkTextTag
+ * @start: one bound of range to be untagged
+ * @end: other bound of range to be untagged
+ *
+ * Emits the "remove_tag" signal. The default handler for the signal
+ * removes all occurrences of @tag from the given range. @start and
+ * @end don't have to be in order.
+ * 
+ **/
 void
 gtk_text_buffer_remove_tag (GtkTextBuffer *buffer,
                             GtkTextTag    *tag,
@@ -1919,9 +1959,20 @@ gtk_text_buffer_remove_tag (GtkTextBuffer *buffer,
 }
 
 
+/**
+ * gtk_text_buffer_apply_tag_by_name:
+ * @buffer: a #GtkTextBuffer
+ * @name: name of a named #GtkTextTag
+ * @start: one bound of range to be tagged
+ * @end: other bound of range to be tagged
+ *
+ * Calls gtk_text_tag_table_lookup() on the buffer's tag table to
+ * get a #GtkTextTag, then calls gtk_text_buffer_apply_tag().
+ * 
+ **/
 void
 gtk_text_buffer_apply_tag_by_name (GtkTextBuffer *buffer,
-                                   const gchar *name,
+                                   const gchar   *name,
                                    const GtkTextIter *start,
                                    const GtkTextIter *end)
 {
@@ -1944,6 +1995,18 @@ gtk_text_buffer_apply_tag_by_name (GtkTextBuffer *buffer,
   gtk_text_buffer_emit_tag (buffer, tag, TRUE, start, end);
 }
 
+/**
+ * gtk_text_buffer_remove_tag_by_name:
+ * @buffer: a #GtkTextBuffer
+ * @name: name of a #GtkTextTag
+ * @start: one bound of range to be untagged
+ * @end: other bound of range to be untagged
+ *
+ * Calls gtk_text_tag_table_lookup() on the buffer's tag table to
+ * get a #GtkTextTag, then calls gtk_text_buffer_remove_tag().
+ * 
+ * 
+ **/
 void
 gtk_text_buffer_remove_tag_by_name (GtkTextBuffer *buffer,
                                     const gchar *name,
@@ -1974,6 +2037,19 @@ gtk_text_buffer_remove_tag_by_name (GtkTextBuffer *buffer,
  * Obtain various iterators
  */
 
+/**
+ * gtk_text_buffer_get_iter_at_line_offset:
+ * @buffer: a #GtkTextBuffer
+ * @iter: iterator to initialize
+ * @line_number: line number counting from 0
+ * @char_offset: char offset from start of line
+ *
+ * Obtains an iterator pointing to @char_offset within the given
+ * line. The @char_offset must exist, offsets off the end of the line
+ * are not allowed. Note <emphasis>characters</emphasis>, not bytes;
+ * UTF-8 may encode one character as multiple bytes.
+ * 
+ **/
 void
 gtk_text_buffer_get_iter_at_line_offset (GtkTextBuffer      *buffer,
                                          GtkTextIter        *iter,
@@ -1984,9 +2060,22 @@ gtk_text_buffer_get_iter_at_line_offset (GtkTextBuffer      *buffer,
   g_return_if_fail (GTK_IS_TEXT_BUFFER (buffer));
 
   _gtk_text_btree_get_iter_at_line_char (get_btree (buffer),
-                                        iter, line_number, char_offset);
+                                         iter, line_number, char_offset);
 }
 
+/**
+ * gtk_text_buffer_get_iter_at_line_index:
+ * @buffer: a #GtkTextBuffer 
+ * @iter: iterator to initialize 
+ * @line_number: line number counting from 0
+ * @byte_index: byte index from start of line
+ *
+ * Obtains an iterator pointing to @byte_index within the given line.
+ * @byte_index must be the start of a UTF-8 character, and must not be
+ * beyond the end of the line.  Note <emphasis>bytes</emphasis>, not
+ * characters; UTF-8 may encode one character as multiple bytes.
+ * 
+ **/
 void
 gtk_text_buffer_get_iter_at_line_index  (GtkTextBuffer *buffer,
                                          GtkTextIter   *iter,
@@ -1997,9 +2086,17 @@ gtk_text_buffer_get_iter_at_line_index  (GtkTextBuffer *buffer,
   g_return_if_fail (GTK_IS_TEXT_BUFFER (buffer));
 
   _gtk_text_btree_get_iter_at_line_byte (get_btree (buffer),
-                                        iter, line_number, byte_index);
+                                         iter, line_number, byte_index);
 }
 
+/**
+ * gtk_text_buffer_get_iter_at_line:
+ * @buffer: a #GtkTextBuffer 
+ * @iter: iterator to initialize
+ * @line_number: line number counting from 0
+ * 
+ * Initializes @iter to the start of the given line.
+ **/
 void
 gtk_text_buffer_get_iter_at_line    (GtkTextBuffer      *buffer,
                                      GtkTextIter        *iter,
@@ -2011,6 +2108,16 @@ gtk_text_buffer_get_iter_at_line    (GtkTextBuffer      *buffer,
   gtk_text_buffer_get_iter_at_line_offset (buffer, iter, line_number, 0);
 }
 
+/**
+ * gtk_text_buffer_get_iter_at_offset:
+ * @buffer: a #GtkTextBuffer 
+ * @iter: iterator to initialize
+ * @char_offset: char offset from start of buffer, counting from 0
+ *
+ * Initializes @iter to a position @char_offset chars from the start
+ * of the entire buffer.
+ * 
+ **/
 void
 gtk_text_buffer_get_iter_at_offset         (GtkTextBuffer      *buffer,
                                             GtkTextIter        *iter,
@@ -2022,6 +2129,19 @@ gtk_text_buffer_get_iter_at_offset         (GtkTextBuffer      *buffer,
   _gtk_text_btree_get_iter_at_char (get_btree (buffer), iter, char_offset);
 }
 
+/**
+ * gtk_text_buffer_get_last_iter:
+ * @buffer: a #GtkTextBuffer 
+ * @iter: iterator to initialize
+ *
+ * Initializes @iter with the "end iterator," one past the last valid
+ * character in the text buffer. If dereferenced with
+ * gtk_text_iter_get_char(), the end iterator has a character value of
+ * 0. The entire buffer lies in the range from the first position in
+ * the buffer (call gtk_text_buffer_get_iter_at_offset() to get
+ * character position 0) to the end iterator.
+ * 
+ **/
 void
 gtk_text_buffer_get_last_iter         (GtkTextBuffer      *buffer,
                                        GtkTextIter        *iter)
@@ -2032,6 +2152,16 @@ gtk_text_buffer_get_last_iter         (GtkTextBuffer      *buffer,
   _gtk_text_btree_get_last_iter (get_btree (buffer), iter);
 }
 
+/**
+ * gtk_text_buffer_get_bounds:
+ * @buffer: a #GtkTextBuffer 
+ * @start: iterator to initialize with first position in the buffer
+ * @end: iterator to initialize with the end iterator
+ *
+ * Retrieves the first and last iterators in the buffer, i.e. the
+ * entire buffer lies within the range [@start,@end).
+ * 
+ **/
 void
 gtk_text_buffer_get_bounds (GtkTextBuffer *buffer,
                             GtkTextIter   *start,
@@ -2049,6 +2179,17 @@ gtk_text_buffer_get_bounds (GtkTextBuffer *buffer,
  * Modified flag
  */
 
+/**
+ * gtk_text_buffer_modified:
+ * @buffer: a #GtkTextBuffer 
+ * 
+ * Indicates whether the buffer has been modified since the last call
+ * to gtk_text_buffer_set_modified() set the modification flag to
+ * %FALSE. Used for example to enable a "save" function in a text
+ * editor.
+ * 
+ * Return value: %TRUE if the buffer has been modified
+ **/
 gboolean
 gtk_text_buffer_modified (GtkTextBuffer      *buffer)
 {
@@ -2057,6 +2198,18 @@ gtk_text_buffer_modified (GtkTextBuffer      *buffer)
   return buffer->modified;
 }
 
+/**
+ * gtk_text_buffer_set_modified:
+ * @buffer: a #GtkTextBuffer 
+ * @setting: modification flag setting
+ *
+ * Used to keep track of whether the buffer has been modified since the
+ * last time it was saved. Whenever the buffer is saved to disk, call
+ * gtk_text_buffer_set_modified (@buffer, FALSE). When the buffer is modified,
+ * it will automatically toggled on the modified bit again. When the modified
+ * bit flips, the buffer emits a "modified_changed" signal.
+ * 
+ **/
 void
 gtk_text_buffer_set_modified (GtkTextBuffer      *buffer,
                               gboolean             setting)
@@ -2081,6 +2234,15 @@ gtk_text_buffer_set_modified (GtkTextBuffer      *buffer,
  * Assorted other stuff
  */
 
+/**
+ * gtk_text_buffer_get_line_count:
+ * @buffer: a #GtkTextBuffer 
+ * 
+ * Obtains the number of lines in the buffer. This value is cached, so
+ * the function is very fast.
+ * 
+ * Return value: number of lines in the buffer
+ **/
 gint
 gtk_text_buffer_get_line_count (GtkTextBuffer *buffer)
 {
@@ -2089,6 +2251,17 @@ gtk_text_buffer_get_line_count (GtkTextBuffer *buffer)
   return _gtk_text_btree_line_count (get_btree (buffer));
 }
 
+/**
+ * gtk_text_buffer_get_char_count:
+ * @buffer: a #GtkTextBuffer 
+ * 
+ * Gets the number of characters in the buffer; note that characters
+ * and bytes are not the same, you can't e.g. expect the contents of
+ * the buffer in string form to be this many bytes long. The character
+ * count is cached, so this function is very fast.
+ * 
+ * Return value: number of characters in the buffer
+ **/
 gint
 gtk_text_buffer_get_char_count (GtkTextBuffer *buffer)
 {
@@ -2539,6 +2712,17 @@ paste (GtkTextBuffer *buffer,
                                     clipboard_selection_buffer_received, data);    
 }
 
+/**
+ * gtk_text_buffer_paste_primary:
+ * @buffer: a #GtkTextBuffer 
+ * @override_location: location to insert pasted text, or %NULL for at the cursor
+ * @default_editable: whether the buffer is editable by default 
+ * 
+ * Pastes the primary selection at the insertion point, or at @override_location.
+ * (Note: pasting is asynchronous, that is, we'll ask for the paste data
+ * and return, and at some point later after the main loop runs, the paste
+ * data will be inserted.)
+ **/
 void
 gtk_text_buffer_paste_primary (GtkTextBuffer       *buffer,
                                const GtkTextIter   *override_location,
@@ -2552,6 +2736,17 @@ gtk_text_buffer_paste_primary (GtkTextBuffer       *buffer,
   paste (buffer, FALSE, TRUE, default_editable);
 }
 
+/**
+ * gtk_text_buffer_paste_clipboard:
+ * @buffer: a #GtkTextBuffer 
+ * @default_editable: whether the buffer is editable by default
+ *
+ * Pastes the clipboard contents at the insertion point.  (Note:
+ * pasting is asynchronous, that is, we'll ask for the paste data and
+ * return, and at some point later after the main loop runs, the paste
+ * data will be inserted.)
+ * 
+ **/
 void
 gtk_text_buffer_paste_clipboard (GtkTextBuffer *buffer,
                                  gboolean       default_editable)
@@ -2559,6 +2754,19 @@ gtk_text_buffer_paste_clipboard (GtkTextBuffer *buffer,
   paste (buffer, TRUE, TRUE, default_editable);
 }
 
+/**
+ * gtk_text_buffer_delete_selection:
+ * @buffer: a #GtkTextBuffer 
+ * @interactive: whether the deletion is caused by user interaction
+ * @default_editable: whether the buffer is editable by default
+ *
+ * Deletes the range between the "insert" and "selection_bound" marks,
+ * that is, the currently-selected text. If @interactive is %TRUE,
+ * the editability of the selection will be considered (users can't delete
+ * uneditable text).
+ * 
+ * Return value: whether there was a non-empty selection to delete
+ **/
 gboolean
 gtk_text_buffer_delete_selection (GtkTextBuffer *buffer,
                                   gboolean interactive,
@@ -2655,6 +2863,15 @@ cut_or_copy (GtkTextBuffer *buffer,
     }
 }
 
+/**
+ * gtk_text_buffer_cut_clipboard:
+ * @buffer: a #GtkTextBuffer 
+ * @default_editable: default editability of the buffer
+ *
+ * Copies the currently-selected text to the clipboard, then deletes
+ * said text if it's editable.
+ * 
+ **/
 void
 gtk_text_buffer_cut_clipboard (GtkTextBuffer *buffer,
                                gboolean       default_editable)
@@ -2664,6 +2881,13 @@ gtk_text_buffer_cut_clipboard (GtkTextBuffer *buffer,
   gtk_text_buffer_end_user_action (buffer);
 }
 
+/**
+ * gtk_text_buffer_copy_clipboard:
+ * @buffer: a #GtkTextBuffer 
+ *
+ * Copies the currently-selected text to the clipboard.
+ * 
+ **/
 void
 gtk_text_buffer_copy_clipboard (GtkTextBuffer *buffer)
 {
@@ -2675,7 +2899,7 @@ gtk_text_buffer_copy_clipboard (GtkTextBuffer *buffer)
 
 /**
  * gtk_text_buffer_get_selection_bounds:
- * @buffer: a #GtkTextBuffer
+ * @buffer: a #GtkTextBuffer a #GtkTextBuffer
  * @start: iterator to initialize with selection start
  * @end: iterator to initialize with selection end
  *
@@ -2715,9 +2939,9 @@ gtk_text_buffer_get_selection_bounds   (GtkTextBuffer      *buffer,
  *
  * The "interactive" buffer mutation functions, such as
  * gtk_text_buffer_insert_interactive(), automatically call begin/end
- * user action around the buffer operations they perform, so there's no
- * need to add extra calls if you user action consists solely of those
- * functions.
+ * user action around the buffer operations they perform, so there's
+ * no need to add extra calls if you user action consists solely of a
+ * single call to one of those functions.
  **/
 void
 gtk_text_buffer_begin_user_action (GtkTextBuffer *buffer)
diff --git a/gtk/gtktextbuffer.h b/gtk/gtktextbuffer.h
index ae7f7570ce..88bf91190b 100644
--- a/gtk/gtktextbuffer.h
+++ b/gtk/gtktextbuffer.h
@@ -252,20 +252,20 @@ void gtk_text_buffer_place_cursor (GtkTextBuffer     *buffer,
 /* Tag manipulation */
 void gtk_text_buffer_apply_tag             (GtkTextBuffer     *buffer,
                                             GtkTextTag        *tag,
-                                            const GtkTextIter *start_index,
-                                            const GtkTextIter *end_index);
+                                            const GtkTextIter *start,
+                                            const GtkTextIter *end);
 void gtk_text_buffer_remove_tag            (GtkTextBuffer     *buffer,
                                             GtkTextTag        *tag,
-                                            const GtkTextIter *start_index,
-                                            const GtkTextIter *end_index);
+                                            const GtkTextIter *start,
+                                            const GtkTextIter *end);
 void gtk_text_buffer_apply_tag_by_name     (GtkTextBuffer     *buffer,
                                             const gchar       *name,
-                                            const GtkTextIter *start_index,
-                                            const GtkTextIter *end_index);
+                                            const GtkTextIter *start,
+                                            const GtkTextIter *end);
 void gtk_text_buffer_remove_tag_by_name    (GtkTextBuffer     *buffer,
                                             const gchar       *name,
-                                            const GtkTextIter *start_index,
-                                            const GtkTextIter *end_index);
+                                            const GtkTextIter *start,
+                                            const GtkTextIter *end);
 
 
 /* You can either ignore the return value, or use it to
diff --git a/gtk/gtktextiter.c b/gtk/gtktextiter.c
index 549dcb2179..c216d4ca3c 100644
--- a/gtk/gtktextiter.c
+++ b/gtk/gtktextiter.c
@@ -264,6 +264,13 @@ iter_init_from_byte_offset (GtkTextIter *iter,
 
   iter_set_from_byte_offset (real, line, line_byte_offset);
 
+  if (real->segment->type == &gtk_text_char_type &&
+      (real->segment->body.chars[real->segment_byte_offset] & 0xc0) == 0x80)
+    g_warning ("Incorrect line byte index %d falls in the middle of a UTF-8 "
+               "character; this will crash the text buffer. "
+               "Byte indexes must refer to the start of a character.",
+               line_byte_offset);
+  
   return real;
 }
 
@@ -2699,12 +2706,36 @@ find_by_log_attrs (GtkTextIter    *iter,
     }
 }
 
+/**
+ * gtk_text_iter_forward_word_end:
+ * @iter: a #GtkTextIter
+ * 
+ * Moves forward to the next word end. (If @iter is currently on a
+ * word end, moves forward to the next one after that.) Word breaks
+ * are determined by Pango and should be correct for nearly any
+ * language (if not, the correct fix would be to the Pango word break
+ * algorithms).
+ * 
+ * Return value: %TRUE if @iter moved and is not the end iterator 
+ **/
 gboolean
 gtk_text_iter_forward_word_end (GtkTextIter *iter)
 {
   return find_by_log_attrs (iter, find_word_end_func, TRUE, FALSE);
 }
 
+/**
+ * gtk_text_iter_forward_word_end:
+ * @iter: a #GtkTextIter
+ * 
+ * Moves backward to the next word start. (If @iter is currently on a
+ * word start, moves backward to the next one after that.) Word breaks
+ * are determined by Pango and should be correct for nearly any
+ * language (if not, the correct fix would be to the Pango word break
+ * algorithms).
+ * 
+ * Return value: %TRUE if @iter moved and is not the end iterator 
+ **/
 gboolean
 gtk_text_iter_backward_word_start (GtkTextIter      *iter)
 {
@@ -2714,6 +2745,16 @@ gtk_text_iter_backward_word_start (GtkTextIter      *iter)
 /* FIXME a loop around a truly slow function means
  * a truly spectacularly slow function.
  */
+
+/**
+ * gtk_text_iter_forward_word_ends:
+ * @iter: a #GtkTextIter
+ * @count: number of times to move
+ * 
+ * Calls gtk_text_iter_forward_word_end() up to @count times.
+ *
+ * Return value: %TRUE if @iter moved and is not the end iterator 
+ **/
 gboolean
 gtk_text_iter_forward_word_ends (GtkTextIter      *iter,
                                  gint              count)
@@ -2739,6 +2780,15 @@ gtk_text_iter_forward_word_ends (GtkTextIter      *iter,
   return TRUE;
 }
 
+/**
+ * gtk_text_iter_backward_word_starts
+ * @iter: a #GtkTextIter
+ * @count: number of times to move
+ * 
+ * Calls gtk_text_iter_backward_word_starts() up to @count times.
+ *
+ * Return value: %TRUE if @iter moved and is not the end iterator 
+ **/
 gboolean
 gtk_text_iter_backward_word_starts (GtkTextIter      *iter,
                                     gint               count)
@@ -2761,48 +2811,139 @@ gtk_text_iter_backward_word_starts (GtkTextIter      *iter,
   return TRUE;
 }
 
+/**
+ * gtk_text_iter_starts_word:
+ * @iter: a #GtkTextIter
+ * 
+ * Determines whether @iter begins a natural-language word.  Word
+ * breaks are determined by Pango and should be correct for nearly any
+ * language (if not, the correct fix would be to the Pango word break
+ * algorithms).
+ *
+ * Return value: %TRUE if @iter is at the start of a word
+ **/
 gboolean
 gtk_text_iter_starts_word (const GtkTextIter *iter)
 {
   return test_log_attrs (iter, is_word_start_func);
 }
 
+/**
+ * gtk_text_iter_ends_word:
+ * @iter: a #GtkTextIter
+ * 
+ * Determines whether @iter ends a natural-language word.  Word breaks
+ * are determined by Pango and should be correct for nearly any
+ * language (if not, the correct fix would be to the Pango word break
+ * algorithms).
+ *
+ * Return value: %TRUE if @iter is at the end of a word
+ **/
 gboolean
 gtk_text_iter_ends_word (const GtkTextIter *iter)
 {
   return test_log_attrs (iter, is_word_end_func);
 }
 
+/**
+ * gtk_text_iter_inside_word:
+ * @iter: a #GtkTextIter
+ * 
+ * Determines whether @iter is inside a natural-language word (as
+ * opposed to say inside some whitespace).  Word breaks are determined
+ * by Pango and should be correct for nearly any language (if not, the
+ * correct fix would be to the Pango word break algorithms).
+ * 
+ * Return value: %TRUE if @iter is inside a word
+ **/
 gboolean
 gtk_text_iter_inside_word (const GtkTextIter *iter)
 {
   return test_log_attrs (iter, inside_word_func);
 }
 
+/**
+ * gtk_text_iter_starts_sentence:
+ * @iter: a #GtkTextIter
+ * 
+ * Determines whether @iter begins a sentence.  Sentence boundaries are
+ * determined by Pango and should be correct for nearly any language
+ * (if not, the correct fix would be to the Pango text boundary
+ * algorithms).
+ * 
+ * Return value: %TRUE if @iter is at the start of a sentence.
+ **/
 gboolean
 gtk_text_iter_starts_sentence (const GtkTextIter *iter)
 {
   return test_log_attrs (iter, is_sentence_start_func);
 }
 
+/**
+ * gtk_text_iter_ends_sentence:
+ * @iter: a #GtkTextIter
+ * 
+ * Determines whether @iter ends a sentence.  Sentence boundaries are
+ * determined by Pango and should be correct for nearly any language
+ * (if not, the correct fix would be to the Pango text boundary
+ * algorithms).
+ * 
+ * Return value: %TRUE if @iter is at the end of a sentence.
+ **/
 gboolean
 gtk_text_iter_ends_sentence (const GtkTextIter *iter)
 {
   return test_log_attrs (iter, is_sentence_end_func);
 }
 
+/**
+ * gtk_text_iter_inside_sentence:
+ * @iter: a #GtkTextIter
+ * 
+ * Determines whether @iter is inside a sentence (as opposed to in
+ * between two sentences, e.g. after a period and before the first
+ * letter of the next sentence).  Sentence boundaries are determined
+ * by Pango and should be correct for nearly any language (if not, the
+ * correct fix would be to the Pango text boundary algorithms).
+ * 
+ * Return value: %TRUE if @iter is inside a sentence.
+ **/
 gboolean
 gtk_text_iter_inside_sentence (const GtkTextIter *iter)
 {
   return test_log_attrs (iter, inside_sentence_func);
 }
 
+/**
+ * gtk_text_iter_forward_sentence_end:
+ * @iter: a #GtkTextIter
+ * 
+ * Moves forward to the next sentence end. (If @iter is at the end of
+ * a sentence, moves to the next end of sentence.)  Sentence
+ * boundaries are determined by Pango and should be correct for nearly
+ * any language (if not, the correct fix would be to the Pango text
+ * boundary algorithms).
+ * 
+ * Return value: %TRUE if @iter moved and is not the end iterator
+ **/
 gboolean
 gtk_text_iter_forward_sentence_end (GtkTextIter *iter)
 {
   return find_by_log_attrs (iter, find_sentence_end_func, TRUE, FALSE);
 }
 
+/**
+ * gtk_text_iter_backward_sentence_start:
+ * @iter: a #GtkTextIter
+ * 
+ * Moves backward to the next sentence start; if @iter is already at
+ * the start of a sentence, moves backward to the next one.  Sentence
+ * boundaries are determined by Pango and should be correct for nearly
+ * any language (if not, the correct fix would be to the Pango text
+ * boundary algorithms).
+ * 
+ * Return value: %TRUE if @iter moved and is not the end iterator
+ **/
 gboolean
 gtk_text_iter_backward_sentence_start (GtkTextIter      *iter)
 {
@@ -2812,6 +2953,15 @@ gtk_text_iter_backward_sentence_start (GtkTextIter      *iter)
 /* FIXME a loop around a truly slow function means
  * a truly spectacularly slow function.
  */
+/**
+ * gtk_text_iter_forward_sentence_ends:
+ * @iter: a #GtkTextIter
+ * @count: number of sentences to move
+ * 
+ * Calls gtk_text_iter_forward_sentence_end() up to @count times.
+ * 
+ * Return value: %TRUE if @iter moved and is not the end iterator
+ **/
 gboolean
 gtk_text_iter_forward_sentence_ends (GtkTextIter      *iter,
                                      gint              count)
@@ -2837,6 +2987,15 @@ gtk_text_iter_forward_sentence_ends (GtkTextIter      *iter,
   return TRUE;
 }
 
+/**
+ * gtk_text_iter_forward_sentence_ends:
+ * @iter: a #GtkTextIter
+ * @count: number of sentences to move
+ * 
+ * Calls gtk_text_iter_backward_sentence_start() up to @count times.
+ * 
+ * Return value: %TRUE if @iter moved and is not the end iterator
+ **/
 gboolean
 gtk_text_iter_backward_sentence_starts (GtkTextIter      *iter,
                                         gint               count)
@@ -2908,18 +3067,53 @@ is_cursor_pos_func (const PangoLogAttr *attrs,
   return attrs[offset].is_cursor_position;
 }
 
+/**
+ * gtk_text_iter_forward_cursor_position:
+ * @iter: a #GtkTextIter
+ * 
+ * Moves @iter forward by a single cursor position. Cursor positions
+ * are (unsurprisingly) positions where the cursor can appear. Perhaps
+ * surprisingly, there may not be a cursor position between all
+ * characters. The most common example for European languages would be
+ * a carriage return/newline sequence. For some Unicode characters,
+ * the equivalent of say the letter "a" with an accent mark will be
+ * represented as two characters, first the letter then a "combining
+ * mark" that causes the accent to be rendered; so the cursor can't go
+ * between those two characters. See also the #PangoLogAttr structure and
+ * pango_break() function.
+ * 
+ * Return value: %TRUE if we moved and the new position is dereferenceable
+ **/
 gboolean
 gtk_text_iter_forward_cursor_position (GtkTextIter *iter)
 {
   return find_by_log_attrs (iter, find_forward_cursor_pos_func, TRUE, FALSE);
 }
 
+/**
+ * gtk_text_iter_backward_cursor_position:
+ * @iter: a #GtkTextIter
+ * 
+ * Like gtk_text_iter_forward_cursor_position(), but moves backward.
+ * 
+ * Return value: %TRUE if we moved and the new position is dereferenceable
+ **/
 gboolean
 gtk_text_iter_backward_cursor_position (GtkTextIter *iter)
 {
   return find_by_log_attrs (iter, find_backward_cursor_pos_func, FALSE, FALSE);
 }
 
+/**
+ * gtk_text_iter_forward_cursor_positions:
+ * @iter: a #GtkTextIter
+ * @count: number of positions to move
+ * 
+ * Moves up to @count cursor positions. See
+ * gtk_text_iter_forward_cursor_position() for details.
+ * 
+ * Return value: %TRUE if we moved and the new position is dereferenceable
+ **/
 gboolean
 gtk_text_iter_forward_cursor_positions (GtkTextIter *iter,
                                         gint         count)
@@ -2945,6 +3139,16 @@ gtk_text_iter_forward_cursor_positions (GtkTextIter *iter,
   return TRUE;
 }
 
+/**
+ * gtk_text_iter_backward_cursor_positions:
+ * @iter: a #GtkTextIter
+ * @count: number of positions to move
+ *
+ * Moves up to @count cursor positions. See
+ * gtk_text_iter_forward_cursor_position() for details.
+ * 
+ * Return value: %TRUE if we moved and the new position is dereferenceable
+ **/
 gboolean
 gtk_text_iter_backward_cursor_positions (GtkTextIter *iter,
                                          gint         count)
@@ -2970,12 +3174,34 @@ gtk_text_iter_backward_cursor_positions (GtkTextIter *iter,
   return TRUE;
 }
 
+/**
+ * gtk_text_iter_is_cursor_position:
+ * @iter: a #GtkTextIter
+ * 
+ * See gtk_text_iter_forward_cursor_position() or #PangoLogAttr or
+ * pango_break() for details on what a cursor position is.
+ * 
+ * Return value: %TRUE if the cursor can be placed at @iter
+ **/
 gboolean
 gtk_text_iter_is_cursor_position (const GtkTextIter *iter)
 {
   return test_log_attrs (iter, is_cursor_pos_func);
 }
 
+/**
+ * gtk_text_iter_set_line_offset:
+ * @iter: a #GtkTextIter 
+ * @char_on_line: a character offset relative to the start of @iter's current line
+ * 
+ * Moves @iter within a line, to a new <emphasis>character</emphasis>
+ * (not byte) offset. The given character offset must be less than or
+ * equal to the number of characters in the line; if equal, @iter
+ * moves to the start of the next line. See
+ * gtk_text_iter_set_line_index() if you have a byte index rather than
+ * a character offset.
+ *
+ **/
 void
 gtk_text_iter_set_line_offset (GtkTextIter *iter,
                                gint         char_on_line)
@@ -3004,6 +3230,17 @@ gtk_text_iter_set_line_offset (GtkTextIter *iter,
   check_invariants (iter);
 }
 
+/**
+ * gtk_text_iter_set_line_index:
+ * @iter: a #GtkTextIter
+ * @byte_on_line: a byte index relative to the start of @iter's current line
+ *
+ * Same as gtk_text_iter_set_line_offset(), but works with a
+ * <emphasis>byte</emphasis> index. The given byte index must be at
+ * the start of a character, it can't be in the middle of a UTF-8
+ * encoded character.
+ * 
+ **/
 void
 gtk_text_iter_set_line_index (GtkTextIter *iter,
                               gint         byte_on_line)
@@ -3039,6 +3276,14 @@ gtk_text_iter_set_line_index (GtkTextIter *iter,
   check_invariants (iter);
 }
 
+/**
+ * gtk_text_iter_set_line:
+ * @iter: a #GtkTextIter
+ * @line_number: line number (counted from 0)
+ *
+ * Moves iterator @iter to the start of the line @line_number.
+ * 
+ **/
 void
 gtk_text_iter_set_line (GtkTextIter *iter,
                         gint         line_number)
@@ -3066,8 +3311,18 @@ gtk_text_iter_set_line (GtkTextIter *iter,
   check_invariants (iter);
 }
 
+/**
+ * gtk_text_iter_set_offset:
+ * @iter: a #GtkTextIter
+ * @char_offset: a character number
+ *
+ * Sets @iter to point to @char_offset. @char_offset counts from the start
+ * of the entire text buffer, starting with 0.
+ * 
+ **/
 void
-gtk_text_iter_set_offset (GtkTextIter *iter, gint char_index)
+gtk_text_iter_set_offset (GtkTextIter *iter,
+                          gint         char_offset)
 {
   GtkTextLine *line;
   GtkTextRealIter *real;
@@ -3084,11 +3339,11 @@ gtk_text_iter_set_offset (GtkTextIter *iter, gint char_index)
   check_invariants (iter);
 
   if (real->cached_char_index >= 0 &&
-      real->cached_char_index == char_index)
+      real->cached_char_index == char_offset)
     return;
 
   line = _gtk_text_btree_get_line_at_char (real->tree,
-                                           char_index,
+                                           char_offset,
                                            &line_start,
                                            &real_char_index);
 
@@ -3100,8 +3355,17 @@ gtk_text_iter_set_offset (GtkTextIter *iter, gint char_index)
   check_invariants (iter);
 }
 
+/**
+ * gtk_text_iter_forward_to_end:
+ * @iter: a #GtkTextIter
+ *
+ * Moves @iter forward to the "end iterator," which points one past the last
+ * valid character in the buffer. gtk_text_iter_get_char() called on the
+ * end iterator returns 0, which is convenient for writing loops.
+ * 
+ **/
 void
-gtk_text_iter_forward_to_end  (GtkTextIter       *iter)
+gtk_text_iter_forward_to_end  (GtkTextIter *iter)
 {
   GtkTextBuffer *buffer;
   GtkTextRealIter *real;
@@ -3399,6 +3663,17 @@ gtk_text_iter_forward_find_char (GtkTextIter         *iter,
   return FALSE;
 }
 
+/**
+ * gtk_text_iter_backward_find_char:
+ * @iter: a #GtkTextIter
+ * @pred: function to be called on each character
+ * @user_data: user data for @pred
+ * @limit: search limit, or %NULL for none
+ * 
+ * Same as gtk_text_iter_forward_find_char(), but goes backward from @iter.
+ * 
+ * Return value: whether a match was found
+ **/
 gboolean
 gtk_text_iter_backward_find_char (GtkTextIter         *iter,
                                   GtkTextCharPredicate pred,
@@ -3623,7 +3898,9 @@ strbreakup (const char *string,
  * @match_end: return location for end of match, or %NULL
  * @limit: bound for the search, or %NULL for the end of the buffer
  * 
- * 
+ * Searches forward for @str. Any match is returned as the range @match_start,
+ * @match_end. If you specify @visible_only or @slice, the match may have
+ * invisible text, pixbufs, or child widgets interspersed in @str.
  * 
  * Return value: whether a match was found
  **/
@@ -3941,7 +4218,7 @@ my_strrstr (const gchar *haystack,
  * @match_end: return location for end of match, or %NULL
  * @limit: location of last possible @match_start, or %NULL for start of buffer
  * 
- * 
+ * Same as gtk_text_iter_forward_search(), but moves backward.
  * 
  * Return value: whether a match was found
  **/
@@ -4079,6 +4356,19 @@ gtk_text_iter_backward_search (const GtkTextIter *iter,
  * Comparisons
  */
 
+/**
+ * gtk_text_iter_equal:
+ * @lhs: a #GtkTextIter
+ * @rhs: another #GtkTextIter
+ * 
+ * Tests whether two iterators are equal, using the fastest possible
+ * mechanism. This function is very fast; you can expect it to perform
+ * better than e.g. getting the character offset for each iterator and
+ * comparing the offsets yourself. Also, it's a bit faster than
+ * gtk_text_iter_compare().
+ * 
+ * Return value: %TRUE if the iterators point to the same place in the buffer
+ **/
 gboolean
 gtk_text_iter_equal (const GtkTextIter *lhs,
                      const GtkTextIter *rhs)
@@ -4107,8 +4397,21 @@ gtk_text_iter_equal (const GtkTextIter *lhs,
     }
 }
 
+/**
+ * gtk_text_iter_compare:
+ * @lhs: a #GtkTextIter
+ * @rhs: another #GtkTextIter
+ * 
+ * A qsort()-style function that returns negative if @lhs is less than
+ * @rhs, positive if @lhs is greater than @rhs, and 0 if they're equal.
+ * Ordering is in character offset order, i.e. the first character in the buffer
+ * is less than the second character in the buffer.
+ * 
+ * Return value: -1 if @lhs is less than @rhs, 1 if @lhs is greater, 0 if they are equal
+ **/
 gint
-gtk_text_iter_compare (const GtkTextIter *lhs, const GtkTextIter *rhs)
+gtk_text_iter_compare (const GtkTextIter *lhs,
+                       const GtkTextIter *rhs)
 {
   GtkTextRealIter *real_lhs;
   GtkTextRealIter *real_rhs;
@@ -4116,13 +4419,13 @@ gtk_text_iter_compare (const GtkTextIter *lhs, const GtkTextIter *rhs)
   real_lhs = gtk_text_iter_make_surreal (lhs);
   real_rhs = gtk_text_iter_make_surreal (rhs);
 
-  check_invariants (lhs);
-  check_invariants (rhs);
-
   if (real_lhs == NULL ||
       real_rhs == NULL)
     return -1; /* why not */
 
+  check_invariants (lhs);
+  check_invariants (rhs);
+  
   if (real_lhs->line == real_rhs->line)
     {
       gint left_index, right_index;
@@ -4165,6 +4468,18 @@ gtk_text_iter_compare (const GtkTextIter *lhs, const GtkTextIter *rhs)
     }
 }
 
+/**
+ * gtk_text_iter_in_range:
+ * @iter: a #GtkTextIter
+ * @start: start of range
+ * @end: end of range
+ * 
+ * @start and @end must be in order, unlike most text buffer
+ * functions, for efficiency reasons. The function returns %TRUE if
+ * @iter falls in the range [@start, @end).
+ * 
+ * Return value: %TRUE if @iter is in the range
+ **/
 gboolean
 gtk_text_iter_in_range (const GtkTextIter *iter,
                         const GtkTextIter *start,
@@ -4174,6 +4489,19 @@ gtk_text_iter_in_range (const GtkTextIter *iter,
     gtk_text_iter_compare (iter, end) < 0;
 }
 
+/**
+ * gtk_text_iter_reorder:
+ * @first: a #GtkTextIter
+ * @second: another #GtkTextIter
+ *
+ * Swaps the value of @first and @second if @second comes before
+ * @first in the buffer. That is, ensures that @first and @second are
+ * in sequence. Most text buffer functions that take a range call this
+ * automatically on your behalf, so there's no real reason to call it yourself
+ * in those cases. There are some exceptions, such as gtk_text_iter_in_range(),
+ * that expect a pre-sorted range.
+ * 
+ **/
 void
 gtk_text_iter_reorder         (GtkTextIter *first,
                                GtkTextIter *second)
@@ -4261,13 +4589,6 @@ _gtk_text_btree_get_iter_at_line_byte (GtkTextBTree   *tree,
   /* We might as well cache this, since we know it. */
   real->cached_line_number = real_line;
 
-  if (real->segment->type == &gtk_text_char_type &&
-      (real->segment->body.chars[real->segment_byte_offset] & 0xc0) == 0x80)
-    g_warning ("%s: Incorrect byte offset %d falls in the middle of a UTF-8 "
-               "character; this will crash the text buffer. "
-               "Byte indexes must refer to the start of a character.",
-               G_STRLOC, byte_index);
-
   check_invariants (iter);
 }
 
diff --git a/gtk/gtktexttag.c b/gtk/gtktexttag.c
index 1cd630bdbb..153f3417e1 100644
--- a/gtk/gtktexttag.c
+++ b/gtk/gtktexttag.c
@@ -1735,6 +1735,14 @@ gtk_text_attributes_new (void)
   return values;
 }
 
+/**
+ * gtk_text_attributes_copy:
+ * @src: a #GtkTextAttributes to be copied
+ * 
+ * Copies @src and returns a new #GtkTextAttributes.
+ * 
+ * Return value: a copy of @src
+ **/
 GtkTextAttributes*
 gtk_text_attributes_copy (GtkTextAttributes *src)
 {
@@ -1752,7 +1760,7 @@ gtk_text_attributes_copy (GtkTextAttributes *src)
  * @dest: another #GtkTextAttributes
  * 
  * Copies the values from @src to @dest so that @dest has the same values
- * as @src.
+ * as @src. Frees existing values in @dest.
  **/
 void
 gtk_text_attributes_copy_values (GtkTextAttributes *src,
@@ -1803,6 +1811,12 @@ gtk_text_attributes_copy_values (GtkTextAttributes *src,
   dest->realized = FALSE;
 }
 
+/**
+ * gtk_text_attributes_ref:
+ * @values: a #GtkTextAttributes
+ * 
+ * Increments the reference count on @values.
+ **/
 void
 gtk_text_attributes_ref (GtkTextAttributes *values)
 {
@@ -1811,6 +1825,13 @@ gtk_text_attributes_ref (GtkTextAttributes *values)
   values->refcount += 1;
 }
 
+/**
+ * gtk_text_attributes_unref:
+ * @values: a #GtkTextAttributes
+ * 
+ * Decrements the reference count on @values, freeing the structure
+ * if the reference count reaches 0.
+ **/
 void
 gtk_text_attributes_unref (GtkTextAttributes *values)
 {
diff --git a/gtk/gtktipsquery.h b/gtk/gtktipsquery.h
index da1ec6adf5..03b022d0b4 100644
--- a/gtk/gtktipsquery.h
+++ b/gtk/gtktipsquery.h
@@ -27,6 +27,8 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+#ifndef GTK_DISABLE_DEPRECATED
+
 #ifndef __GTKTIPSQUERY_H__
 #define __GTKTIPSQUERY_H__
 
@@ -106,3 +108,5 @@ void		gtk_tips_query_set_labels 	(GtkTipsQuery   *tips_query,
 
 
 #endif	/* __GTKTIPSQUERY_H__ */
+
+#endif /* GTK_DISABLE_DEPRECATED */
diff --git a/gtk/gtktreesortable.h b/gtk/gtktreesortable.h
new file mode 100644
index 0000000000..403073e5b9
--- /dev/null
+++ b/gtk/gtktreesortable.h
@@ -0,0 +1,59 @@
+/* gtktreesortable.h
+ * Copyright (C) 2001  Red Hat, Inc.
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Library General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * 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
+ * Library General Public License for more details.
+ *
+ * You should have received a copy of the GNU Library General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+#ifndef __GTK_TREE_SORTABLE_H__
+#define __GTK_TREE_SORTABLE_H__
+
+#include <gtk/gtktreemodel.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif /* __cplusplus */
+
+#define GTK_TYPE_TREE_SORTABLE            (gtk_tree_sortable_get_type ())
+#define GTK_TREE_SORTABLE(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_TREE_SORTABLE, GtkTreeSortable))
+#define GTK_IS_TREE_SORTABLE(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_TREE_SORTABLE))
+#define GTK_TREE_SORTABLE_GET_IFACE(obj)  ((GtkTreeSortableIface *)g_type_interface_peek (((GTypeInstance *)GTK_TREE_SORTABLE (obj))->g_class, GTK_TYPE_TREE_SORTABLE))
+
+typedef struct _GtkTreeSortable      GtkTreeSortable; /* Dummy typedef */
+typedef struct _GtkTreeSortableIface GtkTreeSortableIface;
+
+struct _GtkTreeSortableIface
+{
+  GTypeInterface g_iface;
+
+  /* FIXME think about sorting reverse when the column is clicked
+   * a second time.
+   */
+  gboolean     (* column_sortable) (GtkTreeSortable *sortable,
+                                    gint             column);
+  gint         (* get_sort_column) (GtkTreeSortable *sortable);
+  void         (* set_sort_column) (GtkTreeSortable *sortable,
+                                    gint             column);
+};
+
+
+GType           gtk_tree_sortable_get_type   (void) G_GNUC_CONST;
+
+#ifdef __cplusplus
+}
+#endif /* __cplusplus */
+
+
+#endif /* __GTK_TREE_SORTABLE_H__ */
diff --git a/gtk/gtkvruler.h b/gtk/gtkvruler.h
index a18a1305ce..e47db489e5 100644
--- a/gtk/gtkvruler.h
+++ b/gtk/gtkvruler.h
@@ -24,6 +24,16 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/. 
  */
 
+/*
+ * NOTE this widget is considered too specialized/little-used for
+ * GTK+, and will in the future be moved to some other package.  If
+ * your application needs this widget, feel free to use it, as the
+ * widget does work and is useful in some applications; it's just not
+ * of general interest. However, we are not accepting new features for
+ * the widget, and it will eventually move out of the GTK+
+ * distribution.
+ */
+
 #ifndef __GTK_VRULER_H__
 #define __GTK_VRULER_H__
 
@@ -69,3 +79,4 @@ GtkWidget* gtk_vruler_new      (void);
 
 
 #endif /* __GTK_VRULER_H__ */
+
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index c78479ce6f..e9fee7463d 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -3661,7 +3661,7 @@ gtk_widget_create_pango_layout (GtkWidget   *widget,
 }
 
 /**
- * gtk_widget_render_stock_icon:
+ * gtk_widget_render_icon:
  * @widget: a #GtkWidget
  * @stock_id: a stock ID
  * @size: a stock size
@@ -3678,10 +3678,10 @@ gtk_widget_create_pango_layout (GtkWidget   *widget,
  * Return value: a new pixbuf, or NULL if the stock ID wasn't known
  **/
 GdkPixbuf*
-gtk_widget_render_stock_icon (GtkWidget      *widget,
-                              const gchar    *stock_id,
-                              const gchar    *size,
-                              const gchar    *detail)
+gtk_widget_render_icon (GtkWidget      *widget,
+                        const gchar    *stock_id,
+                        const gchar    *size,
+                        const gchar    *detail)
 {
   GtkIconSet *icon_set;
   GdkPixbuf *retval;
@@ -3770,14 +3770,24 @@ gtk_widget_get_parent_window   (GtkWidget           *widget)
   return (parent_window != NULL) ? parent_window : widget->parent->window;
 }
 
-/*****************************************
+/**
  * gtk_widget_set_uposition:
+ * @widget: a #GtkWidget
+ * @x: x position
+ * @y: y position
+ * 
  *
- *   arguments:
+ * Sets the position of a widget. The funny "u" in the name comes from
+ * the "user position" hint specified by the X window system, and
+ * exists for legacy reasons. This function doesn't work if a widget
+ * is inside a container; it's only really useful on #GtkWindow.
  *
- *   results:
- *****************************************/
-
+ * Don't use this function to center dialogs over the main application
+ * window; most window managers will do the centering on your behalf
+ * if you call gtk_window_set_transient_for(), and it's really not
+ * possible to get the centering to work correctly in all cases from
+ * application code.
+ **/
 void
 gtk_widget_set_uposition (GtkWidget *widget,
 			  gint	     x,
@@ -3811,14 +3821,31 @@ gtk_widget_set_uposition (GtkWidget *widget,
     gtk_widget_size_allocate (widget, &widget->allocation);
 }
 
-/*****************************************
+/**
  * gtk_widget_set_usize:
+ * @widget: a #GtkWidget
+ * @width: minimum width, or -1 to unset
+ * @height: minimum height, or -1 to unset
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Sets the minimum size of a widget; that is, the widget's size
+ * request will be @width by @height. You can use this function to
+ * force a widget to be either larger or smaller than it is. The
+ * strange "usize" name dates from the early days of GTK+, and derives
+ * from X Window System terminology. In many cases,
+ * gtk_window_set_default_size() is a better choice for toplevel
+ * windows than this function; setting the default size will still
+ * allow users to shrink the window. Setting the usize will force them
+ * to leave the window at least as large as the usize. When dealing
+ * with window sizes, gtk_window_set_geometry_hints() can be a useful
+ * function as well.
+ * 
+ * Note the inherent danger of setting any fixed size - themes,
+ * translations into other languages, different fonts, and user action
+ * can all change the appropriate size for a given widget. So, it's
+ * basically impossible to hardcode a size that will always be
+ * correct.
+ * 
+ **/
 void
 gtk_widget_set_usize (GtkWidget *widget,
 		      gint	 width,
@@ -3847,14 +3874,23 @@ gtk_widget_set_usize (GtkWidget *widget,
     gtk_widget_queue_resize (widget);
 }
 
-/*****************************************
+/**
  * gtk_widget_set_events:
+ * @widget: a #GtkWidget
+ * @events: event mask
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Sets the event mask (see #GdkEventMask) for a widget. The event
+ * mask determines which events a widget will receive. Keep in mind
+ * that different widgets have different default event masks, and by
+ * changing the event mask you may disrupt a widget's functionality,
+ * so be careful. This function must be called while a widget is
+ * unrealized. Consider gtk_widget_add_events() for widgets that are
+ * already realized, or if you want to preserve the existing event
+ * mask. This function can't be used with #GTK_NO_WINDOW widgets;
+ * to get events on those widgets, place them inside a #GtkEventBox
+ * and receive events on the event box.
+ * 
+ **/
 void
 gtk_widget_set_events (GtkWidget *widget,
 		       gint	  events)
@@ -3885,14 +3921,15 @@ gtk_widget_set_events (GtkWidget *widget,
     }
 }
 
-/*****************************************
+/**
  * gtk_widget_add_events:
+ * @widget: a #GtkWidget
+ * @events: an event mask, see #GdkEventMask
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Adds the events in the bitfield @events to the event mask for
+ * @widget. See gtk_widget_set_events() for details.
+ * 
+ **/
 void
 gtk_widget_add_events (GtkWidget *widget,
 		       gint	  events)
@@ -3931,14 +3968,15 @@ gtk_widget_add_events (GtkWidget *widget,
     }
 }
 
-/*****************************************
+/**
  * gtk_widget_set_extension_events:
+ * @widget: a #GtkWidget
+ * @mode: bitfield of extension events to receive
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Sets the extension events mask to @mode. See #GdkExtensionMode
+ * and gdk_input_set_extension_events().
+ * 
+ **/
 void
 gtk_widget_set_extension_events (GtkWidget *widget,
 				 GdkExtensionMode mode)
@@ -3959,14 +3997,21 @@ gtk_widget_set_extension_events (GtkWidget *widget,
   gtk_object_set_data_by_id (GTK_OBJECT (widget), extension_event_key_id, modep);
 }
 
-/*****************************************
+/**
  * gtk_widget_get_toplevel:
+ * @widget: a #GtkWidget
+ * 
+ * This function returns the topmost widget in the container hierarchy
+ * @widget is a part of. If @widget has no parent widgets, it will be
+ * returned as the topmost widget. No reference will be added to the
+ * returned widget; it should not be unreferenced.
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Note the difference in behavior vs. gtk_widget_get_ancestor();
+ * gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW) would return
+ * %NULL if @widget wasn't inside a toplevel window.
+ * 
+ * Return value: the topmost ancestor of @widget, or @widget itself if there's no ancestor
+ **/
 GtkWidget*
 gtk_widget_get_toplevel (GtkWidget *widget)
 {
@@ -3979,14 +4024,18 @@ gtk_widget_get_toplevel (GtkWidget *widget)
   return widget;
 }
 
-/*****************************************
+/**
  * gtk_widget_get_ancestor:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * @widget: a #GtkWidget
+ * @widget_type: ancestor type
+ * 
+ * Gets the first ancestor of @widget with type @widget_type. For example,
+ * gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the first #GtkBox that's
+ * an ancestor of @widget. No reference will be added to the returned widget;
+ * it should not be unreferenced.
+ * 
+ * Return value: the ancestor widget, or %NULL if not found
+ **/
 GtkWidget*
 gtk_widget_get_ancestor (GtkWidget *widget,
 			 GtkType    widget_type)
@@ -4003,14 +4052,15 @@ gtk_widget_get_ancestor (GtkWidget *widget,
   return widget;
 }
 
-/*****************************************
+/**
  * gtk_widget_get_colormap:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * @widget: a #GtkWidget
+ * 
+ * Gets the colormap that will be used to render @widget. No reference will
+ * be added to the returned colormap; it should not be unreferenced.
+ * 
+ * Return value: the colormap used by @widget
+ **/
 GdkColormap*
 gtk_widget_get_colormap (GtkWidget *widget)
 {
@@ -4034,14 +4084,14 @@ gtk_widget_get_colormap (GtkWidget *widget)
   return gtk_widget_get_default_colormap ();
 }
 
-/*****************************************
+/**
  * gtk_widget_get_visual:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * @widget: a #GtkWidget
+ * 
+ * Gets the visual that will be used to render @widget.
+ * 
+ * Return value: the visual for @widget
+ **/
 GdkVisual*
 gtk_widget_get_visual (GtkWidget *widget)
 {
@@ -4050,42 +4100,44 @@ gtk_widget_get_visual (GtkWidget *widget)
   return gdk_colormap_get_visual (gtk_widget_get_colormap (widget));
 }
 
-/*****************************************
- * gtk_widget_set_colormap:
- *    Set the colormap for the widget to the given
- *    value. Widget must not have been previously
- *    realized. This probably should only be used
- *    from an init() function.
- *   arguments:
- *    widget:
- *    colormap:
- *   results:
- *****************************************/
 
+/**
+ * gtk_widget_set_colormap:
+ * @widget: a #GtkWidget
+ * @colormap: a colormap
+ *
+ * Set the colormap for the widget to the given value. Widget must not
+ * have been previously realized. This probably should only be used
+ * from an init() function (i.e. from the constructor for the widget).
+ * 
+ **/
 void
-gtk_widget_set_colormap (GtkWidget *widget, GdkColormap *colormap)
+gtk_widget_set_colormap (GtkWidget   *widget,
+                         GdkColormap *colormap)
 {
   g_return_if_fail (widget != NULL);
   g_return_if_fail (GTK_IS_WIDGET (widget));
   g_return_if_fail (!GTK_WIDGET_REALIZED (widget));
-  g_return_if_fail (colormap != NULL);
+  g_return_if_fail (GDK_IS_COLORMAP (colormap));
 
-  /* FIXME: reference count the colormap.
-   */
+  g_object_ref (G_OBJECT (colormap));
   
-  gtk_object_set_data (GTK_OBJECT (widget), 
-		       colormap_key,
-		       colormap);
+  gtk_object_set_data_full (GTK_OBJECT (widget), 
+                            colormap_key,
+                            colormap,
+                            (GtkDestroyNotify) g_object_unref);
 }
 
-/*****************************************
+/**
  * gtk_widget_get_events:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * @widget: a #GtkWidget
+ * 
+ * Returns the event mask for the widget (a bitfield containing flags
+ * from the #GdkEventMask enumeration). These are the events that the widget
+ * will receive.
+ * 
+ * Return value: event mask for @widget
+ **/
 gint
 gtk_widget_get_events (GtkWidget *widget)
 {
@@ -4101,14 +4153,15 @@ gtk_widget_get_events (GtkWidget *widget)
   return 0;
 }
 
-/*****************************************
+/**
  * gtk_widget_get_extension_events:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * @widget: a #GtkWidget
+ * 
+ * Retrieves the extension events the widget will receive; see
+ * gdk_input_set_extension_events().
+ * 
+ * Return value: extension events for @widget
+ **/
 GdkExtensionMode
 gtk_widget_get_extension_events (GtkWidget *widget)
 {
@@ -4124,14 +4177,19 @@ gtk_widget_get_extension_events (GtkWidget *widget)
   return 0;
 }
 
-/*****************************************
+/**
  * gtk_widget_get_pointer:
+ * @widget: a #GtkWidget
+ * @x: return location for the X coordinate, or %NULL
+ * @y: return location for the Y coordinate, or %NULL
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Obtains the location of the mouse pointer in widget coordinates.
+ * Widget coordinates are a bit odd; for historical reasons, they are
+ * defined as widget->window coordinates for widgets that are not
+ * #GTK_NO_WINDOW widgets, and are relative to widget->allocation.x,
+ * widget->allocation.y for widgets that are #GTK_NO_WINDOW widgets.
+ * 
+ **/
 void
 gtk_widget_get_pointer (GtkWidget *widget,
 			gint	  *x,
@@ -4159,14 +4217,16 @@ gtk_widget_get_pointer (GtkWidget *widget,
     }
 }
 
-/*****************************************
+/**
  * gtk_widget_is_ancestor:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * @widget: a #GtkWidget
+ * @ancestor: another #GtkWidget
+ * 
+ * Determines whether @widget is somewhere inside @ancestor, possibly with
+ * intermediate containers.
+ * 
+ * Return value: %TRUE if @ancestor contains @widget as a child, grandchild, great grandchild, etc.
+ **/
 gboolean
 gtk_widget_is_ancestor (GtkWidget *widget,
 			GtkWidget *ancestor)
@@ -4231,14 +4291,16 @@ gtk_widget_pop_composite_child (void)
     composite_child_stack--;
 }
 
-/*****************************************
+/**
  * gtk_widget_push_colormap:
+ * @cmap: a #GdkColormap
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Pushes @cmap onto a global stack of colormaps; the topmost
+ * colormap on the stack will be used to create all widgets.
+ * Remove @cmap with gtk_widget_pop_colormap(). There's little
+ * reason to use this function.
+ * 
+ **/
 void
 gtk_widget_push_colormap (GdkColormap *cmap)
 {
@@ -4247,14 +4309,12 @@ gtk_widget_push_colormap (GdkColormap *cmap)
   colormap_stack = g_slist_prepend (colormap_stack, cmap);
 }
 
-/*****************************************
+/**
  * gtk_widget_pop_colormap:
  *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * Removes a colormap pushed with gtk_widget_push_colormap().
+ * 
+ **/
 void
 gtk_widget_pop_colormap (void)
 {
@@ -4268,14 +4328,15 @@ gtk_widget_pop_colormap (void)
     }
 }
 
-/*****************************************
+/**
  * gtk_widget_set_default_colormap:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * @colormap: a #GdkColormap
+ * 
+ * Sets the default colormap to use when creating widgets.
+ * gtk_widget_push_colormap() is a better function to use if
+ * you only want to affect a few widgets, rather than all widgets.
+ * 
+ **/
 void
 gtk_widget_set_default_colormap (GdkColormap *colormap)
 {
@@ -4289,31 +4350,30 @@ gtk_widget_set_default_colormap (GdkColormap *colormap)
     }
 }
 
-/*****************************************
+/**
  * gtk_widget_get_default_colormap:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * 
+ * Obtains the default colormap used to create widgets.
+ * 
+ * Return value: default widget colormap
+ **/
 GdkColormap*
 gtk_widget_get_default_colormap (void)
 {
   if (!default_colormap)
-    default_colormap = gdk_colormap_get_system ();
+    gtk_widget_set_default_colormap (gdk_colormap_get_system ());
   
   return default_colormap;
 }
 
-/*****************************************
+/**
  * gtk_widget_get_default_visual:
- *
- *   arguments:
- *
- *   results:
- *****************************************/
-
+ * 
+ * Obtains the visual of the default colormap. Not really useful;
+ * used to be useful before gdk_colormap_get_visual() existed.
+ * 
+ * Return value: visual of the default colormap
+ **/
 GdkVisual*
 gtk_widget_get_default_visual (void)
 {
@@ -4898,6 +4958,17 @@ gtk_widget_reset_shapes (GtkWidget *widget)
     gtk_reset_shapes_recurse (widget, widget->window);
 }
 
+/**
+ * gtk_widget_ref:
+ * @widget: a #GtkWidget
+ * 
+ * Adds a reference to a widget. This function is exactly the same
+ * as calling g_object_ref(), and exists mostly for historical
+ * reasons. It can still be convenient to avoid casting a widget
+ * to a #GObject, it saves a small amount of typing.
+ * 
+ * Return value: the widget that was referenced
+ **/
 GtkWidget*
 gtk_widget_ref (GtkWidget *widget)
 {
@@ -4906,6 +4977,13 @@ gtk_widget_ref (GtkWidget *widget)
   return (GtkWidget*) g_object_ref ((GObject*) widget);
 }
 
+/**
+ * gtk_widget_unref:
+ * @widget: a #GtkWidget
+ *
+ * Inverse of gtk_widget_ref(). Equivalent to g_object_unref().
+ * 
+ **/
 void
 gtk_widget_unref (GtkWidget *widget)
 {
@@ -4914,6 +4992,27 @@ gtk_widget_unref (GtkWidget *widget)
   g_object_unref ((GObject*) widget);
 }
 
+/**
+ * gtk_widget_path:
+ * @widget: a #GtkWidget
+ * @path_length: location to store length of the path
+ * @path: location to store allocated path string 
+ * @path_reversed: location to store allocated reverse path string
+ *
+ * Obtains the full path to @widget. The path is simply the name of a
+ * widget and all its parents in the container hierarchy, separated by
+ * periods. The name of a widget comes from
+ * gtk_widget_get_name(). Paths are used to apply styles to a widget
+ * in gtkrc configuration files.  Widget names are the type of the
+ * widget by default (e.g. "GtkButton") or can be set to an
+ * application-specific value with gtk_widget_set_name().  By setting
+ * the name of a widget, you allow users or theme authors to apply
+ * styles to that specific widget in their gtkrc
+ * file. @path_reversed_p fills in the path in reverse order,
+ * i.e. starting with @widget's name instead of starting with the name
+ * of @widget's outermost ancestor.
+ * 
+ **/
 void
 gtk_widget_path (GtkWidget *widget,
 		 guint     *path_length_p,
@@ -4967,6 +5066,17 @@ gtk_widget_path (GtkWidget *widget,
     }
 }
 
+/**
+ * gtk_widget_class_path:
+ * @widget: a #GtkWidget
+ * @path_length: location to store the length of the class path
+ * @path: location to store the class path as an allocated string
+ * @path_reversed: location to store the reverse class path as an allocated string
+ *
+ * Same as gtk_widget_path(), but always uses the name of a widget's type,
+ * never uses a custom name set with gtk_widget_set_name().
+ * 
+ **/
 void
 gtk_widget_class_path (GtkWidget *widget,
 		       guint     *path_length_p,
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index aa36d1572a..527132673a 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -426,17 +426,21 @@ void	   gtk_widget_queue_draw_area	  (GtkWidget	       *widget,
 					   gint                 y,
 					   gint                 width,
 					   gint                 height);
+#ifndef GTK_DISABLE_DEPRECATED
 void	   gtk_widget_queue_clear	  (GtkWidget	       *widget);
 void	   gtk_widget_queue_clear_area	  (GtkWidget	       *widget,
 					   gint                 x,
 					   gint                 y,
 					   gint                 width,
 					   gint                 height);
+#endif /* GTK_DISABLE_DEPRECATED */
 
 
 void	   gtk_widget_queue_resize	  (GtkWidget	       *widget);
+#ifndef GTK_DISABLE_DEPRECATED
 void	   gtk_widget_draw		  (GtkWidget	       *widget,
 					   GdkRectangle	       *area);
+#endif /* GTK_DISABLE_DEPRECATED */
 void	   gtk_widget_draw_focus	  (GtkWidget	       *widget);
 void	   gtk_widget_draw_default	  (GtkWidget	       *widget);
 void	   gtk_widget_size_request	  (GtkWidget	       *widget,
@@ -575,10 +579,10 @@ PangoContext *gtk_widget_get_pango_context    (GtkWidget   *widget);
 PangoLayout  *gtk_widget_create_pango_layout  (GtkWidget   *widget,
 					       const gchar *text);
 
-GdkPixbuf* gtk_widget_render_stock_icon       (GtkWidget      *widget,
-                                               const gchar    *stock_id,
-                                               const gchar    *size,
-                                               const gchar    *detail);
+GdkPixbuf    *gtk_widget_render_icon          (GtkWidget   *widget,
+                                               const gchar *stock_id,
+                                               const gchar *size,
+                                               const gchar *detail);
 
 /* handle composite names for GTK_COMPOSITE_CHILD widgets,
  * the returned name is newly allocated.
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 09f39f9d92..3d87ca2527 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -433,6 +433,20 @@ gtk_window_get_arg (GtkObject  *object,
     }
 }
 
+/**
+ * gtk_window_new:
+ * @type: type of window
+ * 
+ * Creates a new #GtkWindow, which is a toplevel window that can
+ * contain other widgets. Nearly always, the type of the window should
+ * be #GTK_WINDOW_TOPLEVEL. If you're implementing something like a
+ * popup menu from scratch (which is a bad idea, just use #GtkMenu),
+ * you might use #GTK_WINDOW_TOPLEVEL. #GTK_WINDOW_DIALOG is not
+ * useful; dialogs should be of type #GTK_WINDOW_TOPLEVEL.  (Probably
+ * you want to use the #GtkDialog widget for dialogs anyway).
+ * 
+ * Return value: a new #GtkWindow.
+ **/
 GtkWidget*
 gtk_window_new (GtkWindowType type)
 {
@@ -447,6 +461,19 @@ gtk_window_new (GtkWindowType type)
   return GTK_WIDGET (window);
 }
 
+/**
+ * gtk_window_set_title:
+ * @window: a #GtkWindow
+ * @title: title of the window
+ * 
+ * Sets the title of the #GtkWindow. The title of a window will be displayed in
+ * its title bar; on the X Window System, the title bar is rendered by the
+ * window manager, so exactly how the title appears to users may vary according
+ * to a user's exact configuration. The title should help a user distinguish
+ * this window from other windows they may have open. A good title might
+ * include the application name and current document filename, for example.
+ * 
+ **/
 void
 gtk_window_set_title (GtkWindow   *window,
 		      const gchar *title)
@@ -466,6 +493,21 @@ gtk_window_set_title (GtkWindow   *window,
     }
 }
 
+/**
+ * gtk_window_set_wmclass:
+ * @window: a #GtkWindow
+ * @wmclass_name: window name hint
+ * @wmclass_class: window class hint
+ *
+ * This function sets the X Window System "class" and "name" hints for a window.
+ * According to the ICCCM, you should always set these to the same value for
+ * all windows in an application, and GTK sets them to that value by default,
+ * so calling this function is sort of pointless. However, you may want to
+ * call gtk_window_set_role() on each window in your application, for the
+ * benefit of the session manager. Setting the role allows the window manager
+ * to restore window positions when loading a saved session.
+ * 
+ **/
 void
 gtk_window_set_wmclass (GtkWindow *window,
 			const gchar *wmclass_name,
@@ -484,6 +526,18 @@ gtk_window_set_wmclass (GtkWindow *window,
     g_warning ("shouldn't set wmclass after window is realized!\n");
 }
 
+/**
+ * gtk_window_set_focus:
+ * @window: a #GtkWindow
+ * @focus: widget to be the new focus widget
+ *
+ * If @focus is not the current focus widget, and is focusable, emits
+ * the "set_focus" signal to set @focus as the focus widget for the
+ * window.  This function is more or less GTK-internal; to focus an
+ * entry widget or the like, you should use gtk_widget_grab_focus()
+ * instead of this function.
+ * 
+ **/
 void
 gtk_window_set_focus (GtkWindow *window,
 		      GtkWidget *focus)
@@ -501,6 +555,20 @@ gtk_window_set_focus (GtkWindow *window,
     gtk_signal_emit (GTK_OBJECT (window), window_signals[SET_FOCUS], focus);
 }
 
+/**
+ * gtk_window_set_default:
+ * @window: a #GtkWindow
+ * @default_widget: widget to be the default
+ *
+ * The default widget is the widget that's activated when the user
+ * presses Enter in a dialog (for example). This function tells a
+ * #GtkWindow about the current default widget; it's really a GTK
+ * internal function and you shouldn't need it. Instead, to change the
+ * default widget, first set the #GTK_CAN_DEFAULT flag on the widget
+ * you'd like to make the default using GTK_WIDGET_SET_FLAGS(), then
+ * call gtk_widget_grab_default() to move the default.
+ * 
+ **/
 void
 gtk_window_set_default (GtkWindow *window,
 			GtkWidget *default_widget)
@@ -635,6 +703,20 @@ gtk_window_activate_default (GtkWindow      *window)
   return FALSE;
 }
 
+/**
+ * gtk_window_set_modal:
+ * @window: a #GtkWindow
+ * @modal: whether the window is modal
+ * 
+ * Sets a window modal or non-modal. Modal windows prevent interaction
+ * with other windows in the same application. To keep modal dialogs
+ * on top of main application windows, use
+ * gtk_window_set_transient_for() to make the dialog transient for the
+ * parent; most window managers will then disallow lowering the dialog
+ * below the parent.
+ * 
+ * 
+ **/
 void
 gtk_window_set_modal (GtkWindow *window,
 		      gboolean   modal)
@@ -651,6 +733,15 @@ gtk_window_set_modal (GtkWindow *window,
     gtk_grab_remove (GTK_WIDGET (window));
 }
 
+/**
+ * gtk_window_list_toplevels:
+ * 
+ * Returns a list of all existing toplevel windows. Each widget
+ * in the list has a reference added to it; to free the
+ * list, first unref each widget in the list, then free the list.
+ * 
+ * Return value: list of referenced toplevel widgets
+ **/
 GList*
 gtk_window_list_toplevels (void)
 {
@@ -825,6 +916,19 @@ gtk_window_unset_transient_for  (GtkWindow *window)
     }
 }
 
+/**
+ * gtk_window_set_transient_for:
+ * @window: a #GtkWindow
+ * @parent: parent window
+ *
+ * Dialog windows should be set transient for the main application
+ * window they were spawned from. This allows window managers to
+ * e.g. keep the dialog on top of the main window, or center the
+ * dialog over the main window. gtk_dialog_new_with_buttons() and
+ * other convenience functions in GTK+ will sometimes call
+ * gtk_window_set_transient_for() on yoru behalf.
+ * 
+ **/
 void       
 gtk_window_set_transient_for  (GtkWindow *window, 
 			       GtkWindow *parent)
@@ -938,6 +1042,19 @@ gtk_window_get_geometry_info (GtkWindow *window,
   return info;
 }
 
+/**
+ * gtk_window_set_geometry_hints:
+ * @window: a #GdkWindow
+ * @geometry_widget: widget the geometry hints will be applied to
+ * @geometry: struct containing geometry information
+ * @geom_mask: mask indicating which struct fields should be paid attention to
+ *
+ * This function sets up hints about how a window can be resized by
+ * the user.  You can set a minimum and maximum size; allowed resize
+ * increments (e.g. for xterm, you can only resize by the size of a
+ * character); aspect ratios; and more. See the #GdkGeometry struct.
+ * 
+ **/
 void       
 gtk_window_set_geometry_hints (GtkWindow       *window,
 			       GtkWidget       *geometry_widget,
@@ -969,6 +1086,25 @@ gtk_window_set_geometry_hints (GtkWindow       *window,
   gtk_widget_queue_resize (GTK_WIDGET (window));
 }
 
+/**
+ * gtk_window_set_default_size:
+ * @window: a #GtkWindow
+ * @width: width in pixels, or -1 to leave the default width unchanged
+ * @height: height in pixels, or -1 to leave the default height unchanged
+ *
+ * Sets the default size of a window. If the window's "natural" size
+ * (its size request) is larger than the default, the default will be
+ * ignored. So the default size is a minimum initial size.  Unlike
+ * gtk_widget_set_usize(), which sets a size request for a widget and
+ * thus would keep users from shrinking the window, this function only
+ * sets the initial size, just as if the user had resized the window
+ * themselves. Users can still shrink the window again as they
+ * normally would.
+ *
+ * For more control over a window's initial size and how resizing works,
+ * investigate gtk_window_set_geometry_hints().
+ * 
+ **/
 void       
 gtk_window_set_default_size (GtkWindow   *window,
 			     gint         width,
diff --git a/gtk/testgtk.c b/gtk/testgtk.c
index c5c460d531..df318a0fed 100644
--- a/gtk/testgtk.c
+++ b/gtk/testgtk.c
@@ -969,23 +969,6 @@ statusbar_contexts (GtkStatusbar *statusbar)
 }
 
 static void
-statusbar_dump_stack (GtkStatusbar *statusbar)
-{
-  GSList *list;
-
-  for (list = statusbar->messages; list; list = list->next)
-    {
-      GtkStatusbarMsg *msg;
-
-      msg = list->data;
-      g_print ("context_id: %d, message_id: %d, status_text: \"%s\"\n",
-               msg->context_id,
-               msg->message_id,
-               msg->text);
-    }
-}
-
-static void
 create_statusbar (void)
 {
   static GtkWidget *window = NULL;
@@ -1048,15 +1031,6 @@ create_statusbar (void)
 		    NULL);
 
       button = gtk_widget_new (gtk_button_get_type (),
-			       "label", "dump stack",
-			       "visible", TRUE,
-			       "parent", box2,
-			       NULL);
-      g_object_set (G_OBJECT (button),
-		    "swapped_signal::clicked", statusbar_dump_stack, statusbar,
-		    NULL);
-
-      button = gtk_widget_new (gtk_button_get_type (),
 			       "label", "test contexts",
 			       "visible", TRUE,
 			       "parent", box2,