rhythmbox r5770 - in trunk: . doc/reference shell sources

[jmatthew svn gnome org]

Author: jmatthew
Date: Sun Jun 22 10:15:38 2008
New Revision: 5770
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5770&view=rev

Log:
2008-06-22  Jonathan Matthew  <jonathan d14n org>

	* doc/reference/rhythmbox-sections.txt:
	* shell/rb-shell-preferences.c:
	* shell/rb-shell-preferences.h:
	* sources/rb-browser-source.c:
	* sources/rb-browser-source.h:
	gtk-doc for RBShellPreferences and RBBrowserSource


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/shell/rb-shell-preferences.c
   trunk/shell/rb-shell-preferences.h
   trunk/sources/rb-browser-source.c
   trunk/sources/rb-browser-source.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Sun Jun 22 10:15:38 2008
@@ -264,10 +264,13 @@
 
 <SECTION>
 <FILE>rb-shell-preferences</FILE>
-RBShellPreferencesPrivate
+<TITLE>RBShellPreferences</TITLE>
+RBShellPreferences
+RBShellPreferencesClass
 rb_shell_preferences_new
 rb_shell_preferences_append_page
 <SUBSECTION Standard>
+RBShellPreferencesPrivate
 RB_SHELL_PREFERENCES
 RB_IS_SHELL_PREFERENCES
 RB_TYPE_SHELL_PREFERENCES
@@ -424,8 +427,10 @@
 
 <SECTION>
 <FILE>rb-shell-player</FILE>
+<TITLE>RBShellPlayer</TITLE>
+RBShellPlayer
+RBShellPlayerClass
 RBShellPlayerError
-RBShellPlayerPrivate
 rb_shell_player_new
 rb_shell_player_set_selected_source
 rb_shell_player_set_playing_source
@@ -467,6 +472,7 @@
 RB_SHELL_PLAYER_GET_CLASS
 RB_SHELL_PLAYER_ERROR
 rb_shell_player_error_quark
+RBShellPlayerPrivate
 </SECTION>
 
 <SECTION>
@@ -2453,12 +2459,15 @@
 
 <SECTION>
 <FILE>rb-browser-source</FILE>
-RBBrowserSourcePrivate
-RBBrowserSourceFeatureFunc
-RBBrowserSourceStringFunc
+<TITLE>RBBrowserSource</TITLE>
+RBBrowserSource
+RBBrowserSourceClass
 rb_browser_source_get_paned_key
 rb_browser_source_has_drop_support
 <SUBSECTION Standard>
+RBBrowserSourcePrivate
+RBBrowserSourceFeatureFunc
+RBBrowserSourceStringFunc
 RB_BROWSER_SOURCE
 RB_IS_BROWSER_SOURCE
 RB_TYPE_BROWSER_SOURCE

Modified: trunk/shell/rb-shell-preferences.c
==============================================================================
--- trunk/shell/rb-shell-preferences.c	(original)
+++ trunk/shell/rb-shell-preferences.c	Sun Jun 22 10:15:38 2008
@@ -29,6 +29,25 @@
  *
  */
 
+/**
+ * SECTION:rb-shell-preferences
+ * @short_description: preferences dialog
+ *
+ * The preferences dialog is built around a #GtkNotebook widget, with two built-in
+ * pages and additional pages for various sources.
+ *
+ * The 'general' preferences page controls the set of browser views that are visible
+ * (artist and album; genre and artist; or genre, artist, and album), the columns
+ * that are visible, and the appearance of buttons in the main toolbar.  The browser
+ * and column settings apply to all sources.
+ *
+ * The 'playback' preferences page controls whether the crossfading player backend is used,
+ * and if enabled, the crossfade duration and network buffer size.
+ *
+ * Currently, the library and podcast sources add pages to the notebook, for configuring the
+ * location and layout of the library and the podcast download location and update frequency.
+ */
+
 #include <config.h>
 
 #include <string.h>
@@ -316,6 +335,14 @@
 	G_OBJECT_CLASS (rb_shell_preferences_parent_class)->finalize (object);
 }
 
+/**
+ * rb_shell_preferences_append_page:
+ * @prefs: the #RBShellPreferences instance
+ * @name: name of the page to append
+ * @widget: the #GtkWidget to use as the contents of the page
+ *
+ * Appends a new page to the preferences dialog notebook.
+ */
 void
 rb_shell_preferences_append_page (RBShellPreferences *prefs,
 				  const char *name,
@@ -346,6 +373,15 @@
 	rb_shell_preferences_append_page (prefs, name, widget);
 }
 
+/**
+ * rb_shell_preferences_new:
+ * @views: list of #RBSource objects to check for preferences pages
+ *
+ * Creates the #RBShellPreferences instance, populating it with the
+ * preferences pages for the sources in the list.
+ *
+ * Return value: the #RBShellPreferences instance
+ */
 GtkWidget *
 rb_shell_preferences_new (GList *views)
 {
@@ -406,6 +442,14 @@
 	rb_shell_preferences_sync (shell_preferences);
 }
 
+/**
+ * rb_shell_preferences_column_check_changed_cb:
+ * @butt: the #GtkCheckButton that was changed
+ * @shell_preferences: the #RBShellPreferences instance
+ *
+ * Signal handler used for the checkboxes used to configure the set of visible columns.
+ * This updates the GConf key that contains the list of visible columns.
+ */
 void
 rb_shell_preferences_column_check_changed_cb (GtkCheckButton *butt,
 					      RBShellPreferences *shell_preferences)
@@ -590,6 +634,14 @@
 	eel_gconf_set_integer (CONF_UI_TOOLBAR_STYLE, selection);
 }
 
+/**
+ * rb_shell_preferences_browser_views_activated_cb:
+ * @widget: the radio button that was selected
+ * @shell_preferences: the #RBShellPreferences instance
+ *
+ * Signal handler used for the radio buttons used to configure the
+ * visible browser views.
+ */
 void
 rb_shell_preferences_browser_views_activated_cb (GtkWidget *widget,
 						 RBShellPreferences *shell_preferences)

Modified: trunk/shell/rb-shell-preferences.h
==============================================================================
--- trunk/shell/rb-shell-preferences.h	(original)
+++ trunk/shell/rb-shell-preferences.h	Sun Jun 22 10:15:38 2008
@@ -42,19 +42,21 @@
 #define RB_IS_SHELL_PREFERENCES_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_SHELL_PREFERENCES))
 #define RB_SHELL_PREFERENCES_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_SHELL_PREFERENCES, RBShellPreferencesClass))
 
+typedef struct _RBShellPreferences RBShellPreferences;
+typedef struct _RBShellPreferencesClass RBShellPreferencesClass;
 typedef struct RBShellPreferencesPrivate RBShellPreferencesPrivate;
 
-typedef struct
+struct _RBShellPreferences
 {
 	GtkDialog parent;
 
 	RBShellPreferencesPrivate *priv;
-} RBShellPreferences;
+};
 
-typedef struct
+struct _RBShellPreferencesClass
 {
 	GtkDialogClass parent_class;
-} RBShellPreferencesClass;
+};
 
 GType		rb_shell_preferences_get_type		(void);
 

Modified: trunk/sources/rb-browser-source.c
==============================================================================
--- trunk/sources/rb-browser-source.c	(original)
+++ trunk/sources/rb-browser-source.c	Sun Jun 22 10:15:38 2008
@@ -29,6 +29,18 @@
  *
  */
 
+/**
+ * SECTION:rb-browser-source
+ * @short_description: base class for sources that include genre/artist/album browsers
+ *
+ * This class simplifies implementation of sources that include genre/artist/album browsers.
+ * It also handles searching (using the search box) and a few other UI niceties.
+ * 
+ * Instances of browser sources will use a query that will match all entries of
+ * the entry type assigned to the source, so it's mostly suited for sources that
+ * have an entry type of their own.
+ */
+
 #include "config.h"
 
 #include <string.h>
@@ -801,6 +813,15 @@
 	}
 }
 
+/**
+ * rb_browser_source_get_paned_key:
+ * @source: a #RBBrowserSource
+ *
+ * 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
+ */
 char *
 rb_browser_source_get_paned_key (RBBrowserSource *source)
 {
@@ -812,6 +833,15 @@
 		return NULL;
 }
 
+/**
+ * rb_browser_source_has_drop_support:
+ * @source: a #RBBrowser
+ *
+ * This is a virtual method that should be implemented by subclasses.  It returns %TRUE
+ * if drag and drop target support for the source should be activated.
+ *
+ * Return value: %TRUE if drop support should be activated
+ */
 gboolean
 rb_browser_source_has_drop_support (RBBrowserSource *source)
 {

Modified: trunk/sources/rb-browser-source.h
==============================================================================
--- trunk/sources/rb-browser-source.h	(original)
+++ trunk/sources/rb-browser-source.h	Sun Jun 22 10:15:38 2008
@@ -46,16 +46,18 @@
 #define RB_IS_BROWSER_SOURCE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_BROWSER_SOURCE))
 #define RB_BROWSER_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_BROWSER_SOURCE, RBBrowserSourceClass))
 
+typedef struct _RBBrowserSource RBBrowserSource;
+typedef struct _RBBrowserSourceClass RBBrowserSourceClass;
 typedef struct RBBrowserSourcePrivate RBBrowserSourcePrivate;
 
-typedef struct
+struct _RBBrowserSource
 {
 	RBSource parent;
 
 	RBBrowserSourcePrivate *priv;
-} RBBrowserSource;
+};
 
-typedef struct
+struct _RBBrowserSourceClass
 {
 	RBSourceClass parent;
 
@@ -63,7 +65,7 @@
 	char *		(*impl_get_paned_key)		(RBBrowserSource *source);
 	gboolean	(*impl_has_drop_support)	(RBBrowserSource *source);
 	void		(*impl_show_entry_popup)	(RBBrowserSource *source);
-} RBBrowserSourceClass;
+};
 
 typedef gboolean	(*RBBrowserSourceFeatureFunc)	(RBBrowserSource *source);
 typedef char*		(*RBBrowserSourceStringFunc)	(RBBrowserSource *source);