GNOME.org
 

[rhythmbox] query-model: add gtk-doc

commit 772fd202a9eba07293111151097fb51e3b1a2619
Author: Jonathan Matthew <jonathan d14n org>
Date:   Fri Mar 19 07:11:15 2010 +1000

    query-model: add gtk-doc

 rhythmdb/rhythmdb-query-model.c |  390 ++++++++++++++++++++++++++++++++++++++-
 rhythmdb/rhythmdb-query-model.h |   14 +-
 2 files changed, 395 insertions(+), 9 deletions(-)
---
diff --git a/rhythmdb/rhythmdb-query-model.c b/rhythmdb/rhythmdb-query-model.c
index 344dd0b..b9d53fa 100644
--- a/rhythmdb/rhythmdb-query-model.c
+++ b/rhythmdb/rhythmdb-query-model.c
@@ -207,7 +207,7 @@ static const GtkTargetEntry rhythmdb_query_model_drag_types[] = {
 
 static GtkTargetList *rhythmdb_query_model_drag_target_list = NULL;
 
-struct RhythmDBQueryModelPrivate
+struct _RhythmDBQueryModelPrivate
 {
 	RhythmDB *db;
 
@@ -273,6 +273,39 @@ enum
 
 static guint rhythmdb_query_model_signals[LAST_SIGNAL] = { 0 };
 
+/**
+ * SECTION:rhythmdb-query-model
+ * @short_description: a #GtkTreeModel containing #RhythmDBEntry items
+ *
+ * A RhythmDBQueryModel contains an ordered set of #RhythmDBEntry items,
+ * either generated by running a query against the database, or populated
+ * by adding individual entries.
+ *
+ * All sources use a #RhythmDBQueryModel to provide their track listing.
+ * Since most sources provide a search or filtering capacity, there is
+ * usually a distinction between the source's base query model, which contains
+ * all entries for the source, and its current query model, which reflects
+ * the current search terms and filter selections.
+ *
+ * A RhythmDBQueryModel can be populated directly from the #RhythmDB, or it
+ * can be chained to another query model.  Chained query models inherit the
+ * set of entries from the query model they chain to and then restrict the
+ * set using a query.
+ *
+ * The query model consists of a #GSequence, which provides ordering of entries,
+ * and a #GHashTable, which allows efficient checks to see if a given entry
+ * is in the model.  A side effect of this is that an entry can only be placed
+ * into a query model in one location.
+ *
+ * In addition to the query, a #RhythmDBQueryModel can have a sort order and
+ * a limit, specified in terms of file size, duration, or number of entries.
+ * A query model can only have a limit if it also has a sort order, as the
+ * sort order is required to determine which entries fall inside the limit.
+ * When a limit is applied, entries that match the query but fall outside the
+ * limit are maintained in a separate #GSequence and #GHashTable inside the
+ * query model.
+ */
+
 static void
 rhythmdb_query_model_class_init (RhythmDBQueryModelClass *klass)
 {
@@ -347,7 +380,7 @@ rhythmdb_query_model_class_init (RhythmDBQueryModelClass *klass)
 					 PROP_SHOW_HIDDEN,
 					 g_param_spec_boolean ("show-hidden",
 							       "show hidden",
-							       "maximum time (seconds)",
+							       "if TRUE, include entries that are ordinarily hidden",
 							       FALSE,
 							       G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 	g_object_class_install_property (object_class,
@@ -358,6 +391,20 @@ rhythmdb_query_model_class_init (RhythmDBQueryModelClass *klass)
 							      RHYTHMDB_TYPE_QUERY_MODEL,
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT));
 
+	/**
+	 * RhythmDBQueryModel::entry-prop-changed:
+	 * @model: the #RhythmDBQueryModel
+	 * @entry: the #RhythmDBEntry that changed
+	 * @prop: the #RhythmDBPropType that was changed
+	 * @old: the previous value for the property
+	 * @new_value: the new value for the property
+	 *
+	 * Emitted when an entry in the query model is changed.  When multiple
+	 * properties are changed, the entry-prop-changed signals will be emitted
+	 * in the order that the changes were made.  At the point that the
+	 * signal is emitted, all changes have already been applied to the
+	 * #RhythmDBEntry.
+	 */
 	rhythmdb_query_model_signals[ENTRY_PROP_CHANGED] =
 		g_signal_new ("entry-prop-changed",
 			      RHYTHMDB_TYPE_QUERY_MODEL,
@@ -367,6 +414,15 @@ rhythmdb_query_model_class_init (RhythmDBQueryModelClass *klass)
 			      rb_marshal_VOID__BOXED_INT_POINTER_POINTER,
 			      G_TYPE_NONE,
 			      4, RHYTHMDB_TYPE_ENTRY, G_TYPE_INT, G_TYPE_POINTER, G_TYPE_POINTER);
+	/**
+	 * RhythmDBQueryModel::entry-removed:
+	 * @model: the #RhythmDBQueryModel
+	 * @entry: the #RhythmDBEntry that was removed
+	 *
+	 * Emitted when an entry is removed from the model.  There is some
+	 * difference between this and the #GtkTreeModel row-removed signal
+	 * but I don't know what it is right now.
+	 */
 	rhythmdb_query_model_signals[ENTRY_REMOVED] =
 		g_signal_new ("entry-removed",
 			      RHYTHMDB_TYPE_QUERY_MODEL,
@@ -376,6 +432,15 @@ rhythmdb_query_model_class_init (RhythmDBQueryModelClass *klass)
 			      g_cclosure_marshal_VOID__BOXED,
 			      G_TYPE_NONE,
 			      1, RHYTHMDB_TYPE_ENTRY);
+	/**
+	 * RhythmDBQueryModel::non-entry-dropped:
+	 * @model: the #RhythmDBQueryModel
+	 * @uri: the URI that was dropped
+	 * @position: the position in the query model at which it was dropped
+	 *
+	 * Emitted when a URI that does not match an existing #RhythmDBEntry
+	 * is dropped into the query model.
+	 */
 	rhythmdb_query_model_signals[NON_ENTRY_DROPPED] =
 		g_signal_new ("non-entry-dropped",
 			      RHYTHMDB_TYPE_QUERY_MODEL,
@@ -384,6 +449,12 @@ rhythmdb_query_model_class_init (RhythmDBQueryModelClass *klass)
 			      NULL, NULL,
 			      rb_marshal_VOID__POINTER_INT,
 			      G_TYPE_NONE, 2, G_TYPE_STRING, G_TYPE_INT);
+	/**
+	 * RhythmDBQueryModel::complete:
+	 * @model: the #RhythmDBQueryModel
+	 *
+	 * Emitted when the database query populating the model is complete.
+	 */
 	rhythmdb_query_model_signals[COMPLETE] =
 		g_signal_new ("complete",
 			      RHYTHMDB_TYPE_QUERY_MODEL,
@@ -392,6 +463,13 @@ rhythmdb_query_model_class_init (RhythmDBQueryModelClass *klass)
 			      NULL, NULL,
 			      g_cclosure_marshal_VOID__VOID,
 			      G_TYPE_NONE, 0);
+	/**
+	 * RhythmDBQueryModel::post-entry-delete:
+	 * @model: the #RhythmDBQueryModel
+	 * @entry: the #RhythmDBEntry that was removed
+	 *
+	 * Emitted after an entry has been removed from the model.
+	 */
 	rhythmdb_query_model_signals[POST_ENTRY_DELETE] =
 		g_signal_new ("post-entry-delete",
 			      RHYTHMDB_TYPE_QUERY_MODEL,
@@ -721,6 +799,20 @@ rhythmdb_query_model_finalize (GObject *object)
 	G_OBJECT_CLASS (rhythmdb_query_model_parent_class)->finalize (object);
 }
 
+/**
+ * rhythmdb_query_model_new:
+ * @db: the #RhythmDB
+ * @query: the query for the new model
+ * @sort_func: the sort function for the new model
+ * @sort_data: data to pass to the sort function
+ * @sort_data_destroy: function to call when destroying the sort data
+ * @sort_reverse: if %TRUE, reverse the sort order
+ *
+ * Constructs a new #RhythmDBQueryModel with the specified query and sorting
+ * parameters.
+ *
+ * Return value: the newly constructed query model
+ */
 RhythmDBQueryModel *
 rhythmdb_query_model_new (RhythmDB *db,
 			  GPtrArray *query,
@@ -742,6 +834,16 @@ rhythmdb_query_model_new (RhythmDB *db,
 	return model;
 }
 
+/**
+ * rhythmdb_query_model_new_empty:
+ * @db: the #RhythmDB
+ *
+ * Constructs a new empty query model with no query or sorting parameters.
+ * This should only be used when the query model will be populated by
+ * explicitly adding entries.
+ *
+ * Return value: the newly constructed query model
+ */
 RhythmDBQueryModel *
 rhythmdb_query_model_new_empty (RhythmDB *db)
 {
@@ -759,6 +861,13 @@ _copy_contents_foreach_cb (RhythmDBEntry *entry, RhythmDBQueryModel *dest)
 	}
 }
 
+/**
+ * rhythmdb_query_model_copy_contents:
+ * @dest: destination #RhythmDBQueryModel
+ * @src: source #RhythmDBQueryModel
+ *
+ * Copies all entries from @src to @dest.
+ */
 void
 rhythmdb_query_model_copy_contents (RhythmDBQueryModel *dest,
 				    RhythmDBQueryModel *src)
@@ -769,6 +878,16 @@ rhythmdb_query_model_copy_contents (RhythmDBQueryModel *dest,
 	g_sequence_foreach (src->priv->entries, (GFunc)_copy_contents_foreach_cb, dest);
 }
 
+/**
+ * rhythmdb_query_model_chain:
+ * @model: the #RhythmDBQueryModel to chain
+ * @base: the #RhythmDBQueryModel to chain it to
+ * @import_entries: if %TRUE, copy all existing entries from @base to @model
+ *
+ * Chains @model to @base.  All changes made to the base model will be reflected in
+ * the child model, and all changes made to the child model will be passed on to the
+ * base model.
+ */
 void
 rhythmdb_query_model_chain (RhythmDBQueryModel *model,
 			    RhythmDBQueryModel *base,
@@ -842,6 +961,15 @@ rhythmdb_query_model_chain (RhythmDBQueryModel *model,
 	}
 }
 
+/**
+ * rhythmdb_query_model_has_pending_changes:
+ * @model: a #RhythmDBQueryModel
+ *
+ * Checks if a #RhythmDBQueryModel has any outstanding changes that are
+ * yet to be processed.  This is not very useful.
+ *
+ * Return value: %TRUE if there are outstanding changes to the model
+ */
 gboolean
 rhythmdb_query_model_has_pending_changes (RhythmDBQueryModel *model)
 {
@@ -1093,6 +1221,15 @@ idle_process_update (struct RhythmDBQueryModelUpdate *update)
 	g_free (update);
 }
 
+/**
+ * rhythmdb_query_model_add_entry:
+ * @model: a #RhythmDBQueryModel
+ * @entry: a #RhythmDBEntry to add
+ * @index: position at which to add it, or -1 to add at the end
+ *
+ * Adds an entry to the query model at the specified position.  Does not check
+ * if the entry matches the query (if any).
+ */
 void
 rhythmdb_query_model_add_entry (RhythmDBQueryModel *model,
 				RhythmDBEntry *entry,
@@ -1128,12 +1265,28 @@ rhythmdb_query_model_add_entry (RhythmDBQueryModel *model,
 	rhythmdb_query_model_process_update (update);
 }
 
+/**
+ * rhythmdb_query_model_get_size:
+ * @model: the #RhythmDBQueryModel
+ *
+ * Returns the total size of all entries in the model.
+ *
+ * Return value: the total size (in bytes) of all entries in the model
+ */
 guint64
 rhythmdb_query_model_get_size (RhythmDBQueryModel *model)
 {
 	return model->priv->total_size;
 }
 
+/**
+ * rhythmdb_query_model_get_duration:
+ * @model: the #RhythmDBQueryModel
+ *
+ * Returns the total duration of all entries in the model.
+ *
+ * Return value: the total duration (in seconds) of all entries in the model
+ */
 long
 rhythmdb_query_model_get_duration (RhythmDBQueryModel *model)
 {
@@ -1508,6 +1661,12 @@ rhythmdb_query_model_filter_out_entry (RhythmDBQueryModel *model,
 	}
 }
 
+/**
+ * rhythmdb_query_model_shuffle_entries:
+ * @model: a #RhythmDBQueryModel
+ *
+ * Shuffles the entries in the model into a new random order.
+ */
 void
 rhythmdb_query_model_shuffle_entries (RhythmDBQueryModel *model)
 {
@@ -1565,6 +1724,16 @@ rhythmdb_query_model_shuffle_entries (RhythmDBQueryModel *model)
 	g_free (entries);
 }
 
+/**
+ * rhythmdb_query_model_move_entry:
+ * @model: a #RhythmDBQueryModel
+ * @entry: the #RhythmDBEntry to move
+ * @index: position to move to
+ *
+ * Moves an entry to a new position in the query model.
+ * The position must be a between 0 and the number of entries in the model.
+ * Specifying -1 does not move the entry to the end of the model.
+ */
 void
 rhythmdb_query_model_move_entry (RhythmDBQueryModel *model,
 				 RhythmDBEntry *entry,
@@ -1600,6 +1769,15 @@ rhythmdb_query_model_move_entry (RhythmDBQueryModel *model,
 	rhythmdb_query_model_emit_reorder (model, old_pos, index);
 }
 
+/**
+ * rhythmdb_query_model_remove_entry:
+ * @model: a #RhythmDBQueryModel
+ * @entry: the #RhythmDBEntry to remove
+ *
+ * Removes an entry from the query model.
+ *
+ * Return value: %TRUE if the entry was removed
+ */
 gboolean
 rhythmdb_query_model_remove_entry (RhythmDBQueryModel *model,
 				   RhythmDBEntry *entry)
@@ -1623,6 +1801,16 @@ rhythmdb_query_model_remove_entry (RhythmDBQueryModel *model,
 	return TRUE;
 }
 
+/**
+ * rhythmdb_query_model_entry_to_iter:
+ * @model: a #RhythmDBQueryModel
+ * @entry: the #RhythmDBEntry to look up
+ * @iter: holds the returned #GtkTreeIter
+ *
+ * Creates a #GtkTreeIter pointing to the specified entry in the model.
+ *
+ * Return value: %TRUE if the iterator now points to the entry
+ */
 gboolean
 rhythmdb_query_model_entry_to_iter (RhythmDBQueryModel *model,
 				    RhythmDBEntry *entry,
@@ -1643,6 +1831,16 @@ rhythmdb_query_model_entry_to_iter (RhythmDBQueryModel *model,
 	return TRUE;
 }
 
+/**
+ * rhythmdb_query_model_tree_path_to_entry:
+ * @model: a #RhythmDBQueryModel
+ * @path: a #GtkTreePath
+ *
+ * Locates the #RhythmDBEntry identified by the specified path in the model.
+ * The caller owns a reference to the returned entry.
+ *
+ * Return value: the #RhythmDBEntry, if any
+ */
 RhythmDBEntry *
 rhythmdb_query_model_tree_path_to_entry (RhythmDBQueryModel *model,
 					 GtkTreePath *path)
@@ -1653,6 +1851,16 @@ rhythmdb_query_model_tree_path_to_entry (RhythmDBQueryModel *model,
 	return rhythmdb_query_model_iter_to_entry (model, &entry_iter);
 }
 
+/**
+ * rhythmdb_query_model_iter_to_entry:
+ * @model: a #RhythmDBQueryModel
+ * @entry_iter: a #GtkTreeIter to dereference
+ *
+ * Locates and returns the #RhythmDBEntry pointed to by the specified iterator
+ * in the model.  The caller owns a reference to the returned entry.
+ *
+ * Return value: the #RhythmDBEntry, if any
+ */
 RhythmDBEntry *
 rhythmdb_query_model_iter_to_entry (RhythmDBQueryModel *model,
 				    GtkTreeIter *entry_iter)
@@ -1662,6 +1870,16 @@ rhythmdb_query_model_iter_to_entry (RhythmDBQueryModel *model,
 	return entry;
 }
 
+/**
+ * rhythmdb_query_model_get_next_from_entry:
+ * @model: a #RhythmDBQueryModel
+ * @entry: a #RhythmDBEntry
+ *
+ * Locates and returns the next #RhythmDBEntry in the model after the specified
+ * entry.  The caller owns a reference to the returned entry.
+ *
+ * Return value: the next #RhythmDBEntry in the model, if any
+ */
 RhythmDBEntry *
 rhythmdb_query_model_get_next_from_entry (RhythmDBQueryModel *model,
 					  RhythmDBEntry *entry)
@@ -1682,6 +1900,16 @@ rhythmdb_query_model_get_next_from_entry (RhythmDBQueryModel *model,
 	return rhythmdb_query_model_iter_to_entry (model, &iter);
 }
 
+/**
+ * rhythmdb_query_model_get_previous_from_entry:
+ * @model: a #RhythmDBQueryModel
+ * @entry: a #RhythmDBEntry
+ *
+ * Locates and returns the  #RhythmDBEntry in the model before the specified
+ * entry.  The caller owns a reference to the returned entry.
+ *
+ * Return value: the previous #RhythmDBEntry in the model, if any
+ */
 RhythmDBEntry *
 rhythmdb_query_model_get_previous_from_entry (RhythmDBQueryModel *model,
 					      RhythmDBEntry *entry)
@@ -2229,6 +2457,16 @@ rhythmdb_query_model_iter_parent (GtkTreeModel *tree_model,
 	return FALSE;
 }
 
+/**
+ * rhythmdb_query_model_compute_status_normal:
+ * @model: a #RhythmDBQueryModel
+ * @singular: singular form of the pattern describing the number of entries ("%d song")
+ * @plural: plural form of the pattern describing the number of entries ("%d songs")
+ *
+ * Constructs a status string describing the contents of the model.
+ *
+ * Return value: allocated status string, to be freed by the caller.
+ */
 char *
 rhythmdb_query_model_compute_status_normal (RhythmDBQueryModel *model,
 					    const char *singular,
@@ -2280,6 +2518,17 @@ apply_updated_entry_sequence (RhythmDBQueryModel *model,
 	g_free (reorder_map);
 }
 
+/**
+ * rhythmdb_query_model_set_sort_order:
+ * @model: a #RhythmDBQueryModel
+ * @sort_func: new sort function
+ * @sort_data: data to pass to the new sort function
+ * @sort_data_destroy: function to call to free the sort data
+ * @sort_reverse: if %TRUE, reverse the sort order
+ *
+ * Sets a new sort order on the model.  This reorders the entries
+ * in the model to match the new sort order.
+ */
 void
 rhythmdb_query_model_set_sort_order (RhythmDBQueryModel *model,
 				     GCompareDataFunc sort_func,
@@ -2525,6 +2774,20 @@ _reapply_query_foreach_cb (RhythmDBEntry *entry, _ReapplyQueryForeachData *data)
 	}
 }
 
+/**
+ * rhythmdb_query_model_reapply_query:
+ * @model: a #RhythmDBQueryModel
+ * @filter: if %FALSE, emit entry-removed signals
+ *
+ * Reapplies the existing query to the entries in the model.  This
+ * is mostly useful when the query contains relative time criteria
+ * (such as 'not played in the last hour').  This will only remove
+ * entries that are already in the model, it will not find entries
+ * that previously did not match the query.
+ *
+ * The 'filter' parameter should be set to TRUE when the query is
+ * being used as a filter, rather than to define a base set of entries.
+ */
 void
 rhythmdb_query_model_reapply_query (RhythmDBQueryModel *model,
 				    gboolean filter)
@@ -2579,6 +2842,16 @@ _reverse_sorting_func (gpointer a,
 	return - reverse_data->func (a, b, reverse_data->data);
 }
 
+/**
+ * rhythmdb_query_model_location_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by location.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_location_sort_func (RhythmDBEntry *a,
 					 RhythmDBEntry *b,
@@ -2601,6 +2874,17 @@ rhythmdb_query_model_location_sort_func (RhythmDBEntry *a,
 		return strcmp (a_val, b_val);
 }
 
+/**
+ * rhythmdb_query_model_title_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by title.  Falls back to sorting
+ * by location if the titles are the same.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_title_sort_func (RhythmDBEntry *a,
 				      RhythmDBEntry *b,
@@ -2610,7 +2894,6 @@ rhythmdb_query_model_title_sort_func (RhythmDBEntry *a,
 	const char *b_val;
 	gint ret;
 
-	/* Sort by album name */
 	a_val = rhythmdb_entry_get_string (a, RHYTHMDB_PROP_TITLE_SORT_KEY);
 	b_val = rhythmdb_entry_get_string (b, RHYTHMDB_PROP_TITLE_SORT_KEY);
 
@@ -2630,6 +2913,17 @@ rhythmdb_query_model_title_sort_func (RhythmDBEntry *a,
 		return rhythmdb_query_model_location_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_album_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by album.  Sorts by album, then
+ * disc number, then track number, then title.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_album_sort_func (RhythmDBEntry *a,
 				      RhythmDBEntry *b,
@@ -2693,6 +2987,17 @@ rhythmdb_query_model_album_sort_func (RhythmDBEntry *a,
 		return rhythmdb_query_model_location_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_artist_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by artist.  Sorts by artist, then
+ * album, then disc number, then track number, then title.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_artist_sort_func (RhythmDBEntry *a,
 				       RhythmDBEntry *b,
@@ -2727,6 +3032,17 @@ rhythmdb_query_model_artist_sort_func (RhythmDBEntry *a,
 		return rhythmdb_query_model_album_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_genre_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by genre.  Sorts by genre, then artist,
+ * then album, then disc number, then track number, then title.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_genre_sort_func (RhythmDBEntry *a, RhythmDBEntry *b,
 				      gpointer data)
@@ -2754,6 +3070,17 @@ rhythmdb_query_model_genre_sort_func (RhythmDBEntry *a, RhythmDBEntry *b,
 		return rhythmdb_query_model_artist_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_track_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by track.  Sorts by artist,
+ * then album, then disc number, then track number, then title.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_track_sort_func (RhythmDBEntry *a,
 				      RhythmDBEntry *b,
@@ -2762,6 +3089,18 @@ rhythmdb_query_model_track_sort_func (RhythmDBEntry *a,
 	return rhythmdb_query_model_album_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_double_ceiling_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: property to sort on
+ *
+ * Sort function for sorting by a rounded floating point value.
+ * The property value is rounded up to an integer value for sorting.
+ * If the values are the same, falls back to sorting by location.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_double_ceiling_sort_func (RhythmDBEntry *a,
 					       RhythmDBEntry *b,
@@ -2781,6 +3120,17 @@ rhythmdb_query_model_double_ceiling_sort_func (RhythmDBEntry *a,
 		return rhythmdb_query_model_location_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_ulong_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: property to sort on
+ *
+ * Sort function for sorting by an unsigned integer property value.
+ * If the values are the same, falls back to sorting by location.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_ulong_sort_func (RhythmDBEntry *a,
 				      RhythmDBEntry *b,
@@ -2799,6 +3149,18 @@ rhythmdb_query_model_ulong_sort_func (RhythmDBEntry *a,
 		return rhythmdb_query_model_location_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_bitrate_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by bitrate.  Lossless encodings (as identified
+ * by media type) are considered to have the highest possible bitrate.
+ * Falls back to sorting by location for equal bitrates.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_bitrate_sort_func (RhythmDBEntry *a,
 					RhythmDBEntry *b,
@@ -2825,6 +3187,17 @@ rhythmdb_query_model_bitrate_sort_func (RhythmDBEntry *a,
 		return rhythmdb_query_model_location_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_date_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: nothing
+ *
+ * Sort function for sorting by release date.
+ * Falls back to album sort order for equal dates.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_date_sort_func (RhythmDBEntry *a,
 				     RhythmDBEntry *b,
@@ -2846,6 +3219,17 @@ rhythmdb_query_model_date_sort_func (RhythmDBEntry *a,
 		return rhythmdb_query_model_album_sort_func (a, b, data);
 }
 
+/**
+ * rhythmdb_query_model_string_sort_func:
+ * @a: a #RhythmDBEntry
+ * @b: a #RhythmDBEntry
+ * @data: property to sort on
+ *
+ * Sort function for sorting by a single string property
+ * Falls back to location sort order if the strings are equal.
+ *
+ * Returns: result of sort comparison between a and b.
+ */
 gint
 rhythmdb_query_model_string_sort_func (RhythmDBEntry *a,
 				       RhythmDBEntry *b,
diff --git a/rhythmdb/rhythmdb-query-model.h b/rhythmdb/rhythmdb-query-model.h
index dcec85b..7ee1ab6 100644
--- a/rhythmdb/rhythmdb-query-model.h
+++ b/rhythmdb/rhythmdb-query-model.h
@@ -54,18 +54,20 @@ typedef enum {
 	RHYTHMDB_QUERY_MODEL_LIMIT_TIME,
 } RhythmDBQueryModelLimitType;
 
-typedef struct RhythmDBQueryModelPrivate RhythmDBQueryModelPrivate;
+typedef struct _RhythmDBQueryModel RhythmDBQueryModel;
+typedef struct _RhythmDBQueryModelClass RhythmDBQueryModelClass;
+typedef struct _RhythmDBQueryModelPrivate RhythmDBQueryModelPrivate;
 
 #define RHYTHMDB_QUERY_MODEL_SUGGESTED_UPDATE_CHUNK 1024
 
-typedef struct
+struct _RhythmDBQueryModel
 {
 	GObject parent;
 
 	RhythmDBQueryModelPrivate *priv;
-} RhythmDBQueryModel;
+};
 
-typedef struct
+struct _RhythmDBQueryModelClass
 {
 	GObjectClass parent;
 
@@ -86,7 +88,7 @@ typedef struct
 	gboolean (*filter_entry_drop)	(RhythmDBQueryModel *model,
 					 RhythmDBEntry *entry);
 
-} RhythmDBQueryModelClass;
+};
 
 GType			rhythmdb_query_model_get_type		(void);
 
@@ -102,7 +104,7 @@ RhythmDBQueryModel *	rhythmdb_query_model_new_empty		(RhythmDB *db);
 void			rhythmdb_query_model_copy_contents	(RhythmDBQueryModel *dest,
 								 RhythmDBQueryModel *src);
 
-void			rhythmdb_query_model_chain		(RhythmDBQueryModel *child,
+void			rhythmdb_query_model_chain		(RhythmDBQueryModel *model,
 								 RhythmDBQueryModel *base,
 								 gboolean import_entries);
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]