GNOME.org
 

rhythmbox r5668 - in trunk: . doc/reference shell

Author: jmatthew
Date: Sat Apr  5 01:33:04 2008
New Revision: 5668
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5668&view=rev

Log:
2008-04-05  Jonathan Matthew  <jonathan d14n org>

	* doc/reference/rhythmbox-sections.txt:
	* shell/rb-history.c: (rb_history_class_init),
	(rb_history_limit_size):
	* shell/rb-history.h:
	Add gtk-doc for RBHistory
	
	* doc/reference/rhythmbox-docs.sgml:
	No point documenting rb-missing-plugins


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-docs.sgml
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/shell/rb-history.c
   trunk/shell/rb-history.h

Modified: trunk/doc/reference/rhythmbox-docs.sgml
==============================================================================
--- trunk/doc/reference/rhythmbox-docs.sgml	(original)
+++ trunk/doc/reference/rhythmbox-docs.sgml	Sat Apr  5 01:33:04 2008
@@ -22,9 +22,7 @@
 		<xi:include href="xml/rb-debug.xml"/>
 		<xi:include href="xml/rb-file-helpers.xml"/>
 		<xi:include href="xml/rb-glade-helpers.xml"/>
-		<xi:include href="xml/rb-preferences.xml"/>
 		<xi:include href="xml/rb-proxy-config.xml"/>
-		<xi:include href="xml/rb-stock-icons.xml"/>
 		<xi:include href="xml/rb-string-value-map.xml"/>
 		<xi:include href="xml/rb-tree-dnd.xml"/>
 		<xi:include href="xml/rb-util.xml"/>
@@ -48,7 +46,6 @@
 	<chapter>  	
 		<title>Shell</title>
 		<xi:include href="xml/rb-history.xml"/>
-		<xi:include href="xml/rb-missing-plugins.xml"/>
 		<xi:include href="xml/rb-play-order.xml"/>
 		<xi:include href="xml/rb-playlist-manager.xml"/>
 		<xi:include href="xml/rb-removable-media-manager.xml"/>

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Sat Apr  5 01:33:04 2008
@@ -130,7 +130,9 @@
 
 <SECTION>
 <FILE>rb-history</FILE>
-RBHistoryPrivate
+<TITLE>RBHistory</TITLE>
+RBHistory
+RBHistoryClass
 rb_history_new
 rb_history_set_destroy_notify
 rb_history_set_truncate_on_play
@@ -161,6 +163,7 @@
 RB_HISTORY_CLASS
 RB_IS_HISTORY_CLASS
 RB_HISTORY_GET_CLASS
+RBHistoryPrivate
 </SECTION>
 
 <SECTION>

Modified: trunk/shell/rb-history.c
==============================================================================
--- trunk/shell/rb-history.c	(original)
+++ trunk/shell/rb-history.c	Sat Apr  5 01:33:04 2008
@@ -29,6 +29,18 @@
 
 #include "rhythmdb.h"
 
+/**
+ * SECTION:rb-history
+ * @short_description: sequence data structure useful for implementing play orders
+ *
+ * RBHistory is a GSequence that maintains a "current" pointer and can delete
+ * an arbitrary element in amortized O(log(N)) time. It can call a deletion
+ * callback when it removes one of its entries.
+ *
+ * All operations take amortized O(log(N)) (worst-case O(N)) time unless noted
+ * otherwise.
+ */
+
 struct RBHistoryPrivate
 {
 	GSequence *seq;
@@ -86,6 +98,11 @@
 	object_class->set_property = rb_history_set_property;
 	object_class->get_property = rb_history_get_property;
 
+	/**
+	 * RBHistory:truncate-on-play:
+	 *
+	 * If set, rb_history_set_playing() truncates the rest of the history
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_TRUNCATE_ON_PLAY,
 					 g_param_spec_boolean ("truncate-on-play",
@@ -94,6 +111,11 @@
 							       FALSE,
 							       G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
+	/**
+	 * RBHistory:maximum-size:
+	 *
+	 * Maximum number of entries to store in the history.  If 0, no limit is applied.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_MAX_SIZE,
 					 g_param_spec_uint ("maximum-size",
@@ -106,6 +128,14 @@
 	g_type_class_add_private (klass, sizeof (RBHistoryPrivate));
 }
 
+/**
+ * rb_history_new:
+ * @truncate_on_play: Whether rb_history_set_playing() should truncate the history
+ * @destroyer: function to call when removing an entry from the history
+ * @destroy_userdata: data to pass to @destroyer
+ *
+ * Return value: a new #RBHistory
+ */
 RBHistory *
 rb_history_new (gboolean truncate_on_play, GFunc destroyer, gpointer destroy_userdata)
 {
@@ -198,6 +228,14 @@
 
 }
 
+/**
+ * rb_history_set_destroy_notify:
+ * @hist: a #RBHistory
+ * @destroyer: function to call when removing an entry from the history
+ * @destroy_userdata: data to pass to @destroyer
+ *
+ * Sets a new function to call when removing entries from the history.
+ */
 void
 rb_history_set_destroy_notify (RBHistory *hist, GFunc destroyer, gpointer destroy_userdata)
 {
@@ -207,6 +245,13 @@
 	hist->priv->destroy_userdata = destroy_userdata;
 }
 
+/**
+ * rb_history_set_truncate_on_play:
+ * @hist: a #RBHistory
+ * @truncate_on_play: Whether rb_history_set_playing() should truncate the history
+ *
+ * Sets the 'truncate-on-play' property.
+ */
 void
 rb_history_set_truncate_on_play (RBHistory *hist, gboolean truncate_on_play)
 {
@@ -216,6 +261,13 @@
 	g_object_notify (G_OBJECT (hist), "truncate-on-play");
 }
 
+/**
+ * rb_history_set_maximum_size:
+ * @hist: a #RBHistory
+ * @maximum_size: new maximum size of the history (or 0 for no limit)
+ *
+ * Sets the maximum-size property
+ */
 void
 rb_history_set_maximum_size (RBHistory *hist, guint maximum_size)
 {
@@ -225,6 +277,12 @@
 	g_object_notify (G_OBJECT (hist), "maximum-size");
 }
 
+/**
+ * rb_history_length:
+ * @hist: a #RBHistory
+ *
+ * Return value: the number of entries in the history
+ */
 guint
 rb_history_length (RBHistory *hist)
 {
@@ -233,6 +291,12 @@
 	return g_sequence_get_length (hist->priv->seq);
 }
 
+/**
+ * rb_history_first:
+ * @hist: a #RBHistory
+ *
+ * Return value: the first entry in the history
+ */
 RhythmDBEntry *
 rb_history_first (RBHistory *hist)
 {
@@ -243,6 +307,12 @@
 	return g_sequence_iter_is_end (begin) ? NULL : g_sequence_get (begin);
 }
 
+/**
+ * rb_history_previous:
+ * @hist: a #RBHistory
+ *
+ * Return value: the #RhythmDBEntry before the current position
+ */
 RhythmDBEntry *
 rb_history_previous (RBHistory *hist)
 {
@@ -254,6 +324,12 @@
 	return prev == hist->priv->current ? NULL : g_sequence_get (prev);
 }
 
+/**
+ * rb_history_current:
+ * @hist: a #RBHistory
+ *
+ * Return value: the current #RhythmDBEntry, or NULL if there is no current position
+ */
 RhythmDBEntry *
 rb_history_current (RBHistory *hist)
 {
@@ -262,6 +338,12 @@
 	return g_sequence_iter_is_end (hist->priv->current) ? NULL : g_sequence_get (hist->priv->current);
 }
 
+/**
+ * rb_history_next:
+ * @hist: a #RBHistory
+ *
+ * Return value: the #RhythmDBEntry after the current position
+ */
 RhythmDBEntry *
 rb_history_next (RBHistory *hist)
 {
@@ -272,6 +354,12 @@
 	return g_sequence_iter_is_end (next) ? NULL : g_sequence_get (next);
 }
 
+/**
+ * rb_history_last:
+ * @hist: a #RBHistory
+ *
+ * Return value: the last #RhythmDBEntry in the history
+ */
 RhythmDBEntry *
 rb_history_last (RBHistory *hist)
 {
@@ -283,6 +371,12 @@
 	return g_sequence_iter_is_end (last) ? NULL : g_sequence_get (last);
 }
 
+/**
+ * rb_history_go_first:
+ * @hist: a #RBHistory
+ *
+ * Moves the current position to the first entry in the history
+ */
 void
 rb_history_go_first (RBHistory *hist)
 {
@@ -291,6 +385,13 @@
 	hist->priv->current = g_sequence_get_begin_iter (hist->priv->seq);
 }
 
+/**
+ * rb_history_go_previous:
+ * @hist: a #RBHistory
+ *
+ * Moves the current position to the previous entry.  If the current position is
+ * already at the start of the history, nothing happens.
+ */
 void
 rb_history_go_previous (RBHistory *hist)
 {
@@ -302,6 +403,13 @@
 		hist->priv->current = prev;
 }
 
+/**
+ * rb_history_go_next:
+ * @hist: a #RBHistory
+ *
+ * Moves the current position to the next entry.  If the current position is
+ * already at the end of the history, nothing happens.
+ */
 void
 rb_history_go_next (RBHistory *hist)
 {
@@ -310,6 +418,12 @@
 	hist->priv->current = g_sequence_iter_next (hist->priv->current);
 }
 
+/**
+ * rb_history_go_last:
+ * @hist: a #RBHistory
+ *
+ * Moves the current position to the last entry in the history
+ */
 void
 rb_history_go_last (RBHistory *hist)
 {
@@ -326,6 +440,15 @@
 	rb_history_remove_entry_internal (hist, entry, FALSE);
 }
 
+/**
+ * rb_history_set_playing:
+ * @hist: a #RBHistory
+ * @entry: the new playing #RhythmDBEntry
+ *
+ * Updates the current position to point to the specified entry.
+ * If the truncate-on-play property is set, this will remove all entries
+ * after that.
+ */
 void
 rb_history_set_playing (RBHistory *hist, RhythmDBEntry *entry)
 {
@@ -357,6 +480,15 @@
 	rb_history_limit_size (hist, TRUE);
 }
 
+/**
+ * rb_history_append:
+ * @hist: a #RBHistory
+ * @entry: a #RhythmDBEntry to append
+ *
+ * Adds a new entry to the end of the history list.
+ * If a size limit is set, an entry may be removed from the start to
+ * keep the history list within the limit.
+ */
 void
 rb_history_append (RBHistory *hist, RhythmDBEntry *entry)
 {
@@ -382,6 +514,15 @@
 	rb_history_limit_size (hist, TRUE);
 }
 
+/**
+ * rb_history_get_current_index:
+ * @hist: a #RBHistory
+ *
+ * Gets the index of the current entry. This is guaranteed to be < the
+ * history's size, so if the history is empty, it returns -1.
+ *
+ * Return value: index of the current entry
+ */
 gint
 rb_history_get_current_index (RBHistory *hist)
 {
@@ -390,6 +531,14 @@
 	return g_sequence_iter_get_position (hist->priv->current);
 }
 
+/**
+ * rb_history_insert_at_index:
+ * @hist: a #RBHistory
+ * @entry: a #RhythmDBEntry to insert
+ * @index: position at which to insert @entry
+ *
+ * Inserts @entry at @index within the history list. 0<= index<=size
+ */
 void
 rb_history_insert_at_index (RBHistory *hist, RhythmDBEntry *entry, guint index)
 {
@@ -425,7 +574,7 @@
 static void
 rb_history_limit_size (RBHistory *hist, gboolean cut_from_beginning)
 {
-	if (hist->priv->maximum_size != 0)
+	if (hist->priv->maximum_size != 0) {
 		while (g_sequence_get_length (hist->priv->seq) > hist->priv->maximum_size) {
 			if (cut_from_beginning
 					|| hist->priv->current == g_sequence_iter_prev (g_sequence_get_end_iter (hist->priv->seq))) {
@@ -434,8 +583,16 @@
 				rb_history_remove_entry (hist, rb_history_last (hist));
 			}
 		}
+	}
 }
 
+/**
+ * rb_history_remove_entry:
+ * @hist: a #RBHistory
+ * @entry: the #RhythmDBEntry to remove
+ *
+ * Removes the specified entry from the history list.
+ */
 void
 rb_history_remove_entry (RBHistory *hist, RhythmDBEntry *entry)
 {
@@ -464,6 +621,12 @@
 	}
 }
 
+/**
+ * rb_history_clear:
+ * @hist: a #RBHistory
+ *
+ * Empties the history list.
+ */
 void
 rb_history_clear (RBHistory *hist)
 {
@@ -477,6 +640,16 @@
 	g_assert (g_hash_table_size (hist->priv->entry_to_seqptr) == 0);
 }
 
+/**
+ * rb_history_dump:
+ * @hist: a #RBHistory
+ *
+ * Constructs a copy of the whole history in order. Caller must free the result.
+ * The caller does not own any references on the entries in the returned array.
+ * Takes O(Nlog(N)) time.
+ *
+ * Return value: a copy of the history list
+ */
 GPtrArray *
 rb_history_dump (RBHistory *hist)
 {
@@ -494,6 +667,13 @@
 	return result;
 }
 
+/**
+ * rb_history_contains_entry:
+ * @hist: a #RBHistory
+ * @entry: a #RhythmDBEntry to check for
+ *
+ * Return value: TRUE if the entry is present in the history list.
+ */
 gboolean
 rb_history_contains_entry (RBHistory *hist, RhythmDBEntry *entry)
 {

Modified: trunk/shell/rb-history.h
==============================================================================
--- trunk/shell/rb-history.h	(original)
+++ trunk/shell/rb-history.h	Sat Apr  5 01:33:04 2008
@@ -19,19 +19,6 @@
  *
  */
 
-/*
- * RBHistory is a GSequence that maintains a "current" pointer and can delete
- * an arbitrary element in amortized O(log(N)) time. It can call a deletion
- * callback when it removes one of its entries. RBHistory is a pure data
- * structure and can probably lose its GObject-ness.
- *
- * I may also add another "enqueued" pointer to help manage a queue of next
- * songs under shuffle.
- *
- * All operations take amortized O(log(N)) (worst-case O(N)) time unless noted
- * otherwise.
- */
-
 #include <glib/glist.h>
 #include "rhythmdb.h"
 #include "rb-shell-player.h"
@@ -48,20 +35,22 @@
 #define RB_IS_HISTORY_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_HISTORY))
 #define RB_HISTORY_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_HISTORY, RBHistoryClass))
 
+typedef struct _RBHistory RBHistory;
+typedef struct _RBHistoryClass RBHistoryClass;
+
 typedef struct RBHistoryPrivate RBHistoryPrivate;
 
-typedef struct
+struct _RBHistory
 {
 	GObject parent;
 
 	RBHistoryPrivate *priv;
-} RBHistory;
+};
 
-typedef struct
+struct _RBHistoryClass
 {
 	GObjectClass parent_class;
-
-} RBHistoryClass;
+};
 
 GType                   rb_history_get_type	(void);
 
@@ -83,45 +72,23 @@
 RhythmDBEntry *		rb_history_next		(RBHistory *hist);
 RhythmDBEntry *		rb_history_last		(RBHistory *hist);
 
-/* These move around within the history but never go beyond the head or tail */
 void			rb_history_go_first	(RBHistory *hist);
 void			rb_history_go_previous	(RBHistory *hist);
 void			rb_history_go_next	(RBHistory *hist);
 void			rb_history_go_last	(RBHistory *hist);
 
-/*
- * Sets the song after "current" to @entry and, depending on the value of the
- * "truncate-on-play" property, may remove the entries after this.
- */
 void			rb_history_set_playing	(RBHistory *hist, RhythmDBEntry *entry);
 
-/*
- * Adds entry onto the end of the history list
- */
 void			rb_history_append	(RBHistory *hist, RhythmDBEntry *entry);
 
-/*
- * Gets the index of the current entry. This is guaranteed to be < the
- * history's size, so if the history is empty, it returns -1.
- */
 gint			rb_history_get_current_index	(RBHistory *hist);
 
-/*
- * Inserts @entry at @index within the history list. 0<= index<=size
- */
 void			rb_history_insert_at_index	(RBHistory *hist, RhythmDBEntry *entry, guint index);
 
-/*
- * If the entry is in the history, removes all instances of it. Unrefs the
- * entry and decrements the list size.
- */
 void			rb_history_remove_entry	(RBHistory *hist, RhythmDBEntry *entry);
 
-/* Empties the history list */
 void			rb_history_clear	(RBHistory *hist);
 
-/* Returns a copy of the whole history in order. Caller must free the result.
- * Takes O(Nlog(N)) time. */
 GPtrArray *		rb_history_dump		(RBHistory *hist);
 
 gboolean		rb_history_contains_entry	(RBHistory *hist, RhythmDBEntry *entry);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]