[gtk+/gi-annotations: 3/9] Update GI annotations in 'Windows'

[Pavel Holejsovsky <pholejs src gnome org>]

commit b3d122820b050b65e9561667420598ec403a6af0
Author: Pavel Holejsovsky <pholejs src gnome org>
Date:   Sat Jan 8 19:17:13 2011 +0100

    Update GI annotations in 'Windows'
    
    'Windows' group from GTK+ manual are: GtkDialog, GtkInvisible,
    GtkMessageDialog, GtkWindow, GtkWindowGroup, GtkAboutDialog,
    GtkAssistant, GtkOffscreenWindow.

 gtk/gtkaboutdialog.c |   24 ++++++++++++------------
 gtk/gtkassistant.h   |    2 +-
 gtk/gtkdialog.c      |    8 +++++---
 gtk/gtkwindow.c      |   26 +++++++++++++-------------
 4 files changed, 31 insertions(+), 29 deletions(-)
---
diff --git a/gtk/gtkaboutdialog.c b/gtk/gtkaboutdialog.c
index 414355e..7e34c99 100644
--- a/gtk/gtkaboutdialog.c
+++ b/gtk/gtkaboutdialog.c
@@ -1480,9 +1480,9 @@ gtk_about_dialog_set_website_label (GtkAboutDialog *about,
  * Returns the string which are displayed in the authors tab
  * of the secondary credits dialog.
  *
- * Return value: A %NULL-terminated string array containing
- *  the authors. The array is owned by the about dialog
- *  and must not be modified.
+ * Return value: (array zero-terminated=1) (transfer none): A
+ *  %NULL-terminated string array containing the authors. The array is
+ *  owned by the about dialog and must not be modified.
  *
  * Since: 2.6
  */
@@ -1535,9 +1535,9 @@ gtk_about_dialog_set_authors (GtkAboutDialog  *about,
  * Returns the string which are displayed in the documenters
  * tab of the secondary credits dialog.
  *
- * Return value: A %NULL-terminated string array containing
- *  the documenters. The array is owned by the about dialog
- *  and must not be modified.
+ * Return value: (array zero-terminated=1) (transfer none): A
+ *  %NULL-terminated string array containing the documenters. The
+ *  array is owned by the about dialog and must not be modified.
  *
  * Since: 2.6
  */
@@ -1590,9 +1590,9 @@ gtk_about_dialog_set_documenters (GtkAboutDialog *about,
  * Returns the string which are displayed in the artists tab
  * of the secondary credits dialog.
  *
- * Return value: A %NULL-terminated string array containing
- *  the artists. The array is owned by the about dialog
- *  and must not be modified.
+ * Return value: (array zero-terminated=1) (transfer none): A
+ *  %NULL-terminated string array containing the artists. The array is
+ *  owned by the about dialog and must not be modified.
  *
  * Since: 2.6
  */
@@ -1706,9 +1706,9 @@ gtk_about_dialog_set_translator_credits (GtkAboutDialog *about,
  *
  * Returns the pixbuf displayed as logo in the about dialog.
  *
- * Return value: the pixbuf displayed as logo. The pixbuf is
- *   owned by the about dialog. If you want to keep a reference
- *   to it, you have to call g_object_ref() on it.
+ * Return value: (transfer none): the pixbuf displayed as logo. The
+ *   pixbuf is owned by the about dialog. If you want to keep a
+ *   reference to it, you have to call g_object_ref() on it.
  *
  * Since: 2.6
  */
diff --git a/gtk/gtkassistant.h b/gtk/gtkassistant.h
index ea3ae81..62f9ead 100644
--- a/gtk/gtkassistant.h
+++ b/gtk/gtkassistant.h
@@ -111,7 +111,7 @@ struct _GtkAssistantClass
 /**
  * GtkAssistantPageFunc:
  * @current_page: The page number used to calculate the next page.
- * @data: user data.
+ * @data: (closure): user data.
  *
  * A function used by gtk_assistant_set_forward_page_func() to know which
  * is the next page given a current one. It's called both for computing the
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 424b2d2..99d00b3 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -765,7 +765,7 @@ gtk_dialog_add_action_widget (GtkDialog *dialog,
  * appended to the end of the dialog's action area. The button widget is
  * returned, but usually you don't need it.
  *
- * Return value: (transfer full): the button widget that was added
+ * Return value: (transfer none): the button widget that was added
  **/
 GtkWidget*
 gtk_dialog_add_button (GtkDialog   *dialog,
@@ -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
  */
@@ -1322,7 +1323,8 @@ gtk_dialog_set_alternative_button_order (GtkDialog *dialog,
  * gtk_dialog_set_alternative_button_order_from_array:
  * @dialog: a #GtkDialog
  * @n_params: the number of response ids in @new_order
- * @new_order: an array of response ids of @dialog's buttons
+ * @new_order: (array length=n_params): an array of response ids of
+ *     @dialog's buttons
  *
  * Sets an alternative button order. If the
  * #GtkSettings:gtk-alternative-button-order setting is set to %TRUE,
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index b92627a..cec3615 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -2598,7 +2598,7 @@ gtk_window_get_opacity (GtkWindow *window)
  *
  * Gets the #GtkApplication associated with the window (if any).
  *
- * Return value: a #GtkApplication, or %NULL
+ * Return value: (transfer none): a #GtkApplication, or %NULL
  *
  * Since: 3.0
  **/
@@ -2629,7 +2629,7 @@ gtk_window_release_application (GtkWindow *window)
 /**
  * gtk_window_set_application:
  * @window: a #GtkWindow
- * @application: a #GtkApplication, or %NULL
+ * @application: (allow-none): a #GtkApplication, or %NULL
  *
  * Sets or unsets the #GtkApplication associated with the window.
  *
@@ -3426,7 +3426,7 @@ gtk_window_unrealize_icon (GtkWindow *window)
 /**
  * gtk_window_set_icon_list:
  * @window: a #GtkWindow
- * @list: (element-type GdkPixbuf) (transfer container): list of #GdkPixbuf
+ * @list: (element-type GdkPixbuf): list of #GdkPixbuf
  *
  * Sets up the icon representing a #GtkWindow. The icon is used when
  * the window is minimized (also known as iconified).  Some window
@@ -3686,7 +3686,7 @@ load_pixbuf_verbosely (const char *filename,
 /**
  * gtk_window_set_icon_from_file:
  * @window: a #GtkWindow
- * @filename: location of icon file
+ * @filename: (type filename): location of icon file
  * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets the icon for @window.  
@@ -3719,7 +3719,7 @@ gtk_window_set_icon_from_file (GtkWindow   *window,
 
 /**
  * gtk_window_set_default_icon_list:
- * @list: (element-type GdkPixbuf) (transfer container): a list of #GdkPixbuf
+ * @list: (element-type GdkPixbuf): a list of #GdkPixbuf
  *
  * Sets an icon list to be used as fallback for windows that haven't
  * had gtk_window_set_icon_list() called on them to set up a
@@ -3864,7 +3864,7 @@ gtk_window_get_default_icon_name (void)
 
 /**
  * gtk_window_set_default_icon_from_file:
- * @filename: location of icon file
+ * @filename: (type filename): location of icon file
  * @err: (allow-none): location to store error, or %NULL.
  *
  * Sets an icon to be used as fallback for windows that haven't
@@ -5582,8 +5582,8 @@ gtk_window_get_has_resize_grip (GtkWindow *window)
 /**
  * gtk_window_get_resize_grip_area:
  * @window: a #GtkWindow
- * @rect: a pointer to a #GdkRectangle which we should store the
- *     resize grip area
+ * @rect: (out): a pointer to a #GdkRectangle which we should store
+ *     the resize grip area
  *
  * If a window has a resize grip, this will retrieve the grip
  * position, width and height into the specified #GdkRectangle.
@@ -8049,7 +8049,7 @@ gtk_window_begin_move_drag  (GtkWindow *window,
                               timestamp);
 }
 
-/** 
+/**
  * gtk_window_set_screen:
  * @window: a #GtkWindow.
  * @screen: a #GdkScreen.
@@ -8336,8 +8336,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
  **/
@@ -8415,7 +8415,7 @@ gtk_window_has_group (GtkWindow *window)
  * Gets the current grab widget of the given group,
  * see gtk_grab_add().
  *
- * Returns: the current grab widget of the group
+ * Returns: (transfer none): the current grab widget of the group
  *
  * Since: 2.22
  */
@@ -8514,7 +8514,7 @@ _gtk_window_group_remove_device_grab (GtkWindowGroup *window_group,
  *
  * Returns the current grab widget for @device, or %NULL if none.
  *
- * Returns: The grab widget, or %NULL
+ * Returns: (transfer none): The grab widget, or %NULL
  *
  * Since: 3.0
  */