GNOME.org
 

rhythmbox r5636 - in trunk: . backends doc/reference lib sources widgets

Author: jmatthew
Date: Fri Mar 21 10:16:10 2008
New Revision: 5636
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5636&view=rev

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

	* backends/rb-player-gst-data-tee.c:
	(rb_player_gst_data_tee_interface_init):
	* backends/rb-player-gst-data-tee.h:
	* backends/rb-player.c: (rb_player_interface_init):
	* doc/reference/rhythmbox-sections.txt:
	* lib/rb-async-queue-watch.c:
	* lib/rb-debug.c:
	* sources/rb-import-errors-source.c:
	* sources/rb-import-errors-source.h:
	* widgets/rb-search-entry.c:
	More gtk-doc additions and fixes.


Modified:
   trunk/ChangeLog
   trunk/backends/rb-player-gst-data-tee.c
   trunk/backends/rb-player-gst-data-tee.h
   trunk/backends/rb-player.c
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/lib/rb-async-queue-watch.c
   trunk/lib/rb-debug.c
   trunk/sources/rb-import-errors-source.c
   trunk/sources/rb-import-errors-source.h
   trunk/widgets/rb-search-entry.c

Modified: trunk/backends/rb-player-gst-data-tee.c
==============================================================================
--- trunk/backends/rb-player-gst-data-tee.c	(original)
+++ trunk/backends/rb-player-gst-data-tee.c	Fri Mar 21 10:16:10 2008
@@ -32,11 +32,23 @@
 
 static guint signals[LAST_SIGNAL] = { 0 };
 
+/**
+ * SECTION:rb-player-gst-data-tee
+ * @short_description: player interface for processing raw data
+ * @include: rb-player-gst-data-tee.h
+ *
+ * This interface allows a caller to add a branch to the GStreamer playback
+ * pipeline that receives a copy of the raw data from the playback source
+ * element.
+ *
+ * This interface is not currently implemented by either playback backend.
+ */
+
 static void
 rb_player_gst_data_tee_interface_init (RBPlayerGstDataTeeIface *iface)
 {
 	/**
-	 * RBPlayerGstDataTee::tee-inserted
+	 * RBPlayerGstDataTee::data-tee-inserted:
 	 * @data_tee: the element which has been inserted
 	 *
 	 * The 'data_tee-inserted' signal is emitted when the tee element has been
@@ -53,7 +65,7 @@
 			      1, G_TYPE_OBJECT);
 
 	/**
-	 * RBPlayerGstDataTee::tee-pre-remove
+	 * RBPlayerGstDataTee::data-tee-pre-remove:
 	 * @data_tee: the element which is about to be removed
 	 *
 	 * The 'data_tee-pre-remove' signal is emitted immediately before the element
@@ -94,6 +106,15 @@
 	return our_type;
 }
 
+/**
+ * rb_player_gst_data_tee_add_data_tee:
+ * @player: a #RBPlayerGstDataTee implementation
+ * @element: data tee branch to add
+ *
+ * Adds a raw data tee branch to the playback pipeline.
+ *
+ * Return value: TRUE if the tee branch was added successfully
+ */
 gboolean
 rb_player_gst_data_tee_add_data_tee (RBPlayerGstDataTee *player, GstElement *element)
 {
@@ -102,6 +123,15 @@
 	return iface->add_data_tee (player, element);
 }
 
+/**
+ * rb_player_gst_data_tee_remove_data_tee:
+ * @player: a #RBPlayerGstDataTee implementation
+ * @element: data tee branch to add
+ *
+ * Removes a raw data tee branch.
+ * 
+ * Return value: TRUE if the tee branch was found and removed
+ */
 gboolean
 rb_player_gst_data_tee_remove_data_tee (RBPlayerGstDataTee *player, GstElement *element)
 {

Modified: trunk/backends/rb-player-gst-data-tee.h
==============================================================================
--- trunk/backends/rb-player-gst-data-tee.h	(original)
+++ trunk/backends/rb-player-gst-data-tee.h	Fri Mar 21 10:16:10 2008
@@ -35,8 +35,9 @@
 #define RB_PLAYER_GST_DATA_TEE_GET_IFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE ((o), RB_TYPE_PLAYER_GST_DATA_TEE, RBPlayerGstDataTeeIface))
 
 typedef struct _RBPlayerGstDataTee RBPlayerGstDataTee;
+typedef struct _RBPlayerGstDataTeeIface RBPlayerGstDataTeeIface;
 
-typedef struct
+struct _RBPlayerGstDataTeeIface
 {
 	GTypeInterface	g_iface;
 
@@ -47,7 +48,7 @@
 	/* signals */
 	void		(*data_tee_inserted)	(RBPlayerGstDataTee *player, GstElement *data_tee);
 	void		(*data_tee_pre_remove)	(RBPlayerGstDataTee *player, GstElement *data_tee);
-} RBPlayerGstDataTeeIface;
+};
 
 GType		rb_player_gst_data_tee_get_type   (void);
 

Modified: trunk/backends/rb-player.c
==============================================================================
--- trunk/backends/rb-player.c	(original)
+++ trunk/backends/rb-player.c	Fri Mar 21 10:16:10 2008
@@ -39,6 +39,42 @@
 
 static guint signals[LAST_SIGNAL] = { 0 };
 
+/**
+ * SECTION:rb-player
+ * @short_description: playback backend interface
+ * @include: rb-player.h
+ *
+ * This is the interface implemented by the rhythmbox playback backends.
+ * It allows the caller to control playback (open, play, pause, close), 
+ * seek (set_time), control volume (get_volume, set_volume, set_replaygain)
+ * and receive playback state information (get_time, various signals).
+ *
+ * The playback interface allows for multiple streams to be playing (or at
+ * least open) concurrently. The caller associates some data with each stream
+ * it opens (#rb_player_open), which is included in the paramters with each
+ * signal emitted. The caller should not assume that the new stream is playing
+ * immediately upon returning from #rb_player_play. Instead, it should use
+ * the 'playing-stream' signal to determine that.
+ *
+ * The player implementation should emit signals for metadata extracted from the
+ * stream using the 'info' signal
+ *
+ * While playing, the player implementation should emit 'tick' signals frequently
+ * enough to update an elapsed/remaining time display consistently.  The duration
+ * value included in tick signal emissions is used to prepare the next stream before
+ * the current stream reaches EOS, so it should be updated for each emission to account
+ * for variable bitrate streams that produce inaccurate duration estimates early on.
+ *
+ * When playing a stream from the network, the player can report buffering status
+ * using the 'buffering' signal.  The value included in the signal indicates the
+ * percentage of the buffer that has been filled.
+ *
+ * The 'event' signal can be used to communicate events from the player to the application.
+ * For GStreamer-based player implementations, events are triggered by elements in the
+ * pipeline posting application messages.  The name of the message becomes the name of the
+ * event.
+ */
+
 static void
 rb_player_interface_init (RBPlayerIface *iface)
 {
@@ -166,7 +202,7 @@
 	 *
 	 * The 'playing-stream' signal is emitted when the main playing stream
 	 * changes. It should be used to update the UI to show the new
-	 * stream. It can either be emitted before or after rb_player_play returns,
+	 * stream. It can either be emitted before or after #rb_player_play returns,
 	 * depending on the player backend.
 	 */
 	signals[PLAYING_STREAM] =
@@ -217,7 +253,7 @@
  * implementation, this may stop any existing stream being
  * played.  The stream preparation process may continue
  * asynchronously, in which case errors may be reported from
- * rb_player_play or using the 'error' signal.
+ * #rb_player_play or using the 'error' signal.
  *
  * Return value: TRUE if the stream preparation was not unsuccessful
  */

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Fri Mar 21 10:16:10 2008
@@ -1111,7 +1111,6 @@
 rb_debug_init
 rb_debug_init_match
 rb_debug_matches
-rb_debug_real
 rb_debug_get_args
 rb_debug_stop_in_debugger
 RBProfiler
@@ -1121,6 +1120,8 @@
 rb_profiler_free
 rb_profile_start
 rb_profile_end
+<SUBSECTION Standard>
+rb_debug_real
 </SECTION>
 
 <SECTION>
@@ -2039,7 +2040,9 @@
 
 <SECTION>
 <FILE>rb-player-gst-data-tee</FILE>
+<TITLE>RBPlayerGstDataTee</TITLE>
 RBPlayerGstDataTee
+RBPlayerGstDataTeeIface
 rb_player_gst_data_tee_add_data_tee
 rb_player_gst_data_tee_remove_data_tee
 <SUBSECTION Standard>
@@ -2249,6 +2252,9 @@
 
 <SECTION>
 <FILE>rb-import-errors-source</FILE>
+<TITLE>RBImportErrorsSource</TITLE>
+RBImportErrorsSource
+RBImportErrorsSourceClass
 RBImportErrorsSourcePrivate
 rb_import_errors_source_new
 <SUBSECTION Standard>

Modified: trunk/lib/rb-async-queue-watch.c
==============================================================================
--- trunk/lib/rb-async-queue-watch.c	(original)
+++ trunk/lib/rb-async-queue-watch.c	Fri Mar 21 10:16:10 2008
@@ -22,6 +22,11 @@
 
 #include <rb-async-queue-watch.h>
 
+/**
+ * SECTION:rb-async-queue-watch
+ * @short_description: GSource for watching a GAsyncQueue in the main loop
+ */
+
 typedef struct {
 	GSource source;
 	GAsyncQueue *queue;
@@ -80,6 +85,21 @@
 	rb_async_queue_watch_finalize
 };
 
+/**
+ * rb_async_queue_watch_new:
+ * @queue:	the #GAsyncQueue to watch
+ * @priority:	priority value for the #GSource
+ * @callback:	callback to invoke when the queue is non-empty
+ * @user_data:	user data to pass to the callback
+ * @notify:	function to call to clean up the user data for the callback
+ * @context:	the #GMainContext to attach the source to
+ *
+ * Creates a new #GSource that triggers when the #GAsyncQueue is
+ * non-empty.  This is used in rhythmbox to process queues within
+ * #RhythmDB in the main thread without polling.
+ *
+ * Return value: the ID of the new #GSource
+ */
 guint rb_async_queue_watch_new (GAsyncQueue *queue,
 				gint priority,
 				RBAsyncQueueWatchFunc callback,

Modified: trunk/lib/rb-debug.c
==============================================================================
--- trunk/lib/rb-debug.c	(original)
+++ trunk/lib/rb-debug.c	Fri Mar 21 10:16:10 2008
@@ -35,6 +35,14 @@
 
 #include "rb-debug.h"
 
+/**
+ * SECTION:rb-debug
+ * @short_description: debugging support functions
+ *
+ * In addition to a simple debug output system, we have two distinct
+ * profiling mechanisms for timing sections of code.
+ */
+
 static void log_handler (const char *domain,
 	                 GLogLevelFlags level,
 	                 const char *message,
@@ -43,6 +51,14 @@
 static const char *debug_everything = "everything";
 static const char *debug_match = NULL;
 
+/**
+ * rb_debug_matches:
+ * @func: function to check
+ * @file: filename to check
+ *
+ * Return value: TRUE if @func or @file match the current
+ * debug output settings.
+ */
 gboolean
 rb_debug_matches (const char *func,
 		  const char *file)
@@ -56,8 +72,27 @@
 	return TRUE;
 }
 
-/* Our own funky debugging function, should only be used when something
- * is not going wrong, if something *is* wrong use g_warning.
+/**
+ * rb_debug:
+ * @...: printf-style format string followed by any substitution values
+ *
+ * If the call site function or file name matches the current debug output
+ * settings, the message will be formatted and printed to standard error,
+ * including a timestamp, the thread ID, the file and function names, and
+ * the line number.  A newline will be appended, so the format string shouldn't
+ * include one.
+ */
+
+/**
+ * rb_debug_real:
+ * @func: function name
+ * @file: file name
+ * @line: line number
+ * @newline: if TRUE, add a newline to the output
+ * @format: printf style format specifier
+ *
+ * If the debug output settings match the function or file names,
+ * the debug message will be formatted and written to standard error.
  */
 void
 rb_debug_real (const char *func,
@@ -87,12 +122,30 @@
 		    str_time, g_thread_self (), func, file, line, buffer);
 }
 
+/**
+ * rb_debug_init:
+ * @debug: if TRUE, enable all debug output
+ *
+ * Sets up debug output, with either all debug enabled
+ * or none.
+ */
 void
 rb_debug_init (gboolean debug)
 {
 	rb_debug_init_match (debug ? debug_everything : NULL);
 }
 
+/**
+ * rb_debug_init_match:
+ * @match: string to match functions and filenames against
+ *
+ * Sets up debug output, enabling debug output from file and function
+ * names that contain the specified match string.
+ *
+ * Also sets up a GLib log handler that will trigger a debugger
+ * break for critical or warning level output if any debug output
+ * at all is enabled.
+ */
 void
 rb_debug_init_match (const char *match)
 {
@@ -153,6 +206,15 @@
 	rb_debug ("Debugging enabled");
 }
 
+/**
+ * rb_debug_get_args:
+ *
+ * Constructs arguments to pass to another process using
+ * this debug output code that will produce the same debug output
+ * settings.
+ *
+ * Return value: debug output arguments, must be freed with #g_strfreev()
+ */
 char **
 rb_debug_get_args (void)
 {
@@ -170,7 +232,10 @@
 	return args;
 }
 
-/* Raise a SIGINT signal to get the attention of the debugger.
+/**
+ * rb_debug_stop_in_debugger:
+ *
+ * Raises a SIGINT signal to get the attention of the debugger.
  * When not running under the debugger, we don't want to stop,
  * so we ignore the signal for just the moment that we raise it.
  */
@@ -207,6 +272,15 @@
 	char *name;
 };
 
+/**
+ * rb_profiler_new:
+ * @name: profiler name
+ *
+ * Creates a new profiler instance.  This can be used to
+ * time certain sections of code.
+ *
+ * Return value: profiler instance
+ */
 RBProfiler *
 rb_profiler_new (const char *name)
 {
@@ -224,6 +298,13 @@
 	return profiler;
 }
 
+/**
+ * rb_profiler_dump:
+ * @profiler: profiler instance
+ *
+ * Produces debug output for the profiler instance,
+ * showing the elapsed time.
+ */
 void
 rb_profiler_dump (RBProfiler *profiler)
 {
@@ -241,6 +322,12 @@
 		  elapsed / (G_USEC_PER_SEC / 1000), seconds);
 }
 
+/**
+ * rb_profiler_reset:
+ * @profiler: profiler instance
+ *
+ * Resets the elapsed time for the profiler
+ */
 void
 rb_profiler_reset (RBProfiler *profiler)
 {
@@ -252,6 +339,12 @@
 	g_timer_start (profiler->timer);
 }
 
+/**
+ * rb_profiler_free:
+ * @profiler: profiler instance to destroy
+ *
+ * Frees the memory associated with a profiler instance.
+ */
 void
 rb_profiler_free (RBProfiler *profiler)
 {
@@ -278,6 +371,36 @@
 	}
 }
 
+/**
+ * rb_profile_start:
+ * @msg: profile point message
+ *
+ * Records a start point for profiling.
+ * This profile mechanism operates by issuing file access
+ * requests with filenames indicating the profile points.
+ * Use 'strace -e access' to gather this information.
+ */
+
+/**
+ * rb_profile_end:
+ * @msg: profile point message
+ *
+ * Records an end point for profiling.  See @rb_profile_start.
+ */
+
+/**
+ * _rb_profile_log:
+ * @func: call site function name
+ * @file: call site file name
+ * @line: call site line number
+ * @indent: indent level for output
+ * @msg1: message part 1
+ * @msg2: message part 2
+ *
+ * Issues a file access request with a constructed filename.
+ * Run rhythmbox under 'strace -ttt -e access' to show these profile
+ * points.
+ */
 void
 _rb_profile_log (const char *func,
 		 const char *file,

Modified: trunk/sources/rb-import-errors-source.c
==============================================================================
--- trunk/sources/rb-import-errors-source.c	(original)
+++ trunk/sources/rb-import-errors-source.c	Fri Mar 21 10:16:10 2008
@@ -18,10 +18,6 @@
  *
  */
 
-/*
- * This source lists files rhythmbox failed to import.
- */
-
 #include <config.h>
 #include <gtk/gtk.h>
 #include <glib/gi18n.h>
@@ -44,7 +40,7 @@
 							 gboolean over_entry,
 							 RBImportErrorsSource *source);
 
-struct RBImportErrorsSourcePrivate
+struct _RBImportErrorsSourcePrivate
 {
 	RhythmDB *db;
 	RBEntryView *view;
@@ -52,6 +48,29 @@
 
 G_DEFINE_TYPE (RBImportErrorsSource, rb_import_errors_source, RB_TYPE_SOURCE);
 
+/**
+ * SECTION:rb-import-errors-source
+ * @short_description: source for displaying import errors
+ *
+ * This source is used to display the names of files that could not
+ * be imported into the library, along with any error messages from
+ * the import process.  When there are no import errors to display,
+ * the source is hidden.
+ *
+ * The source allows the user to delete the import error entries,
+ * and to move the files to the trash.
+ *
+ * When a file import fails, a #RhythmDBEntry is created with a
+ * specific entry type for import errors.  This source uses a query
+ * model that matches all such import error entries.
+ *
+ * To keep import errors from removable devices separate from those
+ * from the main library, multiple import error sources can be created,
+ * with separate entry types.  The generic audio player plugin, for
+ * example, creates an import error source for each device and inserts
+ * it into the source list as a child of the main source for the device.
+ */
+
 static void
 rb_import_errors_source_class_init (RBImportErrorsSourceClass *klass)
 {
@@ -181,6 +200,16 @@
 	return source->priv->view;
 }
 
+/**
+ * rb_import_errors_source_new:
+ * @shell: the #RBShell instance
+ * @entry_type: the entry type to display in the source
+ *
+ * Creates a new source for displaying import errors of the
+ * specified type.
+ *
+ * Return value: a new import error source
+ */
 RBSource *
 rb_import_errors_source_new (RBShell *shell,
 			     RhythmDBEntryType entry_type)

Modified: trunk/sources/rb-import-errors-source.h
==============================================================================
--- trunk/sources/rb-import-errors-source.h	(original)
+++ trunk/sources/rb-import-errors-source.h	Fri Mar 21 10:16:10 2008
@@ -33,19 +33,21 @@
 #define RB_IS_IMPORT_ERRORS_SOURCE_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_IMPORT_ERRORS_SOURCE))
 #define RB_IMPORT_ERRORS_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_IMPORT_ERRORS_SOURCE, RBImportErrorsSourceClass))
 
-typedef struct RBImportErrorsSourcePrivate RBImportErrorsSourcePrivate;
+typedef struct _RBImportErrorsSource RBImportErrorsSource;
+typedef struct _RBImportErrorsSourceClass RBImportErrorsSourceClass;
+typedef struct _RBImportErrorsSourcePrivate RBImportErrorsSourcePrivate;
 
-typedef struct
+struct _RBImportErrorsSource
 {
 	RBSource parent;
 
 	RBImportErrorsSourcePrivate *priv;
-} RBImportErrorsSource;
+};
 
-typedef struct
+struct _RBImportErrorsSourceClass
 {
 	RBSourceClass parent;
-} RBImportErrorsSourceClass;
+};
 
 GType		rb_import_errors_source_get_type		(void);
 

Modified: trunk/widgets/rb-search-entry.c
==============================================================================
--- trunk/widgets/rb-search-entry.c	(original)
+++ trunk/widgets/rb-search-entry.c	Fri Mar 21 10:16:10 2008
@@ -58,7 +58,7 @@
 #define RB_SEARCH_ENTRY_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), RB_TYPE_SEARCH_ENTRY, RBSearchEntryPrivate))
 
 /**
- * SECTION:RBSearchEntry:
+ * SECTION:rb-search-entry
  * @short_description: text entry widget for the search box
  *
  * The search entry contains a label and a text entry box.
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]