[rhythmbox] Update annotations for gobject-introspection



commit 9a84078beefac3d584ed97ab045c79a5913380e3
Author: Jonathan Matthew <jonathan d14n org>
Date:   Tue Feb 1 08:03:28 2011 +1000

    Update annotations for gobject-introspection

 backends/rb-encoder.c                |   12 +++---
 backends/rb-encoder.h                |    6 +-
 backends/rb-player.c                 |    2 +-
 backends/rb-player.h                 |    2 +-
 lib/libmediaplayerid/mpid-util.c     |    2 +-
 lib/rb-builder-helpers.c             |    2 +-
 lib/rb-debug.c                       |   10 ++--
 lib/rb-file-helpers.c                |    4 +-
 lib/rb-string-value-map.c            |    2 +-
 lib/rb-util.c                        |   79 +++++++++++++++++-----------------
 metadata/rb-metadata-dbus-client.c   |   14 +++---
 rhythmdb/rhythmdb-entry.h            |    4 +-
 rhythmdb/rhythmdb-private.h          |    2 +-
 rhythmdb/rhythmdb-query.c            |   10 +++--
 rhythmdb/rhythmdb-song-entry-types.c |    2 +-
 rhythmdb/rhythmdb.c                  |   33 +++++++-------
 rhythmdb/rhythmdb.h                  |    4 --
 shell/rb-history.c                   |   16 +++---
 shell/rb-play-order.c                |   34 +++++++++++----
 shell/rb-playlist-manager.c          |   32 +++++++-------
 shell/rb-plugin.c                    |    4 +-
 shell/rb-plugin.h                    |    9 ++--
 shell/rb-removable-media-manager.c   |    6 +++
 shell/rb-shell-player.c              |   20 ++++----
 shell/rb-shell-preferences.c         |    6 +-
 shell/rb-shell.c                     |   14 +++---
 shell/rb-track-transfer-batch.c      |    2 +-
 shell/rb-track-transfer-queue.c      |    2 +-
 sources/rb-auto-playlist-source.c    |   12 +++---
 sources/rb-browser-source.c          |    3 +-
 sources/rb-display-page-group.c      |    2 +-
 sources/rb-display-page-model.c      |    2 +-
 sources/rb-display-page-tree.c       |    2 +-
 sources/rb-display-page.c            |   35 +++++++++++++--
 sources/rb-media-player-source.c     |   40 +++++++++++++++--
 sources/rb-playlist-source.c         |    4 +-
 sources/rb-removable-media-source.c  |   23 +++++++++-
 sources/rb-source-search.c           |    6 +-
 sources/rb-source.c                  |   67 +++++++++++++++++++++++-----
 sources/rb-static-playlist-source.c  |    2 +-
 sources/rb-streaming-source.c        |    4 +-
 widgets/rb-dialog.c                  |    2 +-
 widgets/rb-entry-view.c              |   22 +++++-----
 widgets/rb-library-browser.c         |   12 +++---
 widgets/rb-property-view.c           |    6 +-
 widgets/rb-query-creator.c           |   12 +++---
 widgets/rb-segmented-bar.c           |    8 +++
 47 files changed, 372 insertions(+), 227 deletions(-)
---
diff --git a/backends/rb-encoder.c b/backends/rb-encoder.c
index 02ad222..6c6d327 100644
--- a/backends/rb-encoder.c
+++ b/backends/rb-encoder.c
@@ -208,7 +208,7 @@ rb_encoder_get_type (void)
  *
  * Returns the #RBEncoderFactory instance.
  *
- * Return value: the #RBEncoderFactory
+ * Return value: (transfer none): the #RBEncoderFactory
  */
 RBEncoderFactory *
 rb_encoder_factory_get ()
@@ -266,9 +266,9 @@ rb_encoder_cancel (RBEncoder *encoder)
  * rb_encoder_get_media_type:
  * @encoder: a #RBEncoder
  * @entry: the source #RhythmDBEntry
- * @dest_media_types: a #GList of media type strings in order of preference
- * @media_type: returns the selected media type, if any
- * @extension: returns the file extension associated with the selected media type, if any
+ * @dest_media_types: (element-type utf8): media type strings in order of preference
+ * @media_type: (out callee-allocates) (allow-none): returns the selected media type, if any
+ * @extension: (out callee-allocates) (allow-none): returns the file extension associated with the selected media type, if any
  *
  * Identifies the first media type in the list that the encoder can actually encode to.
  * The file extension (eg. '.mp3' for audio/mpeg) associated with the selected type is
@@ -292,7 +292,7 @@ rb_encoder_get_media_type (RBEncoder *encoder,
  * rb_encoder_get_missing_plugins:
  * @encoder: a #RBEncoder
  * @media_type: the media type required
- * @details: returns plugin installer detail strings
+ * @details: (out callee-allocates): returns plugin installer detail strings
  *
  * Retrieves the plugin installer detail strings for any missing plugins
  * required to encode the specified media type.
@@ -313,7 +313,7 @@ rb_encoder_get_missing_plugins (RBEncoder *encoder,
  *
  * Creates a new #RBEncoder instance.
  *
- * Return value: the new #RBEncoder
+ * Return value: (transfer full): the new #RBEncoder
  */
 RBEncoder*
 rb_encoder_new (void)
diff --git a/backends/rb-encoder.h b/backends/rb-encoder.h
index 21d9f6f..4bef216 100644
--- a/backends/rb-encoder.h
+++ b/backends/rb-encoder.h
@@ -47,17 +47,17 @@ G_BEGIN_DECLS
 #define RB_IS_ENCODER_FACTORY_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_ENCODER_FACTORY))
 #define RB_ENCODER_FACTORY_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_ENCODER_FACTORY, RBEncoderFactoryClass))
 
-enum
+typedef enum
 {
 	RB_ENCODER_ERROR_FORMAT_UNSUPPORTED,
 	RB_ENCODER_ERROR_INTERNAL,
 	RB_ENCODER_ERROR_FILE_ACCESS,
 	RB_ENCODER_ERROR_OUT_OF_SPACE,
 	RB_ENCODER_ERROR_DEST_READ_ONLY
-};
+} RBEncoderError;
 
 GType rb_encoder_error_get_type (void);
-#define RB_TYPE_ENCODER_ERROR	(rb_encoer_error_get_type())
+#define RB_TYPE_ENCODER_ERROR	(rb_encoder_error_get_type())
 #define RB_ENCODER_ERROR rb_encoder_error_quark ()
 GQuark rb_encoder_error_quark (void);
 
diff --git a/backends/rb-player.c b/backends/rb-player.c
index fc10c4f..c8de8fc 100644
--- a/backends/rb-player.c
+++ b/backends/rb-player.c
@@ -576,7 +576,7 @@ rb_player_multiple_open (RBPlayer *player)
  *
  * Creates a new player object.
  *
- * Return value: new player object.
+ * Return value: (transfer full): new player object.
  */
 RBPlayer*
 rb_player_new (gboolean want_crossfade, GError **error)
diff --git a/backends/rb-player.h b/backends/rb-player.h
index f82e9af..daf42bd 100644
--- a/backends/rb-player.h
+++ b/backends/rb-player.h
@@ -98,7 +98,7 @@ struct _RBPlayerIface
 
 	gboolean	(*seekable)		(RBPlayer *player);
 	void		(*set_time)		(RBPlayer *player,
-						 gint64 time);
+						 gint64 newtime);
 	gint64		(*get_time)		(RBPlayer *player);
 	gboolean	(*multiple_open)	(RBPlayer *player);
 
diff --git a/lib/libmediaplayerid/mpid-util.c b/lib/libmediaplayerid/mpid-util.c
index 7e70774..2986c19 100644
--- a/lib/libmediaplayerid/mpid-util.c
+++ b/lib/libmediaplayerid/mpid-util.c
@@ -54,7 +54,7 @@ mpid_error_get_type (void)
 			{ 0, 0, 0 }
 		};
 
-		etype = g_enum_register_static ("MPIDErrorType", values);
+		etype = g_enum_register_static ("MPIDError", values);
 	}
 
 	return etype;
diff --git a/lib/rb-builder-helpers.c b/lib/rb-builder-helpers.c
index 10cf3cd..bc8ed33 100644
--- a/lib/rb-builder-helpers.c
+++ b/lib/rb-builder-helpers.c
@@ -51,7 +51,7 @@
  * relative to the shared data directory, or its 'ui' or 'art'
  * subdirectories.
  *
- * Return value: #GtkBuilder object built from the file
+ * Return value: (transfer full): #GtkBuilder object built from the file
  */
 GtkBuilder *
 rb_builder_load (const char *file, gpointer user_data)
diff --git a/lib/rb-debug.c b/lib/rb-debug.c
index b45eead..f1ed2c0 100644
--- a/lib/rb-debug.c
+++ b/lib/rb-debug.c
@@ -220,7 +220,7 @@ rb_debug_init_match (const char *match)
  * this debug output code that will produce the same debug output
  * settings.
  *
- * Return value: debug output arguments, must be freed with #g_strfreev()
+ * Return value: (transfer full): debug output arguments, must be freed with #g_strfreev()
  */
 char **
 rb_debug_get_args (void)
@@ -280,7 +280,7 @@ struct RBProfiler
 };
 
 /**
- * rb_profiler_new:
+ * rb_profiler_new: (skip):
  * @name: profiler name
  *
  * Creates a new profiler instance.  This can be used to
@@ -306,7 +306,7 @@ rb_profiler_new (const char *name)
 }
 
 /**
- * rb_profiler_dump:
+ * rb_profiler_dump: (skip):
  * @profiler: profiler instance
  *
  * Produces debug output for the profiler instance,
@@ -330,7 +330,7 @@ rb_profiler_dump (RBProfiler *profiler)
 }
 
 /**
- * rb_profiler_reset:
+ * rb_profiler_reset: (skip):
  * @profiler: profiler instance
  *
  * Resets the elapsed time for the profiler
@@ -347,7 +347,7 @@ rb_profiler_reset (RBProfiler *profiler)
 }
 
 /**
- * rb_profiler_free:
+ * rb_profiler_free: (skip):
  * @profiler: profiler instance to destroy
  *
  * Frees the memory associated with a profiler instance.
diff --git a/lib/rb-file-helpers.c b/lib/rb-file-helpers.c
index 1b121af..6b61e30 100644
--- a/lib/rb-file-helpers.c
+++ b/lib/rb-file-helpers.c
@@ -838,7 +838,7 @@ _uri_handle_recurse (GFile *dir,
  * rb_uri_handle_recursively:
  * @uri: URI to visit
  * @cancel: an optional #GCancellable to allow cancellation
- * @func: Callback function
+ * @func: (scope call): Callback function
  * @user_data: Data for callback function
  *
  * Calls @func for each file found under the directory identified by @uri.
@@ -1384,7 +1384,7 @@ rb_uri_create_parent_dirs (const char *uri, GError **error)
  * the nearest extant ancestor of the specified file, which may be
  * the file itself if it exists.
  * 
- * Return value: #GFile for the nearest extant ancestor
+ * Return value: (transfer full): #GFile for the nearest extant ancestor
  */
 GFile *
 rb_file_find_extant_parent (GFile *file)
diff --git a/lib/rb-string-value-map.c b/lib/rb-string-value-map.c
index 3130f06..d31dca9 100644
--- a/lib/rb-string-value-map.c
+++ b/lib/rb-string-value-map.c
@@ -197,7 +197,7 @@ rb_string_value_map_peek (RBStringValueMap *map,
  * Extracts and returns the underlying hash table from the map,
  * and creates a new empty map.
  *
- * Return value: #GHashTable from the map
+ * Return value: (transfer full): #GHashTable from the map
  */
 GHashTable*
 rb_string_value_map_steal_hashtable (RBStringValueMap *map)
diff --git a/lib/rb-util.c b/lib/rb-util.c
index dece114..ebf486a 100644
--- a/lib/rb-util.c
+++ b/lib/rb-util.c
@@ -52,7 +52,7 @@
 static GPrivate * private_is_primary_thread;
 
 /**
- * rb_true_function:
+ * rb_true_function: (skip):
  * @dummy: unused
  *
  * Just returns %TRUE, useful as a callback function.
@@ -66,7 +66,7 @@ rb_true_function (gpointer dummy)
 }
 
 /**
- * rb_false_function:
+ * rb_false_function: (skip):
  * @dummy: unused
  *
  * Just returns %FALSE, useful as a callback function.
@@ -80,7 +80,7 @@ rb_false_function (gpointer dummy)
 }
 
 /**
- * rb_null_function:
+ * rb_null_function: (skip):
  * @dummy: unused
  *
  * Just returns NULL.  Useful as a callback function.
@@ -94,7 +94,7 @@ rb_null_function (gpointer dummy)
 }
 
 /**
- * rb_copy_function:
+ * rb_copy_function: (skip):
  * @data: generic argument
  *
  * Just returns its first argument.  Useful as a callback function.
@@ -109,7 +109,7 @@ rb_copy_function (gpointer data)
 
 
 /**
- * rb_gvalue_compare:
+ * rb_gvalue_compare: (skip):
  * @a: left hand side
  * @b: right hand size
  *
@@ -337,7 +337,7 @@ totem_pixbuf_mirror (GdkPixbuf *pixbuf)
  * Same as @gtk_image_new_from_stock except that it mirrors the icons for RTL
  * languages.
  *
- * Return value: a #GtkImage of the requested stock item
+ * Return value: (transfer full): a #GtkImage of the requested stock item
  */
 GtkWidget *
 rb_image_new_from_stock (const gchar *stock_id, GtkIconSize size)
@@ -377,7 +377,7 @@ rb_image_new_from_stock (const gchar *stock_id, GtkIconSize size)
 }
 
 /**
- * rb_gtk_action_popup_menu:
+ * rb_gtk_action_popup_menu: (skip):
  * @uimanager: a #GtkUIManager
  * @path: UI path for the popup to display
  *
@@ -440,7 +440,7 @@ _threads_leave (void)
 
 
 /**
- * rb_assert_locked:
+ * rb_assert_locked: (skip):
  * @mutex: a #GMutex
  *
  * Asserts that @mutex is currently locked.  Does not work with all
@@ -454,7 +454,7 @@ rb_assert_locked (GMutex *mutex)
 }
 
 /**
- * rb_threads_init:
+ * rb_threads_init: (skip):
  *
  * Initializes various thread helpers.  Must be called on startup.
  */
@@ -491,7 +491,7 @@ rb_threads_init (void)
  *
  * Splits @string on word boundaries using Unicode character definitions.
  *
- * Return value: NULL-terminated array of strings, must be freed by caller (see @g_strfreev)
+ * Return value: (array zero-terminated=1) (transfer full): NULL-terminated array of strings
  */
 gchar **
 rb_string_split_words (const gchar *string)
@@ -605,7 +605,7 @@ rb_string_split_words (const gchar *string)
  * Returns a case-folded and punctuation-stripped version of @original, useful
  * for performing text searches.
  *
- * Return value: case-folded string, must be freed by caller.
+ * Return value: (transfer full): case-folded string
  */
 gchar*
 rb_search_fold (const char *original)
@@ -680,7 +680,7 @@ rb_search_fold (const char *original)
  * Constructs a string describing the specified duration.  The string
  * describes hours, minutes, and seconds, and its format is localised.
  *
- * Return value: duration string, must be freed by caller.
+ * Return value: (transfer full): duration string
  */
 char *
 rb_make_duration_string (guint duration)
@@ -712,7 +712,7 @@ rb_make_duration_string (guint duration)
  * minutes, and seconds, and its format is localised.  The string can describe either
  * the elapsed time or the time remaining.
  *
- * Return value: elapsed/remaining time string, must be freed by caller
+ * Return value: (transfer full): elapsed/remaining time string
  */
 char *
 rb_make_elapsed_time_string (guint elapsed, guint duration, gboolean show_remaining)
@@ -764,9 +764,9 @@ rb_make_elapsed_time_string (guint elapsed, guint duration, gboolean show_remain
 }
 
 /**
- * rb_string_list_equal:
- * @a: list of strings to compare
- * @b: other list of strings to compare
+ * rb_string_list_equal: (skip):
+ * @a: (element-type utf8): list of strings to compare
+ * @b: (element-type utf8): other list of strings to compare
  *
  * Checks if @a and @b contain exactly the same set of strings,
  * regardless of order.
@@ -819,13 +819,12 @@ list_copy_cb (const char *s, GList **list)
 }
 
 /**
- * rb_string_list_copy:
- * @list: list of strings to copy
+ * rb_string_list_copy: (skip):
+ * @list: (element-type utf8): list of strings to copy
  *
  * Creates a deep copy of @list.
  *
- * Return value: copied list, must be freed (and its contents freed)
- *  by caller
+ * Return value: (element-type utf8) (transfer full): copied list
  */
 GList *
 rb_string_list_copy (GList *list)
@@ -842,8 +841,8 @@ rb_string_list_copy (GList *list)
 }
 
 /**
- * rb_string_list_contains:
- * @list: list to check
+ * rb_string_list_contains: (skip):
+ * @list: (element-type utf8) list to check
  * @s: string to check for
  *
  * Checks if @list contains the string @s.
@@ -864,7 +863,7 @@ rb_string_list_contains (GList *list, const char *s)
 }
 
 /**
- * rb_list_destroy_free:
+ * rb_list_destroy_free: (skip):
  * @list: list to destroy
  * @destroyer: function to call to free elements of @list
  *
@@ -878,8 +877,8 @@ rb_list_destroy_free (GList *list, GDestroyNotify destroyer)
 }
 
 /**
- * rb_list_deep_free:
- * @list: list to free
+ * rb_list_deep_free: (skip):
+ * @list: (element-type any) (transfer full): list to free
  *
  * Frees each element of @list and @list itself.
  */
@@ -890,8 +889,8 @@ rb_list_deep_free (GList *list)
 }
 
 /**
- * rb_slist_deep_free:
- * @list: list to free
+ * rb_slist_deep_free: (skip):
+ * @list: (element-type any) (transfer full): list to free
  *
  * Frees each element of @list and @list itself.
  */
@@ -915,13 +914,13 @@ collate_values_cb (gpointer key, gpointer value, GList **list)
 }
 
 /**
- * rb_collate_hash_table_keys:
+ * rb_collate_hash_table_keys: (skip):
  * @table: #GHashTable to collate
  *
  * Returns a #GList containing all keys from @table.  The keys are
  * not copied.
  *
- * Return value: #GList of keys, must be freed by caller
+ * Return value: (element-type any) (transfer container): #GList of keys
  */
 GList*
 rb_collate_hash_table_keys (GHashTable *table)
@@ -935,13 +934,13 @@ rb_collate_hash_table_keys (GHashTable *table)
 }
 
 /**
- * rb_collate_hash_table_values:
+ * rb_collate_hash_table_values: (skip):
  * @table: #GHashTable to collate
  *
  * Returns a #GList containing all values from @table.  The values are
  * not copied.
  *
- * Return value: #GList of values, must be freed by caller
+ * Return value: (element-type any) (transfer container): #GList of values
  */
 GList*
 rb_collate_hash_table_values (GHashTable *table)
@@ -961,7 +960,7 @@ rb_collate_hash_table_values (GHashTable *table)
  * Converts a single string containing a list of URIs into
  * a #GList of URI strings.
  *
- * Return value: #GList of URI strings, must be deep-freed by caller
+ * Return value: (element-type utf8) (transfer full): #GList of URI strings
  */
 GList *
 rb_uri_list_parse (const char *uri_list)
@@ -1027,7 +1026,7 @@ rb_mime_get_friendly_name (const char *mime_type)
 }
 
 /**
- * rb_signal_accumulator_object_handled:
+ * rb_signal_accumulator_object_handled: (skip):
  * @hint: a #GSignalInvocationHint
  * @return_accu: holds the accumulated return value
  * @handler_return: holds the return value to be accumulated
@@ -1059,7 +1058,7 @@ rb_signal_accumulator_object_handled (GSignalInvocationHint *hint,
 }
 
 /**
- * rb_signal_accumulator_value_array:
+ * rb_signal_accumulator_value_array: (skip):
  * @hint: a #GSignalInvocationHint
  * @return_accu: holds the accumulated return value
  * @handler_return: holds the return value to be accumulated
@@ -1110,7 +1109,7 @@ rb_signal_accumulator_value_array (GSignalInvocationHint *hint,
 }
 
 /**
- * rb_value_array_append_data:
+ * rb_value_array_append_data: (skip):
  * @array: #GValueArray to append to
  * @type: #GType of the value being appended
  * @Varargs: value to append
@@ -1138,8 +1137,8 @@ rb_value_array_append_data (GValueArray *array, GType type, ...)
 }
 
 /**
- * rb_value_free:
- * @val: a #GValue
+ * rb_value_free: (skip):
+ * @val: (transfer full): a #GValue
  *
  * Unsets and frees @val.  @val must have been allocated using
  * @g_slice_new or @g_slice_new0.
@@ -1152,7 +1151,7 @@ rb_value_free (GValue *val)
 }
 
 /**
- * rb_str_in_strv:
+ * rb_str_in_strv: (skip):
  * @needle: string to search for
  * @haystack: array of strings to search
  *
@@ -1182,7 +1181,7 @@ rb_str_in_strv (const char *needle, const char **haystack)
  * @treeview: the #GtkTreeView containing the column
  * @column: the #GtkTreeViewColumn to size
  * @renderer: the #GtkCellRenderer used in the column
- * @strings: a NULL-terminated set of strings to base the size on
+ * @strings: (array zero-terminated=1): a NULL-terminated set of strings to base the size on
  * @padding: a small amount of extra padding for the column
  *
  * Sets a fixed size for a tree view column based on
@@ -1224,7 +1223,7 @@ rb_set_tree_view_column_fixed_width (GtkWidget  *treeview,
  * Creates a new #GdkPixbuf from the original one, for a target of
  * size, respecting the aspect ratio of the image.
  *
- * Return value: scaled #GdkPixbuf
+ * Return value: (transfer full): scaled #GdkPixbuf
  */
 GdkPixbuf *
 rb_scale_pixbuf_to_size (GdkPixbuf *pixbuf, GtkIconSize size)
diff --git a/metadata/rb-metadata-dbus-client.c b/metadata/rb-metadata-dbus-client.c
index 9009bb3..56e83bb 100644
--- a/metadata/rb-metadata-dbus-client.c
+++ b/metadata/rb-metadata-dbus-client.c
@@ -615,8 +615,10 @@ rb_metadata_has_missing_plugins (RBMetaData *md)
 /**
  * rb_metadata_get_missing_plugins:
  * @md: a #RBMetaData
- * @missing_plugins: returns machine-readable missing plugin information
- * @plugin_descriptions: returns human-readable missing plugin descriptions
+ * @missing_plugins: (out) (array zero-terminated=1): returns machine-readable
+ * missing plugin information
+ * @plugin_descriptions: (out) (array zero-terminated=1): returns human-readable
+ * missing plugin descriptions
  *
  * This function returns the information used to request automatic
  * installation of media framework plugins required to decode the target URI.
@@ -643,7 +645,7 @@ rb_metadata_get_missing_plugins (RBMetaData *md,
  * rb_metadata_get:
  * @md: a #RBMetaData
  * @field: the #RBMetaDataField to retrieve
- * @val: returns the field value
+ * @val: (out caller-allocates) (transfer full): returns the field value
  *
  * Retrieves the value of a metadata field extracted from the target URI.
  * If the target URI contained no value for the field, returns FALSE.
@@ -670,7 +672,7 @@ rb_metadata_get (RBMetaData *md, RBMetaDataField field, GValue *ret)
  * rb_metadata_set:
  * @md: a #RBMetaData
  * @field: the #RBMetaDataField to set
- * @val: the vaule to set
+ * @val: the value to set
  *
  * Sets a metadata field value.  The value is only stored inside the
  * #RBMetaData object until rb_metadata_save is called.
@@ -742,8 +744,8 @@ rb_metadata_can_save (RBMetaData *md, const char *mimetype)
  * Constructs a list of the media types for which the metadata backend
  * implements tag saving.
  *
- * Return value: a NULL-terminated array of media type strings.  Use g_strfreev
- *  to free it.
+ * Return value: (transfer full) (array zero-terminated=1): a NULL-terminated
+ * array of media type strings.  Use g_strfreev to free it.
  */
 char **
 rb_metadata_get_saveable_types (RBMetaData *md)
diff --git a/rhythmdb/rhythmdb-entry.h b/rhythmdb/rhythmdb-entry.h
index c24a4e0..068dc50 100644
--- a/rhythmdb/rhythmdb-entry.h
+++ b/rhythmdb/rhythmdb-entry.h
@@ -32,8 +32,8 @@
 
 G_BEGIN_DECLS
 
-struct RhythmDBEntry_;
-typedef struct RhythmDBEntry_ RhythmDBEntry;
+struct _RhythmDBEntry;
+typedef struct _RhythmDBEntry RhythmDBEntry;
 GType rhythmdb_entry_get_type (void);
 
 #define RHYTHMDB_TYPE_ENTRY      (rhythmdb_entry_get_type ())
diff --git a/rhythmdb/rhythmdb-private.h b/rhythmdb/rhythmdb-private.h
index 0e657c6..aa1bffd 100644
--- a/rhythmdb/rhythmdb-private.h
+++ b/rhythmdb/rhythmdb-private.h
@@ -64,7 +64,7 @@ enum {
 	RHYTHMDB_ENTRY_PRIVATE_FLAG_BASE = 65536,
 };
 
-struct RhythmDBEntry_ {
+struct _RhythmDBEntry {
 	/* internal bits */
 	guint flags;
 	volatile gint refcount;
diff --git a/rhythmdb/rhythmdb-query.c b/rhythmdb/rhythmdb-query.c
index 24d8f4f..294bd41 100644
--- a/rhythmdb/rhythmdb-query.c
+++ b/rhythmdb/rhythmdb-query.c
@@ -63,7 +63,8 @@
  *
  * Creates a copy of a query.
  *
- * Return value: a copy of the passed query. It must be freed with rhythmdb_query_free()
+ * Return value: (transfer full): a copy of the passed query.
+ * It must be freed with rhythmdb_query_free()
  **/
 GPtrArray *
 rhythmdb_query_copy (GPtrArray *array)
@@ -205,7 +206,8 @@ rhythmdb_query_parse_valist (RhythmDB *db, va_list args)
  * 	b) that have "cat" in their title, or
  * 	c) have a rating of at least 2.5, and a play count of at most 10
  *
- * Returns: a the newly created query. It must be freed with rhythmdb_query_free()
+ * Returns: (transfer full): a the newly created query.
+ * It must be freed with rhythmdb_query_free()
  **/
 GPtrArray *
 rhythmdb_query_parse (RhythmDB *db, ...)
@@ -593,7 +595,7 @@ rhythmdb_query_serialize (RhythmDB *db, GPtrArray *query,
  *
  * Converts a serialized query back into a @GPtrArray query.
  *
- * Return value: deserialized query.
+ * Return value: (transfer full): deserialized query.
  */
 GPtrArray *
 rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr parent)
@@ -861,7 +863,7 @@ rhythmdb_query_preprocess (RhythmDB *db, GPtrArray *query)
  * @db: the #RhythmDB
  * @query: the query to append to
  * @propid: property ID to match
- * @items: #GList of values to match against
+ * @items: (element-type GObject.Value): #GList of values to match against
  *
  * Appends a set of criteria to a query to match against any of the values
  * listed in @items.
diff --git a/rhythmdb/rhythmdb-song-entry-types.c b/rhythmdb/rhythmdb-song-entry-types.c
index 1ed629b..9e83e07 100644
--- a/rhythmdb/rhythmdb-song-entry-types.c
+++ b/rhythmdb/rhythmdb-song-entry-types.c
@@ -194,7 +194,7 @@ import_error_update_availability (RhythmDBEntryType *entry_type,
  *
  * Returns the #RhythmDBEntryType for normal songs.
  *
- * Return value: (transfer none): the entry type for normal songs
+ * Returns: (transfer none): the entry type for normal songs
  */
 RhythmDBEntryType *
 rhythmdb_get_song_entry_type (void)
diff --git a/rhythmdb/rhythmdb.c b/rhythmdb/rhythmdb.c
index aad947d..7ab1210 100644
--- a/rhythmdb/rhythmdb.c
+++ b/rhythmdb/rhythmdb.c
@@ -603,7 +603,7 @@ rhythmdb_class_init (RhythmDBClass *klass)
 	 *
 	 * Emitted to request creation of a #GMountOperation to use to mount a volume.
 	 *
-	 * Return value: a #GMountOperation (usually actually a #GtkMountOperation)
+	 * Returns: (transfer full): a #GMountOperation (usually actually a #GtkMountOperation)
 	 */
 	rhythmdb_signals[CREATE_MOUNT_OP] =
 		g_signal_new ("create-mount-op",
@@ -1698,7 +1698,7 @@ rhythmdb_entry_allocate (RhythmDB *db,
  * Callers should use the RHYTHMDB_ENTRY_GET_TYPE_DATA macro for
  * a slightly more friendly interface to this functionality.
  *
- * Return value: type-specific data pointer
+ * Return value: (transfer none): type-specific data pointer
  */
 gpointer
 rhythmdb_entry_get_type_data (RhythmDBEntry *entry,
@@ -3895,7 +3895,7 @@ rhythmdb_entry_lookup_from_string (RhythmDB *db,
 /**
  * rhythmdb_entry_foreach:
  * @db: a #RhythmDB.
- * @func: the function to call with each entry.
+ * @func: (scope call): the function to call with each entry.
  * @data: user data to pass to the function.
  *
  * Calls the given function for each of the entries in the database.
@@ -3930,7 +3930,7 @@ rhythmdb_entry_count (RhythmDB *db)
  * rhythmdb_entry_foreach_by_type:
  * @db: a #RhythmDB.
  * @entry_type: the type of entry to retrieve
- * @func: the function to call with each entry
+ * @func: (scope call): the function to call with each entry
  * @data: user data to pass to the function.
  *
  * Calls the given function for each of the entries in the database
@@ -4325,7 +4325,7 @@ rhythmdb_emit_entry_extra_metadata_notify (RhythmDB *db,
 }
 
 /**
- * rhythmdb_entry_extra_gather:
+ * rhythmdb_entry_gather_metadata:
  * @db: a #RhythmDB
  * @entry: a #RhythmDBEntry
  *
@@ -4335,8 +4335,8 @@ rhythmdb_emit_entry_extra_metadata_notify (RhythmDB *db,
  * provide extra metadata should connect to the "entry_extra_metadata_gather"
  * signal.
  *
- * Returns: a RBStringValueMap containing metadata for the entry.  This must be freed
- * using g_object_unref.
+ * Returns: (transfer full): a RBStringValueMap containing metadata for the entry.
+ * This must be freed using g_object_unref.
  */
 RBStringValueMap *
 rhythmdb_entry_gather_metadata (RhythmDB *db,
@@ -4428,19 +4428,19 @@ rhythmdb_is_busy (RhythmDB *db)
  * rhythmdb_get_progress_info:
  * @db: a #RhythmDB.
  * @text: used to return progress text
- * @fraction: used to return progress fraction
+ * @progress: used to return progress fraction
  *
  * Provides progress information for rhythmdb operations, if any are running.
  */
 void
-rhythmdb_get_progress_info (RhythmDB *db, char **text, float *fraction)
+rhythmdb_get_progress_info (RhythmDB *db, char **text, float *progress)
 {
 	if (db->priv->stat_thread_running && db->priv->stat_thread_count > 0) {
 		g_free (*text);
 		*text = g_strdup_printf (_("Checking (%d/%d)"),
 					 db->priv->stat_thread_done,
 					 db->priv->stat_thread_count);
-		*fraction = ((float)db->priv->stat_thread_done /
+		*progress = ((float)db->priv->stat_thread_done /
 			     (float)db->priv->stat_thread_count);
 	}
 }
@@ -4596,7 +4596,7 @@ rhythmdb_entry_type_foreach (RhythmDB *db,
  * Locates a #RhythmDBEntryType by name. Returns NULL if no entry
  * type is registered with the specified name.
  *
- * Returns: the #RhythmDBEntryType
+ * Returns: (transfer none): the #RhythmDBEntryType
  */
 RhythmDBEntryType *
 rhythmdb_entry_type_get_by_name (RhythmDB *db,
@@ -4999,7 +4999,7 @@ rhythmdb_entry_get_uint64 (RhythmDBEntry *entry,
  * entry type properties, to check that entries are of the same type,
  * and to call entry type methods.
  *
- * Return value: the #RhythmDBEntryType for @entry
+ * Return value: (transfer none): the #RhythmDBEntryType for @entry
  */
 RhythmDBEntryType *
 rhythmdb_entry_get_entry_type (RhythmDBEntry *entry)
@@ -5016,7 +5016,7 @@ rhythmdb_entry_get_entry_type (RhythmDBEntry *entry)
  *
  * Returns the value of an object property of @entry.
  *
- * Return value: property value
+ * Return value: (transfer none): property value
  */
 GObject *
 rhythmdb_entry_get_object (RhythmDBEntry *entry,
@@ -5217,11 +5217,10 @@ rhythmdb_entry_keyword_has	(RhythmDB *db,
  *
  * Gets the list ofkeywords that have been added to an entry.
  *
- * Returns: the list of keywords that have been added to the entry.
- *          The caller is responsible for unref'ing the RBRefStrings and
- *          freeing the list with g_list_free.
+ * Returns: (element-type RBRefString) (transfer full): the list of keywords
+ *          that have been added to the entry.
  */
-GList* /*<RBRefString>*/
+GList*
 rhythmdb_entry_keywords_get	(RhythmDB *db,
 				 RhythmDBEntry *entry)
 {
diff --git a/rhythmdb/rhythmdb.h b/rhythmdb/rhythmdb.h
index 9e03748..4c68f3b 100644
--- a/rhythmdb/rhythmdb.h
+++ b/rhythmdb/rhythmdb.h
@@ -158,14 +158,12 @@ typedef enum
 	RHYTHMDB_PROP_ALBUM_SORTNAME_FOLDED,
 
 	RHYTHMDB_PROP_COMMENT,
-
 	RHYTHMDB_PROP_ALBUM_ARTIST,
 	RHYTHMDB_PROP_ALBUM_ARTIST_SORT_KEY,
 	RHYTHMDB_PROP_ALBUM_ARTIST_FOLDED,
 	RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME,
 	RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME_SORT_KEY,
 	RHYTHMDB_PROP_ALBUM_ARTIST_SORTNAME_FOLDED,
-
 	RHYTHMDB_PROP_BPM,
 
 	RHYTHMDB_NUM_PROPERTIES
@@ -308,8 +306,6 @@ struct _RhythmDBClass
 
 GType		rhythmdb_get_type	(void);
 
-RhythmDB *	rhythmdb_new		(const char *name);
-
 void		rhythmdb_shutdown	(RhythmDB *db);
 
 void		rhythmdb_load		(RhythmDB *db);
diff --git a/shell/rb-history.c b/shell/rb-history.c
index e8b9564..4e114eb 100644
--- a/shell/rb-history.c
+++ b/shell/rb-history.c
@@ -136,7 +136,7 @@ rb_history_class_init (RBHistoryClass *klass)
 /**
  * rb_history_new:
  * @truncate_on_play: Whether rb_history_set_playing() should truncate the history
- * @destroyer: function to call when removing an entry from the history
+ * @destroyer: (scope async): function to call when removing an entry from the history
  * @destroy_userdata: data to pass to @destroyer
  *
  * Creates a new history instance.
@@ -238,7 +238,7 @@ rb_history_get_property (GObject *object,
 /**
  * rb_history_set_destroy_notify:
  * @hist: a #RBHistory
- * @destroyer: function to call when removing an entry from the history
+ * @destroyer: (scope async): function to call when removing an entry from the history
  * @destroy_userdata: data to pass to @destroyer
  *
  * Sets a new function to call when removing entries from the history.
@@ -306,7 +306,7 @@ rb_history_length (RBHistory *hist)
  *
  * Returns the first entry in the history.
  *
- * Return value: first entry
+ * Return value: (transfer none): first entry
  */
 RhythmDBEntry *
 rb_history_first (RBHistory *hist)
@@ -324,7 +324,7 @@ rb_history_first (RBHistory *hist)
  *
  * Returns the #RhythmDBEntry before the current position.
  *
- * Return value: previous entry
+ * Return value: (transfer none): previous entry
  */
 RhythmDBEntry *
 rb_history_previous (RBHistory *hist)
@@ -343,7 +343,7 @@ rb_history_previous (RBHistory *hist)
  *
  * Returns the current #RhythmDBEntry, or NULL if there is no current position
  *
- * Return value: current entry or NULL
+ * Return value: (transfer none): current entry or NULL
  */
 RhythmDBEntry *
 rb_history_current (RBHistory *hist)
@@ -359,7 +359,7 @@ rb_history_current (RBHistory *hist)
  *
  * Returns the #RhythmDBEntry after the current position
  *
- * Return value: next entry
+ * Return value: (transfer none): next entry
  */
 RhythmDBEntry *
 rb_history_next (RBHistory *hist)
@@ -377,7 +377,7 @@ rb_history_next (RBHistory *hist)
  *
  * Returns the last #RhythmDBEntry in the history
  *
- * Return value: last entry
+ * Return value: (transfer none): last entry
  */
 RhythmDBEntry *
 rb_history_last (RBHistory *hist)
@@ -667,7 +667,7 @@ rb_history_clear (RBHistory *hist)
  * The caller does not own any references on the entries in the returned array.
  * Takes O(Nlog(N)) time.
  *
- * Return value: a copy of the history list
+ * Return value: (element-type RB.RhythmDBEntry) (transfer container): a copy of the history list
  */
 GPtrArray *
 rb_history_dump (RBHistory *hist)
diff --git a/shell/rb-play-order.c b/shell/rb-play-order.c
index c8c099b..d658ece 100644
--- a/shell/rb-play-order.c
+++ b/shell/rb-play-order.c
@@ -315,8 +315,8 @@ rb_play_order_get_property (GObject *object,
  *
  * Only for use by #RBPlayOrder subclasses.
  *
- * Returns: #RBShellPlayer instance
- **/
+ * Returns: (transfer none): #RBShellPlayer instance
+ */
 RBShellPlayer *
 rb_play_order_get_player (RBPlayOrder *porder)
 {
@@ -331,7 +331,7 @@ rb_play_order_get_player (RBPlayOrder *porder)
  *
  * Only for use by #RBPlayOrder subclasses.
  *
- * Returns: the playing #RBSource instance.
+ * Returns: (transfer none): the playing #RBSource instance.
  **/
 RBSource *
 rb_play_order_get_source (RBPlayOrder *porder)
@@ -347,7 +347,7 @@ rb_play_order_get_source (RBPlayOrder *porder)
  *
  * Only for use by #RBPlayOrder subclasses.
  *
- * Returns: the #RhythmDB instance.
+ * Returns: (transfer none): the #RhythmDB instance.
  **/
 RhythmDB *
 rb_play_order_get_db (RBPlayOrder *porder)
@@ -363,7 +363,7 @@ rb_play_order_get_db (RBPlayOrder *porder)
  *
  * Only for use by #RBPlayOrder subclasses.
  *
- * Returns: the active #RhythmDBQueryModel for the playing source.
+ * Returns: (transfer none): the active #RhythmDBQueryModel for the playing source.
  */
 RhythmDBQueryModel *
 rb_play_order_get_query_model (RBPlayOrder *porder)
@@ -392,7 +392,7 @@ rb_play_order_player_is_playing (RBPlayOrder *porder)
 /**
  * rb_play_order_set_playing_entry:
  * @porder: #RBPlayOrder instance
- * @entry: The new playing entry (or NULL for none)
+ * @entry: (transfer none) (allow-none): The new playing entry (or NULL for none)
  *
  * Sets the playing entry in the play order.
  **/
@@ -411,7 +411,7 @@ rb_play_order_set_playing_entry (RBPlayOrder *porder,
  *
  * Returns the current playing entry in the play order.
  *
- * Returns: playing entry
+ * Returns: (transfer full) playing entry
  */
 RhythmDBEntry *
 rb_play_order_get_playing_entry (RBPlayOrder *porder)
@@ -752,7 +752,7 @@ rb_play_order_has_next (RBPlayOrder *porder)
  *
  * Returns the next entry in the play order, or the first if not currently playing.
  *
- * Returns: next entry to play
+ * Returns: (transfer full): next entry to play
  */
 RhythmDBEntry *
 rb_play_order_get_next (RBPlayOrder *porder)
@@ -812,7 +812,7 @@ rb_play_order_has_previous (RBPlayOrder *porder)
  *
  * Returns the previous entry in the play order, or NULL if not currently playing.
  *
- * Return value: previous entry
+ * Return value: (transfer full): previous entry
  */
 RhythmDBEntry *
 rb_play_order_get_previous (RBPlayOrder *porder)
@@ -896,3 +896,19 @@ rb_play_order_update_have_next_previous (RBPlayOrder *porder)
 		porder->priv->have_previous = have_previous;
 	}
 }
+
+/* annotations for methods */
+
+/**
+ * get_next:
+ * @porder: the play order
+ *
+ * Return value: (transfer full): the next entry
+ */
+
+/**
+ * get_previous:
+ * @porder: the play order
+ *
+ * Return value: (transfer full): the previous entry
+ */
diff --git a/shell/rb-playlist-manager.c b/shell/rb-playlist-manager.c
index c20292c..6b52a3e 100644
--- a/shell/rb-playlist-manager.c
+++ b/shell/rb-playlist-manager.c
@@ -742,7 +742,7 @@ append_new_playlist_source (RBPlaylistManager *mgr, RBPlaylistSource *source)
 }
 
 /**
- * rb_playlist_manager_load_playlists
+ * rb_playlist_manager_load_playlists:
  * @mgr: the #RBPlaylistManager
  *
  * Loads the user's playlists, or if the playlist file does not exists,
@@ -933,7 +933,7 @@ save_playlist_cb (GtkTreeModel *model,
 }
 
 /**
- * rb_playlist_manager_save_playlists
+ * rb_playlist_manager_save_playlists:
  * @mgr: the #RBPlaylistManager
  * @force: if TRUE, save playlists synchronously and unconditionally
  *
@@ -985,15 +985,15 @@ rb_playlist_manager_save_playlists (RBPlaylistManager *mgr, gboolean force)
 }
 
 /**
- * rb_playlist_manager_new_playlist
+ * rb_playlist_manager_new_playlist:
  * @mgr: the #RBPlaylistManager
  * @suggested_name: optional name to use for the new playlist
  * @automatic: if TRUE, create an auto playlist
  *
  * Creates a new playlist and adds it to the source list.
  *
- * Return value: the new playlist object.
- **/
+ * Return value: (transfer none): the new playlist object.
+ */
 RBSource *
 rb_playlist_manager_new_playlist (RBPlaylistManager *mgr,
 				  const char *suggested_name,
@@ -1122,7 +1122,7 @@ create_name_from_selection_data (RBPlaylistManager *mgr,
 }
 
 /**
- * rb_playlist_manager_new_playlist_from_selection_data
+ * rb_playlist_manager_new_playlist_from_selection_data:
  * @mgr: the #RBPlaylistManager
  * @data: the #GtkSelectionData from which to create a playlist
  *
@@ -1130,7 +1130,7 @@ create_name_from_selection_data (RBPlaylistManager *mgr,
  * Used to implement playlist creation through drag and drop
  * to the source list.
  *
- * Return value: the new playlist.
+ * Return value: (transfer none): the new playlist.
  **/
 RBSource *
 rb_playlist_manager_new_playlist_from_selection_data (RBPlaylistManager *mgr,
@@ -1649,12 +1649,12 @@ list_playlists_cb (GtkTreeModel *model,
 
 
 /**
- * rb_playlist_manager_get_playlists
+ * rb_playlist_manager_get_playlists:
  * @mgr: the #RBPlaylistManager
  *
  * Returns a #GList containing all local playlist source objects.
  *
- * Return value: list of playlists
+ * Return value: (element-type RB.Source) (transfer container): list of playlists
  **/
 GList *
 rb_playlist_manager_get_playlists (RBPlaylistManager *mgr)
@@ -1668,9 +1668,9 @@ rb_playlist_manager_get_playlists (RBPlaylistManager *mgr)
 }
 
 /**
- * rb_playlist_manager_get_playlist_names
+ * rb_playlist_manager_get_playlist_names:
  * @mgr: the #RBPlaylistManager
- * @playlists: holds the array of playlist names on reutrn
+ * @playlists: (out callee-allocates) (transfer full): holds the array of playlist names on reutrn
  * @error: holds a #GError on return on failure
  *
  * Allocates and returns an array containing the names of all local
@@ -1754,7 +1754,7 @@ _get_playlist_by_name (RBPlaylistManager *mgr,
 }
 
 /**
- * rb_playlist_manager_create_static_playlist
+ * rb_playlist_manager_create_static_playlist:
  * @mgr: the #RBPlaylistManager
  * @name: name of the new playlist
  * @error: holds a #GError on return on failure
@@ -1784,7 +1784,7 @@ rb_playlist_manager_create_static_playlist (RBPlaylistManager *mgr,
 }
 
 /**
- * rb_playlist_manager_delete_playlist
+ * rb_playlist_manager_delete_playlist:
  * @mgr: the #RBPlaylistManager
  * @name: name of the playlist to delete
  * @error: holds a #GError on return on failure
@@ -1814,7 +1814,7 @@ rb_playlist_manager_delete_playlist (RBPlaylistManager *mgr,
 }
 
 /**
- * rb_playlist_manager_add_to_playlist
+ * rb_playlist_manager_add_to_playlist:
  * @mgr: the #RBPlaylistManager
  * @name: name of the playlist to add to
  * @uri: URI of the entry to add to the playlist
@@ -1854,7 +1854,7 @@ rb_playlist_manager_add_to_playlist (RBPlaylistManager *mgr,
 }
 
 /**
- * rb_playlist_manager_remove_from_playlist
+ * rb_playlist_manager_remove_from_playlist:
  * @mgr: the #RBPlaylistManager
  * @name: name of the playlist to remove from
  * @uri: URI of the entry to remove from the playlist
@@ -1896,7 +1896,7 @@ rb_playlist_manager_remove_from_playlist (RBPlaylistManager *mgr,
 }
 
 /**
- * rb_playlist_manager_export_playlist
+ * rb_playlist_manager_export_playlist:
  * @mgr: the #RBPlaylistManager
  * @name: name of the playlist to export
  * @uri: playlist save location
diff --git a/shell/rb-plugin.c b/shell/rb-plugin.c
index 8aa3e2d..2b84291 100644
--- a/shell/rb-plugin.c
+++ b/shell/rb-plugin.c
@@ -224,7 +224,7 @@ rb_plugin_is_configurable (RBPlugin *plugin)
  * the dialog instance the first time it is created and just return it
  * thereafter.
  *
- * Return value: configuration widget for @plugin
+ * Return value: (transfer none): configuration widget for @plugin
  */
 GtkWidget *
 rb_plugin_create_configure_dialog (RBPlugin *plugin)
@@ -244,7 +244,7 @@ rb_plugin_create_configure_dialog (RBPlugin *plugin)
  *
  * Returns a list containing the paths to search for plugins.
  *
- * Return value: #GList of paths, must be freed by caller
+ * Return value: (element-type utf8) (transfer full): list of paths.
  */
 GList *
 rb_get_plugin_paths (void)
diff --git a/shell/rb-plugin.h b/shell/rb-plugin.h
index d94195e..b0d1353 100644
--- a/shell/rb-plugin.h
+++ b/shell/rb-plugin.h
@@ -71,14 +71,13 @@ struct _RBPluginClass
 	GObjectClass parent_class;
 
 	/* Virtual public methods */
+	void (*activate) (RBPlugin *plugin, RBShell *shell);
+	void (*deactivate) (RBPlugin *plugin, RBShell *shell);
 
-	RBPluginActivationFunc		activate;
-	RBPluginActivationFunc		deactivate;
-	RBPluginWidgetFunc		create_configure_dialog;
-
+	GtkWidget* (*create_configure_dialog) (RBPlugin *plugin);
 	/* Plugins should not override this, it's handled automatically by
 	   the RbPluginClass */
-	RBPluginBooleanFunc		is_configurable;
+	gboolean (*is_configurable) (RBPlugin *plugin);
 };
 
 /*
diff --git a/shell/rb-removable-media-manager.c b/shell/rb-removable-media-manager.c
index c3d3a2f..a3aba01 100644
--- a/shell/rb-removable-media-manager.c
+++ b/shell/rb-removable-media-manager.c
@@ -234,6 +234,8 @@ rb_removable_media_manager_class_init (RBRemovableMediaManagerClass *klass)
 	 * corresponding #RBSource.  The first signal handler that returns a
 	 * source wins.  Plugins should only use this signal if there will be
 	 * no #GVolume or #GMount created for the device.
+	 *
+	 * Return value: (transfer full): a source for the device, or NULL
 	 */
 	rb_removable_media_manager_signals[CREATE_SOURCE_DEVICE] =
 		g_signal_new ("create-source-device",
@@ -254,6 +256,8 @@ rb_removable_media_manager_class_init (RBRemovableMediaManagerClass *klass)
 	 * a source wins.  A plugin should only use this signal if it
 	 * doesn't require the volume to be mounted.  If the volume must be
 	 * mounted to be useful, use the create-source-mount signal instead.
+	 *
+	 * Return value: (transfer full): a source for the volume, or NULL
 	 */
 	rb_removable_media_manager_signals[CREATE_SOURCE_VOLUME] =
 		g_signal_new ("create-source-volume",
@@ -275,6 +279,8 @@ rb_removable_media_manager_class_init (RBRemovableMediaManagerClass *klass)
 	 * corresponding #RBSource.  The first signal handler that returns
 	 * a source wins.  If a source was created for the #GVolume
 	 * for a mount, then this signal will not be emitted.
+	 *
+	 * Return value: (transfer full): a source for the mount, or NULL
 	 */
 	rb_removable_media_manager_signals[CREATE_SOURCE_MOUNT] =
 		g_signal_new ("create-source-mount",
diff --git a/shell/rb-shell-player.c b/shell/rb-shell-player.c
index 2301e99..946b119 100644
--- a/shell/rb-shell-player.c
+++ b/shell/rb-shell-player.c
@@ -1433,7 +1433,7 @@ rb_shell_player_set_selected_source (RBShellPlayer *player,
  * #rb_shell_player_get_active_source when the current song came
  * from the play queue.
  *
- * Return value: the current playing #RBSource
+ * Return value: (transfer none): the current playing #RBSource
  */
 RBSource *
 rb_shell_player_get_playing_source (RBShellPlayer *player)
@@ -1448,7 +1448,7 @@ rb_shell_player_get_playing_source (RBShellPlayer *player)
  * Retrieves the active source.  This is the source that the user
  * selected for playback.
  *
- * Return value: the active #RBSource
+ * Return value: (transfer none): the active #RBSource
  */
 RBSource *
 rb_shell_player_get_active_source (RBShellPlayer *player)
@@ -1486,7 +1486,7 @@ rb_shell_player_new (RhythmDB *db,
  * nothing is playing.  The caller must unref the entry
  * (using #rhythmdb_entry_unref) when it is no longer needed.
  *
- * Return value: the currently playing #RhythmDBEntry, or NULL
+ * Return value: (transfer full) (allow-none): the currently playing #RhythmDBEntry, or NULL
  */
 RhythmDBEntry *
 rb_shell_player_get_playing_entry (RBShellPlayer *player)
@@ -1810,8 +1810,8 @@ gconf_play_order_changed (GConfClient *client,
 /**
  * rb_shell_player_get_playback_state:
  * @player: the #RBShellPlayer
- * @shuffle: returns the current shuffle setting
- * @repeat: returns the current repeat setting
+ * @shuffle: (out): returns the current shuffle setting
+ * @repeat: (out): returns the current repeat setting
  *
  * Retrieves the current state of the shuffle and repeat settings.
  *
@@ -2590,7 +2590,7 @@ rb_shell_player_set_volume_relative (RBShellPlayer *player,
 /**
  * rb_shell_player_get_volume:
  * @player: the #RBShellPlayer
- * @volume: returns the volume level
+ * @volume: (out): returns the volume level
  * @error: returns error information
  *
  * Returns the current volume level
@@ -2638,7 +2638,7 @@ rb_shell_player_set_mute (RBShellPlayer *player,
 /**
  * rb_shell_player_get_mute:
  * @player: the #RBShellPlayer
- * @mute: returns the current mute setting
+ * @mute: (out): returns the current mute setting
  * @error: returns error information
  *
  * Returns %TRUE if currently muted
@@ -3272,7 +3272,7 @@ rb_shell_player_pause (RBShellPlayer *player,
 /**
  * rb_shell_player_get_playing:
  * @player: a #RBShellPlayer
- * @playing: playback state return
+ * @playing: (out): playback state return
  * @error: error return
  *
  * Reports whether playback is occuring by setting #playing.
@@ -3310,7 +3310,7 @@ rb_shell_player_get_playing_time_string (RBShellPlayer *player)
 /**
  * rb_shell_player_get_playing_time:
  * @player: the #RBShellPlayer
- * @time: returns the current playback position
+ * @time: (out): returns the current playback position
  * @error: returns error information
  *
  * Retrieves the current playback position.  Fails if
@@ -3792,7 +3792,7 @@ player_image_cb (RBPlayer *player,
 /**
  * rb_shell_player_get_playing_path:
  * @player: the #RBShellPlayer
- * @path: returns the URI of the current playing entry
+ * @path: (out callee-allocates) (transfer full): returns the URI of the current playing entry
  * @error: returns error information
  *
  * Retrieves the URI of the current playing entry.  The
diff --git a/shell/rb-shell-preferences.c b/shell/rb-shell-preferences.c
index 4918670..2caccbd 100644
--- a/shell/rb-shell-preferences.c
+++ b/shell/rb-shell-preferences.c
@@ -374,7 +374,7 @@ rb_shell_preferences_append_view_page (RBShellPreferences *prefs,
 
 /**
  * rb_shell_preferences_new:
- * @views: list of #RBSource objects to check for preferences pages
+ * @views: (element-type RB.Source) (transfer none): list of sources to check for preferences pages
  *
  * Creates the #RBShellPreferences instance, populating it with the
  * preferences pages for the sources in the list.
@@ -717,7 +717,7 @@ get_box_for_location (RBShellPreferences *prefs, RBShellPrefsUILocation location
 
 /**
  * rb_shell_preferences_add_widget:
- * @shell: the #RBShellPreferences
+ * @prefs: the #RBShellPreferences
  * @widget: the #GtkWidget to insert into the preferences window
  * @location: the location at which to insert the widget
  * @expand: whether the widget should be given extra space
@@ -742,7 +742,7 @@ rb_shell_preferences_add_widget (RBShellPreferences *prefs,
 
 /**
  * rb_shell_preferences_remove_widget:
- * @shell: the #RBShellPreferences
+ * @prefs: the #RBShellPreferences
  * @widget: the #GtkWidget to remove from the preferences window
  * @location: the UI location to which the widget was originally added
  *
diff --git a/shell/rb-shell.c b/shell/rb-shell.c
index 323efa9..07a488a 100644
--- a/shell/rb-shell.c
+++ b/shell/rb-shell.c
@@ -1954,7 +1954,7 @@ rb_shell_db_save_error_cb (RhythmDB *db,
  * Looks up and returns the source that owns entries of the specified
  * type.
  *
- * Return value: source instance, if any
+ * Return value: (transfer none): source instance, if any
  */
 RBSource *
 rb_shell_get_source_by_entry_type (RBShell *shell,
@@ -1991,7 +1991,7 @@ rb_shell_register_entry_type_for_source (RBShell *shell,
  * rb_shell_append_display_page:
  * @shell: the #RBShell
  * @page: the new #RBDisplayPage
- * @parent: the parent page for the new page (optional)
+ * @parent: (allow-none): the parent page for the new page
  *
  * Adds a new display page to the shell.
  */
@@ -3108,7 +3108,7 @@ rb_shell_session_init (RBShell *shell)
  * This iterates through all sources, calling #rb_source_want_uri,
  * returning the source that returns the highest value.
  *
- * Return value: the most appropriate #RBSource for the uri
+ * Return value: (transfer none): the most appropriate #RBSource for the uri
  */
 RBSource *
 rb_shell_guess_source_for_uri (RBShell *shell,
@@ -3436,7 +3436,7 @@ rb_shell_get_party_mode (RBShell *shell)
  *
  * Returns the #RBShellPlayer object
  *
- * Return value: the #RBShellPlayer object
+ * Return value: (transfer none): the #RBShellPlayer object
  */
 GObject *
 rb_shell_get_player (RBShell *shell)
@@ -3464,7 +3464,7 @@ rb_shell_get_player_path (RBShell *shell)
  *
  * Returns the #RBPlaylistManager object
  *
- * Return value: the #RBPlaylistManager object
+ * Return value: (transfer none): the #RBPlaylistManager object
  */
 GObject *
 rb_shell_get_playlist_manager (RBShell *shell)
@@ -3492,7 +3492,7 @@ rb_shell_get_playlist_manager_path (RBShell *shell)
  *
  * Returns the main #GtkUIManager object
  *
- * Return value: the main #GtkUIManager object
+ * Return value: (transfer none): the main #GtkUIManager object
  */
 GObject *
 rb_shell_get_ui_manager (RBShell *shell)
@@ -3658,7 +3658,7 @@ rb_shell_activate_source_by_uri (RBShell *shell,
  * rb_shell_get_song_properties:
  * @shell: the #RBShell
  * @uri: the URI to query
- * @properties: returns the properties of the specified URI
+ * @properties: (out callee-allocates) (element-type utf8 GObject.Value) returns the properties of the specified URI
  * @error: returns error information
  *
  * Gathers and returns all metadata (including extra metadata such as album
diff --git a/shell/rb-track-transfer-batch.c b/shell/rb-track-transfer-batch.c
index 05020d0..c6cceeb 100644
--- a/shell/rb-track-transfer-batch.c
+++ b/shell/rb-track-transfer-batch.c
@@ -108,7 +108,7 @@ G_DEFINE_TYPE (RBTrackTransferBatch, rb_track_transfer_batch, G_TYPE_OBJECT)
 /**
  * rb_track_transfer_batch_new:
  * @media_types: array containing media type strings describing allowable output formats
- * @media_type_list: GList containing media type strings.
+ * @media_type_list: (element-type utf8): GList containing media type strings.
  * @source: the #RBSource from which the entries are to be transferred
  * @destination: the #RBSource to which the entries are to be transferred
  *
diff --git a/shell/rb-track-transfer-queue.c b/shell/rb-track-transfer-queue.c
index c1a290a..297a6fb 100644
--- a/shell/rb-track-transfer-queue.c
+++ b/shell/rb-track-transfer-queue.c
@@ -547,7 +547,7 @@ find_batches (RBTrackTransferBatch *batch, struct FindBatchData *data)
  * found in the queue, so waiting for the @RBTrackTransferBatch::complete signal
  * on the last one is sufficient to wait for them all to finish.
  *
- * Return value: #GList of #RBTrackTransferBatch objects, not referenced
+ * Return value: (element-type RBTrackTransferBatch) (transfer container): #GList of #RBTrackTransferBatch objects, not referenced
  */
 GList *
 rb_track_transfer_queue_find_batch_by_source (RBTrackTransferQueue *queue, RBSource *source)
diff --git a/sources/rb-auto-playlist-source.c b/sources/rb-auto-playlist-source.c
index 91bfbbe..71f5caf 100644
--- a/sources/rb-auto-playlist-source.c
+++ b/sources/rb-auto-playlist-source.c
@@ -797,7 +797,7 @@ rb_auto_playlist_source_do_query (RBAutoPlaylistSource *source, gboolean subset)
 /**
  * rb_auto_playlist_source_set_query:
  * @source: the #RBAutoPlaylistSource
- * @query: the new database query
+ * @query: (transfer none): the new database query
  * @limit_type: the playlist limit type
  * @limit_value: the playlist limit value
  * @sort_key: the sorting key
@@ -855,11 +855,11 @@ rb_auto_playlist_source_set_query (RBAutoPlaylistSource *source,
 /**
  * rb_auto_playlist_source_get_query:
  * @source: the #RBAutoPlaylistSource
- * @query: returns the database query for the playlist
- * @limit_type: returns the playlist limit type
- * @limit_value: returns the playlist limit value
- * @sort_key: returns the playlist sorting key
- * @sort_order: returns the playlist sorting direction (as a #GtkSortType)
+ * @query: (out caller-allocates) (transfer full): returns the database query for the playlist
+ * @limit_type: (out callee-allocates): returns the playlist limit type
+ * @limit_value: (out callee-allocates): returns the playlist limit value
+ * @sort_key: (out callee-allocates) (transfer full): returns the playlist sorting key
+ * @sort_order: (out callee-allocates): returns the playlist sorting direction (as a #GtkSortType)
  *
  * Extracts the current query, playlist limit, and sorting settings for the playlist.
  */
diff --git a/sources/rb-browser-source.c b/sources/rb-browser-source.c
index 04e5a0d..b4e7a68 100644
--- a/sources/rb-browser-source.c
+++ b/sources/rb-browser-source.c
@@ -807,7 +807,7 @@ impl_browser_toggled (RBSource *asource, gboolean disclosed)
  * Retrieves the GConf key that stores the height of the browser pane for the source.
  * This is a virtual method that should be implemented by subclasses.
  *
- * Return value: allocated string containing the GConf key name
+ * Return value: (transfer full): allocated string containing the GConf key name
  */
 char *
 rb_browser_source_get_paned_key (RBBrowserSource *source)
@@ -948,4 +948,3 @@ default_pack_paned (RBBrowserSource *source, GtkWidget *paned)
 	gtk_box_pack_start (GTK_BOX (box), paned, TRUE, TRUE, 0);
 	gtk_container_add (GTK_CONTAINER (source), box);
 }
-
diff --git a/sources/rb-display-page-group.c b/sources/rb-display-page-group.c
index d8b22e1..657bfc8 100644
--- a/sources/rb-display-page-group.c
+++ b/sources/rb-display-page-group.c
@@ -108,7 +108,7 @@ rb_display_page_group_add_core_groups (GObject *shell, RBDisplayPageModel *page_
  * Locates a page group by name.  If the page group has not been registered yet,
  * returns NULL instead.
  *
- * Return value: existing page group, or NULL.
+ * Return value: (transfer none): existing page group, or NULL.
  */
 RBDisplayPageGroup *
 rb_display_page_group_get_by_id (const char *id)
diff --git a/sources/rb-display-page-model.c b/sources/rb-display-page-model.c
index 00126c2..930fd2a 100644
--- a/sources/rb-display-page-model.c
+++ b/sources/rb-display-page-model.c
@@ -546,7 +546,7 @@ update_group_visibility_cb (GtkTreeModel *model, GtkTreePath *path, GtkTreeIter
 
 /**
  * rb_display_page_model_set_dnd_targets:
- * @sourcelist: the #RBDisplayPageModel
+ * @page_model: the #RBDisplayPageModel
  * @treeview: the sourcel ist #GtkTreeView
  *
  * Sets up the drag and drop targets for the display page tree.
diff --git a/sources/rb-display-page-tree.c b/sources/rb-display-page-tree.c
index 0827f45..992f79d 100644
--- a/sources/rb-display-page-tree.c
+++ b/sources/rb-display-page-tree.c
@@ -294,7 +294,7 @@ expander_cell_data_func (GtkTreeViewColumn *column,
 		gboolean     row_expanded;
 
 		path = gtk_tree_model_get_path (model, iter);
-		row_expanded = gtk_tree_view_row_expanded (GTK_TREE_VIEW (gtk_tree_view_column_get_tree_view (column)),
+		row_expanded = gtk_tree_view_row_expanded (GTK_TREE_VIEW (display_page_tree->priv->treeview),
 							   path);
 		gtk_tree_path_free (path);
 
diff --git a/sources/rb-display-page.c b/sources/rb-display-page.c
index f06c904..c69580e 100644
--- a/sources/rb-display-page.c
+++ b/sources/rb-display-page.c
@@ -227,7 +227,7 @@ rb_display_page_activate (RBDisplayPage *page)
  * configuration widget. The widget will be displayed in a
  * page in the preferences dialog.
  *
- * Return value: configuration widget
+ * Return value: (transfer none): configuration widget
  */
 GtkWidget *
 rb_display_page_get_config_widget (RBDisplayPage *page,
@@ -249,7 +249,7 @@ rb_display_page_get_config_widget (RBDisplayPage *page,
  * Returns a list of UI action names.  Items for
  * these actions will be added to the toolbar.
  *
- * Return value: list of action names
+ * Return value: (element-type utf8) (transfer full): list of action names
  */
 GList *
 rb_display_page_get_ui_actions (RBDisplayPage *page)
@@ -265,9 +265,9 @@ rb_display_page_get_ui_actions (RBDisplayPage *page)
 /**
  * rb_display_page_get_status:
  * @page: a #RBDisplayPage
- * @text: holds the returned status text (allocated)
- * @progress_text: holds the returned text for the progress bar (allocated)
- * @progress: holds the progress value
+ * @text: (inout) (allow-none) (transfer full): holds the returned status text
+ * @progress_text: (inout) (allow-none) (transfer full): holds the returned text for the progress bar
+ * @progress: (inout) (allow-none): holds the progress value
  *
  * Retrieves the details to display in the status bar for the page.
  * If the progress value returned is less than zero, the progress bar
@@ -722,3 +722,28 @@ rb_display_page_class_init (RBDisplayPageClass *klass)
 
 	g_type_class_add_private (object_class, sizeof (RBDisplayPagePrivate));
 }
+
+/* introspection annotations for vmethods */
+
+/**
+ * impl_get_status:
+ * @source: a #RBSource
+ * @text: (inout) (allow-none) (transfer full): holds the returned status text
+ * @progress_text: (inout) (allow-none) (transfer full): holds the returned text for the progress bar
+ * @progress: (inout): holds the progress value
+ */
+
+/**
+ * impl_get_config_widget:
+ * @source: a #RBSource
+ * @prefs: a #RBShellPreferences
+ *
+ * Return value: (transfer none): configuration widget
+ */
+
+/**
+ * impl_get_ui_actions:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type utf8) (transfer full): list of action names
+ */
diff --git a/sources/rb-media-player-source.c b/sources/rb-media-player-source.c
index cc77963..2be14e3 100644
--- a/sources/rb-media-player-source.c
+++ b/sources/rb-media-player-source.c
@@ -269,25 +269,39 @@ rb_media_player_source_get_free_space (RBMediaPlayerSource *source)
 	return klass->impl_get_free_space (source);
 }
 
+/**
+ * rb_media_player_source_get_entries:
+ * @source: the #RBMediaPlayerSource
+ * @category: the sync category name
+ * @entries: (element-type utf8 RB.RhythmDBEntry): map to hold the entries
+ */
 void
 rb_media_player_source_get_entries (RBMediaPlayerSource *source,
 				    const char *category,
-				    GHashTable *map)
+				    GHashTable *entries)
 {
 	RBMediaPlayerSourceClass *klass = RB_MEDIA_PLAYER_SOURCE_GET_CLASS (source);
-	klass->impl_get_entries (source, category, map);
+	klass->impl_get_entries (source, category, entries);
 }
 
+/**
+ * rb_media_player_source_delete_entries:
+ * @source: the #RBMediaPlayerSource
+ * @entries: (element-type RB.RhythmDBEntry) (transfer full): list of entries to delete
+ * @callback: callback to call on completion
+ * @user_data: (closure) (scope notified): data for callback
+ * @destroy_data: callback to free the callback data
+ */
 void
 rb_media_player_source_delete_entries	(RBMediaPlayerSource *source,
 					 GList *entries,
 					 RBMediaPlayerSourceDeleteCallback callback,
-					 gpointer callback_data,
+					 gpointer user_data,
 					 GDestroyNotify destroy_data)
 {
 	RBMediaPlayerSourceClass *klass = RB_MEDIA_PLAYER_SOURCE_GET_CLASS (source);
 
-	klass->impl_delete_entries (source, entries, callback, callback_data, destroy_data);
+	klass->impl_delete_entries (source, entries, callback, user_data, destroy_data);
 }
 
 static void
@@ -747,3 +761,21 @@ sync_cmd (GtkAction *action, RBSource *source)
 {
 	rb_media_player_source_sync (RB_MEDIA_PLAYER_SOURCE (source));
 }
+
+/* annotations for methods */
+
+/**
+ * impl_delete_entries:
+ * @source: the source
+ * @entries: (element-type RB.RhythmDBEntry) (transfer full): list of entries to delete
+ * @callback: callback to call on completion
+ * @data: (closure) (scope notified): callback data
+ * @destroy_data: callback to free callback data
+ */
+
+/**
+ * impl_add_playlist:
+ * @source: the source
+ * @name: new playlist name
+ * @entries: (element-type RB.RhythmDBEntry) (transfer full): list of entries to add
+ */
diff --git a/sources/rb-playlist-source.c b/sources/rb-playlist-source.c
index 1c41718..33dbc09 100644
--- a/sources/rb-playlist-source.c
+++ b/sources/rb-playlist-source.c
@@ -1010,7 +1010,7 @@ rb_playlist_source_set_query_model (RBPlaylistSource *source,
  * Returns the #RhythmDB instance.  The caller must not
  * unref the object once finished with it.
  *
- * Return value: the #RhythmDB instance
+ * Return value: (transfer none): the #RhythmDB instance
  */
 RhythmDB *
 rb_playlist_source_get_db (RBPlaylistSource *source)
@@ -1027,7 +1027,7 @@ rb_playlist_source_get_db (RBPlaylistSource *source)
  * Returns the current #RhythmDBQueryModel for the playlist.
  * The caller must not unref the object once finished with it.
  *
- * Return value: the current #RhythmDBQueryModel
+ * Return value: (transfer none): the current #RhythmDBQueryModel
  */
 RhythmDBQueryModel *
 rb_playlist_source_get_query_model (RBPlaylistSource *source)
diff --git a/sources/rb-removable-media-source.c b/sources/rb-removable-media-source.c
index 4c8ea37..70eab4d 100644
--- a/sources/rb-removable-media-source.c
+++ b/sources/rb-removable-media-source.c
@@ -665,7 +665,7 @@ rb_removable_media_source_build_dest_uri (RBRemovableMediaSource *source,
  * for Ogg Vorbis, "audio/x-flac" for FLAC, and "audio/x-aac" for
  * MP4/AAC.
  *
- * Return value: list of media types
+ * Return value: (element-type utf8) (transfer full): list of media types
  */
 GList *
 rb_removable_media_source_get_mime_types (RBRemovableMediaSource *source)
@@ -686,7 +686,7 @@ rb_removable_media_source_get_mime_types (RBRemovableMediaSource *source)
  * the formats supported by the device.  The list and the strings
  * it holds must be freed by the caller.
  *
- * Return value: list of descriptions.
+ * Return value: (element-type utf8) (transfer full): list of descriptions.
  */
 GList *
 rb_removable_media_source_get_format_descriptions (RBRemovableMediaSource *source)
@@ -1043,3 +1043,22 @@ rb_removable_media_source_eject (RBRemovableMediaSource *source)
 	RBRemovableMediaSourceClass *klass = RB_REMOVABLE_MEDIA_SOURCE_GET_CLASS (source);
 	klass->impl_eject (source);
 }
+
+/* annotations for methods */
+
+/**
+ * impl_build_dest_uri:
+ * @source: the source
+ * @entry: entry to build URI for
+ * @mimetype: destination media type
+ * @extension: extension for destination media type
+ *
+ * Return value: (transfer full): destination URI for the entry
+ */
+
+/**
+ * impl_get_mime_types:
+ * @source: the source
+ *
+ * Return value: (element-type utf8) (transfer full): list of media types
+ */
diff --git a/sources/rb-source-search.c b/sources/rb-source-search.c
index e89282b..ce96192 100644
--- a/sources/rb-source-search.c
+++ b/sources/rb-source-search.c
@@ -102,7 +102,7 @@ rb_source_search_is_subset (RBSourceSearch *search, const char *current, const c
  *
  * Creates a #RhythmDBQuery from the user's search text.
  *
- * Return value: #RhythmDBQuery for the source to use
+ * Return value: (transfer full): #RhythmDBQuery for the source to use
  */
 RhythmDBQuery *
 rb_source_search_create_query (RBSourceSearch *search, RhythmDB *db, const char *search_text)
@@ -121,7 +121,7 @@ rb_source_search_create_query (RBSourceSearch *search, RhythmDB *db, const char
  *
  * Creates a basic search query.
  *
- * Return value: the #RhythmDBQuery for the search text and property, or NULL
+ * Return value: (transfer full): the #RhythmDBQuery for the search text and property, or NULL
  *   if no search text is specified.
  */
 RhythmDBQuery *
@@ -161,7 +161,7 @@ rb_source_search_action_attach (RBSourceSearch *search, GObject *action)
  * Returns the #RBSourceSearch associated with the
  * specified UI action.
  *
- * Return value: associated #RBSourceSearch
+ * Return value: (transfer none): associated #RBSourceSearch
  */
 RBSourceSearch *
 rb_source_search_get_from_action (GObject *action)
diff --git a/sources/rb-source.c b/sources/rb-source.c
index aef06d0..a50cbc7 100644
--- a/sources/rb-source.c
+++ b/sources/rb-source.c
@@ -604,7 +604,7 @@ rb_source_update_play_statistics (RBSource *source,
  *
  * Returns the entry view widget for the source.
  *
- * Return value: the #RBEntryView instance for the source
+ * Return value: (transfer none): the #RBEntryView instance for the source
  */
 RBEntryView *
 rb_source_get_entry_view (RBSource *source)
@@ -627,7 +627,7 @@ default_get_property_views (RBSource *source)
  * Returns a list containing the #RBPropertyView instances for the
  * source, if any.
  *
- * Return value:  list of property views
+ * Return value: (element-type RB.PropertyView) (transfer container): list of property views
  */
 GList *
 rb_source_get_property_views (RBSource *source)
@@ -679,8 +679,8 @@ rb_source_can_rename (RBSource *source)
 /**
  * rb_source_search:
  * @source: a #RBSource
- * @search: the active #RBSourceSearch instance (may be NULL)
- * @cur_text: the current search text (may be NULL)
+ * @search: (allow-none): the active #RBSourceSearch instance
+ * @cur_text: (allow-none): the current search text
  * @new_text: the new search text
  *
  * Updates the source with new search text.  The source
@@ -798,8 +798,8 @@ rb_source_can_copy (RBSource *source)
  * Removes the currently selected entries from the source and
  * returns them so they can be pasted into another source.
  *
- * Return value: a list of #RhythmDBEntry objects cut from
- * the source.
+ * Return value: (element-type RB.RhythmDBEntry) (transfer full): entries cut
+ * from the source.
  */
 GList *
 rb_source_cut (RBSource *source)
@@ -826,8 +826,8 @@ default_copy (RBSource *source)
  *
  * Copies the selected entries to the clipboard.
  *
- * Return value: a list containing the currently selected entries from
- * the source.
+ * Return value: (element-type RB.RhythmDBEntry) (transfer full): a list containing
+ * the currently selected entries from the source.
  */
 GList *
 rb_source_copy (RBSource *source)
@@ -840,7 +840,7 @@ rb_source_copy (RBSource *source)
 /**
  * rb_source_paste:
  * @source: a #RBSource
- * @entries: a list of #RhythmDBEntry objects to paste in
+ * @entries: (element-type RB.RhythmDBEntry): a list of #RhythmDBEntry objects to paste in
  *
  * Adds a list of entries previously cut or copied from another
  * source.  If the entries are not of the type used by the source,
@@ -851,7 +851,7 @@ rb_source_copy (RBSource *source)
  * is returned so the caller can monitor the transfer progress.  The caller does not
  * own a reference on the batch object.
  *
- * Return value: the #RBTrackTransferBatch used to perform the transfer (if any)
+ * Return value: (transfer none): the #RBTrackTransferBatch used to perform the transfer (if any)
  */
 RBTrackTransferBatch *
 rb_source_paste (RBSource *source, GList *entries)
@@ -1178,7 +1178,7 @@ default_get_search_actions (RBSource *source)
  * must identify the selected search action when constructing
  * a database query for searching
  *
- * Return value: list of search actions
+ * Return value: (element-type utf8) (transfer full): list of search actions
  */
 GList *
 rb_source_get_search_actions (RBSource *source)
@@ -1260,7 +1260,7 @@ rb_source_gather_hash_keys (char *key,
  * This is used to implement the 'browse this artist' (etc.)
  * actions.
  *
- * Return value: list of property values
+ * Return value: (element-type utf8) (transfer full): list of property values
  */
 GList *
 rb_source_gather_selected_properties (RBSource *source,
@@ -1383,3 +1383,46 @@ rb_source_search_type_get_type (void)
 
 	return etype;
 }
+
+/* introspection annotations for vmethods */
+
+/**
+ * impl_get_entry_view:
+ * @source: a #RBSource
+ *
+ * Return value: (transfer none): the RBEntryView for the source
+ */
+
+/**
+ * impl_get_property_views:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type RB.PropertyView) (transfer container): list of property views
+ */
+
+/**
+ * impl_cut:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type RB.RhythmDBEntry) (transfer full): list of entries
+ */
+
+/**
+ * impl_copy:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type RB.RhythmDBEntry) (transfer full): list of entries
+ */
+
+/**
+ * impl_paste:
+ * @source: a #RBSource
+ * @entries: (element-type RB.RhythmDBEntry) (transfer none): list of entries to paste
+ */
+
+/**
+ * impl_get_search_actions:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type utf8) (transfer full): list of action names
+ */
diff --git a/sources/rb-static-playlist-source.c b/sources/rb-static-playlist-source.c
index aafe50b..a119ab4 100644
--- a/sources/rb-static-playlist-source.c
+++ b/sources/rb-static-playlist-source.c
@@ -829,7 +829,7 @@ rb_static_playlist_source_add_location (RBStaticPlaylistSource *source,
 /**
  * rb_static_playlist_source_add_locations:
  * @source: an #RBStaticPlaylistSource
- * @locations: a #GList of strings to add
+ * @locations: (element-type utf8) (transfer none): URI strings to add
  *
  * Adds the locations specified in @locations to the playlist.
  * See @rb_static_playlist_source_add_location for details.
diff --git a/sources/rb-streaming-source.c b/sources/rb-streaming-source.c
index 46c400b..937784c 100644
--- a/sources/rb-streaming-source.c
+++ b/sources/rb-streaming-source.c
@@ -203,8 +203,8 @@ impl_handle_eos (RBSource *asource)
 /**
  * rb_streaming_source_get_progress:
  * @source: a #RBStreamingSource
- * @text: returns buffering status text
- * @progress: returns buffering progress fraction
+ * @text: (out callee-allocates) (transfer full): returns buffering status text
+ * @progress: (out callee-allocates): returns buffering progress fraction
  *
  * Provides status text and progress fraction suitable for use in
  * a streaming source's @rb_source_get_status method.
diff --git a/widgets/rb-dialog.c b/widgets/rb-dialog.c
index a076806..1648865 100644
--- a/widgets/rb-dialog.c
+++ b/widgets/rb-dialog.c
@@ -116,7 +116,7 @@ rb_error_dialog (GtkWindow *parent,
  * After creating the dialog, the caller should connect a handler to its 
  * 'response' signal to process the user's selected files or folders.
  *
- * Return value: the file chooser #GtkWidget
+ * Return value: (transfer full): the file chooser #GtkWidget
  */
 GtkWidget *
 rb_file_chooser_new (const char *title,
diff --git a/widgets/rb-entry-view.c b/widgets/rb-entry-view.c
index 2d5ec7b..15fa8b5 100644
--- a/widgets/rb-entry-view.c
+++ b/widgets/rb-entry-view.c
@@ -1217,7 +1217,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)
@@ -1287,8 +1287,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 callee-allocates) (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.
  */
@@ -1365,7 +1365,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)
@@ -1766,11 +1766,11 @@ rb_entry_view_append_column (RBEntryView *view,
 /**
  * rb_entry_view_append_column_custom:
  * @view: a #RBEntryView
- * @column: a #GtkTreeViewColumn to append
+ * @column: (transfer full): a #GtkTreeViewColumn to append
  * @title: title for the column (translated)
  * @key: sort key for the column (not translated)
  * @sort_func: comparison function to use for sorting on the column
- * @data: data to pass to the sort function
+ * @data: (closure) (scope notified): data to pass to the sort function
  * @data_destroy: function to use to destroy the sort data
  *
  * Appends a custom column to the entry view.  
@@ -1790,11 +1790,11 @@ rb_entry_view_append_column_custom (RBEntryView *view,
 /**
  * rb_entry_view_insert_column_custom:
  * @view: a #RBEntryView
- * @column: a #GtkTreeViewColumn to append
+ * @column: (transfer full): a #GtkTreeViewColumn to append
  * @title: title for the column (translated)
  * @key: sort key for the column (not translated)
  * @sort_func: comparison function to use for sorting on the column
- * @data: data to pass to the sort function
+ * @data: (closure) (scope notified): data to pass to the sort function
  * @data_destroy: function to use to destroy the sort data
  * @position: position at which to insert the column (-1 to insert at the end)
  *
@@ -2079,8 +2079,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)
@@ -2624,7 +2624,7 @@ rb_entry_view_emit_row_changed (RBEntryView *view,
  * @view: a #RBEntryView
  * @column: the column to set the width for
  * @renderer: a temporary cell renderer to use
- * @strings: a NULL-terminated array of strings that will be displayed in the column
+ * @strings: (array zero-terminated=1): a NULL-terminated array of strings that will be displayed in the column
  *
  * Helper function for calling @rb_set_tree_view_column_fixed_width on
  * a column.  This is important for performance reasons, as having the
diff --git a/widgets/rb-library-browser.c b/widgets/rb-library-browser.c
index 7979bb3..e1a98e7 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)
@@ -833,7 +833,7 @@ rb_library_browser_get_property_views (RBLibraryBrowser *widget)
  * Retrieves the property view widget for the specified property,
  * if there is one.
  *
- * Return value: #RBPropertyView widget, or NULL
+ * Return value: (transfer none): #RBPropertyView widget, or NULL
  */
 RBPropertyView *
 rb_library_browser_get_property_view (RBLibraryBrowser *widget,
@@ -849,7 +849,7 @@ rb_library_browser_get_property_view (RBLibraryBrowser *widget,
 /**
  * rb_library_browser_set_model:
  * @widget: a #RBLibraryBrowser
- * @model: the new input #RhythmDBQueryModel
+ * @model: (transfer none): the new input #RhythmDBQueryModel
  * @query_pending: if TRUE, the caller promises to run a
  *  query to populate the input query model.
  *
diff --git a/widgets/rb-property-view.c b/widgets/rb-property-view.c
index dbf8565..2340277 100644
--- a/widgets/rb-property-view.c
+++ b/widgets/rb-property-view.c
@@ -527,7 +527,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)
@@ -744,7 +744,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
@@ -789,7 +789,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 5443874..f7f7c26 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.
diff --git a/widgets/rb-segmented-bar.c b/widgets/rb-segmented-bar.c
index d089d74..c947f62 100644
--- a/widgets/rb-segmented-bar.c
+++ b/widgets/rb-segmented-bar.c
@@ -859,6 +859,14 @@ GtkWidget *rb_segmented_bar_new (void)
 	return g_object_new (RB_TYPE_SEGMENTED_BAR, NULL);
 }
 
+/**
+ * rb_segmented_bar_set_value_formatter:
+ * @bar: a #RBSegmentedBar
+ * @formatter: (scope async): the formatter function to use
+ * @data: data to pass to the formatter
+ *
+ * Sets a value formatter function to use for the bar.
+ */
 void rb_segmented_bar_set_value_formatter (RBSegmentedBar *bar,
 					   RBSegmentedBarValueFormatter formatter,
 					   gpointer data)



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]