fix various minor gtk-doc issues

backends/rb-player-gst-filter.h

@@ -40,8 +40,9 @@ G_BEGIN_DECLS
 #define RB_PLAYER_GST_FILTER_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE ((o), RB_TYPE_PLAYER_GST_FILTER, RBPlayerGstFilterIface))
 
 typedef struct _RBPlayerGstFilter RBPlayerGstFilter;
+typedef struct _RBPlayerGstFilterIface RBPlayerGstFilterIface;
 
-typedef struct
+struct _RBPlayerGstFilterIface
 {
 	GTypeInterface	g_iface;
 
@@ -52,7 +53,7 @@ typedef struct
 	/* signals */
 	void		(*filter_inserted)	(RBPlayerGstFilter *player, GstElement *filter);
 	void		(*filter_pre_remove)	(RBPlayerGstFilter *player, GstElement *filter);
-} RBPlayerGstFilterIface;
+};
 
 GType		rb_player_gst_filter_get_type   (void);
 

metadata/rb-metadata-common.c

@@ -63,6 +63,7 @@
  * @RB_METADATA_FIELD_MUSICBRAINZ_ALBUMID: MusicBrainz album ID
  * @RB_METADATA_FIELD_MUSICBRAINZ_ALBUMARTISTID: MusicBrainz album artist ID
  * @RB_METADATA_FIELD_ARTIST_SORTNAME: Person(s) responsible for the recording, as used for sorting
+ * @RB_METADATA_FIELD_ALBUM_SORTNAME: Album containing the recording, as used for sorting
  * @RB_METADATA_FIELD_LAST:  invalid field
  *
  * Metadata fields that can be read from and written to files.

metadata/rb-metadata-dbus-client.c

@@ -752,6 +752,7 @@ rb_metadata_get_saveable_types (RBMetaData *md)
 /**
  * rb_metadata_save:
  * @md: a #RBMetaData
+ * @uri: the target URI
  * @error: returns error information
  *
  * Saves all metadata changes made with rb_metadata_set to the

rhythmdb/rhythmdb-query.c

@@ -146,6 +146,7 @@ rhythmdb_query_parse_valist (RhythmDB *db, va_list args)
 /**
  * rhythmdb_query_parse:
  * @db: a #RhythmDB instance
+ * @Varargs: query criteria to parse
  *
  * Creates a query from a list of criteria.
  *
@@ -203,6 +204,7 @@ rhythmdb_query_parse (RhythmDB *db, ...)
  * rhythmdb_query_append:
  * @db: a #RhythmDB instance
  * @query: a query.
+ * @Varargs: query criteria to append
  *
  * Appends new criteria to the query @query.
  *
@@ -815,6 +817,8 @@ rhythmdb_query_is_time_relative (RhythmDB *db, GPtrArray *query)
  *
  * Returns a supposedly human-readable form of the query.
  * This is only intended for debug usage.
+ *
+ * Returns: allocated string form of the query
  **/
 char *
 rhythmdb_query_to_string (RhythmDB *db, GPtrArray *query)

shell/rb-removable-media-manager.c

@@ -536,6 +536,8 @@ rb_removable_media_manager_get_property (GObject *object,
  * @shell: the #RBShell
  *
  * Creates the #RBRemovableMediaManager instance.
+ *
+ * Return value: the #RBRemovableMediaManager
  */
 RBRemovableMediaManager *
 rb_removable_media_manager_new (RBShell *shell)

shell/rb-removable-media-manager.h

@@ -85,7 +85,7 @@ GType			rb_removable_media_manager_get_type	(void);
 
 void			rb_removable_media_manager_scan (RBRemovableMediaManager *manager);
 
-void	rb_removable_media_manager_queue_transfer (RBRemovableMediaManager *mgr,
+void	rb_removable_media_manager_queue_transfer (RBRemovableMediaManager *manager,
 						   RhythmDBEntry *entry,
 						   const char *dest,
 						   GList *mime_types,

sources/rb-auto-playlist-source.c

@@ -802,7 +802,7 @@ rb_auto_playlist_source_do_query (RBAutoPlaylistSource *source, gboolean subset)
  * @limit_type: the playlist limit type
  * @limit_value: the playlist limit value
  * @sort_key: the sorting key
- * @sort_direction: the sorting direction (as a #GtkSortType)
+ * @sort_order: the sorting direction (as a #GtkSortType)
  *
  * Sets the database query used to populate the playlist, and also the limit on
  * playlist size, and the sorting type used.
@@ -813,7 +813,7 @@ rb_auto_playlist_source_set_query (RBAutoPlaylistSource *source,
 				   RhythmDBQueryModelLimitType limit_type,
 				   GValueArray *limit_value,
 				   const char *sort_key,
-				   gint sort_direction)
+				   gint sort_order)
 {
 	RBAutoPlaylistSourcePrivate *priv = GET_PRIVATE (source);
 	RhythmDB *db = rb_playlist_source_get_db (RB_PLAYLIST_SOURCE (source));
@@ -834,7 +834,7 @@ rb_auto_playlist_source_set_query (RBAutoPlaylistSource *source,
 
 	/* playlists that aren't limited, with a particular sort order, are user-orderable */
 	rb_entry_view_set_columns_clickable (songs, (limit_type == RHYTHMDB_QUERY_MODEL_LIMIT_NONE));
-	rb_entry_view_set_sorting_order (songs, sort_key, sort_direction);
+	rb_entry_view_set_sorting_order (songs, sort_key, sort_order);
 
 	priv->query = rhythmdb_query_copy (query);
 	priv->limit_type = limit_type;
@@ -860,7 +860,7 @@ rb_auto_playlist_source_set_query (RBAutoPlaylistSource *source,
  * @limit_type: returns the playlist limit type
  * @limit_value: returns the playlist limit value
  * @sort_key: returns the playlist sorting key
- * @sort_direction: returns the playlist sorting direction (as a GtkSortOrder)
+ * @sort_order: returns the playlist sorting direction (as a GtkSortOrder)
  *
  * Extracts the current query, playlist limit, and sorting settings for the playlist.
  */
@@ -870,7 +870,7 @@ rb_auto_playlist_source_get_query (RBAutoPlaylistSource *source,
 				   RhythmDBQueryModelLimitType *limit_type,
 				   GValueArray **limit_value,
 				   char **sort_key,
-				   gint *sort_direction)
+				   gint *sort_order)
 {
 	RBAutoPlaylistSourcePrivate *priv;
 	RBEntryView *songs;
@@ -884,7 +884,7 @@ rb_auto_playlist_source_get_query (RBAutoPlaylistSource *source,
 	*limit_type = priv->limit_type;
 	*limit_value = (priv->limit_value) ? g_value_array_copy (priv->limit_value) : NULL;
 
-	rb_entry_view_get_sorting_order (songs, sort_key, sort_direction);
+	rb_entry_view_get_sorting_order (songs, sort_key, sort_order);
 }
 
 static void

sources/rb-removable-media-source.h

@@ -41,12 +41,15 @@ G_BEGIN_DECLS
 #define RB_IS_REMOVABLE_MEDIA_SOURCE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_REMOVABLE_MEDIA_SOURCE))
 #define RB_REMOVABLE_MEDIA_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_REMOVABLE_MEDIA_SOURCE, RBRemovableMediaSourceClass))
 
-typedef struct
+typedef struct _RBRemovableMediaSource RBRemovableMediaSource;
+typedef struct _RBRemovableMediaSourceClass RBRemovableMediaSourceClass;
+
+struct _RBRemovableMediaSource
 {
 	RBBrowserSource parent;
-} RBRemovableMediaSource;
+};
 
-typedef struct
+struct _RBRemovableMediaSourceClass
 {
 	RBBrowserSourceClass parent;
 
@@ -66,7 +69,7 @@ typedef struct
 						 GError *error);
 	gboolean	(*impl_should_paste)	(RBRemovableMediaSource *source,
 						 RhythmDBEntry *entry);
-} RBRemovableMediaSourceClass;
+};
 
 typedef gboolean	(*RBRemovableMediaSourceShouldPasteFunc) (RBRemovableMediaSource *source,
 								  RhythmDBEntry *entry);

sources/rb-source-group.h

@@ -46,15 +46,15 @@ GType rb_source_group_category_get_type (void);
 
 #define RB_TYPE_SOURCE_GROUP_CATEGORY (rb_source_group_category_get_type())
 
+typedef struct _RBSourceGroup RBSourceGroup;
 
-struct RBSourceGroup
+struct _RBSourceGroup
 {
 	char                 *name;
 	char                 *display_name;
 	RBSourceGroupCategory category;
 };
 
-typedef struct RBSourceGroup RBSourceGroup;
 
 GType          rb_source_group_get_type    (void);
 #define RB_TYPE_SOURCE_GROUP	(rb_source_group_get_type ())

sources/rb-source-search-basic.c

@@ -26,6 +26,15 @@
  *
  */
 
+/**
+ * SECTION:rb-source-search-basic
+ * @short_description: Simple implementation of #RBSourceSearch
+ *
+ * This implementation of #RBSourceSearch constructs queries that
+ * search on a single #RhythmDBEntry property.  It's useful for
+ * providing basic searches.
+ */
+
 #include "config.h"
 
 #include "rb-source-search-basic.h"
@@ -115,12 +124,13 @@ rb_source_search_basic_init (RBSourceSearchBasic *search)
 
 /**
  * rb_source_search_basic_new:
+ * @prop:	the #RhythmDBPropType to search
  *
  * Creates a new #RBSourceSearchBasic instance.
  * This performs simple string matching on a specified
  * property.
  *
- * @prop:	the #RhythmDBPropType to search
+ * Return value: newly created #RBSourceSearchBasic
  */
 RBSourceSearch *
 rb_source_search_basic_new (RhythmDBPropType prop)
@@ -130,15 +140,14 @@ rb_source_search_basic_new (RhythmDBPropType prop)
 
 /**
  * rb_source_search_basic_create_for_actions:
+ * @action_group:	the GtkActionGroup containing the actions
+ * @actions:		the GtkRadioActionEntries for the actions
+ * @n_actions:		the number of actions
  *
  * Creates #RBSourceSearchBasic instances for a set of
  * search actions and associates them with the actions.
  * The property to match on is taken from the action
  * value in the GtkRadioActionEntry structure.
- *
- * @action_group:	the GtkActionGroup containing the actions
- * @actions:		the GtkRadioActionEntries for the actions
- * @n_actions:		the number of actions
  */
 void
 rb_source_search_basic_create_for_actions (GtkActionGroup *action_group,

sources/rb-source-search-basic.h

@@ -46,16 +46,19 @@ G_BEGIN_DECLS
 #define RB_IS_SOURCE_SEARCH_BASIC_CLASS(o)  (G_TYPE_CHECK_CLASS_TYPE ((o), RB_TYPE_SOURCE_SEARCH_BASIC))
 #define RB_SOURCE_SEARCH_BASIC_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_SOURCE_SEARCH_BASIC, RBSourceSearchBasicClass))
 
-typedef struct
+typedef struct _RBSourceSearchBasic RBSourceSearchBasic;
+typedef struct _RBSourceSearchBasicClass RBSourceSearchBasicClass;
+
+struct _RBSourceSearchBasic
 {
 	RBSourceSearch parent;
 	RhythmDBPropType search_prop;
-} RBSourceSearchBasic;
+};
 
-typedef struct
+struct _RBSourceSearchBasicClass
 {
 	RBSourceSearchClass parent_class;
-} RBSourceSearchBasicClass;
+};
 
 GType		rb_source_search_basic_get_type	(void);
 

sources/rb-source-search.c

@@ -26,6 +26,22 @@
  *
  */
 
+/**
+ * SECTION:rb-source-search
+ * @short_description: Base class for source search implementations
+ *
+ * These translate the text in the search entry box into a
+ * RhythmDBQuery.  The basic implementation will return
+ * a query like RHYTHMDB_QUERY_PROP_LIKE, RHYTHMDB_PROP_SEARCH_MATCH,
+ * text.  Simple variants can restrict the search to single
+ * properties (artist, album, genre).  More complicated searches
+ * could implement something like the Xesam User Query spec.
+ *
+ * The source header finds the search instance to use by looking
+ * for the 'rb-source-search' data item on the active search
+ * action.
+ */
+
 #include "config.h"
 
 #include "rb-source-search.h"
@@ -60,16 +76,16 @@ rb_source_search_init (RBSourceSearch *search)
 
 /**
  * rb_source_search_is_subset:
+ * @search: a #RBSourceSearch
+ * @current: the current search text (or NULL if the current search was done with a different
+ *    search implementation and so cannot be considered)
+ * @next: the new search text
  *
  * Determines whether the new search text will result in a
  * subset of entries matched by the previous search.  This is
  * used to optimise the search query.
  *
- * @search: a #RBSourceSearch
- * @current: the current search text (or NULL if the current search was done with a different
- *    search implementation and so cannot be considered)
- * @next: the new search text
- * @return: TRUE iff the new search text will match a subset of those matched by the current search.
+ * Return value: TRUE iff the new search text will match a subset of those matched by the current search.
  */
 gboolean
 rb_source_search_is_subset (RBSourceSearch *search, const char *current, const char *next)
@@ -80,13 +96,13 @@ rb_source_search_is_subset (RBSourceSearch *search, const char *current, const c
 
 /**
  * rb_source_search_create_query:
- *
- * Creates a #RhythmDBQuery from the user's search text.
- *
  * @search: a #RBSourceSearch
  * @db: the #RhythmDB
  * @search_text: the search text
- * @return: #RhythmDBQuery for the source to use
+ *
+ * Creates a #RhythmDBQuery from the user's search text.
+ *
+ * Return value: #RhythmDBQuery for the source to use
  */
 RhythmDBQuery *
 rb_source_search_create_query (RBSourceSearch *search, RhythmDB *db, const char *search_text)
@@ -98,14 +114,14 @@ rb_source_search_create_query (RBSourceSearch *search, RhythmDB *db, const char
 
 /**
  * _rb_source_search_create_simple_query:
- *
- * Creates a basic search query.
- *
  * @search: the #RBSourceSearch
  * @db: the #RhythmDB
  * @search_text: the search text such as RHYTHMDB_PROP_SEARCH_MATCH
  * @search_prop: the search property
- * @return: the #RhythmDBQuery for the search text and property, or NULL
+ *
+ * Creates a basic search query.
+ *
+ * Return value: the #RhythmDBQuery for the search text and property, or NULL
  *   if no search text is specified.
  */
 RhythmDBQuery *
@@ -123,12 +139,11 @@ _rb_source_search_create_simple_query (RBSourceSearch *search, RhythmDB *db, con
 
 /**
  * rb_source_search_action_attach:
+ * @search: #RBSourceSearch to associate with the action
+ * @action: UI action to associate the search with
  *
  * Attaches a #RBSourceSearch to a UI action so that
  * the search implementation will be used when the action is active.
- *
- * @search: #RBSourceSearch to associate with the action
- * @action: UI action to associate the search with
  */
 void
 rb_source_search_action_attach (RBSourceSearch *search, GObject *action)
@@ -141,12 +156,12 @@ rb_source_search_action_attach (RBSourceSearch *search, GObject *action)
 
 /**
  * rb_source_search_get_from_action:
+ * @action: the action to find the #RBSourceSearch for
  *
  * Returns the #RBSourceSearch associated with the
  * specified UI action.
  *
- * @action: the action to find the #RBSourceSearch for
- * @return: associated #RBSourceSearch
+ * Return value: associated #RBSourceSearch
  */
 RBSourceSearch *
 rb_source_search_get_from_action (GObject *action)