add gtk-doc for refstring, removable media, static playlist, streaming

doc/reference/rhythmbox-sections.txt

@@ -446,7 +446,11 @@ RBRemovableMediaSource
 RBRemovableMediaSourceClass
 rb_removable_media_source_build_dest_uri
 rb_removable_media_source_track_added
+rb_removable_media_source_track_add_error
 rb_removable_media_source_get_mime_types
+rb_removable_media_source_get_format_descriptions
+rb_removable_media_source_should_paste
+rb_removable_media_source_should_paste_no_duplicate
 <SUBSECTION Standard>
 RB_REMOVABLE_MEDIA_SOURCE
 RB_IS_REMOVABLE_MEDIA_SOURCE
@@ -1099,18 +1103,6 @@ rb_refstring_equal
 rb_refstring_get_type
 </SECTION>
 
-<SECTION>
-<FILE>rb-query-creator-private</FILE>
-CriteriaCreateWidget
-CriteriaSetWidgetData
-CriteriaGetWidgetData
-num_property_options
-num_sort_options
-DEFAULT_SORTING_COLUMN
-DEFAULT_SORTING_ORDER
-get_box_widget_at_pos
-</SECTION>
-
 <SECTION>
 <FILE>rb-dialog</FILE>
 rb_error_dialog
@@ -1338,7 +1330,9 @@ RB_IMPORT_ERRORS_SOURCE_GET_CLASS
 
 <SECTION>
 <FILE>rb-streaming-source</FILE>
-RBStreamingSourcePrivate
+<TITLE>RBStreamingSource</TITLE>
+RBStreamingSource
+RBStreamingSourceClass
 rb_streaming_source_get_progress
 rb_streaming_source_set_streaming_title
 rb_streaming_source_set_streaming_artist
@@ -1351,6 +1345,7 @@ rb_streaming_source_get_type
 RB_STREAMING_SOURCE_CLASS
 RB_IS_STREAMING_SOURCE_CLASS
 RB_STREAMING_SOURCE_GET_CLASS
+RBStreamingSourcePrivate
 </SECTION>
 
 <SECTION>
@@ -1374,6 +1369,9 @@ RB_AUTO_PLAYLIST_SOURCE_GET_CLASS
 
 <SECTION>
 <FILE>rb-static-playlist-source</FILE>
+<TITLE>RBStaticPlaylistSource</TITLE>
+RBStaticPlaylistSource
+RBStaticPlaylistSourceClass
 rb_static_playlist_source_new
 rb_static_playlist_source_new_from_xml
 rb_static_playlist_source_load_from_xml

lib/rb-async-queue-watch.c

@@ -33,6 +33,9 @@
 /**
  * SECTION:rb-async-queue-watch
  * @short_description: GSource for watching a GAsyncQueue in the main loop
+ *
+ * This provides a way to feed work items to the main loop using a #GAsyncQueue
+ * without polling it.
  */
 
 /**

lib/rb-text-helpers.c

@@ -33,6 +33,9 @@
 /**
  * SECTION:rb-text-helpers
  * @short_description: text direction (LTR/RTL) functions
+ *
+ * Provides some helper functions for constructing strings that
+ * may include both left-to-right and right-to-left text.
  */
 
 /* unicode direction markup characters

rhythmdb/rb-refstring.c

@@ -55,6 +55,11 @@ rb_refstring_free (RBRefString *refstr)
 	g_free (refstr);
 }
 
+/**
+ * rb_refstring_system_init:
+ *
+ * Sets up the refstring system.  Called on startup.
+ */
 void
 rb_refstring_system_init ()
 {
@@ -64,6 +69,16 @@ rb_refstring_system_init ()
 					       NULL, (GDestroyNotify) rb_refstring_free);
 }
 
+/**
+ * rb_refstring_new:
+ * @init: string to intern
+ *
+ * Returns an #RBRefString for the specified string.
+ * If one already exists, its reference count is incremented and it is
+ * returned.  Otherwise, a new #RBRefString is created and returned.
+ *
+ * Return value: #RBRefString for @init
+ */
 RBRefString *
 rb_refstring_new (const char *init)
 {
@@ -90,6 +105,16 @@ rb_refstring_new (const char *init)
 	return ret;
 }
 
+/**
+ * rb_refstring_find:
+ * @init: string to find
+ *
+ * Returns an existing #RBRefString for @init if one exists,
+ * otherwise returns NULL.  If an existing refstring is found,
+ * its reference count is increased.
+ *
+ * Return value: existing #RBRefString, or NULL
+ */
 RBRefString *
 rb_refstring_find (const char *init)
 {
@@ -105,6 +130,13 @@ rb_refstring_find (const char *init)
 	return ret;
 }
 
+/**
+ * rb_refstring_unref:
+ * @val: #RBRefString to unref
+ *
+ * Drops a reference to an #RBRefString.  If this is the last
+ * reference, the string will be freed.
+ */
 void
 rb_refstring_unref (RBRefString *val)
 {
@@ -123,13 +155,28 @@ rb_refstring_unref (RBRefString *val)
 	}
 }
 
+/**
+ * rb_refstring_system_shutdown:
+ *
+ * Frees all data associated with the refstring system.
+ * Only called on shutdown.
+ */
 void
 rb_refstring_system_shutdown (void)
 {
 	g_hash_table_destroy (rb_refstrings);
 	g_mutex_free (rb_refstrings_mutex);
 }
 
+/**
+ * rb_refstring_ref:
+ * @val: a #RBRefString to reference
+ *
+ * Increases the reference count for an existing #RBRefString.
+ * The refstring is returned for convenience.
+ *
+ * Return value: the same refstring
+ */
 RBRefString *
 rb_refstring_ref (RBRefString *val)
 {
@@ -142,6 +189,14 @@ rb_refstring_ref (RBRefString *val)
 	return val;
 }
 
+/**
+ * rb_refstring_get:
+ * @val: an #RBRefString
+ *
+ * Returns the actual string for a #RBRefString.
+ *
+ * Return value: underlying string, must not be freed
+ */
 const char *
 rb_refstring_get (const RBRefString *val)
 {
@@ -155,6 +210,17 @@ rb_refstring_get (const RBRefString *val)
  * get called often.
  */
 
+/**
+ * rb_refstring_get_folded:
+ * @val: an #RBRefString
+ *
+ * Returns the case-folded version of the string underlying @val.
+ * The case-folded string is cached inside the #RBRefString for
+ * speed.  See @rb_search_fold for information on case-folding
+ * strings.
+ *
+ * Return value: case-folded string, must not be freed
+ */
 const char *
 rb_refstring_get_folded (RBRefString *val)
 {
@@ -182,6 +248,18 @@ rb_refstring_get_folded (RBRefString *val)
 	return string;
 }
 
+/**
+ * rb_refstring_get_sort_key:
+ * @val: an #RBRefString
+ *
+ * Returns the sort key version of the string underlying @val.
+ * The sort key string is cached inside the #RBRefString for speed.
+ * Sort key strings are not generally human readable, so don't display
+ * them anywhere.  See @g_utf8_collate_key_for_filename for information
+ * on sort keys.
+ *
+ * Return value: sort key string, must not be freed.
+ */
 const char *
 rb_refstring_get_sort_key (RBRefString *val)
 {
@@ -213,13 +291,32 @@ rb_refstring_get_sort_key (RBRefString *val)
 	return string;
 }
 
+/**
+ * rb_refstring_hash:
+ * @p: an #RBRefString
+ *
+ * Hash function suitable for use with @GHashTable.
+ *
+ * Return value: hash value for the string underlying @p
+ */
 guint
 rb_refstring_hash (gconstpointer p)
 {
 	const RBRefString *ref = p;
 	return g_str_hash (rb_refstring_get (ref));
 }
 
+/**
+ * rb_refstring_equal:
+ * @ap: an #RBRefString
+ * @bp: another #RBRefstring
+ *
+ * Key equality function suitable for use with #GHashTable.
+ * Equality checks for #RBRefString are just pointer comparisons,
+ * since there can only be one refstring for a given string.
+ *
+ * Return value: %TRUE if the strings are the same
+ */
 gboolean
 rb_refstring_equal (gconstpointer ap, gconstpointer bp)
 {