[GI] Cosmetic cleanups of annotations and doc comments

This change does not introduce any functionality change, mostly
cosmtic cleanups, like re-linebreak when introduced annotations messed
up indentation or whitespace errors fixes.

18 files changed, 45 insertions, 36 deletions

diff --git a/gdk/gdk.c b/gdk/gdk.c
index 9bf97e59a8..6bb7f8deea 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -777,7 +777,7 @@ gdk_threads_dispatch_free (gpointer data)
 /**
  * gdk_threads_add_idle_full:
  * @priority: the priority of the idle source. Typically this will be in the
- *            range btweeen #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE
+ *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE
  * @function: function to call
  * @data:     data to pass to @function
  * @notify: (allow-none):   function to call when the idle is removed, or %NULL
diff --git a/gdk/gdkcursor.c b/gdk/gdkcursor.c
index fe5f38ced7..1418b1bd0a 100644
--- a/gdk/gdkcursor.c
+++ b/gdk/gdkcursor.c
@@ -355,7 +355,7 @@ gdk_cursor_new_from_pixbuf (GdkDisplay *display,
   return GDK_DISPLAY_GET_CLASS (display)->get_cursor_for_pixbuf (display, pixbuf, x, y);
 }
 
-/** 
+/**
  * gdk_cursor_get_display:
  * @cursor: a #GdkCursor.
  *
diff --git a/gdk/gdkkeys.c b/gdk/gdkkeys.c
index c992ef5ae1..74993d6c20 100644
--- a/gdk/gdkkeys.c
+++ b/gdk/gdkkeys.c
@@ -284,7 +284,7 @@ gdk_keyval_is_lower (guint keyval)
   return FALSE;
 }
 
-/** 
+/**
  * gdk_keymap_get_default:
  *
  * Returns the #GdkKeymap attached to the default display.
diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index 9e43ccaf7c..560386dd31 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -819,8 +819,11 @@ _gtk_accel_group_get_accelerables (GtkAccelGroup *accel_group)
  * @accel_group:      the accelerator group to query
  * @accel_key:        key value of the accelerator
  * @accel_mods:       modifier combination of the accelerator
- * @n_entries: (allow-none):        location to return the number of entries found, or %NULL
- * @returns: (allow-none):          an array of @n_entries #GtkAccelGroupEntry elements, or %NULL. The array is owned by GTK+ and must not be freed. 
+ * @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.
diff --git a/gtk/gtkaction.c b/gtk/gtkaction.c
index 5514c25e72..c9a644107f 100644
--- a/gtk/gtkaction.c
+++ b/gtk/gtkaction.c
@@ -506,7 +506,8 @@ gtk_action_buildable_get_name (GtkBuildable *buildable)
 /**
  * gtk_action_new:
  * @name: A unique name for the action
- * @label: (allow-none): the label displayed in menu items and on buttons, or %NULL
+ * @label: (allow-none): the label displayed in menu items and on buttons,
+ *         or %NULL
  * @tooltip: (allow-none): a tooltip for the action, or %NULL
  * @stock_id: (allow-none): the stock icon to display in widgets representing
  *            the action, or %NULL
diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index d86ca46528..116bfb7713 100644
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -301,7 +301,7 @@ gtk_button_class_init (GtkButtonClass *klass)
                                                       GTK_PARAM_READWRITE));
 
   /**
-   * GtkButton::image:
+   * GtkButton:image:
    *
    * The child widget to appear next to the button text.
    *
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 424b2d232e..0aa57773d5 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -1131,7 +1131,8 @@ gtk_dialog_run (GtkDialog *dialog)
  * Gets the widget button that uses the given response ID in the action area
  * of a dialog.
  *
- * Returns: (transfer none):the @widget button that uses the given @response_id, or %NULL.
+ * Returns: (transfer none): the @widget button that uses the given
+ *     @response_id, or %NULL.
  *
  * Since: 2.20
  */
diff --git a/gtk/gtkfilechooser.c b/gtk/gtkfilechooser.c
index 41f8d1eb48..da9d7c5e94 100644
--- a/gtk/gtkfilechooser.c
+++ b/gtk/gtkfilechooser.c
@@ -2447,9 +2447,9 @@ gtk_file_chooser_remove_shortcut_folder_uri (GtkFileChooser    *chooser,
  * Queries the list of shortcut folders in the file chooser, as set by
  * gtk_file_chooser_add_shortcut_folder_uri().
  *
- * Return value: (element-type utf8) (transfer full): A list of folder URIs, or %NULL if there are no shortcut
- * folders.  Free the returned list with g_slist_free(), and the URIs with
- * g_free().
+ * Return value: (element-type utf8) (transfer full): A list of folder
+ * URIs, or %NULL if there are no shortcut folders.  Free the returned
+ * list with g_slist_free(), and the URIs with g_free().
  *
  * Since: 2.4
  **/
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 9035510b72..705cc122f7 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -1793,10 +1793,10 @@ gtk_icon_theme_list_icons (GtkIconTheme *icon_theme,
  * Gets the list of contexts available within the current
  * hierarchy of icon themes
  *
- * Return value: (element-type utf8) (transfer full): a #GList list holding the names of all the
- *  contexts in the theme. You must first free each element
- *  in the list with g_free(), then free the list itself
- *  with g_list_free().
+ * Return value: (element-type utf8) (transfer full): a #GList list
+ *  holding the names of all the contexts in the theme. You must first
+ *  free each element in the list with g_free(), then free the list
+ *  itself with g_list_free().
  *
  * Since: 2.12
  **/
diff --git a/gtk/gtkiconview.c b/gtk/gtkiconview.c
index 406a9e55b5..9f89851cf3 100644
--- a/gtk/gtkiconview.c
+++ b/gtk/gtkiconview.c
@@ -4562,7 +4562,7 @@ gtk_icon_view_set_tooltip_column (GtkIconView *icon_view,
   g_object_notify (G_OBJECT (icon_view), "tooltip-column");
 }
 
-/** 
+/**
  * gtk_icon_view_get_tooltip_column:
  * @icon_view: a #GtkIconView
  *
diff --git a/gtk/gtkimcontextsimple.c b/gtk/gtkimcontextsimple.c
index 522b21ea0a..ef724b575c 100644
--- a/gtk/gtkimcontextsimple.c
+++ b/gtk/gtkimcontextsimple.c
@@ -155,7 +155,7 @@ gtk_im_context_simple_finalize (GObject *obj)
   G_OBJECT_CLASS (gtk_im_context_simple_parent_class)->finalize (obj);
 }
 
-/** 
+/**
  * gtk_im_context_simple_new:
  * 
  * Creates a new #GtkIMContextSimple.
diff --git a/gtk/gtkmenu.c b/gtk/gtkmenu.c
index e1b4ca3f8a..0a125adacc 100644
--- a/gtk/gtkmenu.c
+++ b/gtk/gtkmenu.c
@@ -1337,9 +1337,9 @@ gtk_menu_remove (GtkContainer *container,
 /**
  * gtk_menu_new:
  *
- * Creates a new #GtkMenu.
+ * Creates a new #GtkMenu
  *
- * Returns: a new #GtkMenu.
+ * Returns: a new #GtkMenu
  */
 GtkWidget*
 gtk_menu_new (void)
@@ -1444,7 +1444,7 @@ popup_grab_on_window (GdkWindow *window,
 
 /**
  * gtk_menu_popup_for_device:
- * @menu: a #GtkMenu.
+ * @menu: a #GtkMenu
  * @device: (allow-none): a #GdkDevice
  * @parent_menu_shell: (allow-none): the menu shell containing the triggering
  *     menu item, or %NULL
diff --git a/gtk/gtkradioaction.c b/gtk/gtkradioaction.c
index a71c0d5bde..e225825537 100644
--- a/gtk/gtkradioaction.c
+++ b/gtk/gtkradioaction.c
@@ -193,7 +193,8 @@ gtk_radio_action_init (GtkRadioAction *action)
 /**
  * gtk_radio_action_new:
  * @name: A unique name for the action
- * @label: (allow-none): The label displayed in menu items and on buttons, or %NULL
+ * @label: (allow-none): The label displayed in menu items and on buttons,
+ *   or %NULL
  * @tooltip: (allow-none): A tooltip for this action, or %NULL
  * @stock_id: (allow-none): The stock icon to display in widgets representing
  *   this action, or %NULL
diff --git a/gtk/gtkradiobutton.c b/gtk/gtkradiobutton.c
index 4044b3ed1d..0eff06f197 100644
--- a/gtk/gtkradiobutton.c
+++ b/gtk/gtkradiobutton.c
@@ -175,7 +175,7 @@ gtk_radio_button_class_init (GtkRadioButtonClass *class)
 
   /**
    * GtkRadioButton::group-changed:
-   * @style: the object which received the signal
+   * @button: the object which received the signal
    *
    * Emitted when the group of radio buttons that a radio button belongs
    * to changes. This is emitted when a radio button switches from
diff --git a/gtk/gtkrecentaction.c b/gtk/gtkrecentaction.c
index 015cf9b080..8d21ae4830 100644
--- a/gtk/gtkrecentaction.c
+++ b/gtk/gtkrecentaction.c
@@ -670,7 +670,8 @@ gtk_recent_action_init (GtkRecentAction *action)
 /**
  * gtk_recent_action_new:
  * @name: a unique name for the action
- * @label: (allow-none): the label displayed in menu items and on buttons, or %NULL
+ * @label: (allow-none): the label displayed in menu items and on buttons,
+ *   or %NULL
  * @tooltip: (allow-none): a tooltip for the action, or %NULL
  * @stock_id: (allow-none): the stock icon to display in widgets representing
  *   the action, or %NULL
@@ -702,7 +703,8 @@ gtk_recent_action_new (const gchar *name,
 /**
  * gtk_recent_action_new_for_manager:
  * @name: a unique name for the action
- * @label: (allow-none): the label displayed in menu items and on buttons, or %NULL
+ * @label: (allow-none): the label displayed in menu items and on buttons,
+ *   or %NULL
  * @tooltip: (allow-none): a tooltip for the action, or %NULL
  * @stock_id: (allow-none): the stock icon to display in widgets representing
  *   the action, or %NULL
diff --git a/gtk/gtkstatusicon.c b/gtk/gtkstatusicon.c
index fdc5171f74..c22b0a87b4 100644
--- a/gtk/gtkstatusicon.c
+++ b/gtk/gtkstatusicon.c
@@ -2464,14 +2464,14 @@ gtk_status_icon_position_menu (GtkMenu  *menu,
 /**
  * gtk_status_icon_get_geometry:
  * @status_icon: a #GtkStatusIcon
- * @screen: (out) (transfer none) (allow-none): return location for the screen, or %NULL if the
- *          information is not needed
- * @area: (out) (allow-none): return location for the area occupied by the status
- *        icon, or %NULL
- * @orientation: (out) (allow-none): return location for the orientation of the panel
- *    in which the status icon is embedded, or %NULL. A panel
- *    at the top or bottom of the screen is horizontal, a panel
- *    at the left or right is vertical.
+ * @screen: (out) (transfer none) (allow-none): return location for
+ *          the screen, or %NULL if the information is not needed
+ * @area: (out) (allow-none): return location for the area occupied by
+ *        the status icon, or %NULL
+ * @orientation: (out) (allow-none): return location for the
+ *    orientation of the panel in which the status icon is embedded,
+ *    or %NULL. A panel at the top or bottom of the screen is
+ *    horizontal, a panel at the left or right is vertical.
  *
  * Obtains information about the location of the status icon
  * on screen. This information can be used to e.g. position 
diff --git a/gtk/gtktoggleaction.c b/gtk/gtktoggleaction.c
index 9dcc83d1e0..c36a924cfe 100644
--- a/gtk/gtktoggleaction.c
+++ b/gtk/gtktoggleaction.c
@@ -166,7 +166,8 @@ gtk_toggle_action_init (GtkToggleAction *action)
 /**
  * gtk_toggle_action_new:
  * @name: A unique name for the action
- * @label: (allow-none): The label displayed in menu items and on buttons, or %NULL
+ * @label: (allow-none): The label displayed in menu items and on buttons,
+ *         or %NULL
  * @tooltip: (allow-none): A tooltip for the action, or %NULL
  * @stock_id: (allow-none): The stock icon to display in widgets representing
  *            the action, or %NULL
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index c16fffbbe3..45a11fb177 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -8048,7 +8048,7 @@ gtk_window_begin_move_drag  (GtkWindow *window,
                               timestamp);
 }
 
-/** 
+/**
  * gtk_window_set_screen:
  * @window: a #GtkWindow.
  * @screen: a #GdkScreen.
@@ -8335,8 +8335,8 @@ gtk_window_group_remove_window (GtkWindowGroup *window_group,
  *
  * Returns a list of the #GtkWindows that belong to @window_group.
  *
- * Returns: (element-type GtkWidget) (transfer container): A newly-allocated list of
- *   windows inside the group.
+ * Returns: (element-type GtkWindow) (transfer container): A
+ *   newly-allocated list of windows inside the group.
  *
  * Since: 2.14
  **/