Documentation additions.

        * gtk/gtkoldeditable.c, gtk/gtkrc.c,
        gtk/gtkstyle.c: Documentation additions.

        * gtk/gtkmenu.c (gtk_menu_set_accel_path),
        gtk/gtkmenuitem.c (gtk_menu_item_set_accel_path),
        gtk/gtkwidget.c (gtk_widget_add_accelerator): Typo and markup fixes.

        * gtk/gtkitemfactory.c (gtk_item_factory_add_foreign): Document.

        * gtk/gtkaccelmap.c (gtk_accel_map_add_filter): Explain intended use.

        * gtk/running.sgml: Add ids to some elements to make them
        addressable as link targets.

8 files changed, 297 insertions, 16 deletions

diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c
index 2f4e6d1fb3..ebcf23fc46 100644
--- a/gtk/gtkaccelmap.c
+++ b/gtk/gtkaccelmap.c
@@ -749,6 +749,10 @@ gtk_accel_map_foreach_unfiltered (gpointer           data,
  *
  * Accel map entries whose accel path matches one of the filters
  * are skipped by gtk_accel_map_foreach().
+ *
+ * This function is intended for GTK+ modules that create their own
+ * menus, but don't want them to be saved into the applications accelerator
+ * map dump.
  */
 void
 gtk_accel_map_add_filter (const gchar *filter_pattern)
diff --git a/gtk/gtkitemfactory.c b/gtk/gtkitemfactory.c
index bb4790bf28..877ccab11b 100644
--- a/gtk/gtkitemfactory.c
+++ b/gtk/gtkitemfactory.c
@@ -200,7 +200,8 @@ gtk_item_factory_init (GtkItemFactory	    *ifactory)
  * gtk_item_factory_new:
  * @container_type: the kind of menu to create; can be
  *    #GTK_TYPE_MENU_BAR, #GTK_TYPE_MENU or #GTK_TYPE_OPTION_MENU
- * @path: the path of the menu, a string of the form "<name>"
+ * @path: the factory path of the new item factory, a string of the form 
+ *    <literal>"&lt;name&gt;"</literal>
  * @accel_group: a #GtkAccelGroup to which the accelerators for the
  *    menu items will be added, or %NULL to create a new one
  * @returns: a new #GtkItemFactory
@@ -251,6 +252,22 @@ gtk_item_factory_item_remove_widget (GtkWidget		*widget,
   gtk_object_remove_data_by_id (GTK_OBJECT (widget), quark_item_path);
 }
 
+/**
+ * gtk_item_factory_add_foreign:
+ * @accel_widget:     widget to install an accelerator on 
+ * @full_path:	      the full path for the @accel_widget 
+ * @accel_group:      the accelerator group to install the accelerator in
+ * @accel_key:        key value of the accelerator
+ * @accel_mods:       modifier combination of the accelerator
+ *
+ * Installs an accelerator for @accel_widget in @accel_group, that causes
+ * the ::activate signal to be emitted if the accelerator is activated.
+ * 
+ * This function can be used to make widgets participate in the accel
+ * saving/restoring functionality provided by gtk_accel_map_save() and
+ * gtk_accel_map_load(), even if they haven't been created by an item
+ * factory. 
+ */
 void
 gtk_item_factory_add_foreign (GtkWidget      *accel_widget,
 			      const gchar    *full_path,
@@ -393,7 +410,8 @@ gtk_item_factory_add_item (GtkItemFactory		*ifactory,
  * @ifactory: a #GtkItemFactory
  * @container_type: the kind of menu to create; can be
  *    #GTK_TYPE_MENU_BAR, #GTK_TYPE_MENU or #GTK_TYPE_OPTION_MENU
- * @path: the path of the menu, a string of the form "<name>"
+ * @path: the factory path of @ifactory, a string of the form 
+ *    <literal>"&lt;name&gt;"</literal>
  * @accel_group: a #GtkAccelGroup to which the accelerators for the
  *    menu items will be added, or %NULL to create a new one
  * 
@@ -445,10 +463,13 @@ gtk_item_factory_construct (GtkItemFactory	*ifactory,
 
 /**
  * gtk_item_factory_from_path:
- * @path: a string starting with a factory path of the form <literal>"&lt;name&gt;"</literal>
+ * @path: a string starting with a factory path of the form 
+ *   <literal>"&lt;name&gt;"</literal>
  * @returns: the #GtkItemFactory created for the given factory path, or %NULL 
  *
- * Finds an item factory which has been constructed using the <literal>"&lt;name&gt;"</literal> prefix of @path as the @path argument for gtk_item_factory_new().
+ * Finds an item factory which has been constructed using the 
+ * <literal>"&lt;name&gt;"</literal> prefix of @path as the @path argument 
+ * for gtk_item_factory_new().
  */
 GtkItemFactory*
 gtk_item_factory_from_path (const gchar      *path)
@@ -1486,10 +1507,10 @@ gtk_item_factory_popup_with_data (GtkItemFactory	*ifactory,
  * @ifactory: a #GtkItemFactory
  * @func: the #GtkTranslateFunc function to be used to translate path elements 
  * @data: data to pass to @func and @notify
- * @notify: a #GtkDestroyNotify function to be called @ifactory is destroyed 
- *   and when the translation function is changed again
+ * @notify: a #GtkDestroyNotify function to be called when @ifactory is 
+ *   destroyed and when the translation function is changed again
  * 
- * Sets a function to be use for translating the path elements before they
+ * Sets a function to be used for translating the path elements before they
  * are displayed. 
  */ 
 void
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 133c9fe887..5d8a4efc94 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -876,9 +876,10 @@ gtk_menu_get_accel_group (GtkMenu *menu)
  * Instead, by just calling gtk_menu_set_accel_path() on their parent,
  * each menu item of this menu, that contains a label describing its purpose,
  * automatically gets an accel path assigned. For example, a menu containing
- * menu items "New" and "Exit", will, after gtk_menu_set_accel_path (menu,
- * "&lt;Gnumeric-Sheet&gt;/File"); has been called, assign its items the accel paths:
- * "&lt;Gnumeric-Sheet&gt;/File/New" and "&lt;Gnumeric-Sheet&gt;/File/Exit".
+ * menu items "New" and "Exit", will, after 
+ * <literal>gtk_menu_set_accel_path (menu, "&lt;Gnumeric-Sheet&gt;/File");</literal>
+ * has been called, assign its items the accel paths:
+ * <literal>"&lt;Gnumeric-Sheet&gt;/File/New"</literal> and <literal>"&lt;Gnumeric-Sheet&gt;/File/Exit"</literal>.
  * Assigning accel paths to menu items then enables the user to change
  * their accelerators at runtime. More details about accelerator paths
  * and their default setups can be found at gtk_accel_map_add_entry().
diff --git a/gtk/gtkmenuitem.c b/gtk/gtkmenuitem.c
index a7d5764706..b5bd0b52ef 100644
--- a/gtk/gtkmenuitem.c
+++ b/gtk/gtkmenuitem.c
@@ -1078,7 +1078,7 @@ _gtk_menu_item_refresh_accel_path (GtkMenuItem   *menu_item,
 /**
  * gtk_menu_item_set_accel_path
  * @menu_item:  a valid #GtkMenuItem
- * @accel_path: accelerator path, corresponding to this menu item's funcitonality
+ * @accel_path: accelerator path, corresponding to this menu item's functionality
  *
  * Set the accelerator path on @menu_item, through which runtime changes of the
  * menu item's accelerator caused by the user can be identified and saved to
diff --git a/gtk/gtkoldeditable.c b/gtk/gtkoldeditable.c
index 5ec2eeb09f..d723ebd0a4 100644
--- a/gtk/gtkoldeditable.c
+++ b/gtk/gtkoldeditable.c
@@ -708,6 +708,15 @@ old_editable_text_received_cb (GtkClipboard *clipboard,
   g_object_unref (G_OBJECT (old_editable));
 }
 
+/**
+ * gtk_old_editable_claim_selection:
+ * @old_editable: a #GtkOldEditable
+ * @claim: if %TRUE, claim ownership of the selection, if %FALSE, give
+ *   up ownership
+ * @time: timestamp for this operation
+ * 
+ * Claims or gives up ownership of the selection.
+ */
 void
 gtk_old_editable_claim_selection (GtkOldEditable *old_editable, 
 				  gboolean        claim, 
@@ -807,6 +816,12 @@ gtk_old_editable_real_paste_clipboard (GtkOldEditable *old_editable)
 			      old_editable_text_received_cb, old_editable);
 }
 
+/**
+ * gtk_old_editable_changed:
+ * @old_editable: a #GtkOldEditable
+ *
+ * Emits the ::changed signal on @old_editable.
+ */
 void
 gtk_old_editable_changed (GtkOldEditable *old_editable)
 {
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index fc34a496bc..bb041ccf6c 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -311,6 +311,15 @@ gtk_rc_make_default_dir (const gchar *type)
   return path;
 }
 
+/**
+ * gtk_rc_get_im_module_path:
+ * @returns: a newly-allocated string containing the path in which to 
+ *    look for IM modules.
+ *
+ * Obtains the path in which to look for IM modules. See the documentation
+ * of the <link linkend="im-module-path"><envar>GTK_IM_MODULE_PATH</envar></link>
+ * environment variable for more details.
+ */
 gchar *
 gtk_rc_get_im_module_path (void)
 {
@@ -327,6 +336,15 @@ gtk_rc_get_im_module_path (void)
   return g_strdup (result);
 }
 
+/**
+ * gtk_rc_get_im_module_file:
+ * @returns: a newly-allocated string containing the name of the file
+ * listing the IM modules to load
+ *
+ * Obtains the path to the IM modules file. See the documentation
+ * of the <link linkend="im-module-file"><envar>GTK_IM_MODULE_FILE</envar></link>
+ * environment variable for more details.
+ * 
 gchar *
 gtk_rc_get_im_module_file (void)
 {
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index 85ca783f1f..9c4ca5a512 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -879,7 +879,22 @@ gtk_draw_vline (GtkStyle     *style,
   GTK_STYLE_GET_CLASS (style)->draw_vline (style, window, state_type, NULL, NULL, NULL, y1, y2, x);
 }
 
-
+/**
+ * gtk_draw_shadow:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: type of shadow to draw
+ * @x: x origin of the rectangle
+ * @y: y origin of the rectangle
+ * @width: width of the rectangle 
+ * @height: width of the rectangle 
+ *
+ * Draws a shadow around the given rectangle in @window 
+ * using the given style and state and shadow type.
+ * 
+ * This function is deprecated, use gtk_paint_shadow() instead.
+ */
 void
 gtk_draw_shadow (GtkStyle      *style,
                  GdkWindow     *window,
@@ -896,6 +911,20 @@ gtk_draw_shadow (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_shadow (style, window, state_type, shadow_type, NULL, NULL, NULL, x, y, width, height);
 }
 
+/**
+ * gtk_draw_polygon:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: type of shadow to draw
+ * @points: an array of #GdkPoint<!>s
+ * @npoints: length of @points
+ * @fill: %TRUE if the polygon should be filled
+ * 
+ * Draws a polygon on @window with the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_polygon() instead.
+ */ 
 void
 gtk_draw_polygon (GtkStyle      *style,
                   GdkWindow     *window,
@@ -911,6 +940,24 @@ gtk_draw_polygon (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_polygon (style, window, state_type, shadow_type, NULL, NULL, NULL, points, npoints, fill);
 }
 
+/**
+ * gtk_draw_arrow:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: the type of shadow to draw
+ * @arrow_type: the type of arrow to draw
+ * @fill: %TRUE if the arrow tip should be filled
+ * @x: x origin of the rectangle to draw the arrow in
+ * @y: y origin of the rectangle to draw the arrow in
+ * @width: width of the rectangle to draw the arrow in
+ * @height: height of the rectangle to draw the arrow in
+ * 
+ * Draws an arrow in the given rectangle on @window using the given 
+ * parameters. @arrow_type determines the direction of the arrow.
+ *
+ * This function is deprecated, use gtk_paint_arrow() instead.
+ */
 void
 gtk_draw_arrow (GtkStyle      *style,
                 GdkWindow     *window,
@@ -929,7 +976,21 @@ gtk_draw_arrow (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_arrow (style, window, state_type, shadow_type, NULL, NULL, NULL, arrow_type, fill, x, y, width, height);
 }
 
-
+/**
+ * gtk_draw_diamond:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: the type of shadow to draw
+ * @x: x origin of the rectangle to draw the diamond in
+ * @y: y origin of the rectangle to draw the diamond in
+ * @width: width of the rectangle to draw the diamond in
+ * @height: height of the rectangle to draw the diamond in
+ *
+ * Draws a diamond in the given rectangle on @window using the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_diamond() instead.
+ */
 void
 gtk_draw_diamond (GtkStyle      *style,
                   GdkWindow     *window,
@@ -946,7 +1007,19 @@ gtk_draw_diamond (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_diamond (style, window, state_type, shadow_type, NULL, NULL, NULL, x, y, width, height);
 }
 
-
+/**
+ * gtk_draw_string:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @x: x origin
+ * @y: y origin
+ * @string: the string to draw
+ * 
+ * Draws a text string on @window with the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_layout() instead.
+ */
 void
 gtk_draw_string (GtkStyle      *style,
                  GdkWindow     *window,
@@ -961,6 +1034,21 @@ gtk_draw_string (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_string (style, window, state_type, NULL, NULL, NULL, x, y, string);
 }
 
+/**
+ * gtk_draw_box:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: the type of shadow to draw
+ * @x: x origin of the box
+ * @y: y origin of the box
+ * @width: the width of the box
+ * @height: the height of the box
+ * 
+ * Draws a box on @window with the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_box() instead.
+ */
 void
 gtk_draw_box (GtkStyle      *style,
               GdkWindow     *window,
@@ -977,6 +1065,21 @@ gtk_draw_box (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_box (style, window, state_type, shadow_type, NULL, NULL, NULL, x, y, width, height);
 }
 
+/**
+ * gtk_draw_flat_box:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: the type of shadow to draw
+ * @x: x origin of the box
+ * @y: y origin of the box
+ * @width: the width of the box
+ * @height: the height of the box
+ * 
+ * Draws a flat box on @window with the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_flat_box() instead.
+ */
 void
 gtk_draw_flat_box (GtkStyle      *style,
                    GdkWindow     *window,
@@ -993,6 +1096,22 @@ gtk_draw_flat_box (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_flat_box (style, window, state_type, shadow_type, NULL, NULL, NULL, x, y, width, height);
 }
 
+/**
+ * gtk_draw_check:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: the type of shadow to draw
+ * @x: x origin of the rectangle to draw the check in
+ * @y: y origin of the rectangle to draw the check in
+ * @width: the width of the rectangle to draw the check in
+ * @height: the height of the rectangle to draw the check in
+ * 
+ * Draws a check button indicator in the given rectangle on @window with 
+ * the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_check() instead.
+ */
 void
 gtk_draw_check (GtkStyle      *style,
                 GdkWindow     *window,
@@ -1009,6 +1128,22 @@ gtk_draw_check (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_check (style, window, state_type, shadow_type, NULL, NULL, NULL, x, y, width, height);
 }
 
+/**
+ * gtk_draw_option:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: the type of shadow to draw
+ * @x: x origin of the rectangle to draw the option in
+ * @y: y origin of the rectangle to draw the option in
+ * @width: the width of the rectangle to draw the option in
+ * @height: the height of the rectangle to draw the option in
+ *
+ * Draws a radio button indicator in the given rectangle on @window with 
+ * the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_option() instead.
+ */
 void
 gtk_draw_option (GtkStyle      *style,
 		 GdkWindow     *window,
@@ -1025,6 +1160,22 @@ gtk_draw_option (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_option (style, window, state_type, shadow_type, NULL, NULL, NULL, x, y, width, height);
 }
 
+/**
+ * gtk_draw_tab:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @shadow_type: the type of shadow to draw
+ * @x: x origin of the rectangle to draw the tab in
+ * @y: y origin of the rectangle to draw the tab in
+ * @width: the width of the rectangle to draw the tab in
+ * @height: the height of the rectangle to draw the tab in
+ *
+ * Draws an option menu tab (i.e. the up and down pointing arrows)
+ * in the given rectangle on @window using the given parameters.
+ * 
+ * This function is deprecated, use gtk_paint_tab() instead.
+ */ 
 void
 gtk_draw_tab (GtkStyle      *style,
 	      GdkWindow     *window,
@@ -1096,6 +1247,20 @@ gtk_draw_extension (GtkStyle       *style,
   GTK_STYLE_GET_CLASS (style)->draw_extension (style, window, state_type, shadow_type, NULL, NULL, NULL, x, y, width, height, gap_side);
 }
 
+/**
+ * gtk_draw_focus:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @x: the x origin of the rectangle around which to draw a focus indicator
+ * @y: the y origin of the rectangle around which to draw a focus indicator
+ * @width: the width of the rectangle around which to draw a focus indicator
+ * @height: the height of the rectangle around which to draw a focus indicator
+ *
+ * Draws a focus indicator around the given rectangle on @window using the
+ * given style.
+ * 
+ * This function is deprecated, use gtk_paint_focus() instead.
+ */
 void
 gtk_draw_focus (GtkStyle      *style,
 		GdkWindow     *window,
@@ -1177,6 +1342,23 @@ gtk_draw_layout (GtkStyle        *style,
                                             x, y, layout);
 }
 
+/**
+ * gtk_draw_resize_grip:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @edge: the edge in which to draw the resize grip, currently only
+ *    %GTK_WINDOW_EDGE_SOUTH_EAST is implemented
+ * @x: the x origin of the rectangle in which to draw the resize grip
+ * @y: the y origin of the rectangle in which to draw the resize grip
+ * @width: the width of the rectangle in which to draw the resize grip
+ * @height: the height of the rectangle in which to draw the resize grip
+ *
+ * Draws a resize grip in the given rectangle on @window using the given
+ * parameters. 
+ * 
+ * This function is deprecated, use gtk_paint_resize_grip() instead.
+ */
 void
 gtk_draw_resize_grip (GtkStyle     *style,
                       GdkWindow    *window,
@@ -1197,6 +1379,15 @@ gtk_draw_resize_grip (GtkStyle     *style,
 }
 
 
+/**
+ * gtk_style_set_background:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * 
+ * Sets the background of @window to the background color or pixmap
+ * specified by @style for the given state.
+ */
 void
 gtk_style_set_background (GtkStyle    *style,
                           GdkWindow   *window,
@@ -1563,6 +1754,21 @@ gtk_style_real_set_background (GtkStyle    *style,
     gdk_window_set_background (window, &style->bg[state_type]);
 }
 
+/**
+ * gtk_style_render_icon:
+ * @style: a #GtkStyle
+ * @source: the #GtkIconSource specifying the icon to render
+ * @direction: a text direction
+ * @state: a state
+ * @size: the size to render the icon at
+ * @widget: the widget 
+ * @detail: a style detail
+ * @returns: a newly-created #GdkPixbuf containing the rendered icon
+ *
+ * Renders the icon specified by @source at the given @size 
+ * according to the given parameterss and returns the result in a 
+ * pixbuf.
+ */
 GdkPixbuf *
 gtk_style_render_icon (GtkStyle            *style,
                        const GtkIconSource *source,
@@ -4836,6 +5042,22 @@ gtk_paint_diamond (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_diamond (style, window, state_type, shadow_type, area, widget, detail, x, y, width, height);
 }
 
+/**
+ * gtk_paint_string:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @area: clip rectangle
+ * @widget: the widget
+ * @detail: a style detail
+ * @x: x origin
+ * @y: y origin
+ * @string: the string to draw
+ * 
+ * Draws a text string on @window with the given parameters.
+ *
+ * This function is deprecated, use gtk_paint_layout() instead.
+ */
 void
 gtk_paint_string (GtkStyle      *style,
                   GdkWindow     *window,
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 6e6f7b7192..5a448e9ec3 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -2596,7 +2596,7 @@ widget_new_accel_closure (GtkWidget *widget,
 /**
  * gtk_widget_add_accelerator
  * @widget:       widget to install an accelerator on
- * @accel_signal: widget signal to emit on accelerator actiavtion
+ * @accel_signal: widget signal to emit on accelerator activation
  * @accel_group:  accel group for this widget, added to its toplevel
  * @accel_key:    GDK keyval of the accelerator
  * @accel_mods:   modifier key combination of the accelerator
@@ -2606,7 +2606,7 @@ widget_new_accel_closure (GtkWidget *widget,
  * @accel_signal to be emitted if the accelerator is activated.
  * The @accel_group needs to be added to the widget's toplevel via
  * gtk_window_add_accel_group(), and the signal must be of type %G_RUN_ACTION.
- * Accelerators added through this function are not user changable during
+ * Accelerators added through this function are not user changeable during
  * runtime. If you want to support accelerators that can be changed by the
  * user, use gtk_accel_map_add_entry() and gtk_menu_item_set_accel_path()
  * instead.