Doc typo fix. (#68172)

        * gtk/gtksocket.c (gtk_socket_get_id): Doc typo fix. (#68172)

        * gtk/gtktreemodel.c (gtk_tree_path_is_descendant): Fix docs.

        * gtk/gtktreemodel.c (gtk_tree_model_rows_reordered): Document.

        * gtk/gtkwindow.c (gtk_window_remove_accel_group): Fix docs.

        * gtk/gtkrc.c (gtk_rc_get_style_by_paths),
        gtk/gtkwidget.c (gtk_widget_get_toplevel,
        gtk_widget_push_composite_child), gtk/gtkdialog.c
        (gtk_dialog_new_with_buttons, gtk_dialog_run): Keep gtk-doc
        from messing up the indentation of inline examples.

        * gtk/gtkmain.c, gtk/gtkrc.c: Consistently call g_getenv()
        instead of getenv().

        * gtk/gtktreemodel.c, gtk/gtkaccelgroup.c, gtk/gtkclipboard.c,
        gtk/gtkdnd.c, gtk/gtkiconfactory.c, gtk/gtkrc.c,
        gtk/gtkstyle.c, gtk/gtkselection.c: Doc fixes.

        * gtk/gtkaccelmap.c (gtk_accel_map_add_filter,
        gtk_accel_map_foreach_unfiltered, gtk_accel_map_load_scanner):
        Document.

        * gtk/tmpl/gtksocket.sgml: Mention gtk_socket_get_id()
        instead of GTK_WINDOW_XWINDOW().  (#68172)

        * gtk/gtk-sections.txt: Move functions which are documented
        as "private" or "internal" into Private subsections.

        * gtk/tmpl/gtkdnd.sgml, gtk/tmpl/gtkobject.sgml,
        gtk/tmpl/gtkrc.sgml, gtk/tmpl/gtktooltips.sgml,
        gtk/tmpl/gtkwidget.sgml, gtk/tmpl/gtkclipboard.sgml,
        gtk/tmpl/gtkstyle.sgml, gtk/tmpl/gtkselection.sgml,
        gtk/tmpl/gtkfeatures.sgml: Minor markup fixes.

        * gtk/tmpl/gtksignal.sgml: Add link to GLib signal docs.

        * gtk/tmpl/gtkpreview.sgml, gtk/tmpl/gtktext.sgml,
        gtk/tmpl/gtktree.sgml: Remove "deprecated" from short desc.

        * gtk/tmpl/gtkrc.sgml: Correct names of default RC files.

14 files changed, 231 insertions, 129 deletions

diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 080b3d0ec..653b69cec 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -264,8 +264,8 @@ gtk_accel_groups_from_object (GObject *object)
  * @returns: the key of the first entry passing @find_func. The key is 
  * owned by GTK+ and must not be freed.
  *
- * Finds the first entry in an accelerator group for which @find_func
- * returns %TRUE and returns its #GtkAccelKey.
+ * Finds the first entry in an accelerator group for which 
+ * @find_func returns %TRUE and returns its #GtkAccelKey.
  *
  */
 GtkAccelKey*
diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c
index 6ba3fe32c..2f4e6d1fb 100644
--- a/gtk/gtkaccelmap.c
+++ b/gtk/gtkaccelmap.c
@@ -104,18 +104,18 @@ _gtk_accel_path_is_valid (const gchar *accel_path)
 }
 
 /**
- * gtk_accel_map_add_entry
+ * gtk_accel_map_add_entry:
  * @accel_path: valid accelerator path
  * @accel_key:  the accelerator key
  * @accel_mods: the accelerator modifiers
  *
- * Register a new accelerator with the global accelerator map.
+ * Registers a new accelerator with the global accelerator map.
  * This function should only be called once per @accel_path
  * with the canonical @accel_key and @accel_mods for this path.
  * To change the accelerator during runtime programatically, use
  * gtk_accel_map_change_entry().
  * The accelerator path must consist of "<WINDOWTYPE>/Category1/Category2/.../Action",
- * where WINDOWTYPE should be a unique application-specific identifier, that
+ * where <WINDOWTYPE> should be a unique application-specific identifier, that
  * corresponds to the kind of window the accelerator is being used in, e.g. "Gimp-Image",
  * "Abiword-Document" or "Gnumeric-Settings".
  * The Category1/.../Action portion is most appropriately chosen by the action the
@@ -164,9 +164,9 @@ gtk_accel_map_add_entry (const gchar *accel_path,
 }
 
 /**
- * gtk_accel_map_lookup_entry
- * @accel_path:  valid accelerator path
- * @key:         accelerator key to be filled in (optional)
+ * gtk_accel_map_lookup_entry:
+ * @accel_path:  a valid accelerator path
+ * @key:         the accelerator key to be filled in (optional)
  * @returns:     %TRUE if @accel_path is known, %FALSE otherwise
  *
  * Looks up the accelerator entry for @accel_path and fills in @key.
@@ -378,14 +378,14 @@ internal_change_entry (const gchar    *accel_path,
 }
 
 /**
- * gtk_accel_map_change_entry
- * @accel_path:  valid accelerator path
- * @accel_key:   new accelerator key
- * @accel_mods:  new accelerator modifiers
+ * gtk_accel_map_change_entry:
+ * @accel_path:  a valid accelerator path
+ * @accel_key:   the new accelerator key
+ * @accel_mods:  the new accelerator modifiers
  * @replace:     %TRUE if other accelerators may be deleted upon conflicts
  * @returns:     %TRUE if the accelerator could be changed, %FALSE otherwise
  *
- * Change the @accel_key and @accel_mods currently associated with @accel_path.
+ * Changes the @accel_key and @accel_mods currently associated with @accel_path.
  * Due to conflicts with other accelerators, a change may not always be possible,
  * @replace indicates whether other accelerators may be deleted to resolve such
  * conflicts. A change will only occur if all conflicts could be resolved (which
@@ -488,6 +488,12 @@ accel_map_parse_statement (GScanner *scanner)
     }
 }
 
+/**
+ * gtk_accel_map_load_scanner:
+ * @scanner: a #GScanner which has already been provided with an input file
+ *
+ * #GScanner variant of gtk_accel_map_load().
+ */
 void
 gtk_accel_map_load_scanner (GScanner *scanner)
 {
@@ -530,10 +536,11 @@ gtk_accel_map_load_scanner (GScanner *scanner)
 }
 
 /**
- * gtk_accel_map_load_fd
- * @fd: valid readable file descriptor
+ * gtk_accel_map_load_fd:
+ * @fd: a valid readable file descriptor
  *
  * Filedescriptor variant of gtk_accel_map_load().
+ *
  * Note that the file descriptor will not be closed by this function.
  */
 void
@@ -553,7 +560,7 @@ gtk_accel_map_load_fd (gint fd)
 }
 
 /**
- * gtk_accel_map_load
+ * gtk_accel_map_load:
  * @file_name: a file containing accelerator specifications
  *
  * Parses a file previously saved with gtk_accel_map_save() for
@@ -613,10 +620,11 @@ accel_map_print (gpointer        data,
 }
 
 /**
- * gtk_accel_map_save_fd
- * @fd: valid writable file descriptor
+ * gtk_accel_map_save_fd:
+ * @fd: a valid writable file descriptor
  *
  * Filedescriptor variant of gtk_accel_map_save().
+ *
  * Note that the file descriptor will not be closed by this function.
  */
 void
@@ -642,7 +650,7 @@ gtk_accel_map_save_fd (gint fd)
 }
 
 /**
- * gtk_accel_map_save
+ * gtk_accel_map_save:
  * @file_name: the file to contain accelerator specifications
  *
  * Saves current accelerator specifications (accelerator path, key
@@ -667,13 +675,15 @@ gtk_accel_map_save (const gchar *file_name)
 }
 
 /**
- * gtk_accel_map_foreach
+ * gtk_accel_map_foreach:
  * @data:         data to be passed into @foreach_func
- * @foreach_func: function to be executed for each accel map entry
+ * @foreach_func: function to be executed for each accel map entry which
+ *                is not filtered out
  *
- * Loop over the entries in the accelerator map, and execute
- * @foreach_func on each. The signature of @foreach_func is that of
- * #GtkAccelMapForeach, the @changed parameter indicates whether
+ * Loops over the entries in the accelerator map whose accel path 
+ * doesn't match any of the filters added with gtk_accel_map_add_filter(), 
+ * and execute @foreach_func on each. The signature of @foreach_func is 
+ * that of #GtkAccelMapForeach, the @changed parameter indicates whether
  * this accelerator was changed during runtime (thus, would need
  * saving during an accelerator map dump).
  */
@@ -701,6 +711,17 @@ gtk_accel_map_foreach (gpointer           data,
   g_slist_free (entries);
 }
 
+/**
+ * gtk_accel_map_foreach_unfiltered:
+ * @data:         data to be passed into @foreach_func
+ * @foreach_func: function to be executed for each accel map entry
+ *
+ * Loops over all entries in the accelerator map, and execute
+ * @foreach_func on each. The signature of @foreach_func is that of
+ * #GtkAccelMapForeach, the @changed parameter indicates whether
+ * this accelerator was changed during runtime (thus, would need
+ * saving during an accelerator map dump).
+ */
 void
 gtk_accel_map_foreach_unfiltered (gpointer           data,
 				  GtkAccelMapForeach foreach_func)
@@ -720,6 +741,15 @@ gtk_accel_map_foreach_unfiltered (gpointer           data,
   g_slist_free (entries);
 }
 
+/**
+ * gtk_accel_map_add_filter:
+ * @filter_pattern: a pattern (see #GPatternSpec)
+ *
+ * Adds a filter to the global list of accel path filters.
+ *
+ * Accel map entries whose accel path matches one of the filters
+ * are skipped by gtk_accel_map_foreach().
+ */
 void
 gtk_accel_map_add_filter (const gchar *filter_pattern)
 {
diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index 4a3f20fd6..b4dbba71f 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -454,7 +454,7 @@ gtk_clipboard_set_with_owner (GtkClipboard          *clipboard,
  * 
  * If the clipboard contents callbacks were set with 
  * gtk_clipboard_set_with_owner(), and the gtk_clipboard_set_with_data() or 
- * gtk_clipboard_clear() has not subsequently called, returns the @owner set 
+ * gtk_clipboard_clear() has not subsequently called, returns the owner set 
  * by gtk_clipboard_set_with_owner().
  * 
  * Return value: the owner of the clipboard, if any; otherwise %NULL.
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 707edbb3a..dec95d524 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -386,14 +386,14 @@ gtk_dialog_new_empty (const gchar     *title,
  *
  * Here's a simple example:
  * <informalexample><programlisting>
- *  GtkWidget *dialog = gtk_dialog_new_with_buttons ("My dialog",
- *                                                   main_app_window,
- *                                                   GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
- *                                                   GTK_STOCK_OK,
- *                                                   GTK_RESPONSE_ACCEPT,
- *                                                   GTK_STOCK_CANCEL,
- *                                                   GTK_RESPONSE_REJECT,
- *                                                   NULL);
+ *  <!>GtkWidget *dialog = gtk_dialog_new_with_buttons ("My dialog",
+ *  <!>                                                 main_app_window,
+ *  <!>                                                 GTK_DIALOG_MODAL | GTK_DIALOG_DESTROY_WITH_PARENT,
+ *  <!>                                                 GTK_STOCK_OK,
+ *  <!>                                                 GTK_RESPONSE_ACCEPT,
+ *  <!>                                                 GTK_STOCK_CANCEL,
+ *  <!>                                                 GTK_RESPONSE_REJECT,
+ *  <!>                                                 NULL);
  * </programlisting></informalexample>
  * 
  * Return value: a new #GtkDialog
@@ -851,17 +851,17 @@ run_destroy_handler (GtkDialog *dialog, gpointer data)
  *
  * Typical usage of this function might be:
  * <informalexample><programlisting>
- *   gint result = gtk_dialog_run (GTK_DIALOG (dialog));
- *   switch (result)
- *     {
- *       case GTK_RESPONSE_ACCEPT:
- *          do_application_specific_something (<!-- -->);
- *          break;
- *       default:
- *          do_nothing_since_dialog_was_cancelled (<!-- -->);
- *          break;
- *     }
- *   gtk_widget_destroy (dialog);
+ * <!>  gint result = gtk_dialog_run (GTK_DIALOG (dialog));
+ * <!>  switch (result)
+ * <!>    {
+ * <!>      case GTK_RESPONSE_ACCEPT:
+ * <!>         do_application_specific_something (<!-- -->);
+ * <!>         break;
+ * <!>      default:
+ * <!>         do_nothing_since_dialog_was_cancelled (<!-- -->);
+ * <!>         break;
+ * <!>    }
+ * <!>  gtk_widget_destroy (dialog);
  * </programlisting></informalexample>
  * 
  * Return value: response ID
diff --git a/gtk/gtkdnd.c b/gtk/gtkdnd.c
index 3e8835880..9611bbe0f 100644
--- a/gtk/gtkdnd.c
+++ b/gtk/gtkdnd.c
@@ -2342,7 +2342,7 @@ gtk_drag_set_icon_default (GdkDragContext    *context)
  * Changes the default drag icon. GTK+ retains references for the
  * arguments, and will release them when they are no longer needed.
  * This function is obsolete. The default icon should now be changed
- * via the stock system by changing the stock pixbuf for %GTK_STOCK_DND.
+ * via the stock system by changing the stock pixbuf for #GTK_STOCK_DND.
  **/
 void 
 gtk_drag_set_default_icon (GdkColormap   *colormap,
@@ -3154,11 +3154,11 @@ gtk_drag_abort_timeout (gpointer data)
  * @current_x: current X coordinate
  * @current_y: current Y coordinate
  * 
- * Checks to see if a mouse drag starting at (start_x, start_y) and ending
- * at (current_x, current_y) has passed the GTK drag threshhold, and thus
+ * Checks to see if a mouse drag starting at (@start_x, @start_y) and ending
+ * at (@current_x, @current_y) has passed the GTK+ drag threshhold, and thus
  * should trigger the beginning of a drag-and-drop operation.
  *
- * Return Value: If the drag threshold has been passed.
+ * Return Value: %TRUE if the drag threshold has been passed.
  **/
 gboolean
 gtk_drag_check_threshold (GtkWidget *widget,
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index f455978e8..df12354ee 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -134,11 +134,11 @@ gtk_icon_factory_finalize (GObject *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
+ * of #GtkIconSet<!>s; 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
+ * #GtkStyle has a list of #GtkIconFactory<!>s 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
@@ -1718,7 +1718,7 @@ gtk_icon_source_set_size (GtkIconSource *source,
  * @source: a #GtkIconSource
  * 
  * Obtains the text direction this icon source applies to. The return
- * value is only useful/meaningful if the text direction is NOT
+ * value is only useful/meaningful if the text direction is <emphasis>not</emphasis> 
  * wildcarded.
  * 
  * Return value: text direction this source matches
@@ -1736,7 +1736,7 @@ gtk_icon_source_get_direction (const GtkIconSource *source)
  * @source: a #GtkIconSource
  * 
  * Obtains the widget state this icon source applies to. The return
- * value is only useful/meaningful if the widget state is NOT
+ * value is only useful/meaningful if the widget state is <emphasis>not</emphasis>
  * wildcarded.
  * 
  * Return value: widget state this source matches
@@ -1754,7 +1754,7 @@ gtk_icon_source_get_state (const GtkIconSource *source)
  * @source: a #GtkIconSource
  * 
  * Obtains the icon size this source applies to. The return value
- * is only useful/meaningful if the icon size is NOT wildcarded.
+ * is only useful/meaningful if the icon size is <emphasis>not</emphasis> wildcarded.
  * 
  * Return value: icon size this source matches.
  **/
diff --git a/gtk/gtkmain.c b/gtk/gtkmain.c
index 8c485c997..1b21483ae 100644
--- a/gtk/gtkmain.c
+++ b/gtk/gtkmain.c
@@ -284,7 +284,7 @@ static gchar **
 get_module_path (void)
 {
   const gchar *module_path_env = g_getenv ("GTK_MODULE_PATH");
-  const gchar *exe_prefix = g_getenv("GTK_EXE_PREFIX");
+  const gchar *exe_prefix = g_getenv ("GTK_EXE_PREFIX");
   gchar **result;
   gchar *module_path;
   gchar *default_dir;
@@ -470,7 +470,7 @@ gtk_init_check (int	 *argc,
   gdk_event_handler_set ((GdkEventFunc)gtk_main_do_event, NULL, NULL);
   
 #ifdef G_ENABLE_DEBUG
-  env_string = getenv ("GTK_DEBUG");
+  env_string = g_getenv ("GTK_DEBUG");
   if (env_string != NULL)
     {
       gtk_debug_flags = g_parse_debug_string (env_string,
@@ -480,7 +480,7 @@ gtk_init_check (int	 *argc,
     }
 #endif	/* G_ENABLE_DEBUG */
 
-  env_string = getenv ("GTK_MODULES");
+  env_string = g_getenv ("GTK_MODULES");
   if (env_string)
     gtk_modules_string = g_string_new (env_string);
 
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index ab453891d..4bc4d58c1 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -301,7 +301,7 @@ gtk_rc_make_default_dir (const gchar *type)
 {
   gchar *var, *path;
 
-  var = getenv("GTK_EXE_PREFIX");
+  var = g_getenv ("GTK_EXE_PREFIX");
   if (var)
     path = g_build_filename (var, "lib", "gtk-2.0", type, GTK_BINARY_VERSION, NULL);
   else
@@ -347,7 +347,7 @@ gtk_rc_get_theme_dir (void)
 {
   gchar *var, *path;
 
-  var = getenv("GTK_DATA_PREFIX");
+  var = g_getenv ("GTK_DATA_PREFIX");
   if (var)
     path = g_build_filename (var, "share", "themes", NULL);
   else
@@ -363,7 +363,7 @@ gtk_rc_get_module_dir (void)
 }
 
 static void
-gtk_rc_append_default_module_path(void)
+gtk_rc_append_default_module_path (void)
 {
   const gchar *var;
   gchar *path;
@@ -373,7 +373,7 @@ gtk_rc_append_default_module_path(void)
   if (n >= GTK_RC_MAX_MODULE_PATHS - 1)
     return;
   
-  var = getenv("GTK_EXE_PREFIX");
+  var = g_getenv ("GTK_EXE_PREFIX");
   if (var)
     path = g_build_filename (var, "lib", "gtk-2.0", GTK_VERSION, "engines", NULL);
   else
@@ -404,7 +404,7 @@ gtk_rc_add_initial_default_files (void)
   gtk_rc_default_files[0] = NULL;
   init = TRUE;
 
-  var = g_getenv("GTK_RC_FILES");
+  var = g_getenv ("GTK_RC_FILES");
   if (var)
     {
       files = g_strsplit (var, G_SEARCHPATH_SEPARATOR_S, 128);
@@ -692,7 +692,7 @@ gtk_rc_parse_default_files (GtkRcContext *context)
       gchar *normalized_locale;
       
       p = strchr (locale, '@');
-      length = p ? (p -locale) : strlen (locale);
+      length = p ? (p - locale) : strlen (locale);
       
       p = strchr (locale, '.');
       if (p)
@@ -1029,7 +1029,7 @@ gtk_rc_style_new (void)
  * @orig: the style to copy
  * 
  * Makes a copy of the specified #GtkRcStyle. This function
- * will correctly copy an rc style that is a member of a class
+ * will correctly copy an RC style that is a member of a class
  * derived from #GtkRcStyle.
  * 
  * Return value: the resulting #GtkRcStyle
@@ -1510,10 +1510,10 @@ gtk_rc_get_style (GtkWidget *widget)
  *
  * The action of gtk_rc_get_style() is similar to:
  * <informalexample><programlisting>
- *  gtk_widget_path (widget, NULL, &amp;path, NULL);
- *  gtk_widget_class_path (widget, NULL, &amp;class_path, NULL);
- *  gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path,
- *                             G_OBJECT_TYPE (widget));
+ * <!> gtk_widget_path (widget, NULL, &amp;path, NULL);
+ * <!> gtk_widget_class_path (widget, NULL, &amp;class_path, NULL);
+ * <!> gtk_rc_get_style_by_paths (gtk_widget_get_settings (widget), path, class_path,
+ * <!>                            G_OBJECT_TYPE (widget));
  * </programlisting></informalexample>
  * 
  * Return value: A style created by matching with the supplied paths,
@@ -1714,7 +1714,7 @@ gtk_rc_parse_any (GtkRcContext *context,
 	      if (scanner->scope_id == 0)
 		{
 		  /* if we are in scope 0, we know the symbol names
-		   * that are associated with certaintoken values.
+		   * that are associated with certain token values.
 		   * so we look them up to make the error messages
 		   * more readable.
 		   */
@@ -2683,7 +2683,7 @@ gtk_rc_check_pixmap_dir (const gchar *dir, const gchar *pixmap_file)
 
 /**
  * gtk_rc_find_pixmap_in_path:
- * @settings: a #GtkSettinsg
+ * @settings: a #GtkSettings
  * @scanner: Scanner used to get line number information for the
  *   warning message, or %NULL
  * @pixmap_file: name of the pixmap file to locate.
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index bb5afe8ed..d7638787e 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -886,7 +886,7 @@ gtk_selection_data_get_text (GtkSelectionData *selection_data)
  *           stored here must be freed with g_free().
  * @n_atoms: location to store number of items in @targets.
  * 
- * Get the contents of @selection_data as an array of targets.
+ * Gets the contents of @selection_data as an array of targets.
  * This can be used to interpret the results of getting
  * the standard TARGETS target that is always supplied for
  * any selection.
@@ -926,7 +926,7 @@ gtk_selection_data_get_targets (GtkSelectionData  *selection_data,
  * @selection_data: a #GtkSelectionData object
  * 
  * Given a #GtkSelectionData object holding a list of targets,
- * Determines if any of the targets in @targets can be used to
+ * determines if any of the targets in @targets can be used to
  * provide text.
  * 
  * Return value: %TRUE if @selection_data holds a list of targets,
diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c
index cc7e306ea..a4879c560 100644
--- a/gtk/gtksocket.c
+++ b/gtk/gtksocket.c
@@ -265,9 +265,10 @@ gtk_socket_add_id (GtkSocket *socket, GdkNativeWindow window_id)
  * 
  * Gets the window ID of a #GtkSocket widget, which can then
  * be used to create a client embedded inside the socket, for
- * instance with gtk_socket_new (id). The #GtkSocket must
- * have already be added into a toplevel window before you
- * can make this call.
+ * instance with gtk_plug_new (). 
+ *
+ * The #GtkSocket must have already be added into a toplevel window 
+ * before you can make this call.
  * 
  * Return value: the window ID for the socket
  **/
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index 9f5d91bad..f503e35b0 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -822,6 +822,20 @@ gtk_style_lookup_icon_set (GtkStyle   *style,
   return gtk_icon_factory_lookup_default (stock_id);
 }
 
+/**
+ * gtk_draw_hline:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @x1: the starting x coordinate
+ * @x2: the ending x coordinate
+ * @y: the y coordinate
+ * 
+ * Draws a horizontal line from (@x1, @y) to (@x2, @y) in @window
+ * using the given style and state.
+ * 
+ * This function is deprecated, use gtk_paint_hline() instead.
+ **/
 void
 gtk_draw_hline (GtkStyle     *style,
                 GdkWindow    *window,
@@ -837,6 +851,20 @@ gtk_draw_hline (GtkStyle     *style,
 }
 
 
+/**
+ * gtk_draw_vline:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @y1: the starting y coordinate
+ * @y2: the ending y coordinate
+ * @x: the x coordinate
+ * 
+ * Draws a vertical line from (@x, @y1) to (@x, @y2) in @window
+ * using the given style and state.
+ * 
+ * This function is deprecated, use gtk_paint_vline() instead.
+ **/
 void
 gtk_draw_vline (GtkStyle     *style,
                 GdkWindow    *window,
@@ -4666,6 +4694,22 @@ hls_to_rgb (gdouble *h,
     }
 }
 
+
+/**
+ * gtk_paint_hline:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @area: rectangle to which the output is clipped
+ * @widget:
+ * @detail: 
+ * @x1: the starting x coordinate
+ * @x2: the ending x coordinate
+ * @y: the y coordinate
+ * 
+ * Draws a horizontal line from (@x1, @y) to (@x2, @y) in @window
+ * using the given style and state.
+ **/ 
 void 
 gtk_paint_hline (GtkStyle      *style,
                  GdkWindow     *window,
@@ -4683,6 +4727,20 @@ gtk_paint_hline (GtkStyle      *style,
   GTK_STYLE_GET_CLASS (style)->draw_hline (style, window, state_type, area, widget, detail, x1, x2, y);
 }
 
+/**
+ * gtk_paint_vline:
+ * @style: a #GtkStyle
+ * @window: a #GdkWindow
+ * @state_type: a state
+ * @area: rectangle to which the output is clipped
+ * @widget:
+ * @detail: 
+ * @y1: the starting y coordinate
+ * @y2: the ending y coordinate
+ * @x: the x coordinate
+ * 
+ * Draws a vertical line from (@x, @y1) to (@x, @y1) in @window
+ * using the given style and state.
 void
 gtk_paint_vline (GtkStyle      *style,
                  GdkWindow     *window,
@@ -5101,9 +5159,9 @@ gtk_border_free (GtkBorder *border)
  * @style: a #GtkStyle
  * 
  * Gets the #GdkFont to use for the given style. This is
- * meant only as a replacement for direct access to style->font
+ * meant only as a replacement for direct access to @style->font
  * and should not be used in new code. New code should
- * use style->font_desc instead.
+ * use @style->font_desc instead.
  * 
  * Return value: the #GdkFont for the style. This font is owned
  *   by the style; if you want to keep around a copy, you must
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index cba492898..07d5f6748 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -148,9 +148,9 @@ gtk_tree_path_new (void)
  * colon separated list of numbers.  For example, the string "10:4:0" would
  * create a path of depth 3 pointing to the 11th child of the root node, the 5th
  * child of that 11th child, and the 1st child of that 5th child.  If an invalid
- * path is past in, NULL is returned.
+ * path is passed in, %NULL is returned.
  *
- * Return value: A newly created #GtkTreePath, or NULL
+ * Return value: A newly-created #GtkTreePath, or %NULL
  **/
 GtkTreePath *
 gtk_tree_path_new_from_string (const gchar *path)
@@ -197,7 +197,7 @@ gtk_tree_path_new_from_string (const gchar *path)
  * Generates a string representation of the path.  This string is a ':'
  * separated list of numbers.  For example, "4:10:0:3" would be an acceptable return value for this string.
  *
- * Return value: A newly allocated string.  Must be freed with #g_free.
+ * Return value: A newly-allocated string.  Must be freed with g_free().
  **/
 gchar *
 gtk_tree_path_to_string (GtkTreePath *path)
@@ -312,7 +312,7 @@ gtk_tree_path_get_depth (GtkTreePath *path)
  * Returns the current indices of @path.  This is an array of integers, each
  * representing a node in a tree.
  *
- * Return value: The current indices, or NULL.
+ * Return value: The current indices, or %NULL.
  **/
 gint *
 gtk_tree_path_get_indices (GtkTreePath *path)
@@ -431,7 +431,7 @@ gtk_tree_path_is_ancestor (GtkTreePath *path,
  * @path: a #GtkTreePath
  * @ancestor: another #GtkTreePath
  *
- *
+ * Returns %TRUE if @path is a descendant of @ancestor.
  *
  * Return value: %TRUE if @ancestor contains @path somewhere below it
  **/
@@ -481,7 +481,7 @@ gtk_tree_path_next (GtkTreePath *path)
  *
  * Moves the @path to point to the previous node at the current depth, if it exists.
  *
- * Return value: TRUE if @path has a previous node, and the move was made.
+ * Return value: %TRUE if @path has a previous node, and the move was made.
  **/
 gboolean
 gtk_tree_path_prev (GtkTreePath *path)
@@ -502,7 +502,7 @@ gtk_tree_path_prev (GtkTreePath *path)
  *
  * Moves the @path to point to it's parent node, if it has a parent.
  *
- * Return value: TRUE if @path has a parent, and the move was made.
+ * Return value: %TRUE if @path has a parent, and the move was made.
  **/
 gboolean
 gtk_tree_path_up (GtkTreePath *path)
@@ -537,10 +537,10 @@ gtk_tree_path_down (GtkTreePath *path)
  *
  * Creates a dynamically allocated tree iterator as a copy of @iter.  This
  * function is not intended for use in applications, because you can just copy
- * the structs by value (GtkTreeIter new_iter = iter;).  You
+ * the structs by value (<literal>GtkTreeIter new_iter = iter;</literal>).  You
  * must free this iter with gtk_tree_iter_free ().
  *
- * Return value: a newly allocated copy of @iter.
+ * Return value: a newly-allocated copy of @iter.
  **/
 GtkTreeIter *
 gtk_tree_iter_copy (GtkTreeIter *iter)
@@ -559,7 +559,7 @@ gtk_tree_iter_copy (GtkTreeIter *iter)
  * gtk_tree_iter_free:
  * @iter: A dynamically allocated tree iterator.
  *
- * Free an iterator that has been allocated on the heap.  This function is
+ * Frees an iterator that has been allocated on the heap.  This function is
  * mainly used for language bindings.
  **/
 void
@@ -595,7 +595,7 @@ gtk_tree_model_get_flags (GtkTreeModel *tree_model)
  * gtk_tree_model_get_n_columns:
  * @tree_model: A #GtkTreeModel.
  *
- * Returns the number of columns supported by the #tree_model
+ * Returns the number of columns supported by @tree_model.
  *
  * Return value: The number of columns.
  **/
@@ -636,7 +636,7 @@ gtk_tree_model_get_column_type (GtkTreeModel *tree_model,
  *
  * Sets @iter to a valid iterator pointing to @path.
  *
- * Return value: TRUE, if @iter was set.
+ * Return value: %TRUE, if @iter was set.
  **/
 gboolean
 gtk_tree_model_get_iter (GtkTreeModel *tree_model,
@@ -661,7 +661,7 @@ gtk_tree_model_get_iter (GtkTreeModel *tree_model,
  * Sets @iter to a valid iterator pointing to @path_string, if it
  * exists. Otherwise, @iter is left invalid and %FALSE is returned.
  *
- * Return value: TRUE, if @iter was set.
+ * Return value: %TRUE, if @iter was set.
  **/
 gboolean
 gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
@@ -691,10 +691,10 @@ gtk_tree_model_get_iter_from_string (GtkTreeModel *tree_model,
  * @tree_model: A #GtkTreeModel.
  * @iter: The uninitialized #GtkTreeIter.
  * 
- * Initialized @iter with the root iterator in the tree (the one at the root
+ * Initializes @iter with the root iterator in the tree (the one at the root
  * path) and returns %TRUE.   Returns %FALSE if the tree is empty.
  * 
- * Return value: TRUE, if @iter was set.
+ * Return value: %TRUE, if @iter was set.
  **/
 gboolean
 gtk_tree_model_get_iter_root (GtkTreeModel *tree_model,
@@ -718,10 +718,10 @@ gtk_tree_model_get_iter_root (GtkTreeModel *tree_model,
  * @tree_model: A #GtkTreeModel.
  * @iter: The #GtkTreeIter.
  *
- * Returns a newly created #GtkTreePath referenced by @iter.  This path should
- * be freed with #gtk_tree_path_free.
+ * Returns a newly-created #GtkTreePath referenced by @iter.  This path should
+ * be freed with gtk_tree_path_free().
  *
- * Return value: a newly created #GtkTreePath.
+ * Return value: a newly-created #GtkTreePath.
  **/
 GtkTreePath *
 gtk_tree_model_get_path (GtkTreeModel *tree_model,
@@ -742,7 +742,7 @@ gtk_tree_model_get_path (GtkTreeModel *tree_model,
  * @value: An empty #GValue to set.
  *
  * Sets initializes and sets @value to that at @column.  When done with @value,
- * #g_value_unset needs to be called to free any allocated memory.
+ * g_value_unset() needs to be called to free any allocated memory.
  **/
 void
 gtk_tree_model_get_value (GtkTreeModel *tree_model,
@@ -764,9 +764,9 @@ gtk_tree_model_get_value (GtkTreeModel *tree_model,
  * @iter: The #GtkTreeIter.
  *
  * Sets @iter to point to the node following it at the current level.  If there
- * is no next @iter, FALSE is returned and @iter is set to be invalid.
+ * is no next @iter, %FALSE is returned and @iter is set to be invalid.
  *
- * Return value: TRUE if @iter has been changed to the next node.
+ * Return value: %TRUE if @iter has been changed to the next node.
  **/
 gboolean
 gtk_tree_model_iter_next (GtkTreeModel  *tree_model,
@@ -786,10 +786,10 @@ gtk_tree_model_iter_next (GtkTreeModel  *tree_model,
  * @parent: The #GtkTreeIter.
  *
  * Sets @iter to point to the first child of @parent.  If @parent has no children,
- * FALSE is returned and @iter is set to be invalid.  @parent will remain a valid
+ * %FALSE is returned and @iter is set to be invalid.  @parent will remain a valid
  * node after this function has been called.
  *
- * Return value: TRUE, if @child has been set to the first child.
+ * Return value: %TRUE, if @child has been set to the first child.
  **/
 gboolean
 gtk_tree_model_iter_children (GtkTreeModel *tree_model,
@@ -808,9 +808,9 @@ gtk_tree_model_iter_children (GtkTreeModel *tree_model,
  * @tree_model: A #GtkTreeModel.
  * @iter: The #GtkTreeIter to test for children.
  *
- * Returns TRUE if @iter has children, FALSE otherwise.
+ * Returns %TRUE if @iter has children, %FALSE otherwise.
  *
- * Return value: TRUE if @iter has children.
+ * Return value: %TRUE if @iter has children.
  **/
 gboolean
 gtk_tree_model_iter_has_child (GtkTreeModel *tree_model,
@@ -826,10 +826,10 @@ gtk_tree_model_iter_has_child (GtkTreeModel *tree_model,
 /**
  * gtk_tree_model_iter_n_children:
  * @tree_model: A #GtkTreeModel.
- * @iter: The #GtkTreeIter, or NULL.
+ * @iter: The #GtkTreeIter, or %NULL.
  *
  * Returns the number of children that @iter has.  As a special case, if @iter
- * is NULL, then the number of toplevel nodes is returned.
+ * is %NULL, then the number of toplevel nodes is returned.
  *
  * Return value: The number of children of @iter.
  **/
@@ -847,16 +847,16 @@ gtk_tree_model_iter_n_children (GtkTreeModel *tree_model,
  * gtk_tree_model_iter_nth_child:
  * @tree_model: A #GtkTreeModel.
  * @iter: The #GtkTreeIter to set to the nth child.
- * @parent: The #GtkTreeIter to get the child from, or NULL.
+ * @parent: The #GtkTreeIter to get the child from, or %NULL.
  * @n: Then index of the desired child.
  *
  * Sets @iter to be the child of @parent, using the given index.  The first
  * index is 0.  If @index is too big, or @parent has no children, @iter is set
- * to an invalid iterator and FALSE is returned.  @parent will remain a valid
+ * to an invalid iterator and %FALSE is returned.  @parent will remain a valid
  * node after this function has been called.  As a special case, if @parent is
- * NULL, then the nth root node is set.
+ * %NULL, then the @n<!>th root node is set.
  *
- * Return value: TRUE, if @parent has an nth child.
+ * Return value: %TRUE, if @parent has an @n<!>th child.
  **/
 gboolean
 gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model,
@@ -879,11 +879,11 @@ gtk_tree_model_iter_nth_child (GtkTreeModel *tree_model,
  * @child: The #GtkTreeIter.
  *
  * Sets @iter to be the parent of @child.  If @child is at the toplevel, and
- * doesn't have a parent, then @iter is set to an invalid iterator and FALSE
+ * doesn't have a parent, then @iter is set to an invalid iterator and %FALSE
  * is returned.  @child will remain a valid node after this function has been
  * called.
  *
- * Return value: TRUE, if @iter is set to the parent of @child.
+ * Return value: %TRUE, if @iter is set to the parent of @child.
  **/
 gboolean
 gtk_tree_model_iter_parent (GtkTreeModel *tree_model,
@@ -910,7 +910,7 @@ gtk_tree_model_iter_parent (GtkTreeModel *tree_model,
  * This function is primarily meant as a way for views to let caching model know
  * when nodes are being displayed (and hence, whether or not to cache that
  * node.)  For example, a file-system based model would not want to keep the
- * entire file-heirarchy in memory, just the sections that are currently being
+ * entire file-hierarchy in memory, just the sections that are currently being
  * displayed by every current view.
  *
  * A model should be expected to be able to get an iter independent of it's
@@ -935,7 +935,7 @@ gtk_tree_model_ref_node (GtkTreeModel *tree_model,
  * implement.  To be more specific, models may ignore this call as it exists
  * primarily for performance reasons.
  *
- * For more information on what this means, please see #gtk_tree_model_ref_node.
+ * For more information on what this means, see gtk_tree_model_ref_node().
  * Please note that nodes that are deleted are not unreffed.
  **/
 void
@@ -961,7 +961,8 @@ gtk_tree_model_unref_node (GtkTreeModel *tree_model,
  * 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: <literal>gtk_tree_model_get (model, iter, 0, &amp;place_string_here, -1)</literal>,
- * where place_string_here is a gchar* to be filled with the string.
+ * where <literal>place_string_here</literal> is a <type>gchar*</type> to be 
+ * filled with the string.
  * If appropriate, the returned values have to be freed or unreferenced.
  *
  **/
@@ -984,10 +985,10 @@ gtk_tree_model_get (GtkTreeModel *tree_model,
  * gtk_tree_model_get_valist:
  * @tree_model: a #GtkTreeModel
  * @iter: a row in @tree_model
- * @var_args: va_list of column/return location pairs
+ * @var_args: <type>va_list</type> of column/return location pairs
  *
- * See gtk_tree_model_get(), this version takes a va_list for language bindings
- * to use.
+ * See gtk_tree_model_get(), this version takes a <type>va_list</type> 
+ * for language bindings to use.
  **/
 void
 gtk_tree_model_get_valist (GtkTreeModel *tree_model,
@@ -1113,6 +1114,18 @@ gtk_tree_model_row_deleted (GtkTreeModel *tree_model,
   g_signal_emit_by_name (tree_model, "row_deleted", path);
 }
 
+/**
+ * gtk_tree_model_rows_reordered:
+ * @tree_model: A #GtkTreeModel
+ * @path: A #GtkTreePath pointing to the tree node whose children have been reordered
+ * @iter: A valid #GtkTreeIter pointing to the node whose children have been reordered
+ * @new_order: an array of integers containing the new indices of the children,
+ *      i.e. the former child <literal>n</literal> is now at position
+ *      @new_order<literal>[n]</literal>. 
+ * 
+ * Emits the "rows_reordered" signal on @tree_model.  This should be called by
+ * models when their rows have been reordered.  
+ **/
 void
 gtk_tree_model_rows_reordered (GtkTreeModel *tree_model,
 			       GtkTreePath  *path,
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 7f8a4fb65..495022d37 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -4974,11 +4974,11 @@ gtk_widget_set_extension_events (GtkWidget *widget,
  * gtk_widget_get_toplevel() and check if the %TOPLEVEL flags
  * is set on the result.
  *  <informalexample><programlisting>
- *  GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
- *  if (GTK_WIDGET_TOPLEVEL (toplevel))
- *   {
- *     [ Perform action on toplevel. ]
- *   }
+ *  <!>GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
+ *  <!>if (GTK_WIDGET_TOPLEVEL (toplevel))
+ *  <!> {
+ *  <!>   [ Perform action on toplevel. ]
+ *  <!> }
  *  </programlisting></informalexample>
  *
  * Return value: the topmost ancestor of @widget, or @widget itself if there's no ancestor.
@@ -5286,13 +5286,13 @@ gtk_widget_get_composite_name (GtkWidget *widget)
  * 
  * Here is a simple example:
  * <informalexample><programlisting>
- *   gtk_widget_push_composite_child (<!>);
- *   scrolled_window->hscrollbar = gtk_hscrollbar_new (hadjustment);
- *   gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar");
- *   gtk_widget_pop_composite_child (<!>);
- *   gtk_widget_set_parent (scrolled_window->hscrollbar, 
- *                          GTK_WIDGET (scrolled_window));
- *   gtk_widget_ref (scrolled_window->hscrollbar);
+ * <!>  gtk_widget_push_composite_child (<!>);
+ * <!>  scrolled_window->hscrollbar = gtk_hscrollbar_new (hadjustment);
+ * <!>  gtk_widget_set_composite_name (scrolled_window->hscrollbar, "hscrollbar");
+ * <!>  gtk_widget_pop_composite_child (<!>);
+ * <!>  gtk_widget_set_parent (scrolled_window->hscrollbar, 
+ * <!>                         GTK_WIDGET (scrolled_window));
+ * <!>  gtk_widget_ref (scrolled_window->hscrollbar);
  * </programlisting></informalexample>
  **/
 void
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 7a5153e08..b96832dd2 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -1091,9 +1091,9 @@ gtk_window_add_accel_group (GtkWindow     *window,
 }
 
 /**
- * gtk_accel_group_detach:
+ * gtk_window_remove_accel_group:
+ * @window: a #GtkWindow
  * @accel_group: a #GtkAccelGroup
- * @object: a #GObject
  *
  * Reverses the effects of gtk_window_add_accel_group().
  **/