Documentation fixes

Mostly making sure that return values and varargs don't loose
their docs.

33 files changed, 194 insertions, 164 deletions

diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index e5a0890721..6ee269d954 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -903,6 +903,7 @@ gtk_container_child_get_property
 gtk_container_child_set_property
 gtk_container_child_get_valist
 gtk_container_child_set_valist
+gtk_container_child_notify
 gtk_container_forall
 gtk_container_get_border_width
 gtk_container_set_border_width
diff --git a/gdk/gdkscreen.c b/gdk/gdkscreen.c
index ebdf2c64d9..c1de0f64e9 100644
--- a/gdk/gdkscreen.c
+++ b/gdk/gdkscreen.c
@@ -287,13 +287,14 @@ gdk_screen_get_monitor_at_point (GdkScreen *screen,
  * gdk_screen_get_monitor_at_window:
  * @screen: a #GdkScreen.
  * @window: a #GdkWindow
- * @returns: the monitor number in which most of @window is located,
- *           or if @window does not intersect any monitors, a monitor,
- *           close to @window.
  *
- * Returns the number of the monitor in which the largest area of the 
+ * Returns the number of the monitor in which the largest area of the
  * bounding rectangle of @window resides.
  *
+ * Returns: the monitor number in which most of @window is located,
+ *     or if @window does not intersect any monitors, a monitor,
+ *     close to @window.
+ *
  * Since: 2.2
  **/
 gint 
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index e015895dbf..65ddfa08f1 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -2483,7 +2483,7 @@ close_cb (GtkAboutDialog *about)
  * gtk_show_about_dialog:
  * @parent: (allow-none): transient parent, or %NULL for none
  * @first_property_name: the name of the first property
- * @Varargs: value of first property, followed by more properties, %NULL-terminated
+ * @...: value of first property, followed by more properties, %NULL-terminated
  *
  * This is a convenience function for showing an application's about box.
  * The constructed dialog is associated with the parent window and
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index b9592585b6..7631ece85a 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -242,9 +242,10 @@ gtk_accel_group_init (GtkAccelGroup *accel_group)
 
 /**
  * gtk_accel_group_new:
- * @returns: a new #GtkAccelGroup object
  *
  * Creates a new #GtkAccelGroup.
+ *
+ * Returns: a new #GtkAccelGroup object
  */
 GtkAccelGroup*
 gtk_accel_group_new (void)
@@ -380,11 +381,12 @@ gtk_accel_groups_from_object (GObject *object)
  * @find_func: (scope call): a function to filter the entries
  *    of @accel_group with
  * @data: data to pass to @find_func
- * @returns: (transfer none): 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.
+ *
+ * Returns: (transfer none): the key of the first entry passing
+ *    @find_func. The key is owned by GTK+ and must not be freed.
  */
 GtkAccelKey*
 gtk_accel_group_find (GtkAccelGroup         *accel_group,
@@ -702,12 +704,13 @@ gtk_accel_group_connect_by_path (GtkAccelGroup *accel_group,
  * @accel_group: the accelerator group to remove an accelerator from
  * @closure: (allow-none): the closure to remove from this accelerator
  *     group, or %NULL to remove all closures
- * @returns: %TRUE if the closure was found and got disconnected
  *
  * Removes an accelerator previously installed through
  * gtk_accel_group_connect().
  *
  * Since 2.20 @closure can be %NULL.
+ *
+ * Returns: %TRUE if the closure was found and got disconnected
  */
 gboolean
 gtk_accel_group_disconnect (GtkAccelGroup *accel_group,
@@ -733,11 +736,12 @@ gtk_accel_group_disconnect (GtkAccelGroup *accel_group,
  * @accel_group: the accelerator group to install an accelerator in
  * @accel_key: key value of the accelerator
  * @accel_mods: modifier combination of the accelerator
- * @returns: %TRUE if there was an accelerator which could be
- *     removed, %FALSE otherwise
  *
  * Removes an accelerator previously installed through
  * gtk_accel_group_connect().
+ *
+ * Returns: %TRUE if there was an accelerator which could be
+ *     removed, %FALSE otherwise
  */
 gboolean
 gtk_accel_group_disconnect_key (GtkAccelGroup   *accel_group,
@@ -823,12 +827,13 @@ _gtk_accel_group_get_accelerables (GtkAccelGroup *accel_group)
  * @accel_mods: modifier combination of the accelerator
  * @n_entries: (allow-none): location to return the number
  *     of entries found, or %NULL
- * @returns: (transfer none) (array length=n_entries): an array of
- *     @n_entries #GtkAccelGroupEntry elements, or %NULL. The array
- *     is owned by GTK+ and must not be freed.
  *
  * Queries an accelerator group for all entries matching @accel_key
  * and @accel_mods.
+ *
+ * Returns: (transfer none) (array length=n_entries): an array of
+ *     @n_entries #GtkAccelGroupEntry elements, or %NULL. The array
+ *     is owned by GTK+ and must not be freed.
  */
 GtkAccelGroupEntry*
 gtk_accel_group_query (GtkAccelGroup   *accel_group,
@@ -852,11 +857,12 @@ gtk_accel_group_query (GtkAccelGroup   *accel_group,
 /**
  * gtk_accel_group_from_accel_closure:
  * @closure: a #GClosure
- * @returns: (transfer none): the #GtkAccelGroup to which @closure
- *     is connected, or %NULL
  *
  * Finds the #GtkAccelGroup to which @closure is connected;
  * see gtk_accel_group_connect().
+ *
+ * Returns: (transfer none): the #GtkAccelGroup to which @closure
+ *     is connected, or %NULL
  */
 GtkAccelGroup*
 gtk_accel_group_from_accel_closure (GClosure *closure)
@@ -957,13 +963,14 @@ gtk_accel_groups_activate (GObject         *object,
  * gtk_accelerator_valid:
  * @keyval: a GDK keyval
  * @modifiers: modifier mask
- * @returns: %TRUE if the accelerator is valid
  *
  * Determines whether a given keyval and modifier mask constitute
  * a valid keyboard accelerator. For example, the #GDK_KEY_a keyval
  * plus #GDK_CONTROL_MASK is valid - this is a "Ctrl+a" accelerator.
  * But, you can't, for instance, use the #GDK_KEY_Control_L keyval
  * as an accelerator.
+ *
+ * Returns: %TRUE if the accelerator is valid
  */
 gboolean
 gtk_accelerator_valid (guint           keyval,
@@ -1469,9 +1476,10 @@ gtk_accelerator_set_default_mod_mask (GdkModifierType default_mod_mask)
 
 /**
  * gtk_accelerator_get_default_mod_mask:
- * @returns: the default accelerator modifier mask
  *
  * Gets the value set by gtk_accelerator_set_default_mod_mask().
+ *
+ * Returns: the default accelerator modifier mask
  */
 GdkModifierType
 gtk_accelerator_get_default_mod_mask (void)
diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c
index dd54214461..0c96cdca74 100644
--- a/gtk/gtkaccelmap.c
+++ b/gtk/gtkaccelmap.c
@@ -260,9 +260,10 @@ gtk_accel_map_add_entry (const gchar    *accel_path,
  * gtk_accel_map_lookup_entry:
  * @accel_path: a valid accelerator path
  * @key: (allow-none) (out): 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.
+ *
+ * Returns: %TRUE if @accel_path is known, %FALSE otherwise
  */
 gboolean
 gtk_accel_map_lookup_entry (const gchar *accel_path,
@@ -485,7 +486,6 @@ internal_change_entry (const gchar    *accel_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
  *
  * 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,
@@ -493,10 +493,12 @@ internal_change_entry (const gchar    *accel_path,
  * conflicts. A change will only occur if all conflicts could be resolved (which
  * might not be the case if conflicting accelerators are locked). Successful
  * changes are indicated by a %TRUE return value.
- * 
+ *
  * Note that @accel_path string will be stored in a #GQuark. Therefore, if you
- * pass a static string, you can save some memory by interning it first with 
+ * pass a static string, you can save some memory by interning it first with
  * g_intern_static_string().
+ *
+ * Returns: %TRUE if the accelerator could be changed, %FALSE otherwise
  */
 gboolean
 gtk_accel_map_change_entry (const gchar    *accel_path,
diff --git a/gtk/gtkbindings.c b/gtk/gtkbindings.c
index 15916f3abc..9b2e67b4bd 100644
--- a/gtk/gtkbindings.c
+++ b/gtk/gtkbindings.c
@@ -993,7 +993,7 @@ _gtk_binding_entry_add_signall (GtkBindingSet  *binding_set,
  * @modifiers:   key modifier of binding to install
  * @signal_name: signal to execute upon activation
  * @n_args:      number of arguments to @signal_name
- * @Varargs:     arguments to @signal_name
+ * @...:         arguments to @signal_name
  *
  * Override or install a new key binding for @keyval with @modifiers on
  * @binding_set. When the binding is activated, @signal_name will be
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index d48eea49fc..ef9b7d7127 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -1135,14 +1135,15 @@ gtk_button_new_from_stock (const gchar *stock_id)
  * gtk_button_new_with_mnemonic:
  * @label: The text of the button, with an underscore in front of the
  *         mnemonic character
- * @returns: a new #GtkButton
  *
  * Creates a new #GtkButton containing a label.
  * If characters in @label are preceded by an underscore, they are underlined.
- * If you need a literal underscore character in a label, use '__' (two 
- * underscores). The first underlined character represents a keyboard 
+ * If you need a literal underscore character in a label, use '__' (two
+ * underscores). The first underlined character represents a keyboard
  * accelerator called a mnemonic.
  * Pressing Alt and that key activates the button.
+ *
+ * Returns: a new #GtkButton
  **/
 GtkWidget*
 gtk_button_new_with_mnemonic (const gchar *label)
diff --git a/gtk/gtkcellarea.c b/gtk/gtkcellarea.c
index 7ef6cc9364..590d492644 100644
--- a/gtk/gtkcellarea.c
+++ b/gtk/gtkcellarea.c
@@ -2493,8 +2493,8 @@ gtk_cell_area_class_list_cell_properties (GtkCellAreaClass  *aclass,
  * @area: a #GtkCellArea
  * @renderer: a #GtkCellRenderer to be placed inside @area
  * @first_prop_name: the name of the first cell property to set
- * @Varargs: a %NULL-terminated list of property names and values, starting
- *           with @first_prop_name
+ * @...: a %NULL-terminated list of property names and values, starting
+ *     with @first_prop_name
  *
  * Adds @renderer to @area, setting cell properties at the same time.
  * See gtk_cell_area_add() and gtk_cell_area_cell_set() for more details.
@@ -2534,7 +2534,7 @@ gtk_cell_area_add_with_properties (GtkCellArea        *area,
  * @area: a #GtkCellArea
  * @renderer: a #GtkCellRenderer which is a cell inside @area
  * @first_prop_name: the name of the first cell property to set
- * @Varargs: a %NULL-terminated list of property names and values, starting
+ * @...: a %NULL-terminated list of property names and values, starting
  *           with @first_prop_name
  *
  * Sets one or more cell properties for @cell in @area.
@@ -2562,7 +2562,7 @@ gtk_cell_area_cell_set (GtkCellArea        *area,
  * @area: a #GtkCellArea
  * @renderer: a #GtkCellRenderer which is inside @area
  * @first_prop_name: the name of the first cell property to get
- * @Varargs: return location for the first cell property, followed
+ * @...: return location for the first cell property, followed
  *     optionally by more name/return location pairs, followed by %NULL
  *
  * Gets the values of one or more cell properties for @renderer in @area.
diff --git a/gtk/gtkcelllayout.c b/gtk/gtkcelllayout.c
index 3fd59ade6b..d3870a0526 100644
--- a/gtk/gtkcelllayout.c
+++ b/gtk/gtkcelllayout.c
@@ -449,7 +449,7 @@ gtk_cell_layout_set_attributesv (GtkCellLayout   *cell_layout,
  * gtk_cell_layout_set_attributes:
  * @cell_layout: a #GtkCellLayout
  * @cell: a #GtkCellRenderer
- * @Varargs: a %NULL-terminated list of attributes
+ * @...: a %NULL-terminated list of attributes
  *
  * Sets the attributes in list as the attributes of @cell_layout.
  *
diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index 142afe3645..ac19714535 100644
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -147,12 +147,13 @@ gtk_check_button_new_with_label (const gchar *label)
  * gtk_check_button_new_with_mnemonic:
  * @label: The text of the button, with an underscore in front of the
  *   mnemonic character
- * @returns: a new #GtkCheckButton
  *
  * Creates a new #GtkCheckButton containing a label. The label
  * will be created using gtk_label_new_with_mnemonic(), so underscores
  * in @label indicate the mnemonic for the check button.
- **/
+ *
+ * Returns: a new #GtkCheckButton
+ */
 GtkWidget*
 gtk_check_button_new_with_mnemonic (const gchar *label)
 {
diff --git a/gtk/gtkcheckmenuitem.c b/gtk/gtkcheckmenuitem.c
index 5c6f5f0801..a3e97febd6 100644
--- a/gtk/gtkcheckmenuitem.c
+++ b/gtk/gtkcheckmenuitem.c
@@ -272,13 +272,14 @@ gtk_check_menu_item_new_with_label (const gchar *label)
 /**
  * gtk_check_menu_item_new_with_mnemonic:
  * @label: The text of the button, with an underscore in front of the
- *         mnemonic character
- * @returns: a new #GtkCheckMenuItem
+ *     character
  *
  * Creates a new #GtkCheckMenuItem containing a label. The label
  * will be created using gtk_label_new_with_mnemonic(), so underscores
  * in @label indicate the mnemonic for the menu item.
- **/
+ *
+ * Returns: a new #GtkCheckMenuItem
+ */
 GtkWidget*
 gtk_check_menu_item_new_with_mnemonic (const gchar *label)
 {
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 229fcf6e1f..ac9bcf9726 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1145,8 +1145,8 @@ gtk_container_child_set_property (GtkContainer *container,
  * @container: a #GtkContainer
  * @widget: a widget to be placed inside @container
  * @first_prop_name: the name of the first child property to set
- * @Varargs: a %NULL-terminated list of property names and values, starting
- *           with @first_prop_name
+ * @...: a %NULL-terminated list of property names and values, starting
+ *     with @first_prop_name
  *
  * Adds @widget to @container, setting child properties at the same time.
  * See gtk_container_add() and gtk_container_child_set() for more details.
@@ -1185,8 +1185,8 @@ gtk_container_add_with_properties (GtkContainer *container,
  * @container: a #GtkContainer
  * @child: a widget which is a child of @container
  * @first_prop_name: the name of the first property to set
- * @Varargs: a %NULL-terminated list of property names and values, starting
- *           with @first_prop_name
+ * @...: a %NULL-terminated list of property names and values, starting
+ *     with @first_prop_name
  *
  * Sets one or more child properties for @child and @container.
  */
@@ -1208,11 +1208,11 @@ gtk_container_child_set (GtkContainer      *container,
  * @container: a #GtkContainer
  * @child: a widget which is a child of @container
  * @first_prop_name: the name of the first property to get
- * @Varargs: return location for the first property, followed
+ * @...: return location for the first property, followed
  *     optionally by more name/return location pairs, followed by %NULL
  *
  * Gets the values of one or more child properties for @child and @container.
- **/
+ */
 void
 gtk_container_child_get (GtkContainer      *container,
                          GtkWidget         *child,
@@ -1267,10 +1267,11 @@ gtk_container_class_install_child_property (GtkContainerClass *cclass,
  * gtk_container_class_find_child_property:
  * @cclass: (type GtkContainerClass): a #GtkContainerClass
  * @property_name: the name of the child property to find
- * @returns: (transfer none): the #GParamSpec of the child property or
- *           %NULL if @class has no child property with that name.
  *
  * Finds a child property of a container class by name.
+ *
+ * Returns: (transfer none): the #GParamSpec of the child property
+ *     or %NULL if @class has no child property with that name.
  */
 GParamSpec*
 gtk_container_class_find_child_property (GObjectClass *cclass,
@@ -1289,11 +1290,12 @@ gtk_container_class_find_child_property (GObjectClass *cclass,
  * gtk_container_class_list_child_properties:
  * @cclass: (type GtkContainerClass): a #GtkContainerClass
  * @n_properties: location to return the number of child properties found
- * @returns: (array length=n_properties) (transfer container): a newly
- *           allocated %NULL-terminated array of #GParamSpec*.  The
- *           array must be freed with g_free().
  *
  * Returns all child properties of a container class.
+ *
+ * Returns: (array length=n_properties) (transfer container):
+ *     a newly allocated %NULL-terminated array of #GParamSpec*.
+ *     The array must be freed with g_free().
  */
 GParamSpec**
 gtk_container_class_list_child_properties (GObjectClass *cclass,
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index f743921711..ad32047a71 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -607,7 +607,7 @@ gtk_dialog_new_empty (const gchar     *title,
  * @parent: (allow-none): Transient parent of the dialog, or %NULL
  * @flags: from #GtkDialogFlags
  * @first_button_text: (allow-none): stock ID or text to go in first button, or %NULL
- * @Varargs: response ID for first button, then additional buttons, ending with %NULL
+ * @...: response ID for first button, then additional buttons, ending with %NULL
  *
  * Creates a new #GtkDialog with title @title (or %NULL for the default
  * title; see gtk_window_set_title()) and transient parent @parent (or
@@ -641,7 +641,7 @@ gtk_dialog_new_empty (const gchar     *title,
  * ]|
  *
  * Return value: a new #GtkDialog
- **/
+ */
 GtkWidget*
 gtk_dialog_new_with_buttons (const gchar    *title,
                              GtkWindow      *parent,
@@ -828,13 +828,13 @@ gtk_dialog_add_buttons_valist (GtkDialog      *dialog,
  * gtk_dialog_add_buttons:
  * @dialog: a #GtkDialog
  * @first_button_text: button text or stock ID
- * @Varargs: response ID for first button, then more text-response_id pairs
+ * @...: response ID for first button, then more text-response_id pairs
  *
  * Adds more buttons, same as calling gtk_dialog_add_button()
  * repeatedly.  The variable argument list should be %NULL-terminated
  * as with gtk_dialog_new_with_buttons(). Each button must have both
  * text and response ID.
- **/
+ */
 void
 gtk_dialog_add_buttons (GtkDialog   *dialog,
                         const gchar *first_button_text,
@@ -1265,7 +1265,7 @@ gtk_dialog_set_alternative_button_order_valist (GtkDialog *dialog,
  * gtk_dialog_set_alternative_button_order:
  * @dialog: a #GtkDialog
  * @first_response_id: a response id used by one @dialog's buttons
- * @Varargs: a list of more response ids of @dialog's buttons, terminated by -1
+ * @...: a list of more response ids of @dialog's buttons, terminated by -1
  *
  * Sets an alternative button order. If the
  * #GtkSettings:gtk-alternative-button-order setting is set to %TRUE,
diff --git a/gtk/gtkfilechooserdialog.c b/gtk/gtkfilechooserdialog.c
index de61afdc2d..50d2f630ab 100644
--- a/gtk/gtkfilechooserdialog.c
+++ b/gtk/gtkfilechooserdialog.c
@@ -592,7 +592,7 @@ gtk_file_chooser_dialog_new_valist (const gchar          *title,
  * @parent: (allow-none): Transient parent of the dialog, or %NULL
  * @action: Open or save mode for the dialog
  * @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
- * @Varargs: response ID for the first button, then additional (button, id) pairs, ending with %NULL
+ * @...: response ID for the first button, then additional (button, id) pairs, ending with %NULL
  *
  * Creates a new #GtkFileChooserDialog.  This function is analogous to
  * gtk_dialog_new_with_buttons().
diff --git a/gtk/gtkfontchooserwidget.c b/gtk/gtkfontchooserwidget.c
index 9a3f37cb12..7a9d879ef9 100644
--- a/gtk/gtkfontchooserwidget.c
+++ b/gtk/gtkfontchooserwidget.c
@@ -532,6 +532,7 @@ gtk_font_chooser_widget_init (GtkFontChooserWidget *fontchooser)
   /* Creating fundamental widgets for the private struct */
   priv->search_entry = gtk_entry_new ();
   priv->family_face_list = gtk_tree_view_new ();
+  gtk_tree_view_set_enable_search (GTK_TREE_VIEW (priv->family_face_list), FALSE);
   priv->preview = gtk_entry_new ();
   priv->size_slider = gtk_scale_new_with_range (GTK_ORIENTATION_HORIZONTAL,
                                                 0.0,
diff --git a/gtk/gtkiconfactory.c b/gtk/gtkiconfactory.c
index c17feef5d9..ba25312f13 100644
--- a/gtk/gtkiconfactory.c
+++ b/gtk/gtkiconfactory.c
@@ -1166,10 +1166,11 @@ gtk_icon_size_from_name (const gchar *name)
 /**
  * gtk_icon_size_get_name:
  * @size: (type int): a #GtkIconSize.
- * @returns: the name of the given icon size.
  *
  * Gets the canonical name of the given icon size. The returned string
  * is statically allocated and should not be freed.
+ *
+ * Returns: the name of the given icon size.
  */
 const gchar*
 gtk_icon_size_get_name (GtkIconSize  size)
diff --git a/gtk/gtkimagemenuitem.c b/gtk/gtkimagemenuitem.c
index 480df828ea..81d0ad05a3 100644
--- a/gtk/gtkimagemenuitem.c
+++ b/gtk/gtkimagemenuitem.c
@@ -774,10 +774,11 @@ gtk_image_menu_item_sync_action_properties (GtkActivatable *activatable,
 
 /**
  * gtk_image_menu_item_new:
- * @returns: a new #GtkImageMenuItem.
  *
  * Creates a new #GtkImageMenuItem with an empty label.
- **/
+ *
+ * Returns: a new #GtkImageMenuItem
+ */
 GtkWidget*
 gtk_image_menu_item_new (void)
 {
@@ -787,9 +788,10 @@ gtk_image_menu_item_new (void)
 /**
  * gtk_image_menu_item_new_with_label:
  * @label: the text of the menu item.
- * @returns: a new #GtkImageMenuItem.
  *
  * Creates a new #GtkImageMenuItem containing a label.
+ *
+ * Returns: a new #GtkImageMenuItem.
  */
 GtkWidget*
 gtk_image_menu_item_new_with_label (const gchar *label)
@@ -799,16 +801,16 @@ gtk_image_menu_item_new_with_label (const gchar *label)
                        NULL);
 }
 
-
 /**
  * gtk_image_menu_item_new_with_mnemonic:
  * @label: the text of the menu item, with an underscore in front of the
  *         mnemonic character
- * @returns: a new #GtkImageMenuItem
  *
  * Creates a new #GtkImageMenuItem containing a label. The label
  * will be created using gtk_label_new_with_mnemonic(), so underscores
  * in @label indicate the mnemonic for the menu item.
+ *
+ * Returns: a new #GtkImageMenuItem
  */
 GtkWidget*
 gtk_image_menu_item_new_with_mnemonic (const gchar *label)
@@ -824,7 +826,6 @@ gtk_image_menu_item_new_with_mnemonic (const gchar *label)
  * @stock_id: the name of the stock item.
  * @accel_group: (allow-none): the #GtkAccelGroup to add the menu items
  *   accelerator to, or %NULL.
- * @returns: a new #GtkImageMenuItem.
  *
  * Creates a new #GtkImageMenuItem containing the image and text from a
  * stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK
@@ -835,6 +836,8 @@ gtk_image_menu_item_new_with_mnemonic (const gchar *label)
  * appropriate path for the menu item, use gtk_stock_lookup() to look up the
  * standard accelerator for the stock item, and if one is found, call
  * gtk_accel_map_add_entry() to register it.
+ *
+ * Returns: a new #GtkImageMenuItem.
  */
 GtkWidget*
 gtk_image_menu_item_new_from_stock (const gchar   *stock_id,
diff --git a/gtk/gtkliststore.c b/gtk/gtkliststore.c
index 5ed838fb45..9fd2dca40b 100644
--- a/gtk/gtkliststore.c
+++ b/gtk/gtkliststore.c
@@ -414,18 +414,18 @@ iter_is_valid (GtkTreeIter  *iter,
 /**
  * gtk_list_store_new:
  * @n_columns: number of columns in the list store
- * @Varargs: all #GType types for the columns, from first to last
+ * @...: all #GType types for the columns, from first to last
  *
  * Creates a new list store as with @n_columns columns each of the types passed
- * in.  Note that only types derived from standard GObject fundamental types 
- * are supported. 
+ * in.  Note that only types derived from standard GObject fundamental types
+ * are supported.
  *
  * As an example, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
  * GDK_TYPE_PIXBUF);</literal> will create a new #GtkListStore with three columns, of type
  * int, string and #GdkPixbuf respectively.
  *
  * Return value: a new #GtkListStore
- **/
+ */
 GtkListStore *
 gtk_list_store_new (gint n_columns,
 		    ...)
@@ -1172,7 +1172,7 @@ gtk_list_store_set_valist (GtkListStore *list_store,
  * gtk_list_store_set:
  * @list_store: a #GtkListStore
  * @iter: row iterator
- * @Varargs: pairs of column number and value, terminated with -1
+ * @...: pairs of column number and value, terminated with -1
  *
  * Sets the value of one or more cells in the row referenced by @iter.
  * The variable argument list should contain integer column numbers,
@@ -1183,7 +1183,7 @@ gtk_list_store_set_valist (GtkListStore *list_store,
  *
  * The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it
  * will be copied if it is a %G_TYPE_STRING or %G_TYPE_BOXED.
- **/
+ */
 void
 gtk_list_store_set (GtkListStore *list_store,
 		    GtkTreeIter  *iter,
@@ -2170,18 +2170,18 @@ gtk_list_store_has_default_sort_func (GtkTreeSortable *sortable)
 /**
  * gtk_list_store_insert_with_values:
  * @list_store: A #GtkListStore
- * @iter: (out) (allow-none): An unset #GtkTreeIter to set to the new row, or %NULL.
+ * @iter: (out) (allow-none): An unset #GtkTreeIter to set to the new row, or %NULL
  * @position: position to insert the new row
- * @Varargs: pairs of column number and value, terminated with -1
+ * @...: pairs of column number and value, terminated with -1
+ *
+ * Creates a new row at @position. @iter will be changed to point to this new
+ * row. If @position is larger than the number of rows on the list, then the
+ * new row will be appended to the list. The row will be filled with the
+ * values given to this function.
  *
- * Creates a new row at @position.  @iter will be changed to point to this new
- * row.  If @position is larger than the number of rows on the list, then the
- * new row will be appended to the list. The row will be filled with the 
- * values given to this function. 
- * 
  * Calling
- * <literal>gtk_list_store_insert_with_values(list_store, iter, position...)</literal> 
- * has the same effect as calling 
+ * <literal>gtk_list_store_insert_with_values (list_store, iter, position...)</literal>
+ * has the same effect as calling
  * |[
  * gtk_list_store_insert (list_store, iter, position);
  * gtk_list_store_set (list_store, iter, ...);
@@ -2189,7 +2189,7 @@ gtk_list_store_has_default_sort_func (GtkTreeSortable *sortable)
  * with the difference that the former will only emit a row_inserted signal,
  * while the latter will emit row_inserted, row_changed and, if the list store
  * is sorted, rows_reordered. Since emitting the rows_reordered signal
- * repeatedly can affect the performance of the program, 
+ * repeatedly can affect the performance of the program,
  * gtk_list_store_insert_with_values() should generally be preferred when
  * inserting rows in a sorted list store.
  *
diff --git a/gtk/gtkmessagedialog.c b/gtk/gtkmessagedialog.c
index 19ab948efc..cc154ee07a 100644
--- a/gtk/gtkmessagedialog.c
+++ b/gtk/gtkmessagedialog.c
@@ -582,7 +582,7 @@ gtk_message_dialog_get_property (GObject     *object,
  * @type: type of message
  * @buttons: set of buttons to use
  * @message_format: (allow-none): printf()-style format string, or %NULL
- * @Varargs: arguments for @message_format
+ * @...: arguments for @message_format
  *
  * Creates a new message dialog, which is a simple dialog with an icon
  * indicating the dialog type (error, warning, etc.) and some text the
@@ -591,7 +591,7 @@ gtk_message_dialog_get_property (GObject     *object,
  * #GtkDialog for more details.
  *
  * Return value: (transfer none): a new #GtkMessageDialog
- **/
+ */
 GtkWidget*
 gtk_message_dialog_new (GtkWindow     *parent,
                         GtkDialogFlags flags,
@@ -640,13 +640,13 @@ gtk_message_dialog_new (GtkWindow     *parent,
 
 /**
  * gtk_message_dialog_new_with_markup:
- * @parent: (allow-none): transient parent, or %NULL for none 
+ * @parent: (allow-none): transient parent, or %NULL for none
  * @flags: flags
  * @type: type of message
  * @buttons: set of buttons to use
  * @message_format: (allow-none): printf()-style format string, or %NULL
- * @Varargs: arguments for @message_format
- * 
+ * @...: arguments for @message_format
+ *
  * Creates a new message dialog, which is a simple dialog with an icon
  * indicating the dialog type (error, warning, etc.) and some text which
  * is marked up with the <link linkend="PangoMarkupFormat">Pango text markup language</link>.
@@ -794,16 +794,16 @@ gtk_message_dialog_set_markup (GtkMessageDialog *message_dialog,
  * gtk_message_dialog_format_secondary_text:
  * @message_dialog: a #GtkMessageDialog
  * @message_format: (allow-none): printf()-style format string, or %NULL
- * @Varargs: arguments for @message_format
- * 
- * Sets the secondary text of the message dialog to be @message_format 
+ * @...: arguments for @message_format
+ *
+ * Sets the secondary text of the message dialog to be @message_format
  * (with printf()-style).
  *
  * Note that setting a secondary text makes the primary text become
  * bold, unless you have provided explicit markup.
  *
  * Since: 2.6
- **/
+ */
 void
 gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
                                           const gchar      *message_format,
@@ -842,32 +842,32 @@ gtk_message_dialog_format_secondary_text (GtkMessageDialog *message_dialog,
 /**
  * gtk_message_dialog_format_secondary_markup:
  * @message_dialog: a #GtkMessageDialog
- * @message_format: printf()-style markup string (see 
+ * @message_format: printf()-style markup string (see
      <link linkend="PangoMarkupFormat">Pango markup format</link>), or %NULL
- * @Varargs: arguments for @message_format
- * 
- * Sets the secondary text of the message dialog to be @message_format (with 
- * printf()-style), which is marked up with the 
+ * @...: arguments for @message_format
+ *
+ * Sets the secondary text of the message dialog to be @message_format (with
+ * printf()-style), which is marked up with the
  * <link linkend="PangoMarkupFormat">Pango text markup language</link>.
  *
  * Note that setting a secondary text makes the primary text become
  * bold, unless you have provided explicit markup.
  *
  * Due to an oversight, this function does not escape special XML characters
- * like gtk_message_dialog_new_with_markup() does. Thus, if the arguments 
+ * like gtk_message_dialog_new_with_markup() does. Thus, if the arguments
  * may contain special XML characters, you should use g_markup_printf_escaped()
  * to escape it.
 
  * <informalexample><programlisting>
  * gchar *msg;
- *  
+ *
  * msg = g_markup_printf_escaped (message_format, ...);
  * gtk_message_dialog_format_secondary_markup (message_dialog, "&percnt;s", msg);
  * g_free (msg);
  * </programlisting></informalexample>
  *
  * Since: 2.6
- **/
+ */
 void
 gtk_message_dialog_format_secondary_markup (GtkMessageDialog *message_dialog,
                                             const gchar      *message_format,
diff --git a/gtk/gtkradiomenuitem.c b/gtk/gtkradiomenuitem.c
index b901d1cd1f..a38f667e4d 100644
--- a/gtk/gtkradiomenuitem.c
+++ b/gtk/gtkradiomenuitem.c
@@ -270,12 +270,13 @@ gtk_radio_menu_item_new_with_label (GSList *group,
  * @group: group the radio menu item is inside
  * @label: the text of the button, with an underscore in front of the
  *         mnemonic character
- * @returns: a new #GtkRadioMenuItem
  *
  * Creates a new #GtkRadioMenuItem containing a label. The label
  * will be created using gtk_label_new_with_mnemonic(), so underscores
  * in @label indicate the mnemonic for the menu item.
- **/
+ *
+ * Returns: a new #GtkRadioMenuItem
+ */
 GtkWidget*
 gtk_radio_menu_item_new_with_mnemonic (GSList *group,
 				       const gchar *label)
diff --git a/gtk/gtkrc.c b/gtk/gtkrc.c
index a3692d3659..6ce4822f4d 100644
--- a/gtk/gtkrc.c
+++ b/gtk/gtkrc.c
@@ -912,8 +912,6 @@ gtk_rc_make_default_dir (const gchar *type)
 
 /**
  * gtk_rc_get_im_module_path:
- * @returns: (type filename): 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_PATH</envar></link>
@@ -921,6 +919,9 @@ gtk_rc_make_default_dir (const gchar *type)
  * function is useful solely for utilities supplied with GTK+ and should
  * not be used by applications under normal circumstances.
  *
+ * Returns: (type filename): a newly-allocated string containing the
+ *    path in which to look for IM modules.
+ *
  * Deprecated: 3.0: Use #GtkCssProvider instead.
  */
 gchar *
@@ -935,13 +936,14 @@ gtk_rc_get_im_module_path (void)
 
 /**
  * gtk_rc_get_im_module_file:
- * @returns: (type filename): a newly-allocated string containing the
- *    name of the file listing the IM modules available for loading
  *
  * 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.
  *
+ * Returns: (type filename): a newly-allocated string containing the
+ *    name of the file listing the IM modules available for loading
+ *
  * Deprecated: 3.0: Use #GtkCssProvider instead.
  */
 gchar *
diff --git a/gtk/gtkrecentchooserdialog.c b/gtk/gtkrecentchooserdialog.c
index 9825ac8ca2..7a1a925bb8 100644
--- a/gtk/gtkrecentchooserdialog.c
+++ b/gtk/gtkrecentchooserdialog.c
@@ -337,7 +337,7 @@ gtk_recent_chooser_dialog_new_valist (const gchar      *title,
  * @title: (allow-none): Title of the dialog, or %NULL
  * @parent: (allow-none): Transient parent of the dialog, or %NULL,
  * @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
- * @Varargs: response ID for the first button, then additional (button, id)
+ * @...: response ID for the first button, then additional (button, id)
  *   pairs, ending with %NULL
  *
  * Creates a new #GtkRecentChooserDialog.  This function is analogous to
@@ -373,7 +373,7 @@ gtk_recent_chooser_dialog_new (const gchar *title,
  * @parent: (allow-none): Transient parent of the dialog, or %NULL,
  * @manager: a #GtkRecentManager
  * @first_button_text: (allow-none): stock ID or text to go in the first button, or %NULL
- * @Varargs: response ID for the first button, then additional (button, id)
+ * @...: response ID for the first button, then additional (button, id)
  *   pairs, ending with %NULL
  *
  * Creates a new #GtkRecentChooserDialog with a specified recent manager.
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index d30b30e4e0..89e0118bd3 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -1903,7 +1903,7 @@ gtk_settings_install_property (GParamSpec *pspec)
 
 /**
  * gtk_settings_install_property_parser:
- * @psepc:
+ * @pspec:
  * @parser: (scope call):
  */
 void
diff --git a/gtk/gtkstyle.c b/gtk/gtkstyle.c
index f7e987a347..06ebfe48b2 100644
--- a/gtk/gtkstyle.c
+++ b/gtk/gtkstyle.c
@@ -831,12 +831,13 @@ _gtk_style_new_for_path (GdkScreen     *screen,
 
 /**
  * gtk_style_new:
- * @returns: a new #GtkStyle.
  *
  * Creates a new #GtkStyle.
  *
+ * Returns: a new #GtkStyle.
+ *
  * Deprecated: 3.0: Use #GtkStyleContext
- **/
+ */
 GtkStyle*
 gtk_style_new (void)
 {
@@ -1203,7 +1204,7 @@ gtk_style_get_valist (GtkStyle    *style,
  * @style: a #GtkStyle
  * @widget_type: the #GType of a descendant of #GtkWidget
  * @first_property_name: the name of the first style property to get
- * @Varargs: pairs of property names and locations to
+ * @...: pairs of property names and locations to
  *   return the property values, starting with the location for
  *   @first_property_name, terminated by %NULL.
  *
@@ -1291,9 +1292,8 @@ gtk_style_render_icon (GtkStyle            *style,
 /**
  * gtk_style_apply_default_background:
  * @style:
- * @cr: 
+ * @cr:
  * @window:
- * @set_bg:
  * @state_type:
  * @x:
  * @y:
diff --git a/gtk/gtktextbuffer.c b/gtk/gtktextbuffer.c
index b66eb77a2b..52927cc666 100644
--- a/gtk/gtktextbuffer.c
+++ b/gtk/gtktextbuffer.c
@@ -1489,10 +1489,10 @@ gtk_text_buffer_insert_range_interactive (GtkTextBuffer     *buffer,
  * @text: UTF-8 text
  * @len: length of @text, or -1
  * @first_tag: first tag to apply to @text
- * @Varargs: NULL-terminated list of tags to apply
+ * @...: %NULL-terminated list of tags to apply
  *
  * Inserts @text into @buffer at @iter, applying the list of tags to
- * the newly-inserted text. The last tag specified must be NULL to
+ * the newly-inserted text. The last tag specified must be %NULL to
  * terminate the list. Equivalent to calling gtk_text_buffer_insert(),
  * then gtk_text_buffer_apply_tag() on the inserted text;
  * gtk_text_buffer_insert_with_tags() is just a convenience function.
@@ -1543,7 +1543,7 @@ gtk_text_buffer_insert_with_tags (GtkTextBuffer *buffer,
  * @text: UTF-8 text
  * @len: length of @text, or -1
  * @first_tag_name: name of a tag to apply to @text
- * @Varargs: more tag names
+ * @...: more tag names
  *
  * Same as gtk_text_buffer_insert_with_tags(), but allows you
  * to pass in tag names instead of tag objects.
@@ -2466,7 +2466,7 @@ gtk_text_buffer_select_range (GtkTextBuffer     *buffer,
  * @buffer: a #GtkTextBuffer
  * @tag_name: (allow-none): name of the new tag, or %NULL
  * @first_property_name: (allow-none): name of first property to set, or %NULL
- * @Varargs: %NULL-terminated list of property names and values
+ * @...: %NULL-terminated list of property names and values
  *
  * Creates a tag and adds it to the tag table for @buffer.
  * Equivalent to calling gtk_text_tag_new() and then adding the
diff --git a/gtk/gtktogglebutton.c b/gtk/gtktogglebutton.c
index 3b1a0ada33..5ff3bb0a7d 100644
--- a/gtk/gtktogglebutton.c
+++ b/gtk/gtktogglebutton.c
@@ -309,12 +309,13 @@ gtk_toggle_button_new_with_label (const gchar *label)
  * gtk_toggle_button_new_with_mnemonic:
  * @label: the text of the button, with an underscore in front of the
  *         mnemonic character
- * @returns: a new #GtkToggleButton
  *
  * Creates a new #GtkToggleButton containing a label. The label
  * will be created using gtk_label_new_with_mnemonic(), so underscores
  * in @label indicate the mnemonic for the button.
- **/
+ *
+ * Returns: a new #GtkToggleButton
+ */
 GtkWidget*
 gtk_toggle_button_new_with_mnemonic (const gchar *label)
 {
diff --git a/gtk/gtktreemodel.c b/gtk/gtktreemodel.c
index 3ea382efc5..32b0626d4d 100644
--- a/gtk/gtktreemodel.c
+++ b/gtk/gtktreemodel.c
@@ -652,7 +652,7 @@ gtk_tree_path_new_from_string (const gchar *path)
 /**
  * gtk_tree_path_new_from_indices:
  * @first_index: first integer
- * @varargs: list of integers terminated by -1
+ * @...: list of integers terminated by -1
  *
  * Creates a new path with @first_index and @varargs as indices.
  *
@@ -1700,7 +1700,7 @@ gtk_tree_model_unref_node (GtkTreeModel *tree_model,
  * gtk_tree_model_get:
  * @tree_model: a #GtkTreeModel
  * @iter: a row in @tree_model
- * @Varargs: pairs of column number and value return locations,
+ * @...: 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.
diff --git a/gtk/gtktreestore.c b/gtk/gtktreestore.c
index e0d40dd40f..c8ffb9cdd5 100644
--- a/gtk/gtktreestore.c
+++ b/gtk/gtktreestore.c
@@ -304,11 +304,11 @@ gtk_tree_store_init (GtkTreeStore *tree_store)
 /**
  * gtk_tree_store_new:
  * @n_columns: number of columns in the tree store
- * @Varargs: all #GType types for the columns, from first to last
+ * @...: all #GType types for the columns, from first to last
  *
  * Creates a new tree store as with @n_columns columns each of the types passed
- * in.  Note that only types derived from standard GObject fundamental types 
- * are supported. 
+ * in.  Note that only types derived from standard GObject fundamental types
+ * are supported.
  *
  * As an example, <literal>gtk_tree_store_new (3, G_TYPE_INT, G_TYPE_STRING,
  * GDK_TYPE_PIXBUF);</literal> will create a new #GtkTreeStore with three columns, of type
@@ -1170,13 +1170,13 @@ gtk_tree_store_set_valist (GtkTreeStore *tree_store,
  * gtk_tree_store_set:
  * @tree_store: A #GtkTreeStore
  * @iter: A valid #GtkTreeIter for the row being modified
- * @Varargs: pairs of column number and value, terminated with -1
+ * @...: pairs of column number and value, terminated with -1
  *
  * 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. 
+ * 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 
+ * %G_TYPE_STRING to "Foo", you would write
  * <literal>gtk_tree_store_set (store, iter, 0, "Foo", -1)</literal>.
  *
  * The value will be referenced by the store if it is a %G_TYPE_OBJECT, and it
@@ -1493,11 +1493,11 @@ gtk_tree_store_insert_after (GtkTreeStore *tree_store,
  * @iter: (out) (allow-none): An unset #GtkTreeIter to set the new row, or %NULL.
  * @parent: (allow-none): A valid #GtkTreeIter, or %NULL
  * @position: position to insert the new row
- * @Varargs: pairs of column number and value, terminated with -1
+ * @...: pairs of column number and value, terminated with -1
  *
- * Creates a new row at @position.  @iter will be changed to point to this
- * new row.  If @position is larger than the number of rows on the list, then
- * the new row will be appended to the list.  The row will be filled with
+ * Creates a new row at @position. @iter will be changed to point to this
+ * new row. If @position is larger than the number of rows on the list, then
+ * the new row will be appended to the list. The row will be filled with
  * the values given to this function.
  *
  * Calling
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index 3b2ec9e1eb..44ecbbd26d 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -11988,10 +11988,10 @@ gtk_tree_view_insert_column (GtkTreeView       *tree_view,
 /**
  * gtk_tree_view_insert_column_with_attributes:
  * @tree_view: A #GtkTreeView
- * @position: The position to insert the new column in.
- * @title: The title to set the header to.
- * @cell: The #GtkCellRenderer.
- * @Varargs: A %NULL-terminated list of attributes.
+ * @position: The position to insert the new column in
+ * @title: The title to set the header to
+ * @cell: The #GtkCellRenderer
+ * @...: A %NULL-terminated list of attributes
  *
  * Creates a new #GtkTreeViewColumn and inserts it into the @tree_view at
  * @position.  If @position is -1, then the newly created column is inserted at
diff --git a/gtk/gtktreeviewcolumn.c b/gtk/gtktreeviewcolumn.c
index f2a7ca7e38..52dfe19c12 100644
--- a/gtk/gtktreeviewcolumn.c
+++ b/gtk/gtktreeviewcolumn.c
@@ -1643,12 +1643,12 @@ gtk_tree_view_column_new_with_area (GtkCellArea *area)
 
 /**
  * gtk_tree_view_column_new_with_attributes:
- * @title: The title to set the header to.
- * @cell: The #GtkCellRenderer.
- * @Varargs: A %NULL-terminated list of attributes.
- * 
- * Creates a new #GtkTreeViewColumn with a number of default values.  This is
- * equivalent to calling gtk_tree_view_column_set_title(),
+ * @title: The title to set the header to
+ * @cell: The #GtkCellRenderer
+ * @...: A %NULL-terminated list of attributes
+ *
+ * Creates a new #GtkTreeViewColumn with a number of default values.
+ * This is equivalent to calling gtk_tree_view_column_set_title(),
  * gtk_tree_view_column_pack_start(), and
  * gtk_tree_view_column_set_attributes() on the newly created #GtkTreeViewColumn.
  *
@@ -1787,15 +1787,15 @@ gtk_tree_view_column_set_attributesv (GtkTreeViewColumn *tree_column,
 
 /**
  * gtk_tree_view_column_set_attributes:
- * @tree_column: A #GtkTreeViewColumn.
+ * @tree_column: A #GtkTreeViewColumn
  * @cell_renderer: the #GtkCellRenderer we're setting the attributes of
- * @Varargs: A %NULL-terminated list of attributes.
- * 
+ * @...: A %NULL-terminated list of attributes
+ *
  * Sets the attributes in the list as the attributes of @tree_column.
  * The attributes should be in attribute/column order, as in
  * gtk_tree_view_column_add_attribute(). All existing attributes
  * are removed, and replaced with the new attributes.
- **/
+ */
 void
 gtk_tree_view_column_set_attributes (GtkTreeViewColumn *tree_column,
 				     GtkCellRenderer   *cell_renderer,
diff --git a/gtk/gtkviewport.c b/gtk/gtkviewport.c
index 7319841030..7aa3a81b36 100644
--- a/gtk/gtkviewport.c
+++ b/gtk/gtkviewport.c
@@ -252,13 +252,13 @@ gtk_viewport_init (GtkViewport *viewport)
 
 /**
  * gtk_viewport_new:
- * @hadjustment: horizontal adjustment.
- * @vadjustment: vertical adjustment.
- * @returns: a new #GtkViewport.
+ * @hadjustment: horizontal adjustment
+ * @vadjustment: vertical adjustment
  *
  * Creates a new #GtkViewport with the given adjustments.
  *
- **/
+ * Returns: a new #GtkViewport
+ */
 GtkWidget*
 gtk_viewport_new (GtkAdjustment *hadjustment,
 		  GtkAdjustment *vadjustment)
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index b95ce9a2d8..f90e3b3099 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -3656,8 +3656,8 @@ gtk_widget_thaw_child_notify (GtkWidget *widget)
  * gtk_widget_new:
  * @type: type ID of the widget to create
  * @first_property_name: name of first property to set
- * @Varargs: value of first property, followed by more properties,
- *           %NULL-terminated
+ * @...: value of first property, followed by more properties,
+ *     %NULL-terminated
  *
  * This is a convenience function for creating a widget and setting
  * its properties in one go. For example you might write:
@@ -5406,10 +5406,11 @@ gtk_widget_add_accelerator (GtkWidget      *widget,
  * @accel_group:  accel group for this widget
  * @accel_key:    GDK keyval of the accelerator
  * @accel_mods:   modifier key combination of the accelerator
- * @returns:      whether an accelerator was installed and could be removed
  *
  * Removes an accelerator from @widget, previously installed with
  * gtk_widget_add_accelerator().
+ *
+ * Returns: whether an accelerator was installed and could be removed
  */
 gboolean
 gtk_widget_remove_accelerator (GtkWidget      *widget,
@@ -6342,16 +6343,16 @@ gtk_widget_intersect (GtkWidget	         *widget,
  *          @widget->allocation. That is, relative to @widget->window
  *          for %NO_WINDOW widgets; relative to the parent window
  *          of @widget->window for widgets with their own window.
- * @returns: A newly allocated region holding the intersection of @widget
- *           and @region. The coordinates of the return value are
- *           relative to @widget->window for %NO_WINDOW widgets, and
- *           relative to the parent window of @widget->window for
- *           widgets with their own window.
  *
  * Computes the intersection of a @widget's area and @region, returning
  * the intersection. The result may be empty, use cairo_region_is_empty() to
  * check.
- **/
+ *
+ * Returns: A newly allocated region holding the intersection of @widget
+ *     and @region. The coordinates of the return value are relative to
+ *     @widget->window for %NO_WINDOW widgets, and relative to the parent
+ *     window of @widget->window for widgets with their own window.
+ */
 cairo_region_t *
 gtk_widget_region_intersect (GtkWidget       *widget,
 			     const cairo_region_t *region)
@@ -11579,11 +11580,12 @@ gtk_widget_class_install_style_property (GtkWidgetClass *klass,
  * gtk_widget_class_find_style_property:
  * @klass: a #GtkWidgetClass
  * @property_name: the name of the style property to find
- * @returns: (transfer none): the #GParamSpec of the style property or
- *   %NULL if @class has no style property with that name.
  *
  * Finds a style property of a widget class by name.
  *
+ * Returns: (transfer none): the #GParamSpec of the style property or
+ *   %NULL if @class has no style property with that name.
+ *
  * Since: 2.2
  */
 GParamSpec*
@@ -11602,12 +11604,13 @@ gtk_widget_class_find_style_property (GtkWidgetClass *klass,
  * gtk_widget_class_list_style_properties:
  * @klass: a #GtkWidgetClass
  * @n_properties: location to return the number of style properties found
- * @returns: (array length=n_properties) (transfer container): an
- *       newly allocated array of #GParamSpec*. The array must be
- *       freed with g_free().
  *
  * Returns all style properties of a widget class.
  *
+ * Returns: (array length=n_properties) (transfer container): a
+ *     newly allocated array of #GParamSpec*. The array must be
+ *     freed with g_free().
+ *
  * Since: 2.2
  */
 GParamSpec**
@@ -11752,9 +11755,9 @@ gtk_widget_style_get_valist (GtkWidget   *widget,
  * gtk_widget_style_get:
  * @widget: a #GtkWidget
  * @first_property_name: the name of the first property to get
- * @Varargs: pairs of property names and locations to
- *   return the property values, starting with the location for
- *   @first_property_name, terminated by %NULL.
+ * @...: pairs of property names and locations to return the
+ *     property values, starting with the location for
+ *     @first_property_name, terminated by %NULL.
  *
  * Gets the values of a multiple style properties of @widget.
  */
@@ -14388,7 +14391,7 @@ _gtk_widget_get_sizegroups (GtkWidget    *widget)
  * Returns: the position where the data was inserted
  *
  * Since: 3.2
- **/
+ */
 gint
 gtk_widget_path_append_for_widget (GtkWidgetPath *path,
                                    GtkWidget     *widget)
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index e281d6e081..bdbe861cbc 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -2075,10 +2075,11 @@ gtk_window_remove_mnemonic (GtkWindow *window,
  * gtk_window_mnemonic_activate:
  * @window: a #GtkWindow
  * @keyval: the mnemonic
- * @modifier: the modifiers 
- * @returns: %TRUE if the activation is done. 
- * 
+ * @modifier: the modifiers
+ *
  * Activates the targets associated with the mnemonic.
+ *
+ * Returns: %TRUE if the activation is done.
  */
 gboolean
 gtk_window_mnemonic_activate (GtkWindow      *window,