[rhythmbox/gobject-introspection: 28/34] add some annotations for widgetry (makes sendto plugin work!)

[Jonathan Matthew <jmatthew src gnome org>]

commit 92ca30976f271ed0956c1ac9d9a6c60c23e67500
Author: Jonathan Matthew <jonathan d14n org>
Date:   Wed Jul 14 01:23:16 2010 +1000

    add some annotations for widgetry (makes sendto plugin work!)

 widgets/rb-entry-view.c      |   12 ++++++------
 widgets/rb-library-browser.c |    8 ++++----
 widgets/rb-property-view.c   |    6 +++---
 widgets/rb-query-creator.c   |   12 ++++++------
 4 files changed, 19 insertions(+), 19 deletions(-)
---
diff --git a/widgets/rb-entry-view.c b/widgets/rb-entry-view.c
index f8e3a20..99fd3c2 100644
--- a/widgets/rb-entry-view.c
+++ b/widgets/rb-entry-view.c
@@ -1201,7 +1201,7 @@ rb_entry_view_sync_sorting (RBEntryView *view)
  * This consists of a column name and an order ('ascending' or 'descending')
  * separated by a comma.
  *
- * Return value: sort order description (must be freed)
+ * Return value: (transfer full): sort order description
  */
 char *
 rb_entry_view_get_sorting_type (RBEntryView *view)
@@ -1271,8 +1271,8 @@ rb_entry_view_set_sorting_type (RBEntryView *view,
 /**
  * rb_entry_view_get_sorting_order:
  * @view: a #RBEntryView
- * @column_name: returns the sort column name
- * @sort_order: returns the sort ordering as a #GtkSortType value
+ * @column_name: (out) (allow-none) (transfer full): returns the sort column name
+ * @sort_order: (out) (allow-none) returns the sort ordering as a #GtkSortType value
  *
  * Retrieves the sort settings for the view.
  */
@@ -1349,7 +1349,7 @@ rb_entry_view_column_clicked_cb (GtkTreeViewColumn *column, RBEntryView *view)
  * Retrieves a predefined column from the entry view.  This can be used
  * to insert additional cell renderers into the column.
  *
- * Return value: a #GtkTreeViewColumn instance, or NULL
+ * Return value: (transfer none) a #GtkTreeViewColumn instance, or NULL
  */
 GtkTreeViewColumn *
 rb_entry_view_get_column (RBEntryView *view, RBEntryViewColumn coltype)
@@ -2063,8 +2063,8 @@ harvest_entries (GtkTreeModel *model,
  *
  * Gathers the selected entries from the view.
  *
- * Return value: a #GList of selected entries in the view
- *  (must be freed and the entries unreffed)
+ * Return value: (element-type RhythmDBEntry) (transfer full): a #GList of
+ * selected entries in the view.
  */
 GList *
 rb_entry_view_get_selected_entries (RBEntryView *view)
diff --git a/widgets/rb-library-browser.c b/widgets/rb-library-browser.c
index 68c02fe..335e3a4 100644
--- a/widgets/rb-library-browser.c
+++ b/widgets/rb-library-browser.c
@@ -514,7 +514,7 @@ construct_query_cb (RhythmDBPropType type,
  *
  * Constructs a #RhythmDBQuery from the current selections in the browser.
  *
- * Return value: a #RhythmDBQuery constructed from the current selection.
+ * Return value: (transfer full): a #RhythmDBQuery constructed from the current selection.
  */
 RhythmDBQuery *
 rb_library_browser_construct_query (RBLibraryBrowser *widget)
@@ -754,7 +754,7 @@ destroy_idle_rebuild_model (RBLibraryBrowserRebuildData *data)
  * rb_library_browser_set_selection:
  * @widget: a #RBLibraryBrowser
  * @type: the property for which to set the selection
- * @selection: a list of strings to select
+ * @selection: (element-type utf8) (transfer none) a list of strings to select
  *
  * Replaces any current selection for the specified property.
  */
@@ -814,8 +814,8 @@ rb_library_browser_set_selection (RBLibraryBrowser *widget,
  *
  * Retrieves the property view widgets from the browser.
  *
- * Return value: a GList containing the #RBPropertyView widgets
- *  in the browser.
+ * Return value: (element-type RBPropertyView) (transfer container) a GList
+ * containing the #RBPropertyView widgets in the browser.
  */
 GList*
 rb_library_browser_get_property_views (RBLibraryBrowser *widget)
diff --git a/widgets/rb-property-view.c b/widgets/rb-property-view.c
index 9bdcde6..80dd88f 100644
--- a/widgets/rb-property-view.c
+++ b/widgets/rb-property-view.c
@@ -523,7 +523,7 @@ rb_property_view_reset (RBPropertyView *view)
  * 
  * Returns the #RhythmDBPropertyModel backing the view; no reference is taken
  *
- * Return value: property model
+ * Return value: (transfer none): property model
  */
 RhythmDBPropertyModel *
 rb_property_view_get_model (RBPropertyView *view)
@@ -740,7 +740,7 @@ rb_property_view_row_activated_cb (GtkTreeView *treeview,
 /**
  * rb_property_view_set_selection:
  * @view: a #RBPropertyView
- * @vals: the values to be selected
+ * @vals: (element-type utf8) the values to be selected
  *
  * Replaces the selection in the property view.  All values in the list
  * that are present in the view will be selected, and the view will be
@@ -785,7 +785,7 @@ rb_property_view_set_selection (RBPropertyView *view,
  * Returns a #GList containing the selected property values.  The list must
  * be freed by the caller.
  *
- * Return value: list of selected values
+ * Return value: (element-type utf8) (transfer full) list of selected values
  */
 GList *
 rb_property_view_get_selection (RBPropertyView *view)
diff --git a/widgets/rb-query-creator.c b/widgets/rb-query-creator.c
index d631c39..e7e8827 100644
--- a/widgets/rb-query-creator.c
+++ b/widgets/rb-query-creator.c
@@ -522,7 +522,7 @@ rb_query_creator_new_from_query (RhythmDB *db,
  *
  * Extracts a child widget from a #GtkBox.
  *
- * Return value: child widget from the box
+ * Return value: (transfer none): child widget from the box
  */
 GtkWidget *
 get_box_widget_at_pos (GtkBox *box, guint pos)
@@ -566,7 +566,7 @@ get_entry_for_property (RBQueryCreator *creator,
  *
  * Constructs a database query that represents the criteria in the query creator.
  *
- * Return value: database query array
+ * Return value: (transfer full): database query array
  */
 GPtrArray *
 rb_query_creator_get_query (RBQueryCreator *creator)
@@ -630,8 +630,8 @@ rb_query_creator_get_query (RBQueryCreator *creator)
 /**
  * rb_query_creator_get_limit:
  * @creator: #RBQueryCreator instance
- * @type: used to return the limit type
- * @limit: used to return the limit value
+ * @type: (out): used to return the limit type
+ * @limit: (out): used to return the limit value
  *
  * Retrieves the limit type and value from the query creator.
  * The limit value is returned as the first element in a
@@ -686,8 +686,8 @@ rb_query_creator_get_limit (RBQueryCreator *creator,
 /**
  * rb_query_creator_get_sort_order:
  * @creator: #RBQueryCreator instance
- * @sort_key: returns the sort key name
- * @sort_direction: returns the sort direction
+ * @sort_key: (out) (allow-none): returns the sort key name
+ * @sort_direction: (out) (allow-none): returns the sort direction
  *
  * Retrieves the sort settings from the query creator.
  * The sort direction is returned as a #GtkSortType value.