rhythmbox r5645 - in trunk: . doc/reference sources

[jmatthew svn gnome org]

Author: jmatthew
Date: Mon Mar 24 03:29:36 2008
New Revision: 5645
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5645&view=rev

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

	* doc/reference/rhythmbox-sections.txt:
	* sources/rb-missing-files-source.c:
	* sources/rb-missing-files-source.h:
	* sources/rb-play-queue-source.c:
	(rb_play_queue_source_class_init):
	* sources/rb-play-queue-source.h:
	Add gtk-doc for RBPlayQueueSource and RBMissingFilesSource


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/sources/rb-missing-files-source.c
   trunk/sources/rb-missing-files-source.h
   trunk/sources/rb-play-queue-source.c
   trunk/sources/rb-play-queue-source.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Mon Mar 24 03:29:36 2008
@@ -2390,6 +2390,9 @@
 
 <SECTION>
 <FILE>rb-play-queue-source</FILE>
+<TITLE>RBPlayQueueSource</TITLE>
+RBPlayQueueSource
+RBPlayQueueSourceClass
 rb_play_queue_source_new
 rb_play_queue_source_sidebar_song_info
 rb_play_queue_source_sidebar_delete
@@ -2406,6 +2409,9 @@
 
 <SECTION>
 <FILE>rb-missing-files-source</FILE>
+<TITLE>RBMissingFilesSource</TITLE>
+RBMissingFilesSource
+RBMissingFilesSourceClass
 RBMissingFilesSourcePrivate
 rb_missing_files_source_new
 <SUBSECTION Standard>

Modified: trunk/sources/rb-missing-files-source.c
==============================================================================
--- trunk/sources/rb-missing-files-source.c	(original)
+++ trunk/sources/rb-missing-files-source.c	Mon Mar 24 03:29:36 2008
@@ -18,11 +18,6 @@
  *
  */
 
-/*
- * This source lists files rhythmbox cannot find, and maybe tries to stop
- * you from trying to play them.
- */
-
 #include "config.h"
 
 #include <gtk/gtk.h>
@@ -34,6 +29,20 @@
 #include "rb-util.h"
 #include "rb-debug.h"
 
+/**
+ * SECTION:rb-missing-files-source
+ * @short_description: source displaying files missing from the library
+ *
+ * This source displays files that rhythmbox cannot find at the expected
+ * locations.  On startup, it does a file access check for every file
+ * in the library, hiding those that fail.  This source sets up a
+ * query model that matches only hidden entries.  It displays the file
+ * location and the last time the file was successfully accessed.
+ *
+ * The source only displayed in the source list when there are hidden
+ * entries to show.
+ */
+
 static void rb_missing_files_source_class_init (RBMissingFilesSourceClass *klass);
 static void rb_missing_files_source_init (RBMissingFilesSource *source);
 static GObject *rb_missing_files_source_constructor (GType type, guint n_construct_properties,
@@ -247,6 +256,19 @@
 	}
 }
 
+/**
+ * rb_missing_files_source_new:
+ * @shell: the #RBShell instance
+ * @library: the #RBLibrarySource instance
+ *
+ * Creates the missing files source.  It extracts the
+ * entry type from the library source instance, so it
+ * currently only works for files in the library, but
+ * it would be trivial to make it use any source type
+ * that did file access checks for its contents.
+ * 
+ * Return value: the #RBMissingFiles source
+ */
 RBSource *
 rb_missing_files_source_new (RBShell *shell,
 			     RBLibrarySource *library)

Modified: trunk/sources/rb-missing-files-source.h
==============================================================================
--- trunk/sources/rb-missing-files-source.h	(original)
+++ trunk/sources/rb-missing-files-source.h	Mon Mar 24 03:29:36 2008
@@ -33,24 +33,26 @@
 #define RB_IS_MISSING_FILES_SOURCE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_MISSING_FILES_SOURCE))
 #define RB_MISSING_FILES_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_MISSING_FILES_SOURCE, RBMissingFilesSourceClass))
 
+typedef struct _RBMissingFilesSource RBMissingFilesSource;
+typedef struct _RBMissingFilesSourceClass RBMissingFilesSourceClass;
 typedef struct RBMissingFilesSourcePrivate RBMissingFilesSourcePrivate;
 
-typedef struct
+struct _RBMissingFilesSource
 {
 	RBSource parent;
 
 	RBMissingFilesSourcePrivate *priv;
-} RBMissingFilesSource;
+};
 
-typedef struct
+struct _RBMissingFilesSourceClass
 {
 	RBSourceClass parent;
-} RBMissingFilesSourceClass;
+};
 
 GType		rb_missing_files_source_get_type		(void);
 
 RBSource *      rb_missing_files_source_new			(RBShell *shell,
-								 RBLibrarySource *library_source);
+								 RBLibrarySource *library);
 
 G_END_DECLS
 

Modified: trunk/sources/rb-play-queue-source.c
==============================================================================
--- trunk/sources/rb-play-queue-source.c	(original)
+++ trunk/sources/rb-play-queue-source.c	Mon Mar 24 03:29:36 2008
@@ -31,6 +31,19 @@
 #include "rb-util.h"
 #include "rb-debug.h"
 
+/**
+ * SECTION:rb-play-queue-source
+ * @short_description: source object for the play queue
+ *
+ * The main interesting thing about this source is that is
+ * contains a second #RBEntryView to be displayed in the side
+ * pane (beneath the source list).  This entry view displays
+ * the track title, artist, and album in a single column,
+ * split across three lines so the information mostly fits in
+ * the usual horizontal space allowed for the side bar.
+ */
+
+
 static GObject *rb_play_queue_source_constructor (GType type, guint n_construct_properties,
 						  GObjectConstructParam *construct_properties);
 static void rb_play_queue_source_get_property (GObject *object,
@@ -145,6 +158,11 @@
 	playlist_class->impl_show_entry_view_popup = impl_show_entry_view_popup;
 	playlist_class->impl_save_contents_to_xml = impl_save_contents_to_xml;
 
+	/**
+	 * RBPlayQueueSource:sidebar:
+	 *
+	 * The #RBEntryView for the play queue side pane.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_SIDEBAR,
 					 g_param_spec_object ("sidebar",
@@ -246,6 +264,14 @@
 	}
 }
 
+/**
+ * rb_play_queue_source_new:
+ * @shell: the #RBShell instance
+ *
+ * Creates the play queue source object.
+ * 
+ * Return value: the play queue source
+ */
 RBSource *
 rb_play_queue_source_new (RBShell *shell)
 {
@@ -258,6 +284,13 @@
 					NULL));
 }
 
+/**
+ * rb_play_queue_source_sidebar_song_info:
+ * @source: the #RBPlayQueueSource
+ *
+ * Creates and displays a #RBSongInfo for the currently selected
+ * entry in the side pane play queue view
+ */
 void
 rb_play_queue_source_sidebar_song_info (RBPlayQueueSource *source)
 {
@@ -273,6 +306,13 @@
 		rb_debug ("failed to create dialog, or no selection!");
 }
 
+/**
+ * rb_play_queue_source_sidebar_delete:
+ * @source: the #RBPlayQueueSource
+ *
+ * Deletes the selected entries from the play queue side pane.
+ * This is called by the #RBShellClipboard.
+ */
 void
 rb_play_queue_source_sidebar_delete (RBPlayQueueSource *source)
 {
@@ -287,6 +327,12 @@
 	g_list_free (sel);
 }
 
+/**
+ * rb_play_queue_source_clear_queue:
+ * @source: the #RBPlayQueueSource
+ *
+ * Clears the play queue.
+ */
 void
 rb_play_queue_source_clear_queue (RBPlayQueueSource *source)
 {

Modified: trunk/sources/rb-play-queue-source.h
==============================================================================
--- trunk/sources/rb-play-queue-source.h	(original)
+++ trunk/sources/rb-play-queue-source.h	Mon Mar 24 03:29:36 2008
@@ -36,15 +36,18 @@
 #define RB_IS_PLAY_QUEUE_SOURCE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_PLAY_QUEUE_SOURCE))
 #define RB_PLAY_QUEUE_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_PLAY_QUEUE_SOURCE, RBPlayQueueSourceClass))
 
-typedef struct
+typedef struct _RBPlayQueueSource RBPlayQueueSource;
+typedef struct _RBPlayQueueSourceClass RBPlayQueueSourceClass;
+
+struct _RBPlayQueueSource
 {
 	RBStaticPlaylistSource parent;
-} RBPlayQueueSource;
+};
 
-typedef struct
+struct _RBPlayQueueSourceClass
 {
 	RBStaticPlaylistSourceClass parent;
-} RBPlayQueueSourceClass;
+};
 
 GType		rb_play_queue_source_get_type 		(void);