[gtk+/gtk-2-24] [GI] Backport transfer annotations

[Martin Pitt <martinpitt src gnome org>]

commit a33dceee4b1bd22a03d69312e65a407cd4953a54
Author: Martin Pitt <martin pitt ubuntu com>
Date:   Wed Jan 26 14:09:25 2011 +0100

    [GI] Backport transfer annotations

 gtk/gtkclipboard.c   |   12 +++++++-----
 gtk/gtkcontainer.c   |    5 +++--
 gtk/gtkdialog.c      |    2 +-
 gtk/gtkprogressbar.c |    7 +++++++
 gtk/gtkselection.c   |    7 ++++---
 gtk/gtktreeview.c    |    2 +-
 gtk/gtkwidget.c      |    5 +++--
 gtk/gtkwindow.c      |    2 +-
 8 files changed, 27 insertions(+), 15 deletions(-)
---
diff --git a/gtk/gtkclipboard.c b/gtk/gtkclipboard.c
index d337884..053c88a 100644
--- a/gtk/gtkclipboard.c
+++ b/gtk/gtkclipboard.c
@@ -649,7 +649,7 @@ gtk_clipboard_set_with_owner (GtkClipboard          *clipboard,
  * gtk_clipboard_clear() has not subsequently called, returns the owner set 
  * by gtk_clipboard_set_with_owner().
  * 
- * Return value: the owner of the clipboard, if any; otherwise %NULL.
+ * Return value: (transfer none): the owner of the clipboard, if any; otherwise %NULL.
  **/
 GObject *
 gtk_clipboard_get_owner (GtkClipboard *clipboard)
@@ -1407,7 +1407,8 @@ clipboard_rich_text_received_func (GtkClipboard *clipboard,
  * waits for the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  *
- * Return value: a newly-allocated binary block of data which must
+ * Return value: (array length=length) (transfer full): a
+ *               newly-allocated binary block of data which must
  *               be freed with g_free(), or %NULL if retrieving
  *               the selection data failed. (This could happen
  *               for various reasons, in particular if the
@@ -1473,7 +1474,7 @@ clipboard_image_received_func (GtkClipboard *clipboard,
  * the data to be received using the main loop, so events,
  * timeouts, etc, may be dispatched during the wait.
  * 
- * Return value: a newly-allocated #GdkPixbuf object which must
+ * Return value: (transfer full): a newly-allocated #GdkPixbuf object which must
  *               be disposed with g_object_unref(), or %NULL if 
  *               retrieving the selection data failed. (This 
  *               could happen for various reasons, in particular 
@@ -1569,7 +1570,7 @@ gtk_clipboard_wait_for_uris (GtkClipboard *clipboard)
  *
  * Gets the #GdkDisplay associated with @clipboard
  *
- * Return value: the #GdkDisplay associated with @clipboard
+ * Return value: (transfer none): the #GdkDisplay associated with @clipboard
  *
  * Since: 2.2
  **/
@@ -1725,7 +1726,8 @@ gtk_clipboard_wait_is_uris_available (GtkClipboard *clipboard)
 /**
  * gtk_clipboard_wait_for_targets
  * @clipboard: a #GtkClipboard
- * @targets: location to store an array of targets. The result
+ * @targets: (out) (array length=n_targets) (transfer container):  
+ *           location to store an array of targets. The result
  *           stored here must be freed with g_free().
  * @n_targets: location to store number of items in @targets.
  *
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 2e091e5..96dabf0 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1000,9 +1000,10 @@ gtk_container_class_find_child_property (GObjectClass *cclass,
 
 /**
  * gtk_container_class_list_child_properties:
- * @cclass: a #GtkContainerClass
+ * @cclass: (type GtkContainerClass): a #GtkContainerClass
  * @n_properties: location to return the number of child properties found
- * @returns: a newly allocated %NULL-terminated array of #GParamSpec*. 
+ * @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.
diff --git a/gtk/gtkdialog.c b/gtk/gtkdialog.c
index 32a6b9e..b85dd44 100644
--- a/gtk/gtkdialog.c
+++ b/gtk/gtkdialog.c
@@ -696,7 +696,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,
diff --git a/gtk/gtkprogressbar.c b/gtk/gtkprogressbar.c
index 798c6b4..d5b709a 100644
--- a/gtk/gtkprogressbar.c
+++ b/gtk/gtkprogressbar.c
@@ -388,6 +388,13 @@ gtk_progress_bar_get_property (GObject      *object,
     }
 }
 
+/**
+ * gtk_progress_bar_new:
+ *
+ * Creates a new #GtkProgressBar.
+ *
+ * Returns: a #GtkProgressBar.
+ */
 GtkWidget*
 gtk_progress_bar_new (void)
 {
diff --git a/gtk/gtkselection.c b/gtk/gtkselection.c
index 26f8888..45a10e8 100644
--- a/gtk/gtkselection.c
+++ b/gtk/gtkselection.c
@@ -577,7 +577,7 @@ gtk_target_list_find (GtkTargetList *list,
  * allocated and should be freed using gtk_target_table_free() when no
  * longer needed.
  *
- * Return value: the new table.
+ * Return value: (array length=n_targets) (transfer full): the new table.
  *
  * Since: 2.10
  **/
@@ -611,7 +611,7 @@ gtk_target_table_new_from_list (GtkTargetList *list,
 
 /**
  * gtk_target_table_free:
- * @targets: a #GtkTargetEntry array
+ * @targets: (array length=n_targets): a #GtkTargetEntry array
  * @n_targets: the number of entries in the array
  *
  * This function frees a target table as returned by
@@ -1798,7 +1798,8 @@ gtk_selection_data_get_uris (GtkSelectionData *selection_data)
 /**
  * gtk_selection_data_get_targets:
  * @selection_data: a #GtkSelectionData object
- * @targets: location to store an array of targets. The result
+ * @targets: (out) (array length=n_atoms) (transfer container):
+ *           location to store an array of targets. The result
  *           stored here must be freed with g_free().
  * @n_atoms: location to store number of items in @targets.
  * 
diff --git a/gtk/gtktreeview.c b/gtk/gtktreeview.c
index eea2edf..a72dc1b 100644
--- a/gtk/gtktreeview.c
+++ b/gtk/gtktreeview.c
@@ -12769,7 +12769,7 @@ gtk_tree_view_get_bin_window (GtkTreeView *tree_view)
  * @x: The x position to be identified (relative to bin_window).
  * @y: The y position to be identified (relative to bin_window).
  * @path: (out) (allow-none): A pointer to a #GtkTreePath pointer to be filled in, or %NULL
- * @column: (out) (allow-none): A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL
+ * @column: (out) (transfer none) (allow-none): A pointer to a #GtkTreeViewColumn pointer to be filled in, or %NULL
  * @cell_x: (out) (allow-none): A pointer where the X coordinate relative to the cell can be placed, or %NULL
  * @cell_y: (out) (allow-none): A pointer where the Y coordinate relative to the cell can be placed, or %NULL
  *
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index e3b3300..2428ca7 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -9845,8 +9845,9 @@ 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: an newly allocated array of #GParamSpec*. The array must 
- *       be freed with g_free().
+ * @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.
  *
diff --git a/gtk/gtkwindow.c b/gtk/gtkwindow.c
index 2966fe8..fb65161 100644
--- a/gtk/gtkwindow.c
+++ b/gtk/gtkwindow.c
@@ -3862,7 +3862,7 @@ gtk_window_set_default_icon_from_file (const gchar *filename,
  * but the pixbufs in the list have not had their reference count
  * incremented.
  * 
- * Return value: copy of default icon list 
+ * Return value: (element-type GdkPixbuf) (transfer container): copy of default icon list 
  **/
 GList*
 gtk_window_get_default_icon_list (void)