[rhythmbox] add gtk-doc for refstring, removable media, static playlist, streaming
- From: Jonathan Matthew <jmatthew src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [rhythmbox] add gtk-doc for refstring, removable media, static playlist, streaming
- Date: Sun, 21 Mar 2010 01:36:25 +0000 (UTC)
commit 41e3c46dc6f36612290e7c0337020455bd5b4e18
Author: Jonathan Matthew <jonathan d14n org>
Date: Sun Mar 21 11:34:08 2010 +1000
add gtk-doc for refstring, removable media, static playlist, streaming
doc/reference/rhythmbox-sections.txt | 24 +++----
lib/rb-async-queue-watch.c | 3 +
lib/rb-text-helpers.c | 3 +
rhythmdb/rb-refstring.c | 97 +++++++++++++++++++++++++
rhythmdb/rhythmdb-query.c | 100 ++++++++++++++++++++++++++-
rhythmdb/rhythmdb.h | 4 +-
shell/rb-history.c | 30 ++++++--
sources/rb-removable-media-source.c | 114 ++++++++++++++++++++++++++++++
sources/rb-removable-media-source.h | 2 +-
sources/rb-static-playlist-source.c | 94 ++++++++++++++++++++++++-
sources/rb-static-playlist-source.h | 11 ++-
sources/rb-streaming-source.c | 48 +++++++++++--
sources/rb-streaming-source.h | 15 ++--
tests/test-rhythmdb-tree-serialization.c | 6 +-
widgets/rb-dialog.c | 3 +
15 files changed, 507 insertions(+), 47 deletions(-)
---
diff --git a/doc/reference/rhythmbox-sections.txt b/doc/reference/rhythmbox-sections.txt
index a933e67..90ade41 100644
--- a/doc/reference/rhythmbox-sections.txt
+++ b/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
@@ -1100,18 +1104,6 @@ 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
rb_file_chooser_new
@@ -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
diff --git a/lib/rb-async-queue-watch.c b/lib/rb-async-queue-watch.c
index ce6b33c..02eda10 100644
--- a/lib/rb-async-queue-watch.c
+++ b/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.
*/
/**
diff --git a/lib/rb-text-helpers.c b/lib/rb-text-helpers.c
index b397bda..40d3846 100644
--- a/lib/rb-text-helpers.c
+++ b/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
diff --git a/rhythmdb/rb-refstring.c b/rhythmdb/rb-refstring.c
index a2a42a6..6e18ed2 100644
--- a/rhythmdb/rb-refstring.c
+++ b/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,6 +155,12 @@ 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)
{
@@ -130,6 +168,15 @@ rb_refstring_system_shutdown (void)
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,6 +291,14 @@ 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)
{
@@ -220,6 +306,17 @@ rb_refstring_hash (gconstpointer 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)
{
diff --git a/rhythmdb/rhythmdb-query.c b/rhythmdb/rhythmdb-query.c
index ea990fb..dfd5098 100644
--- a/rhythmdb/rhythmdb-query.c
+++ b/rhythmdb/rhythmdb-query.c
@@ -54,6 +54,7 @@
#define RB_PARSE_YEAR_EQUALS RB_PARSE_EQUALS
#define RB_PARSE_YEAR_GREATER RB_PARSE_GREATER
#define RB_PARSE_YEAR_LESS RB_PARSE_LESS
+
/**
* rhythmdb_query_copy:
* @array: the query to copy.
@@ -76,6 +77,13 @@ rhythmdb_query_copy (GPtrArray *array)
return ret;
}
+/**
+ * rhythmdb_query_concatenate:
+ * @query1: query to append to
+ * @query2: query to append
+ *
+ * Appends @query2 to @query1.
+ */
void
rhythmdb_query_concatenate (GPtrArray *query1, GPtrArray *query2)
{
@@ -101,6 +109,16 @@ rhythmdb_query_concatenate (GPtrArray *query1, GPtrArray *query2)
}
}
+/**
+ * rhythmdb_query_parse_valist:
+ * @db: the #RhythmDB
+ * @args: the arguments to parse
+ *
+ * Converts a va_list into a parsed query in the form of a @GPtrArray.
+ * See @rhythmdb_query_parse for more information on the parsing process.
+ *
+ * Return value: converted query
+ */
GPtrArray *
rhythmdb_query_parse_valist (RhythmDB *db, va_list args)
{
@@ -230,6 +248,16 @@ rhythmdb_query_append (RhythmDB *db, GPtrArray *query, ...)
va_end (args);
}
+/**
+ * rhythmdb_query_append_params:
+ * @db: the #RhythmDB
+ * @query: the query to append to
+ * @type: query type
+ * @prop: query property
+ * @value: query value
+ *
+ * Appends a new query term to @query.
+ */
void
rhythmdb_query_append_params (RhythmDB *db, GPtrArray *query,
RhythmDBQueryType type, RhythmDBPropType prop, const GValue *value)
@@ -273,7 +301,7 @@ rhythmdb_query_append_params (RhythmDB *db, GPtrArray *query,
* @query: a query.
*
* Frees the query @query
- **/
+ */
void
rhythmdb_query_free (GPtrArray *query)
{
@@ -373,6 +401,19 @@ write_encoded_gvalue (RhythmDB *db,
g_free (quoted);
}
+/**
+ * rhythmdb_read_encoded_property:
+ * @db: the #RhythmDB
+ * @content: encoded property value
+ * @propid: property ID
+ * @val: returns the property value
+ *
+ * Converts a string containing a property value into a #GValue
+ * containing the native form of the property value. For boolean
+ * and numeric properties, this converts the string to a number.
+ * For #RHYTHMDB_PROP_TYPE, this looks up the entry type by name.
+ * For strings, no conversion is required.
+ */
void
rhythmdb_read_encoded_property (RhythmDB *db,
const char *content,
@@ -433,6 +474,15 @@ rhythmdb_read_encoded_property (RhythmDB *db,
}
}
+/**
+ * rhythmdb_query_serialize:
+ * @db: the #RhythmDB
+ * @query: query to serialize
+ * @parent: XML node to attach the query to
+ *
+ * Converts @query into XML form as a child of @parent. It can be converted
+ * back into a query by passing @parent to @rhythmdb_query_deserialize.
+ */
void
rhythmdb_query_serialize (RhythmDB *db, GPtrArray *query,
xmlNodePtr parent)
@@ -518,6 +568,15 @@ rhythmdb_query_serialize (RhythmDB *db, GPtrArray *query,
}
}
+/**
+ * rhythmdb_query_deserialize:
+ * @db: the #RhythmDB
+ * @parent: parent XML node of serialized query
+ *
+ * Converts a serialized query back into a @GPtrArray query.
+ *
+ * Return value: deserialized query.
+ */
GPtrArray *
rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr parent)
{
@@ -629,6 +688,26 @@ rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr parent)
* actually implements. e.g. RHYTHMDB_QUERY_YEAR_*
**/
+/**
+ * rhythmdb_query_preprocess:
+ * @db: the #RhythmDB
+ * @query: query to preprocess
+ *
+ * Preprocesses a query to prepare it for execution. This has two main
+ * roles: to perform expensive data transformations once per query, rather
+ * than once per entry, and converting criteria to lower-level forms that
+ * are implemented by the database backend.
+ *
+ * For RHYTHMDB_PROP_SEARCH_MATCH, this converts the search terms into
+ * an array of case-folded words.
+ *
+ * When matching against case-folded properties such as
+ * #RHYTHMDB_PROP_TITLE_FOLDED, this case-folds the query value.
+ *
+ * When performing year-based criteria such as #RHYTHMDB_QUERY_PROP_YEAR_LESS,
+ * it converts the year into the Julian date such that a simple numeric
+ * comparison will work.
+ */
void
rhythmdb_query_preprocess (RhythmDB *db, GPtrArray *query)
{
@@ -740,6 +819,16 @@ rhythmdb_query_preprocess (RhythmDB *db, GPtrArray *query)
}
}
+/**
+ * rhythmdb_query_append_prop_multiple:
+ * @db: the #RhythmDB
+ * @query: the query to append to
+ * @propid: property ID to match
+ * @items: #GList of values to match against
+ *
+ * Appends a set of criteria to a query to match against any of the values
+ * listed in @items.
+ */
void
rhythmdb_query_append_prop_multiple (RhythmDB *db, GPtrArray *query, RhythmDBPropType propid, GList *items)
{
@@ -781,6 +870,15 @@ rhythmdb_query_append_prop_multiple (RhythmDB *db, GPtrArray *query, RhythmDBPro
RHYTHMDB_QUERY_END);
}
+/**
+ * rhythmdb_query_is_time_relative
+ * @db: the #RhythmDB
+ * @query: the query to check
+ *
+ * Checks if a query contains any time-relative criteria.
+ *
+ * Return value: %TRUE if time-relative criteria found
+ */
gboolean
rhythmdb_query_is_time_relative (RhythmDB *db, GPtrArray *query)
{
diff --git a/rhythmdb/rhythmdb.h b/rhythmdb/rhythmdb.h
index 56bce41..498c9a9 100644
--- a/rhythmdb/rhythmdb.h
+++ b/rhythmdb/rhythmdb.h
@@ -473,9 +473,9 @@ RhythmDBQuery * rhythmdb_query_copy (RhythmDBQuery *array);
void rhythmdb_query_preprocess (RhythmDB *db, RhythmDBQuery *query);
void rhythmdb_query_serialize (RhythmDB *db, RhythmDBQuery *query,
- xmlNodePtr node);
+ xmlNodePtr parent);
-RhythmDBQuery * rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr node);
+RhythmDBQuery * rhythmdb_query_deserialize (RhythmDB *db, xmlNodePtr parent);
char * rhythmdb_query_to_string (RhythmDB *db, RhythmDBQuery *query);
diff --git a/shell/rb-history.c b/shell/rb-history.c
index f91e896..e8b9564 100644
--- a/shell/rb-history.c
+++ b/shell/rb-history.c
@@ -139,6 +139,8 @@ rb_history_class_init (RBHistoryClass *klass)
* @destroyer: function to call when removing an entry from the history
* @destroy_userdata: data to pass to @destroyer
*
+ * Creates a new history instance.
+ *
* Return value: a new #RBHistory
*/
RBHistory *
@@ -286,7 +288,9 @@ rb_history_set_maximum_size (RBHistory *hist, guint maximum_size)
* rb_history_length:
* @hist: a #RBHistory
*
- * Return value: the number of entries in the history
+ * Returns the number of entries in the history.
+ *
+ * Return value: number of entries
*/
guint
rb_history_length (RBHistory *hist)
@@ -300,7 +304,9 @@ rb_history_length (RBHistory *hist)
* rb_history_first:
* @hist: a #RBHistory
*
- * Return value: the first entry in the history
+ * Returns the first entry in the history.
+ *
+ * Return value: first entry
*/
RhythmDBEntry *
rb_history_first (RBHistory *hist)
@@ -316,7 +322,9 @@ rb_history_first (RBHistory *hist)
* rb_history_previous:
* @hist: a #RBHistory
*
- * Return value: the #RhythmDBEntry before the current position
+ * Returns the #RhythmDBEntry before the current position.
+ *
+ * Return value: previous entry
*/
RhythmDBEntry *
rb_history_previous (RBHistory *hist)
@@ -333,7 +341,9 @@ rb_history_previous (RBHistory *hist)
* rb_history_current:
* @hist: a #RBHistory
*
- * Return value: the current #RhythmDBEntry, or NULL if there is no current position
+ * Returns the current #RhythmDBEntry, or NULL if there is no current position
+ *
+ * Return value: current entry or NULL
*/
RhythmDBEntry *
rb_history_current (RBHistory *hist)
@@ -347,7 +357,9 @@ rb_history_current (RBHistory *hist)
* rb_history_next:
* @hist: a #RBHistory
*
- * Return value: the #RhythmDBEntry after the current position
+ * Returns the #RhythmDBEntry after the current position
+ *
+ * Return value: next entry
*/
RhythmDBEntry *
rb_history_next (RBHistory *hist)
@@ -363,7 +375,9 @@ rb_history_next (RBHistory *hist)
* rb_history_last:
* @hist: a #RBHistory
*
- * Return value: the last #RhythmDBEntry in the history
+ * Returns the last #RhythmDBEntry in the history
+ *
+ * Return value: last entry
*/
RhythmDBEntry *
rb_history_last (RBHistory *hist)
@@ -677,7 +691,9 @@ rb_history_dump (RBHistory *hist)
* @hist: a #RBHistory
* @entry: a #RhythmDBEntry to check for
*
- * Return value: TRUE if the entry is present in the history list.
+ * Returns %TRUE if the entry is present in the history list.
+ *
+ * Return value: %TRUE if found
*/
gboolean
rb_history_contains_entry (RBHistory *hist, RhythmDBEntry *entry)
diff --git a/sources/rb-removable-media-source.c b/sources/rb-removable-media-source.c
index 6d2284a..4154361 100644
--- a/sources/rb-removable-media-source.c
+++ b/sources/rb-removable-media-source.c
@@ -27,6 +27,16 @@
*
*/
+/**
+ * SECTION:rb-removable-media-source
+ * @short_description: Base class for sources representing removable media
+ *
+ * This class provides support for transferring (and transcoding) entries to
+ * the device using drag and drop or cut and paste. The implementation must
+ * at minimum provide methods for returning a list of supported media types,
+ * and for constructing destination URIs for transfers.
+ */
+
#include <config.h>
#include <string.h>
@@ -117,6 +127,11 @@ rb_removable_media_source_class_init (RBRemovableMediaSourceClass *klass)
klass->impl_should_paste = impl_should_paste;
+ /**
+ * RBRemovableMediaSource:volume
+ *
+ * The #GVolume object that the source represents (optional)
+ */
g_object_class_install_property (object_class,
PROP_VOLUME,
g_param_spec_object ("volume",
@@ -124,6 +139,11 @@ rb_removable_media_source_class_init (RBRemovableMediaSourceClass *klass)
"GIO Volume",
G_TYPE_VOLUME,
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+ /**
+ * RBRemovableMediaSource:mount
+ *
+ * The #GMount object that the source represents
+ */
g_object_class_install_property (object_class,
PROP_MOUNT,
g_param_spec_object ("mount",
@@ -593,6 +613,24 @@ impl_receive_drag (RBSource *asource, GtkSelectionData *data)
return TRUE;
}
+/**
+ * rb_removable_media_source_build_dest_uri:
+ * @source: an #RBRemovableMediaSource
+ * @entry: the #RhythmDBEntry to build a URI for
+ * @mimetype: destination media type
+ * @extension: extension associated with destination media type
+ *
+ * Constructs a URI to use as the destination for a transfer or transcoding
+ * operation. The URI may be on the device itself, if the device is mounted
+ * into the normal filesystem or through gvfs, or it may be a temporary
+ * location used to store the file before uploading it to the device.
+ *
+ * The destination URI should conform to the device's normal URI format,
+ * and should use the provided extension instead of the extension from
+ * the source entry.
+ *
+ * Return value: constructed URI
+ */
char *
rb_removable_media_source_build_dest_uri (RBRemovableMediaSource *source,
RhythmDBEntry *entry,
@@ -622,6 +660,21 @@ rb_removable_media_source_build_dest_uri (RBRemovableMediaSource *source,
return uri;
}
+/**
+ * rb_removable_media_source_get_mime_types:
+ * @source: an #RBRemovableMediaSource
+ *
+ * Returns a #GList of allocated media type strings describing the
+ * formats supported by the device. If possible, these should be
+ * sorted in order of preference, as the first entry in the list
+ * for which an encoder is available will be used.
+ *
+ * Common media types include "audio/mpeg" for MP3, "application/ogg"
+ * for Ogg Vorbis, "audio/x-flac" for FLAC, and "audio/x-aac" for
+ * MP4/AAC.
+ *
+ * Return value: list of media types
+ */
GList *
rb_removable_media_source_get_mime_types (RBRemovableMediaSource *source)
{
@@ -633,6 +686,16 @@ rb_removable_media_source_get_mime_types (RBRemovableMediaSource *source)
return NULL;
}
+/**
+ * rb_removable_media_source_get_format_descriptions:
+ * @source: a #RBRemovableMediaSource
+ *
+ * Returns a #GList of allocated media format descriptions for
+ * the formats supported by the device. The list and the strings
+ * it holds must be freed by the caller.
+ *
+ * Return value: list of descriptions.
+ */
GList *
rb_removable_media_source_get_format_descriptions (RBRemovableMediaSource *source)
{
@@ -660,6 +723,17 @@ rb_removable_media_source_get_format_descriptions (RBRemovableMediaSource *sourc
return desc;
}
+/**
+ * rb_removablem_media_source_should_paste_no_duplicate:
+ * @source: an #RBRemovableMediaSource
+ * @entry: a #RhythmDBEntry to consider pasting
+ *
+ * This implementation of #rb_removable_media_should_paste checks for
+ * an existing entry on the device that matches the title, album, artist,
+ * and track number of the entry being considered.
+ *
+ * Return value: %TRUE if the entry should be transferred to the device.
+ */
gboolean
rb_removable_media_source_should_paste_no_duplicate (RBRemovableMediaSource *source,
RhythmDBEntry *entry)
@@ -722,6 +796,18 @@ impl_should_paste (RBRemovableMediaSource *source, RhythmDBEntry *entry)
return should_paste;
}
+/**
+ * rb_removable_media_source_should_paste:
+ * @source: an #RBRemovableMediaSource
+ * @entry: a #RhythmDBEntry to consider pasting
+ *
+ * Checks whether @entry should be transferred to the device.
+ * The source can check whether a matching entry already exists on the device,
+ * for instance. See @rb_removable_media_source_should_paste_no_duplicate
+ * a useful implementation.
+ *
+ * Return value: %TRUE if the entry should be transferred to the device
+ */
gboolean
rb_removable_media_source_should_paste (RBRemovableMediaSource *source,
RhythmDBEntry *entry)
@@ -731,6 +817,22 @@ rb_removable_media_source_should_paste (RBRemovableMediaSource *source,
return klass->impl_should_paste (source, entry);
}
+/**
+ * rb_removable_media_source_track_added:
+ * @source: an #RBRemovableMediaSource
+ * @entry: the source #RhythmDBEntry for the transfer
+ * @uri: the destination URI
+ * @filesize: size of the destination file
+ * @mimetype: media type of the destination file
+ *
+ * This is called when a transfer to the device has completed.
+ * If the source's impl_track_added method returns %TRUE, the destination
+ * URI will be added to the database using the entry type for the device.
+ *
+ * If the source uses a temporary area as the destination for transfers,
+ * it can instead upload the destination file to the device and create an
+ * entry for it, then return %FALSE.
+ */
void
rb_removable_media_source_track_added (RBRemovableMediaSource *source,
RhythmDBEntry *entry,
@@ -761,6 +863,18 @@ rb_removable_media_source_track_added (RBRemovableMediaSource *source,
}
}
+/**
+ * rb_removable_media_source_track_add_error:
+ * @source: an #RBRemovableMediaSource
+ * @entry: the source #RhythmDBEntry for the transfer
+ * @uri: the destination URI
+ * @error: the transfer error information
+ *
+ * This is called when a transfer fails. If the source's
+ * impl_track_add_error implementation returns %TRUE, an error dialog
+ * will be displayed to the user containing the error message, unless
+ * the error indicates that the destination file already exists.
+ */
void
rb_removable_media_source_track_add_error (RBRemovableMediaSource *source,
RhythmDBEntry *entry,
diff --git a/sources/rb-removable-media-source.h b/sources/rb-removable-media-source.h
index 60b3818..4deac13 100644
--- a/sources/rb-removable-media-source.h
+++ b/sources/rb-removable-media-source.h
@@ -83,7 +83,7 @@ char* rb_removable_media_source_build_dest_uri (RBRemovableMediaSource *source
void rb_removable_media_source_track_added (RBRemovableMediaSource *source,
RhythmDBEntry *entry,
const char *uri,
- guint64 dest_size,
+ guint64 filesize,
const char *mimetype);
void rb_removable_media_source_track_add_error (RBRemovableMediaSource *source,
RhythmDBEntry *entry,
diff --git a/sources/rb-static-playlist-source.c b/sources/rb-static-playlist-source.c
index 2caaa2a..6310bba 100644
--- a/sources/rb-static-playlist-source.c
+++ b/sources/rb-static-playlist-source.c
@@ -27,6 +27,21 @@
*
*/
+/**
+ * SECTION:rb-static-playlist-source
+ * @short_description: Manually defined playlist class
+ *
+ * Static playlists are not defined by a query, but instead by manually selected
+ * and ordered tracks.
+ *
+ * This class is used for static playlists built from the user's library, and is
+ * also a base class for the play queue and for playlists on devices and network
+ * shares.
+ *
+ * It has some ability to track locations that are not yet present in the database
+ * and to add them to the playlist once they are added.
+ */
+
#include "config.h"
#include <string.h>
@@ -336,6 +351,18 @@ rb_static_playlist_source_constructed (GObject *object)
gtk_widget_show_all (GTK_WIDGET (source));
}
+/**
+ * rb_static_playlist_source_new:
+ * @shell: the #RBShell
+ * @name: the playlist name
+ * @sorting_name: the sorting name for the playlist (GConf key friendly)
+ * @local: if %TRUE, the playlist is local to the library
+ * @entry_type: type of database entries that can be added to the playlist.
+ *
+ * Creates a new static playlist source.
+ *
+ * Return value: new playlist.
+ */
RBSource *
rb_static_playlist_source_new (RBShell *shell, const char *name, const char *sorting_name, gboolean local, RhythmDBEntryType entry_type)
{
@@ -389,6 +416,13 @@ rb_static_playlist_source_get_property (GObject *object,
}
}
+/**
+ * rb_static_playlist_source_load_from_xml:
+ * @source: an #RBStaticPlaylistSource
+ * @node: XML node to load from
+ *
+ * Loads the playlist contents from the specified XML document node.
+ */
void
rb_static_playlist_source_load_from_xml (RBStaticPlaylistSource *source, xmlNodePtr node)
{
@@ -410,6 +444,15 @@ rb_static_playlist_source_load_from_xml (RBStaticPlaylistSource *source, xmlNode
}
}
+/**
+ * rb_static_playlist_source_new_from_xml:
+ * @shell: the #RBShell
+ * @node: XML node containing playlist entries
+ *
+ * Constructs a new playlist from the given XML document node.
+ *
+ * Return value: playlist read from XML
+ */
RBSource *
rb_static_playlist_source_new_from_xml (RBShell *shell, xmlNodePtr node)
{
@@ -745,6 +788,16 @@ _add_location_cb (GFile *file,
return TRUE;
}
+/**
+ * rb_static_playlist_source_add_location:
+ * @source: an #RBStaticPlaylistSource
+ * @location: location (URI) to add to the playlist
+ * @index: position at which to add the location (-1 to add at the end)
+ *
+ * If the location matches an entry in the database, the entry is added
+ * to the playlist. Otherwise, if it identifies a directory, the contents
+ * of that directory are added.
+ */
void
rb_static_playlist_source_add_location (RBStaticPlaylistSource *source,
const char *location,
@@ -767,6 +820,14 @@ rb_static_playlist_source_add_location (RBStaticPlaylistSource *source,
}
+/**
+ * rb_static_playlist_source_add_locations:
+ * @source: an #RBStaticPlaylistSource
+ * @locations: a #GList of strings to add
+ *
+ * Adds the locations specified in @locations to the playlist.
+ * See @rb_static_playlist_source_add_location for details.
+ */
void
rb_static_playlist_source_add_locations (RBStaticPlaylistSource *source,
GList *locations)
@@ -779,6 +840,15 @@ rb_static_playlist_source_add_locations (RBStaticPlaylistSource *source,
}
}
+/**
+ * rb_static_playlist_source_remove_location:
+ * @source: an #RBStaticPlaylistSource
+ * @location: location to remove
+ *
+ * Removes the specified location from the playlist. This affects both
+ * the location map and the query model, whether an entry exists for the
+ * location or not.
+ */
void
rb_static_playlist_source_remove_location (RBStaticPlaylistSource *source,
const char *location)
@@ -801,6 +871,14 @@ rb_static_playlist_source_remove_location (RBStaticPlaylistSource *source,
}
}
+/**
+ * rb_static_playlist_source_add_entry:
+ * @source: an #RBStaticPlaylistSource
+ * @entry: entry to add to the playlist
+ * @index: position at which to add it (-1 to add at the end)
+ *
+ * Adds the specified entry to the playlist.
+ */
void
rb_static_playlist_source_add_entry (RBStaticPlaylistSource *source,
RhythmDBEntry *entry,
@@ -812,6 +890,13 @@ rb_static_playlist_source_add_entry (RBStaticPlaylistSource *source,
rb_static_playlist_source_add_location_internal (source, location, index);
}
+/**
+ * rb_static_playlist_source_remove_entry:
+ * @source: an #RBStaticPlaylistSource
+ * @entry: the entry to remove
+ *
+ * Removes the specified entry from the playlist.
+ */
void
rb_static_playlist_source_remove_entry (RBStaticPlaylistSource *source,
RhythmDBEntry *entry)
@@ -822,6 +907,14 @@ rb_static_playlist_source_remove_entry (RBStaticPlaylistSource *source,
rb_static_playlist_source_remove_location (source, location);
}
+/**
+ * rb_static_playlist_source_move_entry:
+ * @source: an #RBStaticPlaylistSource
+ * @entry: the entry to move
+ * @index: new location for the entry
+ *
+ * Moves an entry within the playlist.
+ */
void
rb_static_playlist_source_move_entry (RBStaticPlaylistSource *source,
RhythmDBEntry *entry,
@@ -909,4 +1002,3 @@ impl_want_uri (RBSource *source, const char *uri)
return 0;
}
-
diff --git a/sources/rb-static-playlist-source.h b/sources/rb-static-playlist-source.h
index aa1f61a..02320ba 100644
--- a/sources/rb-static-playlist-source.h
+++ b/sources/rb-static-playlist-source.h
@@ -45,15 +45,18 @@ G_BEGIN_DECLS
#define RB_IS_STATIC_PLAYLIST_SOURCE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_STATIC_PLAYLIST_SOURCE))
#define RB_STATIC_PLAYLIST_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_STATIC_PLAYLIST_SOURCE, RBStaticPlaylistSourceClass))
-typedef struct
+typedef struct _RBStaticPlaylistSource RBStaticPlaylistSource;
+typedef struct _RBStaticPlaylistSourceClass RBStaticPlaylistSourceClass;
+
+struct _RBStaticPlaylistSource
{
RBPlaylistSource parent;
-} RBStaticPlaylistSource;
+};
-typedef struct
+struct _RBStaticPlaylistSourceClass
{
RBPlaylistSourceClass parent;
-} RBStaticPlaylistSourceClass;
+};
GType rb_static_playlist_source_get_type (void);
diff --git a/sources/rb-streaming-source.c b/sources/rb-streaming-source.c
index 3027e1e..4bb8d6e 100644
--- a/sources/rb-streaming-source.c
+++ b/sources/rb-streaming-source.c
@@ -27,12 +27,12 @@
*
*/
-/*
- * base class for streaming sources (internet radio, last.fm streams)
- * provides handling of:
- * - buffering signals (done)
- * - streaming song metadata (done)
- * - possibly updating play count etc.?
+/**
+ * SECTION:rb-streaming-source
+ * @short_description: Base class for streaming sources such as internet radio
+ *
+ * This class provides handling of buffering signals and streaming song metadata
+ * common to different types of sources that play continuous streaming media.
*/
#include "config.h"
@@ -82,7 +82,7 @@ static void extra_metadata_gather_cb (RhythmDB *db,
RBStringValueMap *data,
RBStreamingSource *source);
-struct RBStreamingSourcePrivate
+struct _RBStreamingSourcePrivate
{
RhythmDB *db;
@@ -200,6 +200,15 @@ impl_handle_eos (RBSource *asource)
return RB_SOURCE_EOF_RETRY;
}
+/**
+ * rb_streaming_source_get_progress:
+ * @source: a #RBStreamingSource
+ * @text: returns buffering status text
+ * @progress: returns buffering progress fraction
+ *
+ * Provides status text and progress fraction suitable for use in
+ * a streaming source's @rb_source_get_status method.
+ */
void
rb_streaming_source_get_progress (RBStreamingSource *source, char **text, float *progress)
{
@@ -383,6 +392,14 @@ set_streaming_metadata (RBStreamingSource *source,
source);
}
+/**
+ * rb_streaming_source_set_streaming_title:
+ * @source: a #RBStreamingSource
+ * @title: the new streaming song title
+ *
+ * Updates the streaming song title. Call this when an updated
+ * streaming song title is received from the stream.
+ */
void
rb_streaming_source_set_streaming_title (RBStreamingSource *source,
const char *title)
@@ -394,6 +411,14 @@ rb_streaming_source_set_streaming_title (RBStreamingSource *source,
title);
}
+/**
+ * rb_streaming_source_set_streaming_artist:
+ * @source: a #RBStreamingSource
+ * @artist: the new streaming song artist name
+ *
+ * Updates the streaming song artist name. Call this when an updated
+ * streaming song artist name is received from the stream.
+ */
void
rb_streaming_source_set_streaming_artist (RBStreamingSource *source,
const char *artist)
@@ -405,6 +430,14 @@ rb_streaming_source_set_streaming_artist (RBStreamingSource *source,
artist);
}
+/**
+ * rb_streaming_source_set_streaming_album:
+ * @source: a #RBStreamingSource
+ * @album: the new streaming song album name
+ *
+ * Updates the streaming song album name. Call this when an updated
+ * streaming song album name is received from the stream.
+ */
void
rb_streaming_source_set_streaming_album (RBStreamingSource *source,
const char *album)
@@ -471,4 +504,3 @@ playing_entry_changed_cb (RBShellPlayer *player,
g_object_unref (backend);
}
-
diff --git a/sources/rb-streaming-source.h b/sources/rb-streaming-source.h
index 9929eb6..e75f051 100644
--- a/sources/rb-streaming-source.h
+++ b/sources/rb-streaming-source.h
@@ -39,25 +39,27 @@ G_BEGIN_DECLS
#define RB_IS_STREAMING_SOURCE_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_STREAMING_SOURCE))
#define RB_STREAMING_SOURCE_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_STREAMING_SOURCE, RBStreamingSourceClass))
-typedef struct RBStreamingSourcePrivate RBStreamingSourcePrivate;
+typedef struct _RBStreamingSource RBStreamingSource;
+typedef struct _RBStreamingSourceClass RBStreamingSourceClass;
+typedef struct _RBStreamingSourcePrivate RBStreamingSourcePrivate;
-typedef struct
+struct _RBStreamingSource
{
RBSource parent;
RBStreamingSourcePrivate *priv;
-} RBStreamingSource;
+};
-typedef struct
+struct _RBStreamingSourceClass
{
RBSourceClass parent;
-} RBStreamingSourceClass;
+};
GType rb_streaming_source_get_type (void);
/* methods for subclasses */
void rb_streaming_source_get_progress (RBStreamingSource *source,
- char **progress_text,
+ char **text,
float *progress);
void rb_streaming_source_set_streaming_title (RBStreamingSource *source,
const char *title);
@@ -69,4 +71,3 @@ void rb_streaming_source_set_streaming_album (RBStreamingSource *source,
G_END_DECLS
#endif /* __RB_STREAMING_SOURCE_H */
-
diff --git a/tests/test-rhythmdb-tree-serialization.c b/tests/test-rhythmdb-tree-serialization.c
index d8420ee..f22dbc4 100644
--- a/tests/test-rhythmdb-tree-serialization.c
+++ b/tests/test-rhythmdb-tree-serialization.c
@@ -120,7 +120,7 @@ main (int argc, char **argv)
db = rhythmdb_tree_new ("test.xml");
- /**
+ /*
* TEST 1: Save with no entries
*/
g_print ("Test 1\n");
@@ -135,7 +135,7 @@ main (int argc, char **argv)
rhythmdb_read_unlock (db);
g_print ("Test 1: PASS\n");
- /**
+ /*
* TEST 2: Save with a single entry
*/
g_print ("Test 1\n");
@@ -149,7 +149,7 @@ main (int argc, char **argv)
rhythmdb_write_unlock (db);
- /**
+ /*
* THE END
*/
rhythmdb_shutdown (db);
diff --git a/widgets/rb-dialog.c b/widgets/rb-dialog.c
index 884f9af..a076806 100644
--- a/widgets/rb-dialog.c
+++ b/widgets/rb-dialog.c
@@ -45,6 +45,9 @@
/**
* SECTION:rb-dialog
* @short_description: helper functions for creating gtk+ dialog windows
+ *
+ * This provides a couple of shortcuts for creating dialogs. If you want
+ * to annoy the user by displaying an error message, this is the way to do it.
*/
/**
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
