[rhythmbox/gobject-introspection: 24/27] add a variety of annotations

[Jonathan Matthew <jmatthew src gnome org>]

commit bc0106eefcc7a04018360f3c043594a09e0807bc
Author: Jonathan Matthew <jonathan d14n org>
Date:   Wed Aug 4 11:22:27 2010 +1000

    add a variety of annotations

 backends/rb-encoder.c               |    8 ++--
 backends/rb-player.h                |    2 +-
 lib/rb-util.c                       |   75 ++++++++++++++--------------
 metadata/rb-metadata-dbus-client.c  |   14 +++--
 rhythmdb/rhythmdb-query.c           |    2 +-
 rhythmdb/rhythmdb.c                 |    7 +--
 shell/rb-history.c                  |   12 ++--
 shell/rb-play-order.c               |   34 +++++++++---
 shell/rb-playlist-manager.c         |    6 +-
 shell/rb-plugin.c                   |    2 +-
 shell/rb-shell-player.c             |   20 ++++----
 shell/rb-shell-preferences.c        |    2 +-
 shell/rb-shell.c                    |   12 ++--
 shell/rb-shell.h                    |    4 +-
 sources/rb-auto-playlist-source.c   |   12 ++--
 sources/rb-browser-source.c         |    3 +-
 sources/rb-media-player-source.c    |   32 ++++++++++++
 sources/rb-playlist-source.c        |    4 +-
 sources/rb-removable-media-source.c |   23 ++++++++-
 sources/rb-source-search.c          |    6 +-
 sources/rb-source.c                 |   94 +++++++++++++++++++++++++++++-----
 sources/rb-static-playlist-source.c |    2 +-
 sources/rb-streaming-source.c       |    4 +-
 widgets/rb-entry-view.c             |   14 +++---
 widgets/rb-library-browser.c        |    8 ++--
 widgets/rb-property-view.c          |    4 +-
 26 files changed, 269 insertions(+), 137 deletions(-)
---
diff --git a/backends/rb-encoder.c b/backends/rb-encoder.c
index 02ad222..87bfe32 100644
--- a/backends/rb-encoder.c
+++ b/backends/rb-encoder.c
@@ -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.
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/rb-util.c b/lib/rb-util.c
index b8a3e3b..ba73c2e 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
  *
@@ -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, 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
diff --git a/metadata/rb-metadata-dbus-client.c b/metadata/rb-metadata-dbus-client.c
index 9009bb3..4b0242b 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: (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-query.c b/rhythmdb/rhythmdb-query.c
index 24d8f4f..6f8bcea 100644
--- a/rhythmdb/rhythmdb-query.c
+++ b/rhythmdb/rhythmdb-query.c
@@ -861,7 +861,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.c b/rhythmdb/rhythmdb.c
index a4a0655..a929d6c 100644
--- a/rhythmdb/rhythmdb.c
+++ b/rhythmdb/rhythmdb.c
@@ -5276,11 +5276,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/shell/rb-history.c b/shell/rb-history.c
index e8b9564..f5f5f99 100644
--- a/shell/rb-history.c
+++ b/shell/rb-history.c
@@ -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 RhythmDB.Entry) (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 adc079e..2b85079 100644
--- a/shell/rb-playlist-manager.c
+++ b/shell/rb-playlist-manager.c
@@ -1638,12 +1638,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)
@@ -1663,7 +1663,7 @@ rb_playlist_manager_get_playlists (RBPlaylistManager *mgr)
 /**
  * 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
diff --git a/shell/rb-plugin.c b/shell/rb-plugin.c
index 8aa3e2d..dc84c06 100644
--- a/shell/rb-plugin.c
+++ b/shell/rb-plugin.c
@@ -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-shell-player.c b/shell/rb-shell-player.c
index 4570d14..35e67b6 100644
--- a/shell/rb-shell-player.c
+++ b/shell/rb-shell-player.c
@@ -1434,7 +1434,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)
@@ -1449,7 +1449,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)
@@ -1487,7 +1487,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)
@@ -1784,8 +1784,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.
  *
@@ -2560,7 +2560,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
@@ -2608,7 +2608,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
@@ -3230,7 +3230,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.
@@ -3268,7 +3268,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
@@ -3700,7 +3700,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 b057312..cc49be2 100644
--- a/shell/rb-shell-preferences.c
+++ b/shell/rb-shell-preferences.c
@@ -365,7 +365,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.
diff --git a/shell/rb-shell.c b/shell/rb-shell.c
index b3db3a6..9c21ddf 100644
--- a/shell/rb-shell.c
+++ b/shell/rb-shell.c
@@ -1970,7 +1970,7 @@ rb_shell_register_entry_type_for_source (RBShell *shell,
  * rb_shell_append_source:
  * @shell: the #RBShell
  * @source: the new #RBSource
- * @parent: the parent source for the new source (optional)
+ * @parent: (allow-none): the parent source for the new source
  *
  * Registers a new source with the shell.  All sources must be
  * registered.
@@ -3080,7 +3080,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,
@@ -3345,7 +3345,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)
@@ -3373,7 +3373,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)
@@ -3401,7 +3401,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)
@@ -3500,7 +3500,7 @@ rb_shell_present (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-shell.h b/shell/rb-shell.h
index b1c7065..9a7cb14 100644
--- a/shell/rb-shell.h
+++ b/shell/rb-shell.h
@@ -42,14 +42,14 @@ G_BEGIN_DECLS
 #define RB_IS_SHELL_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_SHELL))
 #define RB_SHELL_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_SHELL, RBShellClass))
 
-enum
+typedef enum
 {
 	RB_SHELL_ERROR_NO_SUCH_URI,
 	RB_SHELL_ERROR_NO_SUCH_PROPERTY,
 	RB_SHELL_ERROR_IMMUTABLE_PROPERTY,
 	RB_SHELL_ERROR_INVALID_PROPERTY_TYPE,
 	RB_SHELL_ERROR_NO_SOURCE_FOR_URI
-};
+} RBShellError;
 
 #define RB_SHELL_ERROR rb_shell_error_quark ()
 
diff --git a/sources/rb-auto-playlist-source.c b/sources/rb-auto-playlist-source.c
index b724fc7..5fe91f6 100644
--- a/sources/rb-auto-playlist-source.c
+++ b/sources/rb-auto-playlist-source.c
@@ -798,7 +798,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
@@ -856,11 +856,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 a31609a..d28bf3e 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-media-player-source.c b/sources/rb-media-player-source.c
index b548fac..f6fd36c 100644
--- a/sources/rb-media-player-source.c
+++ b/sources/rb-media-player-source.c
@@ -269,6 +269,12 @@ 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
+ * @map: (element-type utf8 RhythmDB.Entry): map to hold the entries
+ */
 void
 rb_media_player_source_get_entries (RBMediaPlayerSource *source,
 				    const char *category,
@@ -278,6 +284,14 @@ rb_media_player_source_get_entries (RBMediaPlayerSource *source,
 	klass->impl_get_entries (source, category, map);
 }
 
+/**
+ * rb_media_player_source_delete_entries:
+ * @source: the #RBMediaPlayerSource
+ * @entries: (element-type RhythmDB.Entry) (transfer full): list of entries to delete
+ * @callback: callback to call on completion
+ * @callback_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,
@@ -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 RhythmDB.Entry) (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 RhythmDB.Entry) (transfer full): list of entries to add
+ */
diff --git a/sources/rb-playlist-source.c b/sources/rb-playlist-source.c
index f7cb118..0b74965 100644
--- a/sources/rb-playlist-source.c
+++ b/sources/rb-playlist-source.c
@@ -1008,7 +1008,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)
@@ -1025,7 +1025,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 54f6d64..ae1c36b 100644
--- a/sources/rb-removable-media-source.c
+++ b/sources/rb-removable-media-source.c
@@ -664,7 +664,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)
@@ -685,7 +685,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)
@@ -1042,3 +1042,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 04004e4..05b75fb 100644
--- a/sources/rb-source.c
+++ b/sources/rb-source.c
@@ -738,9 +738,9 @@ default_get_status (RBSource *source,
 /**
  * rb_source_get_status:
  * @source: a #RBSource
- * @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 source.
  * If the progress value returned is less than zero, the progress bar
@@ -907,7 +907,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)
@@ -947,8 +947,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
@@ -1094,8 +1094,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 RhythmDB.Entry) (transfer full): entries cut
+ * from the source.
  */
 GList *
 rb_source_cut (RBSource *source)
@@ -1122,8 +1122,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 RhythmDB.Entry) (transfer full): a list containing
+ * the currently selected entries from the source.
  */
 GList *
 rb_source_copy (RBSource *source)
@@ -1136,7 +1136,7 @@ rb_source_copy (RBSource *source)
 /**
  * rb_source_paste:
  * @source: a #RBSource
- * @entries: a list of #RhythmDBEntry objects to paste in
+ * @entries: (element-type RhythmDB.Entry): 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,
@@ -1558,6 +1558,7 @@ default_get_entry_view (RBSource *source)
 static void
 default_activate (RBSource *source)
 {
+	g_print ("what?\n");
 	return;
 }
 
@@ -1608,7 +1609,7 @@ default_get_ui_actions (RBSource *source)
  * 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_source_get_ui_actions (RBSource *source)
@@ -1633,7 +1634,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)
@@ -1721,7 +1722,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,
@@ -2002,3 +2003,68 @@ rb_source_search_type_get_type (void)
 	return etype;
 }
 
+/* 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_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_get_config_widget:
+ * @source: a #RBSource
+ * @prefs: a #RBShellPreferences
+ *
+ * Return value: (transfer none): configuration widget
+ */
+
+/**
+ * impl_cut:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type RhythmDB.Entry) (transfer full): list of entries
+ */
+
+/**
+ * impl_copy:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type RhythmDB.Entry) (transfer full): list of entries
+ */
+
+/**
+ * impl_paste:
+ * @source: a #RBSource
+ * @entries: (element-type RhythmDB.Entry) (transfer none): list of entries to paste
+ */
+
+/**
+ * impl_get_ui_actions:
+ * @source: a #RBSource
+ *
+ * Return value: (element-type utf8) (transfer full): list of action names
+ */
+
+/**
+ * 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 21ff166..66eb4d7 100644
--- a/sources/rb-static-playlist-source.c
+++ b/sources/rb-static-playlist-source.c
@@ -828,7 +828,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 4bbee36..e27ae7a 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-entry-view.c b/widgets/rb-entry-view.c
index 3dfacf7..082254c 100644
--- a/widgets/rb-entry-view.c
+++ b/widgets/rb-entry-view.c
@@ -1273,7 +1273,7 @@ rb_entry_view_set_sorting_type (RBEntryView *view,
 /**
  * rb_entry_view_get_sorting_order:
  * @view: a #RBEntryView
- * @column_name: (out) (allow-none) (transfer full): returns the sort column name
+ * @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.
@@ -1351,7 +1351,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: (transfer none) a #GtkTreeViewColumn instance, or NULL
+ * Return value: (transfer none): a #GtkTreeViewColumn instance, or NULL
  */
 GtkTreeViewColumn *
 rb_entry_view_get_column (RBEntryView *view, RBEntryViewColumn coltype)
@@ -1752,11 +1752,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.  
@@ -1776,11 +1776,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)
  *
@@ -2610,7 +2610,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 a20b796..e1a98e7 100644
--- a/widgets/rb-library-browser.c
+++ b/widgets/rb-library-browser.c
@@ -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: (element-type utf8) (transfer none) 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,7 +814,7 @@ rb_library_browser_set_selection (RBLibraryBrowser *widget,
  *
  * Retrieves the property view widgets from the browser.
  *
- * Return value: (element-type RBPropertyView) (transfer container) a GList
+ * Return value: (element-type RBPropertyView) (transfer container): a #GList
  * containing the #RBPropertyView widgets in the browser.
  */
 GList*
@@ -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 e9a6352..9ec223c 100644
--- a/widgets/rb-property-view.c
+++ b/widgets/rb-property-view.c
@@ -740,7 +740,7 @@ rb_property_view_row_activated_cb (GtkTreeView *treeview,
 /**
  * rb_property_view_set_selection:
  * @view: a #RBPropertyView
- * @vals: (element-type utf8) 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: (element-type utf8) (transfer full) list of selected values
+ * Return value: (element-type utf8) (transfer full): list of selected values
  */
 GList *
 rb_property_view_get_selection (RBPropertyView *view)