Doc fixes

svn path=/trunk/; revision=20887

10 files changed, 62 insertions, 20 deletions

diff --git a/ChangeLog b/ChangeLog
index c3aeac9da..38e12ddb3 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,15 @@
+2008-07-21  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtktestutils.c:
+	* gtk/gtkscalebutton.c:
+	* gtk/gtkmessagedialog.c:
+	* gtk/gtkmenu.c:
+	* gtk/gtkcontainer.c:
+	* gtk/gtkcolorseldialog.c:
+	* gtk/gtkaccelgroup.c:
+	* gtk/gtkentry.c:
+	* gtk/gtkfontsel.c: Fix some doc problems.
+
 2008-07-21  Michael Natterer  <mitch@imendio.com>
 
 	* gtk/gtkbox.c (gtk_box_add): use gtk_box_pack_start() instead of
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 0dbf810c7..0e0457f5c 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -220,12 +220,12 @@ gtk_accel_group_new (void)
  * gtk_accel_group_get_is_locked:
  * @accel_group: a #GtkAccelGroup
  *
- * @returns: %TRUE if there are 1 or more locks on the @accel_group,
- * %FALSE otherwise.
- *
  * Locks are added and removed using gtk_accel_group_lock() and
  * gtk_accel_group_unlock().
  *
+ * Returns: %TRUE if there are 1 or more locks on the @accel_group,
+ * %FALSE otherwise.
+ *
  * Since: 2.14
  */
 gboolean
@@ -240,9 +240,11 @@ gtk_accel_group_get_is_locked (GtkAccelGroup *accel_group)
  * gtk_accel_group_get_modifier_mask:
  * @accel_group: a #GtkAccelGroup
  *
- * @returns: #GdkModifierType representing the mask for this
+ * Gets a #GdkModifierType representing the mask for this
  * @accel_group. For example, #GDK_CONTROL_MASK, #GDK_SHIFT_MASK, etc.
  *
+ * Returns: the modifier mask for this accel group.
+ *
  * Since: 2.14
  */
 GdkModifierType
diff --git a/gtk/gtkcolorseldialog.c b/gtk/gtkcolorseldialog.c
index be36d7b78..8c8b55f54 100644
--- a/gtk/gtkcolorseldialog.c
+++ b/gtk/gtkcolorseldialog.c
@@ -193,6 +193,8 @@ gtk_color_selection_dialog_new (const gchar *title)
  *
  * Retrieves the #GtkColorSelection widget embedded in the dialog.
  *
+ * Returns: the embedded #GtkColorSelection
+ *
  * Since: 2.14
  **/
 GtkWidget*
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 19fe7c0c2..4a82b3ea1 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1541,9 +1541,9 @@ gtk_container_foreach_full (GtkContainer       *container,
 /**
  * gtk_container_set_focus_child:
  * @container: a #GtkContainer
- * @widget: a #GtkWidget, or %NULL
+ * @child: a #GtkWidget, or %NULL
  *
- * Sets, or unsets if @widget is %NULL, the focused child of @container.
+ * Sets, or unsets if @child is %NULL, the focused child of @container.
  *
  * This function emits the GtkContainer::set_focus_child signal of
  * @container. Implementations of #GtkContainer can override the
@@ -1551,13 +1551,13 @@ gtk_container_foreach_full (GtkContainer       *container,
  */
 void
 gtk_container_set_focus_child (GtkContainer *container,
-			       GtkWidget    *widget)
+			       GtkWidget    *child)
 {
   g_return_if_fail (GTK_IS_CONTAINER (container));
-  if (widget)
-    g_return_if_fail (GTK_IS_WIDGET (widget));
+  if (child)
+    g_return_if_fail (GTK_IS_WIDGET (child));
 
-  g_signal_emit (container, container_signals[SET_FOCUS_CHILD], 0, widget);
+  g_signal_emit (container, container_signals[SET_FOCUS_CHILD], 0, child);
 }
 
 /**
diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index 286b3ca07..0919c8648 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -4671,7 +4671,7 @@ gtk_entry_set_editable (GtkEntry *entry,
 /**
  * gtk_entry_set_overwrite_mode:
  * @entry: a #GtkEntry
- * @setting: new value
+ * @overwrite: new value
  * 
  * Sets whether the text is overwritten when typing in the #GtkEntry.
  *
@@ -4679,11 +4679,11 @@ gtk_entry_set_editable (GtkEntry *entry,
  **/
 void
 gtk_entry_set_overwrite_mode (GtkEntry *entry,
-                              gboolean  setting)
+                              gboolean  overwrite)
 {
   g_return_if_fail (GTK_IS_ENTRY (entry));
   
-  if (entry->overwrite_mode == setting) 
+  if (entry->overwrite_mode == overwrite) 
     return;
   
   gtk_entry_toggle_overwrite (entry);
diff --git a/gtk/gtkfontsel.c b/gtk/gtkfontsel.c
index a74a52b17..97dbcab90 100644
--- a/gtk/gtkfontsel.c
+++ b/gtk/gtkfontsel.c
@@ -1257,6 +1257,8 @@ gtk_font_selection_get_preview_entry (GtkFontSelection *fontsel)
  * gtk_font_selection_get_family:
  * @fontsel: a #GtkFontSelection
  * 
+ * Gets the #PangoFontFamily representing the selected font family.
+ *
  * Return value: A #PangoFontFamily representing the selected font
  * family. Font families are a collection of font faces.
  *
@@ -1274,9 +1276,12 @@ gtk_font_selection_get_family (GtkFontSelection *fontsel)
  * gtk_font_selection_get_face:
  * @fontsel: a #GtkFontSelection
  * 
- * Return value: A #PangoFontFace representing the selected font group
+ * Gets the #PangoFontFace representing the selected font group
  * details (i.e. family, slant, weight, width, etc).   
  *
+ * Return value: A #PangoFontFace representing the selected font group
+ *     details 
+ *
  * Since: 2.14
  **/
 PangoFontFace *
@@ -1291,6 +1296,8 @@ gtk_font_selection_get_face (GtkFontSelection *fontsel)
  * gtk_font_selection_get_size:
  * @fontsel: a #GtkFontSelection
  * 
+ * The selected font size.
+ *
  * Return value: A #gint representing the font size selected, or -1
  * if not.
  *
@@ -1602,6 +1609,8 @@ gtk_font_selection_dialog_new (const gchar *title)
  * gtk_font_selection_dialog_get_ok_button:
  * @fsd: a #GtkFontSelectionDialog
  *
+ * Gets the 'OK' button.
+ *
  * Return value: the #GtkWidget used in the dialog for the 'OK' button.
  *
  * Since: 2.14
@@ -1618,6 +1627,8 @@ gtk_font_selection_dialog_get_ok_button (GtkFontSelectionDialog *fsd)
  * gtk_font_selection_dialog_get_apply_button:
  * @fsd: a #GtkFontSelectionDialog
  *
+ * Gets the 'Apply' button.
+ *
  * Return value: the #GtkWidget used in the dialog for the 'Apply' button.
  *
  * Since: 2.14
@@ -1631,9 +1642,11 @@ gtk_font_selection_dialog_get_apply_button (GtkFontSelectionDialog *fsd)
 }
 
 /**
- * gtk_font_selection_dialog_get_apply_button:
+ * gtk_font_selection_dialog_get_cancel_button:
  * @fsd: a #GtkFontSelectionDialog
  *
+ * Gets the 'Cancel' button.
+ *
  * Return value: the #GtkWidget used in the dialog for the 'Cancel' button.
  */
 GtkWidget *
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index 79caf7e3e..d8c2e33d9 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -1785,6 +1785,8 @@ gtk_menu_set_accel_path (GtkMenu     *menu,
  *
  * Retrieves the accelerator path set on the menu.
  *
+ * Returns: the accelerator path set on the menu.
+ *
  * Since: 2.14
  */
 const gchar*
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index ba6526205..dc6c57f1e 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -647,6 +647,8 @@ gtk_message_dialog_set_image (GtkMessageDialog *dialog,
  * gtk_message_dialog_get_image:
  * @dialog: a #GtkMessageDialog
  *
+ * Gets the dialog's image.
+ *
  * Return value: the dialog's image
  *
  * Since: 2.14
diff --git a/gtk/gtkscalebutton.c b/gtk/gtkscalebutton.c
index 27b9be450..ac491e6b7 100644
--- a/gtk/gtkscalebutton.c
+++ b/gtk/gtkscalebutton.c
@@ -764,6 +764,8 @@ gtk_scale_button_set_orientation (GtkScaleButton *button,
  *
  * Retrieves the plus button of the #GtkScaleButton.
  *
+ * Returns: the plus button of the #GtkScaleButton.
+ *
  * Since: 2.14
  */
 GtkWidget *
@@ -780,6 +782,8 @@ gtk_scale_button_get_plus_button (GtkScaleButton *button)
  *
  * Retrieves the minus button of the #GtkScaleButton.
  *
+ * Returns: the minus button of the #GtkScaleButton.
+ *
  * Since: 2.14
  */
 GtkWidget *
diff --git a/gtk/gtktestutils.c b/gtk/gtktestutils.c
index 966f1d191..5788c2830 100644
--- a/gtk/gtktestutils.c
+++ b/gtk/gtktestutils.c
@@ -40,13 +40,16 @@
  * @argvp: Address of the <parameter>argv</parameter> parameter of main().
  *        Any parameters understood by g_test_init() or gtk_init() are
  *        stripped before return.
+ * @Varargs: currently unused
+ *
+ * This function is used to initialize a GTK+ test program.
  *
- * This function is used to initialize a Gtk+ test program.
  * It will in turn call g_test_init() and gtk_init() to properly
- * initialize the testing framework and graphical toolkit.
- * It'll also set the program's locale to "C" and prevent loading of
- * rc files and Gtk+ modules. This is done to make tets program
+ * initialize the testing framework and graphical toolkit. It'll 
+ * also set the program's locale to "C" and prevent loading of rc 
+ * files and Gtk+ modules. This is done to make tets program
  * environments as deterministic as possible.
+ *
  * Like gtk_init() and g_test_init(), any known arguments will be
  * processed and stripped from @argc and @argv.
  **/
@@ -456,8 +459,10 @@ gtk_test_text_get (GtkWidget *widget)
 
 /**
  * gtk_test_create_widget
- * @widget_type:        valid widget type.
+ * @widget_type: a valid widget type.
  * @first_property_name: Name of first property to set or %NULL
+ * @Varags: value to set the first property to, followed by more
+ *    name-value pairs, terminated by %NULL
  *
  * This function wraps g_object_new() for widget types.
  * It'll automatically show all created non window widgets, also