Mass fixing of trivial doc bugs. (#63544, #57007, #64141, #63472, #57108,

        * gtk/gtkiconfactory.c, gtk/gtktextbuffer.c, gtk/gtktreemodel.c,
        gtk/gtkwindow.c, gtk/gtknotebook.c, gtk/gtkradiobutton.c,
        gtk/gtktextiter.c, gtk/gtkdialog.c: Mass fixing of trivial doc bugs.
        (#63544, #57007, #64141, #63472, #57108, #60818, #61562)

        * gtk/tmpl/gtkaccellabel.sgml, gtk/tmpl/gtkcombo.sgml,
        gtk/tmpl/gtkentry.sgml, gtk/tmpl/gtkhscrollbar.sgml,
        gtk/tmpl/gtkvscrollbar.sgml, gtk/tmpl/gtktoolbar.sgml,
        gtk/tmpl/gtkdialog.sgml, gtk/tmpl/gtkstatusbar.sgml:
        Mass fixing of trivial doc bugs. (#55579, #56760, #58769, #55918,
        #64154, #60422, #54697)

8 files changed, 62 insertions, 64 deletions

diff --git a/docs/reference/gtk/tmpl/gtkaccellabel.sgml b/docs/reference/gtk/tmpl/gtkaccellabel.sgml
index 2c82003aa..a434252bb 100644
--- a/docs/reference/gtk/tmpl/gtkaccellabel.sgml
+++ b/docs/reference/gtk/tmpl/gtkaccellabel.sgml
@@ -30,7 +30,7 @@ automatically adds a #GtkAccelLabel to the #GtkMenuItem and calls
 gtk_accel_label_set_accel_widget() to set it up for you.
 </para>
 <para>
-A #GtkAccelLabel will only display accelerators which have GTK_ACCEL_VISIBLE
+A #GtkAccelLabel will only display accelerators which have %GTK_ACCEL_VISIBLE
 set (see #GtkAccelFlags).
 A #GtkAccelLabel can display multiple accelerators and even signal names,
 though it is almost always used to display just one accelerator key.
@@ -90,7 +90,7 @@ should be accessed using the functions below.
 Creates a new #GtkAccelLabel.
 </para>
 
-@string: the label string. Must be non-NULL.
+@string: the label string. Must be non-%NULL.
 @Returns: a new #GtkAccelLabel.
 
 
@@ -117,7 +117,7 @@ Creates a new #GtkAccelLabel.
 
 </para>
 
-@accel_label: 
+@accel_label:
 
 
 <!-- ##### MACRO gtk_accel_label_set_accel_widget ##### -->
@@ -137,7 +137,7 @@ be needed by applications.
 </para>
 
 @accel_label: a #GtkAccelLabel.
-@Returns: 
+@Returns: the width needed to display the accelerator key(s).
 
 
 <!-- ##### FUNCTION gtk_accel_label_refetch ##### -->
@@ -148,7 +148,7 @@ accelerators are added or removed from the associated widget.
 </para>
 
 @accel_label: a #GtkAccelLabel.
-@Returns: always returns FALSE.
+@Returns: always returns %FALSE.
 
 
 <!-- ##### ARG GtkAccelLabel:accel-object ##### -->
diff --git a/docs/reference/gtk/tmpl/gtkcombo.sgml b/docs/reference/gtk/tmpl/gtkcombo.sgml
index b4510f4af..8034f9cb7 100644
--- a/docs/reference/gtk/tmpl/gtkcombo.sgml
+++ b/docs/reference/gtk/tmpl/gtkcombo.sgml
@@ -137,12 +137,12 @@ the values in the list. If this is set then the user will not be able to
 perform any other action until a valid value has been entered.
 </para>
 <para>
-If an empty field is acceptable, the @ok_if_empty parameter should be TRUE.
+If an empty field is acceptable, the @ok_if_empty parameter should be %TRUE.
 </para>
 
 @combo: a #GtkCombo.
-@val: TRUE if the value entered must match one of the values in the list.
-@ok_if_empty: TRUE if an empty value is considered valid.
+@val: %TRUE if the value entered must match one of the values in the list.
+@ok_if_empty: %TRUE if an empty value is considered valid.
 
 
 <!-- ##### FUNCTION gtk_combo_set_use_arrows ##### -->
@@ -152,7 +152,7 @@ the list. This is on by default.
 </para>
 
 @combo: a #GtkCombo.
-@val: TRUE if the arrow keys can be used to step through the items in the list.
+@val: %TRUE if the arrow keys can be used to step through the items in the list.
 
 
 <!-- ##### FUNCTION gtk_combo_set_use_arrows_always ##### -->
@@ -162,7 +162,8 @@ Specifies if the arrow keys will still work even if the current contents of the
 </para>
 
 @combo: a #GtkCombo.
-@val: 
+@val: %TRUE if the arrow keys will still work even if the current contents of
+the #GtkEntry field do not match any of the list items.
 
 
 <!-- ##### FUNCTION gtk_combo_set_case_sensitive ##### -->
@@ -177,7 +178,7 @@ worried about differences in case.
 </para>
 
 @combo: a #GtkCombo.
-@val: 
+@val: %TRUE if the text in the list items is case sensitive. 
 
 
 <!-- ##### FUNCTION gtk_combo_set_item_string ##### -->
@@ -187,7 +188,7 @@ selected. This is needed if the list item is not a simple label.
 </para>
 
 @combo: a #GtkCombo.
-@item: a #GtkItem which
+@item: a #GtkItem.
 @item_value: the string to place in the #GtkEntry when @item is selected.
 
 
@@ -195,7 +196,7 @@ selected. This is needed if the list item is not a simple label.
 <para>
 Stops the #GtkCombo widget from showing the popup list when the #GtkEntry
 emits the "activate" signal, i.e. when the Return key is pressed.
-This may be useful if, for example. you want the Return key to close a dialog
+This may be useful if, for example, you want the Return key to close a dialog
 instead.
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtkdialog.sgml b/docs/reference/gtk/tmpl/gtkdialog.sgml
index 6f66e231f..f677af775 100644
--- a/docs/reference/gtk/tmpl/gtkdialog.sgml
+++ b/docs/reference/gtk/tmpl/gtkdialog.sgml
@@ -169,7 +169,7 @@ Creates a new dialog box. Widgets should not be packed into this #GtkWindow
 directly, but into the vbox and action_area, as described above. 
 </para>
 
-@Returns: a #GtkWidget - the newly created dialog box.
+@Returns: a new #GtkDialog. 
 
 
 <!-- ##### FUNCTION gtk_dialog_new_with_buttons ##### -->
diff --git a/docs/reference/gtk/tmpl/gtkentry.sgml b/docs/reference/gtk/tmpl/gtkentry.sgml
index 8182e99fd..ec1d13321 100644
--- a/docs/reference/gtk/tmpl/gtkentry.sgml
+++ b/docs/reference/gtk/tmpl/gtkentry.sgml
@@ -136,13 +136,17 @@ use gtk_editable_select_region() instead.
 <para>
 Sets whether the contents of the entry are visible or
 not. When visibility is set to %FALSE, characters
-are displayed as asterisks (*'s), and will also appear
+are displayed as the invisible char, and will also appear
 that way when the text in the entry widget is copied
 elsewhere.
 </para>
+<para>
+The default invisible char is the asterisk '*', but it can
+be changed with gtk_entry_set_invisible_char().
+</para>
 
 @entry: a #GtkEntry.
-@visible: %TRUE if the contents of the entry are displayd
+@visible: %TRUE if the contents of the entry are displayed
           as plaintext.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkhscrollbar.sgml b/docs/reference/gtk/tmpl/gtkhscrollbar.sgml
index f03991fbb..007c8cdd9 100644
--- a/docs/reference/gtk/tmpl/gtkhscrollbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkhscrollbar.sgml
@@ -7,11 +7,11 @@ A horizontal scrollbar
 <!-- ##### SECTION Long_Description ##### -->
 
 <para>
-The HScrollbar widget is a widget arranged horizontally creating a
-scroll bar. See #GtkScrollbar for details on
+The #GtkHScrollbar widget is a widget arranged horizontally creating a
+scrollbar. See #GtkScrollbar for details on
 scrollbars. #GtkAdjustment pointers may be added to handle the
-adjustment of the scrollbars or it may be left NULL in which case one
-will be created you. See #GtkAdjustment for details.
+adjustment of the scrollbar or it may be left %NULL in which case one
+will be created for you. See #GtkAdjustment for details.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -22,7 +22,7 @@ will be created you. See #GtkAdjustment for details.
 <!-- ##### STRUCT GtkHScrollbar ##### -->
 <para>
 The #GtkHScrollbar struct contains private data and should be accessed
-unsing the functions below.
+using the functions below.
 </para>
 
 
@@ -31,7 +31,7 @@ unsing the functions below.
 Creates a new horizontal scrollbar.
 </para>
 
-@adjustment: 
-@Returns: the new GTKHScrollbar
+@adjustment: the #GtkAdjustment to use, or %NULL to create a new adjustment.
+@Returns: the new #GtkHScrollbar.
 
 
diff --git a/docs/reference/gtk/tmpl/gtkstatusbar.sgml b/docs/reference/gtk/tmpl/gtkstatusbar.sgml
index 5865c8f96..3a195ad08 100644
--- a/docs/reference/gtk/tmpl/gtkstatusbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkstatusbar.sgml
@@ -11,7 +11,7 @@ A #GtkStatusbar is usually placed along the bottom of an application's main
 (as is usually the case in a web browser, for example), or may be used to
 simply output a message when the status changes, (when an upload is complete
 in an FTP client, for example). 
-It may also have a resize grip (a triangular area in the lower left corner) 
+It may also have a resize grip (a triangular area in the lower right corner) 
 which can be clicked on to resize the window containing the statusbar.
 </para>
 <para>
@@ -78,7 +78,7 @@ Pushes a new message onto a statusbar's stack.
 
 @statusbar: a #GtkStatusbar.
 @context_id: the message's context id, as returned by
-gkt_statusbar_get_context_id().
+gtk_statusbar_get_context_id().
 @text: the message to add to the statusbar.
 @Returns: the message's new message id for use with gtk_statusbar_remove().
 
@@ -94,7 +94,7 @@ Removes the message at the top of a #GtkStatusBar's stack.
 
 <!-- ##### FUNCTION gtk_statusbar_remove ##### -->
 <para>
-Forces the removal of a message from a statusbar's stack. The exact context_id and message_id must be specified.
+Forces the removal of a message from a statusbar's stack. The exact @context_id and @message_id must be specified.
 </para>
 
 @statusbar: a #GtkStatusBar.
diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml
index 0ef0ffd00..9ee5eb854 100644
--- a/docs/reference/gtk/tmpl/gtktoolbar.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml
@@ -15,7 +15,7 @@ Buttons with text and/or images are added with gtk_toolbar_append_item(), gtk_to
 Any of #GtkToggleButton, #GtkRadioButton, or an arbitrary widget can be added to the toolbar with gtk_toolbar_append_element(), gtk_toolbar_prepend_element(), and gtk_toolbar_insert_element().
 </para>
 <para>
-Widgets can be visibily grouped by adding gaps between widgets using gtk_toolbar_append_space(), gtk_toolbar_prepend_space, and gtk_toolbar_insert_space().
+Widgets can be visibly grouped by adding gaps between widgets using gtk_toolbar_append_space(), gtk_toolbar_prepend_space(), and gtk_toolbar_insert_space().
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -43,17 +43,15 @@ Widgets can be visibily grouped by adding gaps between widgets using gtk_toolbar
 
 <!-- ##### ENUM GtkToolbarChildType ##### -->
 <para>
-is used to set the type of new elements that are added to a #GtkToolbar.
-</para>
-<para>
-SPACE is just a space in the style of the toolbar's GtkToolbarSpaceStyle. BUTTON denotes a #GtkButton. TOGGLEBUTTON denotes a #GtkToggleButton, RADIOBUTTON denotes a #GtkRadioButton, and WIDGET denotes a standard #GtkWidget.
+#GtkToolbarChildType is used to set the type of new elements that are added 
+to a #GtkToolbar.
 </para>
 
-@GTK_TOOLBAR_CHILD_SPACE: 
-@GTK_TOOLBAR_CHILD_BUTTON: 
-@GTK_TOOLBAR_CHILD_TOGGLEBUTTON: 
-@GTK_TOOLBAR_CHILD_RADIOBUTTON: 
-@GTK_TOOLBAR_CHILD_WIDGET: 
+@GTK_TOOLBAR_CHILD_SPACE: a space in the style of the toolbar's #GtkToolbarSpaceStyle. 
+@GTK_TOOLBAR_CHILD_BUTTON: a #GtkButton. 
+@GTK_TOOLBAR_CHILD_TOGGLEBUTTON: a #GtkToggleButton.
+@GTK_TOOLBAR_CHILD_RADIOBUTTON: a #GtkRadioButton.
+@GTK_TOOLBAR_CHILD_WIDGET: a standard #GtkWidget.
 
 <!-- ##### ENUM GtkToolbarSpaceStyle ##### -->
 <para>
@@ -75,18 +73,15 @@ SPACE is just a space in the style of the toolbar's GtkToolbarSpaceStyle. BUTTON
 
 <!-- ##### FUNCTION gtk_toolbar_new ##### -->
 <para>
-creates a new toolbar. 
+Creates a new toolbar. 
 </para>
 
-@Returns: the newly created toolbar.
-<!-- # Unused Parameters # -->
-@orientation: a #GtkOrientation. It determines whether the toolbar appears horizontally or vertically.
-@style: a #GtkToolbarStyle. It determines if the toolbar will contain buttons with just labels, just images, or both.
+@Returns: the newly-created toolbar.
 
 
 <!-- ##### FUNCTION gtk_toolbar_append_item ##### -->
 <para>
-adds a new button to the end (right or bottom edges) of the given toolbar.
+Adds a new button to the end (right or bottom edges) of the given toolbar.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -101,7 +96,7 @@ adds a new button to the end (right or bottom edges) of the given toolbar.
 
 <!-- ##### FUNCTION gtk_toolbar_prepend_item ##### -->
 <para>
-adds a new button to the beginning (top or left edges) of the given toolbar.
+Adds a new button to the beginning (top or left edges) of the given toolbar.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -116,7 +111,7 @@ adds a new button to the beginning (top or left edges) of the given toolbar.
 
 <!-- ##### FUNCTION gtk_toolbar_insert_item ##### -->
 <para>
-inserts a new item into the toolbar. You must specify the position in the toolbar where it will be inserted.
+Inserts a new item into the toolbar. You must specify the position in the toolbar where it will be inserted.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -132,7 +127,7 @@ inserts a new item into the toolbar. You must specify the position in the toolba
 
 <!-- ##### FUNCTION gtk_toolbar_append_space ##### -->
 <para>
-adds a new space to the end of the toolbar.
+Adds a new space to the end of the toolbar.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -140,7 +135,7 @@ adds a new space to the end of the toolbar.
 
 <!-- ##### FUNCTION gtk_toolbar_prepend_space ##### -->
 <para>
-adds a new space to the beginning of the toolbar.
+Adds a new space to the beginning of the toolbar.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -148,7 +143,7 @@ adds a new space to the beginning of the toolbar.
 
 <!-- ##### FUNCTION gtk_toolbar_insert_space ##### -->
 <para>
-inserts a new space in the toolbar at the specified position.
+Inserts a new space in the toolbar at the specified position.
 </para>
 
 @toolbar: a #GtkToolbar
@@ -157,7 +152,7 @@ inserts a new space in the toolbar at the specified position.
 
 <!-- ##### FUNCTION gtk_toolbar_append_element ##### -->
 <para>
-adds a new element to the end of a toolbar.
+Adds a new element to the end of a toolbar.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -174,7 +169,7 @@ adds a new element to the end of a toolbar.
 
 <!-- ##### FUNCTION gtk_toolbar_prepend_element ##### -->
 <para>
-adds a new element to the beginning of a toolbar.
+Adds a new element to the beginning of a toolbar.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -243,7 +238,7 @@ adds a new element to the beginning of a toolbar.
 
 <!-- ##### FUNCTION gtk_toolbar_set_orientation ##### -->
 <para>
-sets whether a toolbar should appear horizontally or vertically.
+Sets whether a toolbar should appear horizontally or vertically.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -252,7 +247,7 @@ sets whether a toolbar should appear horizontally or vertically.
 
 <!-- ##### FUNCTION gtk_toolbar_set_style ##### -->
 <para>
-alters the view of @toolbar to display either icons only, text only, or both.
+Alters the view of @toolbar to display either icons only, text only, or both.
 </para>
 
 @toolbar: a #GtkToolbar.
@@ -261,11 +256,11 @@ alters the view of @toolbar to display either icons only, text only, or both.
 
 <!-- ##### FUNCTION gtk_toolbar_set_tooltips ##### -->
 <para>
-sets if the tooltips of a toolbar should be active or not.
+Sets if the tooltips of a toolbar should be active or not.
 </para>
 
 @toolbar: a #GtkToolbar.
-@enable: set to 0 to disable the tooltips, or 1 to enable them.
+@enable: set to %FALSE to disable the tooltips, or %TRUE to enable them.
 
 
 <!-- ##### FUNCTION gtk_toolbar_insert_stock ##### -->
@@ -290,8 +285,6 @@ sets if the tooltips of a toolbar should be active or not.
 
 @toolbar: 
 @icon_size: 
-<!-- # Unused Parameters # -->
-@stock_size: 
 
 
 <!-- ##### FUNCTION gtk_toolbar_get_icon_size ##### -->
@@ -357,7 +350,7 @@ sets if the tooltips of a toolbar should be active or not.
 
 <!-- ##### SIGNAL GtkToolbar::orientation-changed ##### -->
 <para>
-should be used if you wish to perform an action when the orientation of a toolbar is changed.
+Should be used if you wish to perform an action when the orientation of a toolbar is changed.
 </para>
 
 @toolbar: the object which received the signal.
@@ -365,7 +358,7 @@ should be used if you wish to perform an action when the orientation of a toolba
 
 <!-- ##### SIGNAL GtkToolbar::style-changed ##### -->
 <para>
-should be used if you wish to perform an action when ever the style of a toolbar is adjusted. For example, this would be a useful signal to connect to if you want to display more items on the toolbar when it is in icon-only mode; each item takes less space on the bar.
+Should be used if you wish to perform an action when ever the style of a toolbar is adjusted. For example, this would be a useful signal to connect to if you want to display more items on the toolbar when it is in icon-only mode; each item takes less space on the bar.
 </para>
 
 @toolbar: the object which received the signal.
diff --git a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml
index 36837e20e..738114997 100644
--- a/docs/reference/gtk/tmpl/gtkvscrollbar.sgml
+++ b/docs/reference/gtk/tmpl/gtkvscrollbar.sgml
@@ -6,15 +6,15 @@ A vertical scrollbar
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-The VScrollbar widget is a widget arranged vertically creating a scroll bar. See
-#GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be added to
-handle the adjustment of the scrollbars or it may be left NULL in which case one
-will be created you. See #GtkAdjustment for details.
+The #GtkVScrollbar widget is a widget arranged vertically creating a scrollbar.
+See #GtkScrollbar for details on scrollbars. #GtkAdjustment pointers may be 
+added to handle the adjustment of the scrollbar or it may be left %NULL in which
+case one will be created for you. See #GtkAdjustment for details.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkScrollbar, #GtkScrolledWindow
 </para>
 
 <!-- ##### STRUCT GtkVScrollbar ##### -->
@@ -29,7 +29,7 @@ using the functions below.
 Creates a new vertical scrollbar.
 </para>
 
-@adjustment: 
-@Returns: the new GTKVScrollbar
+@adjustment: the #GtkAdjustment to use, or %NULL to create a new adjustment.
+@Returns: the new #GtkVScrollbar