rhythmbox r5654 - in trunk: . doc/reference sources

[jmatthew svn gnome org]

Author: jmatthew
Date: Thu Mar 27 12:46:00 2008
New Revision: 5654
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5654&view=rev

Log:
2008-03-27  Jonathan Matthew  <jonathan d14n org>

	* doc/reference/rhythmbox-sections.txt:
	* sources/rb-playlist-source.c: (rb_playlist_source_class_init):
	* sources/rb-playlist-source.h:
	* sources/rb-source.c: (rb_source_class_init):
	* sources/rb-sourcelist-model.c: (rb_sourcelist_model_class_init),
	(rb_sourcelist_model_column_get_type):
	* sources/rb-sourcelist-model.h:
	* sources/rb-sourcelist.c: (rb_sourcelist_class_init):
	* sources/rb-sourcelist.h:
	Add gtk-doc for RBPlaylistSource, RBSourceList, RBSourceListModel.
	Add gtk-doc for the new base-query-model property.


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/sources/rb-playlist-source.c
   trunk/sources/rb-playlist-source.h
   trunk/sources/rb-source.c
   trunk/sources/rb-sourcelist-model.c
   trunk/sources/rb-sourcelist-model.h
   trunk/sources/rb-sourcelist.c
   trunk/sources/rb-sourcelist.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Thu Mar 27 12:46:00 2008
@@ -223,7 +223,6 @@
 <TITLE>RBSourceHeader</TITLE>
 RBSourceHeader
 RBSourceHeaderClass
-RBSourceHeaderPrivate
 rb_source_header_new
 rb_source_header_set_source
 rb_source_header_get_source
@@ -231,6 +230,7 @@
 rb_source_header_sync_control_state
 rb_source_header_focus_search_box
 <SUBSECTION Standard>
+RBSourceHeaderPrivate
 RB_SOURCE_HEADER
 RB_IS_SOURCE_HEADER
 RB_TYPE_SOURCE_HEADER
@@ -512,7 +512,9 @@
 
 <SECTION>
 <FILE>rb-sourcelist</FILE>
-RBSourceListPriv
+<TITLE>RBSourceList</TITLE>
+RBSourceList
+RBSourceListClass
 rb_sourcelist_new
 rb_sourcelist_append
 rb_sourcelist_set_playing_source
@@ -520,6 +522,7 @@
 rb_sourcelist_remove
 rb_sourcelist_select
 <SUBSECTION Standard>
+RBSourceListPriv
 RB_SOURCELIST
 RB_IS_SOURCELIST
 RB_TYPE_SOURCELIST
@@ -531,7 +534,10 @@
 
 <SECTION>
 <FILE>rb-sourcelist-model</FILE>
-RBSourceListModelPriv
+<TITLE>RBSourceListModel</TITLE>
+RBSourceListModel
+RBSourceListModelClass
+RBSourceListModelColumn
 rb_sourcelist_model_new
 rb_sourcelist_model_set_dnd_targets
 <SUBSECTION Standard>
@@ -563,7 +569,9 @@
 
 <SECTION>
 <FILE>rb-playlist-source</FILE>
-RBPlaylistSourcePrivate
+<TITLE>RBPlaylistSource</TITLE>
+RBPlaylistSource
+RBPlaylistSourceClass
 rb_playlist_source_new
 rb_playlist_source_new_from_xml
 rb_playlist_source_save_playlist
@@ -576,6 +584,7 @@
 rb_playlist_source_location_in_map
 rb_playlist_source_add_to_map
 <SUBSECTION Standard>
+RBPlaylistSourcePrivate
 RB_PLAYLIST_SOURCE
 RB_IS_PLAYLIST_SOURCE
 RB_TYPE_PLAYLIST_SOURCE
@@ -592,7 +601,6 @@
 RBSourceClass
 RBSourceEOFType
 RB_SOURCE_ICON_SIZE
-RBSourcePrivate
 rb_source_notify_filter_changed
 rb_source_notify_status_changed
 rb_source_update_play_statistics
@@ -925,13 +933,13 @@
 <TITLE>RBSearchEntry</TITLE>
 RBSearchEntry
 RBSearchEntryClass
-RBSearchEntryPrivate
 rb_search_entry_new
 rb_search_entry_clear
 rb_search_entry_set_text
 rb_search_entry_searching
 rb_search_entry_grab_focus
 <SUBSECTION Standard>
+RBSearchEntryPrivate
 RB_SEARCH_ENTRY
 RB_IS_SEARCH_ENTRY
 RB_TYPE_SEARCH_ENTRY
@@ -972,9 +980,9 @@
 <TITLE>RBRating</TITLE>
 RBRating
 RBRatingClass
-RBRatingPrivate
 rb_rating_new
 <SUBSECTION Standard>
+RBRatingPrivate
 RB_RATING
 RB_IS_RATING
 RB_TYPE_RATING
@@ -1101,7 +1109,8 @@
 
 <SECTION>
 <FILE>rb-header</FILE>
-RBHeaderPrivate
+RBHeader
+RBHeaderClass
 rb_header_new
 rb_header_set_playing_entry
 rb_header_show_position_slider
@@ -1109,6 +1118,7 @@
 rb_header_sync_time
 rb_header_get_elapsed_string
 <SUBSECTION Standard>
+RBHeaderPrivate
 RB_HEADER
 RB_IS_HEADER
 RB_TYPE_HEADER
@@ -1426,7 +1436,6 @@
 <TITLE>RhythmDBImportJob</TITLE>
 RhythmDBImportJob
 RhythmDBImportJobClass
-RhythmDBImportJobPrivate
 rhythmdb_import_job_new
 rhythmdb_import_job_add_uri
 rhythmdb_import_job_start
@@ -1436,6 +1445,7 @@
 rhythmdb_import_job_get_total
 rhythmdb_import_job_get_imported
 <SUBSECTION Standard>
+RhythmDBImportJobPrivate
 RHYTHMDB_IMPORT_JOB
 RHYTHMDB_IS_IMPORT_JOB
 RHYTHMDB_TYPE_IMPORT_JOB
@@ -1450,9 +1460,9 @@
 <TITLE>RBURIDialog</TITLE>
 RBURIDialog
 RBURIDialogClass
-RBURIDialogPrivate
 rb_uri_dialog_new
 <SUBSECTION Standard>
+RBURIDialogPrivate
 RB_URI_DIALOG
 RB_IS_URI_DIALOG
 RB_TYPE_URI_DIALOG
@@ -2280,9 +2290,9 @@
 <TITLE>RBImportErrorsSource</TITLE>
 RBImportErrorsSource
 RBImportErrorsSourceClass
-RBImportErrorsSourcePrivate
 rb_import_errors_source_new
 <SUBSECTION Standard>
+RBImportErrorsSourcePrivate
 RB_IMPORT_ERRORS_SOURCE
 RB_IS_IMPORT_ERRORS_SOURCE
 RB_TYPE_IMPORT_ERRORS_SOURCE
@@ -2414,9 +2424,9 @@
 <TITLE>RBMissingFilesSource</TITLE>
 RBMissingFilesSource
 RBMissingFilesSourceClass
-RBMissingFilesSourcePrivate
 rb_missing_files_source_new
 <SUBSECTION Standard>
+RBMissingFilesSourcePrivate
 RB_MISSING_FILES_SOURCE
 RB_IS_MISSING_FILES_SOURCE
 RB_TYPE_MISSING_FILES_SOURCE

Modified: trunk/sources/rb-playlist-source.c
==============================================================================
--- trunk/sources/rb-playlist-source.c	(original)
+++ trunk/sources/rb-playlist-source.c	Thu Mar 27 12:46:00 2008
@@ -47,6 +47,22 @@
 #include "rb-static-playlist-source.h"
 #include "rb-auto-playlist-source.h"
 
+/**
+ * SECTION:rb-playlist-source
+ * @short_description: Base class for playlist sources
+ *
+ * This class provides some common infrastructure for playlist
+ * sources.  A playlist, in this context, is a persistent user-defined
+ * selection from a set of songs.  Playlists (static and auto) based 
+ * on the main library are saved to the playlists.xml file stored
+ * alongside the rhythmdb.xml file.  Playlists on portable music players
+ * are saved on the device in the format the player itself supports.
+ *
+ * This class provides most of the source UI (excluding the search bar),
+ * holds some of the framework for loading and saving the playlists.xml
+ * file, and records which playlists need to be saved.
+ */
+
 static void rb_playlist_source_class_init (RBPlaylistSourceClass *klass);
 static void rb_playlist_source_init (RBPlaylistSource *source);
 static GObject *rb_playlist_source_constructor (GType type,
@@ -157,6 +173,11 @@
 	klass->impl_show_entry_view_popup = default_show_entry_view_popup;
 	klass->impl_mark_dirty = default_mark_dirty;
 
+	/**
+	 * RBPlaylistSource:db:
+	 *
+	 * The #RhythmDB instance
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_DB,
 					 g_param_spec_object ("db",
@@ -164,6 +185,12 @@
 							      "rhythmdb instance",
 							      RHYTHMDB_TYPE,
 							      G_PARAM_READABLE));
+	/**
+	 * RBPlaylistSource:dirty:
+	 *
+	 * Whether the playlist has been changed since it was last saved
+	 * to disk.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_DIRTY,
 					 g_param_spec_boolean ("dirty",
@@ -171,6 +198,12 @@
 							       "whether this playlist should be saved",
 							       FALSE,
 							       G_PARAM_READABLE));
+	/**
+	 * RBPlaylistSource:is-local:
+	 *
+	 * Whether the playlist is attached to the local library.
+	 * Remote DAAP playlists, for example, are not local.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_LOCAL,
 					 g_param_spec_boolean ("is-local",
@@ -523,6 +556,15 @@
 }
 #endif /* TOTEM_PL_PARSER_CHECK_VERSION */
 
+/**
+ * rb_playlist_source_save_playlist:
+ * @source: a #RBPlaylistSource
+ * @uri: destination URI
+ * @m3u_format: if TRUE, save as .m3u, otherwise .pls
+ *
+ * Saves the playlist to an external file in a standard
+ * format (M3U or PLS).
+ */
 void
 rb_playlist_source_save_playlist (RBPlaylistSource *source,
 				  const char *uri,
@@ -633,6 +675,19 @@
 	return name;
 }
 
+/**
+ * rb_playlist_source_new_from_xml:
+ * @shell: the #RBShell instance
+ * @node: libxml node containing the playlist
+ *
+ * Constructs a playlist source instance from the XML serialized
+ * format.  This function knows about all the playlist types that
+ * can be saved to disk, and it hands off the XML node to the
+ * appropriate constructor based on the 'type' attribute of
+ * the root node of the playlist.
+ *
+ * Return value: the playlist
+ */
 RBSource *
 rb_playlist_source_new_from_xml	(RBShell *shell,
 				 xmlNodePtr node)
@@ -672,6 +727,14 @@
 	return source;
 }
 
+/**
+ * rb_playlist_source_save_to_xml:
+ * @source: the playlist source to save
+ * @parent_node: libxml node below which to save the playlist
+ *
+ * Converts the playlist to XML format, below the specified
+ * parent node.
+ */
 void
 rb_playlist_source_save_to_xml (RBPlaylistSource *source,
 				xmlNodePtr parent_node)
@@ -749,6 +812,15 @@
 	g_free (str);
 }
 
+/**
+ * rb_playlist_source_setup_entry_view:
+ * @source: the #RBPlaylistSource
+ * @entry_view: the new #RBEntryView to set up
+ *
+ * Connects signal handlers and sets up drag and drop support for
+ * an entry view to be used by a playlist source.  This only needs
+ * to be called if the playlist subclass is creating a new entry view.
+ */
 void
 rb_playlist_source_setup_entry_view (RBPlaylistSource *source,
 				     RBEntryView *entry_view)
@@ -766,6 +838,18 @@
 			   GDK_ACTION_COPY);
 }
 
+/**
+ * rb_playlist_source_set_query_model:
+ * @source: the #RBPlaylistSource
+ * @model: the new #RhythmDBQueryModel
+ *
+ * Sets a new query model for the playlist.  This updates the
+ * entry view to use the new query model and also updates the
+ * source query-model property.
+ *
+ * This needs to be called when the playlist subclass
+ * creates a new query model.
+ */
 void
 rb_playlist_source_set_query_model (RBPlaylistSource *source,
 				    RhythmDBQueryModel *model)
@@ -796,6 +880,15 @@
 	g_object_set (source, "query-model", source->priv->model, NULL);
 }
 
+/**
+ * rb_playlist_source_get_db:
+ * @source: a #RBPlaylistSource
+ *
+ * Returns the #RhythmDB instance.  The caller must not
+ * unref the object once finished with it.
+ *
+ * Return value: the #RhythmDB instance
+ */
 RhythmDB *
 rb_playlist_source_get_db (RBPlaylistSource *source)
 {
@@ -804,6 +897,15 @@
 	return source->priv->db;
 }
 
+/**
+ * rb_playlist_source_get_query_model:
+ * @source: a #RBPlaylistSource
+ *
+ * Returns the current #RhythmDBQueryModel for the playlist.
+ * The caller must not unref the object once finished with it.
+ *
+ * Return value: the current #RhythmDBQueryModel
+ */
 RhythmDBQueryModel *
 rb_playlist_source_get_query_model (RBPlaylistSource *source)
 {
@@ -818,6 +920,14 @@
 	source->priv->dirty = TRUE;
 }
 
+/**
+ * rb_playlist_source_mark_dirty:
+ * @source: a #RBPlaylistSource
+ *
+ * Marks the playlist dirty.  This generally means that the playlist
+ * will be saved to disk fairly soon, but the exact meaning can vary
+ * between playlist types.
+ */
 void
 rb_playlist_source_mark_dirty (RBPlaylistSource *source)
 {
@@ -828,6 +938,13 @@
 	klass->impl_mark_dirty (source);
 }
 
+/**
+ * rb_playlist_source_location_in_map:
+ * @source: a #RBPlaylistSource
+ * @location: a URI to check
+ *
+ * Return value: TRUE if the specified URI is in the playlist entry map
+ */
 gboolean
 rb_playlist_source_location_in_map (RBPlaylistSource *source,
 				    const char *location)
@@ -848,6 +965,18 @@
 	return found;
 }
 
+/**
+ * rb_playlist_source_add_to_map:
+ * @source: a #RBPlaylistSource
+ * @location: a URI to add
+ *
+ * Adds a URI to the playlist's entry map.  This is useful when the
+ * URI is being added to the database, but no entry exists for it yet.
+ * When the entry is created, it will be added to the query model.
+ *
+ * Return value: TRUE if the URI was added to the entry map,
+ *  FALSE if it was already there.
+ */
 gboolean
 rb_playlist_source_add_to_map (RBPlaylistSource *source,
 			       const char *location)

Modified: trunk/sources/rb-playlist-source.h
==============================================================================
--- trunk/sources/rb-playlist-source.h	(original)
+++ trunk/sources/rb-playlist-source.h	Thu Mar 27 12:46:00 2008
@@ -39,16 +39,19 @@
 #define RB_IS_PLAYLIST_SOURCE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_PLAYLIST_SOURCE))
 #define RB_PLAYLIST_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_PLAYLIST_SOURCE, RBPlaylistSourceClass))
 
+typedef struct _RBPlaylistSource RBPlaylistSource;
+typedef struct _RBPlaylistSourceClass RBPlaylistSourceClass;
+
 typedef struct RBPlaylistSourcePrivate RBPlaylistSourcePrivate;
 
-typedef struct
+struct _RBPlaylistSource
 {
 	RBSource parent;
 
 	RBPlaylistSourcePrivate *priv;
-} RBPlaylistSource;
+};
 
-typedef struct
+struct _RBPlaylistSourceClass
 {
 	RBSourceClass parent;
 
@@ -56,8 +59,7 @@
 	void	(*impl_show_entry_view_popup)	(RBPlaylistSource *source, RBEntryView *view, gboolean over_entry);
 	void	(*impl_save_contents_to_xml)	(RBPlaylistSource *source, xmlNodePtr node);
 	void	(*impl_mark_dirty)		(RBPlaylistSource *source);
-
-} RBPlaylistSourceClass;
+};
 
 GType		rb_playlist_source_get_type	(void);
 
@@ -69,7 +71,7 @@
 						 gboolean m3u_format);
 
 void		rb_playlist_source_save_to_xml	(RBPlaylistSource *source,
-						 xmlNodePtr node);
+						 xmlNodePtr parent_node);
 
 /* methods for subclasses to call */
 

Modified: trunk/sources/rb-source.c
==============================================================================
--- trunk/sources/rb-source.c	(original)
+++ trunk/sources/rb-source.c	Thu Mar 27 12:46:00 2008
@@ -316,6 +316,13 @@
 							      "RBPlugin instance for the plugin that created the source",
 							      RB_TYPE_PLUGIN,
 							      G_PARAM_READWRITE));
+	/**
+	 * RBSource:base-query-model:
+	 *
+	 * The unfiltered query model for the source, containing all entries in the source.
+	 * Source classes should override this if they perform filtering based on the search
+	 * box or a browser.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_BASE_QUERY_MODEL,
 					 g_param_spec_object ("base-query-model",

Modified: trunk/sources/rb-sourcelist-model.c
==============================================================================
--- trunk/sources/rb-sourcelist-model.c	(original)
+++ trunk/sources/rb-sourcelist-model.c	Thu Mar 27 12:46:00 2008
@@ -35,6 +35,29 @@
 #include "rb-marshal.h"
 #include "rb-playlist-source.h"
 
+/**
+ * SECTION:rb-sourcelist-model
+ * @short_description: models backing the source list widget
+ *
+ * The #RBSourceList widget is backed by a #GtkTreeStore containing
+ * the sources and a set of attributes used to structure and display
+ * them, and a #GtkTreeModelFilter that hides sources with the
+ * visibility property set to FALSE.  This class implements the filter
+ * model and also creates the actual model.
+ *
+ * The source list model supports drag and drop in a variety of formats.
+ * The simplest of these are text/uri-list and application/x-rhythmbox-entry,
+ * which convey URIs and IDs of existing database entries.  When dragged
+ * to an existing source, these just add the URIs or entries to the target
+ * source.  When dragged to an empty space in the source list, this results
+ * in the creation of a static playlist.
+ *
+ * text/x-rhythmbox-artist, text/x-rhythmbox-album, and text/x-rhythmbox-genre
+ * are used when dragging items from the library browser.  When dragged to
+ * the source list, these result in the creation of a new auto playlist with
+ * the dragged items as criteria.
+ */
+
 struct RBSourceListModelPrivate
 {
 	gpointer dummy;
@@ -128,6 +151,15 @@
 
 	o_class->finalize = rb_sourcelist_model_finalize;
 
+	/**
+	 * RBSourceListModel::drop-received:
+	 * @model: the #RBSourceListModel
+	 * @target: the #RBSource receiving the drop
+	 * @pos: the drop position
+	 * @data: the drop data
+	 *
+	 * Emitted when a drag and drop operation to the source list completes.
+	 */
 	rb_sourcelist_model_signals[DROP_RECEIVED] =
 		g_signal_new ("drop_received",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -164,6 +196,13 @@
   iface->rb_drag_data_delete = rb_sourcelist_model_drag_data_delete;
 }
 
+/**
+ * rb_sourcelist_model_set_dnd_targets:
+ * @sourcelist: the #RBSourceListModel
+ * @treeview: the sourcel ist #GtkTreeView
+ *
+ * Sets up the drag and drop targets for the source list.
+ */
 void
 rb_sourcelist_model_set_dnd_targets (RBSourceListModel *sourcelist,
 				     GtkTreeView *treeview)
@@ -199,6 +238,14 @@
 	G_OBJECT_CLASS (rb_sourcelist_model_parent_class)->finalize (object);
 }
 
+/**
+ * rb_sourcelist_model_new:
+ *
+ * This constructs both the GtkTreeStore holding the source
+ * data and the filter model that hides invisible sources.
+ * 
+ * Return value: the #RBSourceListModel
+ */
 GtkTreeModel *
 rb_sourcelist_model_new (void)
 {
@@ -546,6 +593,20 @@
 	gtk_tree_model_filter_refilter (GTK_TREE_MODEL_FILTER (sourcelist));
 }
 
+/**
+ * RBSourceListModelColumn:
+ * @RB_SOURCELIST_MODEL_COLUMN_PLAYING: TRUE if the source is playing
+ * @RB_SOURCELIST_MODEL_COLUMN_PIXBUF: the source's icon as a pixbuf
+ * @RB_SOURCELIST_MODEL_COLUMN_NAME: the source name
+ * @RB_SOURCELIST_MODEL_COLUMN_SOURCE: the #RBSource object
+ * @RB_SOURCELIST_MODEL_COLUMN_ATTRIBUTES: Pango attributes used to render the source name
+ * @RB_SOURCELIST_MODEL_COLUMN_VISIBILITY: the source's visibility
+ * @RB_SOURCELIST_MODEL_COLUMN_IS_GROUP: whether the row identifies a group or a source
+ * @RB_SOURCELIST_MODEL_COLUMN_GROUP_CATEGORY: if the row is a group, the category for the group
+ *
+ * Columns present in the source list model.
+ */
+
 /* This should really be standard. */
 #define ENUM_ENTRY(NAME, DESC) { NAME, "" #NAME "", DESC }
 
@@ -562,6 +623,8 @@
 			ENUM_ENTRY (RB_SOURCELIST_MODEL_COLUMN_SOURCE, "Source"),
 			ENUM_ENTRY (RB_SOURCELIST_MODEL_COLUMN_ATTRIBUTES, "Attributes"),
 			ENUM_ENTRY (RB_SOURCELIST_MODEL_COLUMN_VISIBILITY, "Visibility"),
+			ENUM_ENTRY (RB_SOURCELIST_MODEL_COLUMN_IS_GROUP, "Is group"),
+			ENUM_ENTRY (RB_SOURCELIST_MODEL_COLUMN_GROUP_CATEGORY, "Source group category"),
 			{ 0, 0, 0 }
 		};
 

Modified: trunk/sources/rb-sourcelist-model.h
==============================================================================
--- trunk/sources/rb-sourcelist-model.h	(original)
+++ trunk/sources/rb-sourcelist-model.h	Thu Mar 27 12:46:00 2008
@@ -51,23 +51,25 @@
 GType rb_sourcelist_model_column_get_type (void);
 #define RB_TYPE_SOURCELIST_MODEL_COLUMN (rb_sourcelist_model_column_get_type ())
 
+typedef struct _RBSourceListModel RBSourceListModel;
+typedef struct _RBSourceListModelClass RBSourceListModelClass;
 
 typedef struct RBSourceListModelPrivate RBSourceListModelPrivate;
 
-typedef struct RBSourceListModel
+struct _RBSourceListModel
 {
 	GtkTreeModelFilter parent;
 
 	RBSourceListModelPrivate *priv;
-} RBSourceListModel;
+};
 
-typedef struct RBSourceListModelClass
+struct _RBSourceListModelClass
 {
 	GtkTreeModelFilterClass parent_class;
 
 	void (*drop_received) (RBSourceListModel *model, RBSource *target, GtkTreeViewDropPosition pos, GtkSelectionData *data);
 
-} RBSourceListModelClass;
+};
 
 GType		rb_sourcelist_model_get_type	(void);
 

Modified: trunk/sources/rb-sourcelist.c
==============================================================================
--- trunk/sources/rb-sourcelist.c	(original)
+++ trunk/sources/rb-sourcelist.c	Thu Mar 27 12:46:00 2008
@@ -43,6 +43,24 @@
 #include "rb-auto-playlist-source.h"
 #include "rb-static-playlist-source.h"
 
+/**
+ * SECTION:rb-sourcelist
+ * @short_description: source list widget
+ *
+ * The source list widget is a GtkTreeView backed by a GtkListStore
+ * containing the sources and some extra data used to structure the
+ * tree view.
+ *
+ * The source list widget displays the available sources.  Sources are divided into
+ * groups - library, stores, playlists, devices, network shares.  Groups are
+ * displayed as headers, with expanders for hiding and showing the sources in 
+ * the group.  Sources themselves may also have child sources, such as playlists
+ * on portable audio players.
+ *
+ * Sources are displayed with an icon and a name.  If the source is currently
+ * playing, the name is displayed in bold.
+ */
+
 struct RBSourceListPrivate
 {
 	GtkWidget *treeview;
@@ -120,6 +138,11 @@
 	o_class->set_property = rb_sourcelist_set_property;
 	o_class->get_property = rb_sourcelist_get_property;
 
+	/**
+	 * RBSourceList:shell:
+	 *
+	 * The #RBShell instance
+	 */
 	g_object_class_install_property (o_class,
 					 PROP_SHELL,
 					 g_param_spec_object ("shell",
@@ -128,6 +151,11 @@
 							      RB_TYPE_SHELL,
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RBSourceList:model:
+	 *
+	 * The #GtkTreeModel for the source list
+	 */
 	g_object_class_install_property (o_class,
 					 PROP_MODEL,
 					 g_param_spec_object ("model",
@@ -135,6 +163,13 @@
 							      "GtkTreeModel object",
 							      GTK_TYPE_TREE_MODEL,
 							      G_PARAM_READABLE));
+	/**
+	 * RBSourceList::selected:
+	 * @list: the #RBSourceList
+	 * @source: the newly selected #RBSource
+	 *
+	 * Emitted when a source is selected from the source list
+	 */
 	rb_sourcelist_signals[SELECTED] =
 		g_signal_new ("selected",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -146,6 +181,14 @@
 			      1,
 			      G_TYPE_OBJECT);
 
+	/**
+	 * RBSourceList::drop-received:
+	 * @list: the #RBSourceList
+	 * @target: the #RBSource receiving the drop
+	 * @data: the drop data
+	 *
+	 * Emitted when a drag and drop to the source list completes.
+	 */
 	rb_sourcelist_signals[DROP_RECEIVED] =
 		g_signal_new ("drop_received",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -157,6 +200,14 @@
 			      2,
 			      G_TYPE_POINTER, G_TYPE_POINTER);
 
+	/**
+	 * RBSourceList::source-activated:
+	 * @list: the #RBSourceList
+	 * @target: the activated #RBSource
+	 *
+	 * Emitted when a source is activated (by double clicking or hitting
+	 * the enter key)
+	 */
 	rb_sourcelist_signals[SOURCE_ACTIVATED] =
 		g_signal_new ("source_activated",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -168,6 +219,14 @@
 			      1,
 			      G_TYPE_OBJECT);
 
+	/**
+	 * RBSourceList::show-popup:
+	 * @list: the #RBSourceList
+	 * @target: the #RBSource for which a popup menu should be shown
+	 *
+	 * Emitted when a source should display a popup menu in response to some
+	 * user action, such as right clicking or pressing shift-f10.
+	 */
 	rb_sourcelist_signals[SHOW_POPUP] =
 		g_signal_new ("show_popup",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -800,6 +859,12 @@
 	}
 }
 
+/**
+ * rb_sourcelist_new:
+ * @shell: the #RBShell instance
+ *
+ * Return value: the source list widget.
+ */
 GtkWidget *
 rb_sourcelist_new (RBShell *shell)
 {
@@ -1007,6 +1072,16 @@
 	}
 }
 
+/**
+ * rb_sourcelist_append:
+ * @sourcelist: the #RBSourceList
+ * @source: the #RBSource to add
+ * @parent: the #RBSource below which to add the new source, or NULL
+ *
+ * Adds a new source to the source list.  If @parent is not NULL, the new
+ * source is added beneath it.  Otherwise, it is added to the end of the
+ * source group specified by the source's source-group property.
+ */
 void
 rb_sourcelist_append (RBSourceList *sourcelist,
 		      RBSource     *source,
@@ -1178,6 +1253,15 @@
 	return ret;
 }
 
+/**
+ * rb_sourcelist_edit_source_name:
+ * @sourcelist: the #RBSourceList
+ * @source: the #RBSource to edit
+ *
+ * Initiates editing of the name of the specified source.  The row for the source 
+ * is selected and given input focus, allowing the user to edit the name.
+ * source_name_edited_cb is called when the user finishes editing.
+ */
 void
 rb_sourcelist_edit_source_name (RBSourceList *sourcelist,
 				RBSource     *source)
@@ -1213,6 +1297,15 @@
 			    RB_SOURCELIST_MODEL_COLUMN_PLAYING, playing, -1);
 }
 
+/**
+ * rb_sourcelist_set_playing_source:
+ * @sourcelist: the #RBSourceList
+ * @source: the new playing #RBSource
+ *
+ * Updates the source list with the new playing source.
+ * The source list tracks which source is playing in order to display
+ * the name of the playing source in bold type.
+ */
 void
 rb_sourcelist_set_playing_source (RBSourceList *sourcelist,
 				  RBSource     *source)
@@ -1225,6 +1318,15 @@
 		set_source_playing (sourcelist, source, TRUE);
 }
 
+/**
+ * rb_sourcelist_remove:
+ * @sourcelist: the #RBSourceList
+ * @source: the #RBSource being removed
+ *
+ * Removes a source from the source list.  Disconnects signal handlers,
+ * removes the source from the underlying model, and updates the visibility
+ * of the group containing the source.
+ */
 void
 rb_sourcelist_remove (RBSourceList *sourcelist,
 		      RBSource     *source)
@@ -1256,6 +1358,14 @@
 	gtk_tree_view_columns_autosize (GTK_TREE_VIEW (sourcelist->priv->treeview));
 }
 
+/**
+ * rb_sourcelist_select:
+ * @sourcelist: the #RBSourceList
+ * @source: the #RBSource to select
+ *
+ * Selects the specified source in the source list.  This will result in the 'selected'
+ * signal being emitted.
+ */
 void
 rb_sourcelist_select (RBSourceList *sourcelist,
 		      RBSource     *source)

Modified: trunk/sources/rb-sourcelist.h
==============================================================================
--- trunk/sources/rb-sourcelist.h	(original)
+++ trunk/sources/rb-sourcelist.h	Thu Mar 27 12:46:00 2008
@@ -37,16 +37,19 @@
 #define RB_IS_SOURCELIST_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((obj), RB_TYPE_SOURCELIST))
 #define RB_SOURCELIST_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), RB_TYPE_SOURCELIST, RBSourceListClass))
 
+typedef struct _RBSourceList RBSourceList;
+typedef struct _RBSourceListClass RBSourceListClass;
+
 typedef struct RBSourceListPrivate RBSourceListPrivate;
 
-typedef struct RBSourceList
+struct _RBSourceList
 {
 	GtkScrolledWindow    parent;
 
 	RBSourceListPrivate *priv;
-} RBSourceList;
+};
 
-typedef struct RBSourceListClass
+struct _RBSourceListClass
 {
 	GtkScrolledWindowClass parent_class;
 
@@ -58,7 +61,7 @@
 	void (*source_activated) (RBSourceList *list, RBSource *target);
 
 	gboolean (*show_popup) (RBSourceList *list, RBSource *target);
-} RBSourceListClass;
+};
 
 GType		rb_sourcelist_get_type		(void);