GNOME.org
 

rhythmbox r5657 - in trunk: . doc/reference lib metadata rhythmdb sources

Author: jmatthew
Date: Sun Mar 30 14:20:38 2008
New Revision: 5657
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5657&view=rev

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

	* lib/rb-tree-dnd.c: (remove_select_on_drag_timeout),
	(rb_tree_dnd_add_drag_dest_support):
	* metadata/rb-metadata-common.c:
	* metadata/rb-metadata-dbus-client.c: (rb_metadata_get):
	* metadata/rb-metadata.h:
	* rhythmdb/rhythmdb-query-results.c:
	* sources/rb-source-group.c:
	* doc/reference/rhythmbox-sections.txt:
	Add/fix gtk-doc for tree drag and drop stuff, RBMetaData,
	RhythmDBQueryResults, RBSourceGroup.


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/lib/rb-tree-dnd.c
   trunk/metadata/rb-metadata-common.c
   trunk/metadata/rb-metadata-dbus-client.c
   trunk/metadata/rb-metadata.h
   trunk/rhythmdb/rhythmdb-query-results.c
   trunk/sources/rb-source-group.c

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Sun Mar 30 14:20:38 2008
@@ -20,10 +20,6 @@
 
 <SECTION>
 <FILE>rb-tree-dnd</FILE>
-RB_TYPE_TREE_DRAG_DEST
-RB_TREE_DRAG_DEST
-RB_IS_TREE_DRAG_DEST
-RB_TREE_DRAG_DEST_GET_IFACE
 RbTreeDragSource
 RbTreeDragSourceIface
 RbTreeDragDest
@@ -32,7 +28,6 @@
 rb_tree_drag_source_row_draggable
 rb_tree_drag_source_drag_data_delete
 rb_tree_drag_source_drag_data_get
-rb_tree_drag_dest_get_type
 rb_tree_drag_dest_drag_data_received
 rb_tree_drag_dest_row_drop_possible
 rb_tree_drag_dest_row_drop_position
@@ -44,13 +39,20 @@
 RB_TYPE_TREE_DRAG_SOURCE
 rb_tree_drag_source_get_type
 RB_TREE_DRAG_SOURCE_GET_IFACE
+RB_TYPE_TREE_DRAG_DEST
+RB_TREE_DRAG_DEST
+RB_IS_TREE_DRAG_DEST
+RB_TREE_DRAG_DEST_GET_IFACE
+rb_tree_drag_dest_get_type
 </SECTION>
 
 <SECTION>
 <FILE>rb-metadata</FILE>
+<TITLE>RBMetaData</TITLE>
+RBMetaData
+RBMetaDataClass
 RBMetaDataField
 RBMetaDataError
-RBMetaDataPrivate
 rb_metadata_new
 rb_metadata_get_field_type
 rb_metadata_get_field_name
@@ -73,6 +75,7 @@
 RB_METADATA_GET_CLASS
 RB_METADATA_ERROR
 rb_metadata_error_quark
+RBMetaDataPrivate
 </SECTION>
 
 <SECTION>
@@ -648,6 +651,7 @@
 _rb_source_show_popup
 _rb_source_register_action_group
 <SUBSECTION Standard>
+RBSourcePrivate
 RB_SOURCE
 RB_IS_SOURCE
 RB_TYPE_SOURCE
@@ -2126,6 +2130,7 @@
 
 <SECTION>
 <FILE>rhythmdb-query-results</FILE>
+<TITLE>RhythmDBQueryResults</TITLE>
 RhythmDBQueryResults
 RhythmDBQueryResultsIface
 rhythmdb_query_results_set_query
@@ -2378,10 +2383,9 @@
 
 <SECTION>
 <FILE>rb-source-group</FILE>
+<TITLE>RBSourceGroup</TITLE>
 RBSourceGroupCategory
-RB_TYPE_SOURCE_GROUP_CATEGORY
 RBSourceGroup
-rb_source_group_get_type
 RB_SOURCE_GROUP_LIBRARY
 RB_SOURCE_GROUP_PLAYLISTS
 RB_SOURCE_GROUP_DEVICES
@@ -2397,6 +2401,8 @@
 RB_SOURCE_GROUP
 RB_IS_SOURCE_GROUP
 RB_TYPE_SOURCE_GROUP
+rb_source_group_get_type
+RB_TYPE_SOURCE_GROUP_CATEGORY
 rb_source_group_category_get_type
 </SECTION>
 

Modified: trunk/lib/rb-tree-dnd.c
==============================================================================
--- trunk/lib/rb-tree-dnd.c	(original)
+++ trunk/lib/rb-tree-dnd.c	Sun Mar 30 14:20:38 2008
@@ -33,6 +33,26 @@
 /* must be the same value as in gtk_tree_view.c */
 #define SCROLL_EDGE_SIZE 15
 
+
+/**
+ * SECTION:rb-tree-dnd
+ * @short_description: multi-row drag and drop support for GtkTreeViews
+ *
+ * Provides support for drag and drop operations to and from GtkTreeView
+ * widgets that can include multiple rows.  The model backing the tree view
+ * widgets must implement the #RbTreeDragSource and #RbTreeDragDest interfaces.
+ */
+
+/**
+ * RbTreeDestFlag:
+ * @RB_TREE_DEST_EMPTY_VIEW_DROP: If set, drops into empty spaces in the view are accepted
+ * @RB_TREE_DEST_CAN_DROP_INTO: If set, drops into existing rows are accepted
+ * @RB_TREE_DEST_CAN_DROP_BETWEEN: If set, drops between existing rows are accepted
+ * @RB_TREE_DEST_SELECT_ON_DRAG_TIMEOUT: If set, update the drag selection using a timeout
+ *
+ * Flags controlling drag destination behaviour.
+ */
+
 typedef struct
 {
   guint pressed_button;
@@ -66,8 +86,8 @@
   guint select_on_drag_timeout;
 } RbTreeDndData;
 
-RbTreeDndData *init_rb_tree_dnd_data (GtkWidget *widget);
-GList * get_context_data (GdkDragContext *context);
+static RbTreeDndData *init_rb_tree_dnd_data (GtkWidget *widget);
+static GList * get_context_data (GdkDragContext *context);
 static gboolean filter_drop_position (GtkWidget *widget, GdkDragContext *context, GtkTreePath *path, GtkTreeViewDropPosition *pos);
 static gint scroll_row_timeout (gpointer data);
 static gboolean select_on_drag_timeout (gpointer data);
@@ -103,10 +123,10 @@
 
 /**
  * rb_tree_drag_source_row_draggable:
- * @drag_source: a #EggTreeMultiDragSource
+ * @drag_source: a #RbTreeDragSource
  * @path_list: row on which user is initiating a drag
  *
- * Asks the #EggTreeMultiDragSource whether a particular row can be used as
+ * Asks the #RbTreeDragSource whether a particular row can be used as
  * the source of a DND operation. If the source doesn't implement
  * this interface, the row is assumed draggable.
  *
@@ -114,7 +134,7 @@
  **/
 gboolean
 rb_tree_drag_source_row_draggable (RbTreeDragSource *drag_source,
-				   GList                  *path_list)
+				   GList            *path_list)
 {
   RbTreeDragSourceIface *iface = RB_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
 
@@ -131,10 +151,10 @@
 
 /**
  * rb_tree_drag_source_drag_data_delete:
- * @drag_source: a #EggTreeMultiDragSource
+ * @drag_source: a #RbTreeDragSource
  * @path_list: row that was being dragged
  *
- * Asks the #EggTreeMultiDragSource to delete the row at @path, because
+ * Asks the #RbTreeDragSource to delete the row at @path, because
  * it was moved somewhere else via drag-and-drop. Returns %FALSE
  * if the deletion fails because @path no longer exists, or for
  * some model-specific reason. Should robustly handle a @path no
@@ -144,7 +164,7 @@
  **/
 gboolean
 rb_tree_drag_source_drag_data_delete (RbTreeDragSource *drag_source,
-					     GList                  *path_list)
+				      GList            *path_list)
 {
   RbTreeDragSourceIface *iface = RB_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
 
@@ -157,11 +177,11 @@
 
 /**
  * rb_tree_drag_source_drag_data_get:
- * @drag_source: a #EggTreeMultiDragSource
+ * @drag_source: a #RbTreeDragSource
  * @path_list: row that was dragged
- * @selection_data: a #EggSelectionData to fill with data from the dragged row
+ * @selection_data: a #GtkSelectionData to fill with data from the dragged row
  *
- * Asks the #EggTreeMultiDragSource to fill in @selection_data with a
+ * Asks the #RbTreeDragSource to fill in @selection_data with a
  * representation of the row at @path. @selection_data->target gives
  * the required type of the data.  Should robustly handle a @path no
  * longer found in the model!
@@ -170,8 +190,8 @@
  **/
 gboolean
 rb_tree_drag_source_drag_data_get    (RbTreeDragSource *drag_source,
-					     GList                  *path_list,
-					     GtkSelectionData  *selection_data)
+				      GList            *path_list,
+				      GtkSelectionData *selection_data)
 {
   RbTreeDragSourceIface *iface = RB_TREE_DRAG_SOURCE_GET_IFACE (drag_source);
 
@@ -212,7 +232,17 @@
 }
 
 
-
+/**
+ * rb_tree_drag_dest_drag_data_received:
+ * @drag_dest: a #RbTreeDragDest
+ * @dest: the #GtkTreePath on which the data was dropped
+ * @pos: the drop position relative to the row identified by @dest
+ * @selection_data: a #GtkSelectionData containing the drag data
+ *
+ * Asks a #RbTreeDragDest to accept some drag and drop data.
+ *
+ * Return value: %TRUE if the data was accepted, %FALSE otherwise
+ */
 gboolean
 rb_tree_drag_dest_drag_data_received (RbTreeDragDest   *drag_dest,
 				      GtkTreePath       *dest,
@@ -229,7 +259,18 @@
 }
 
 
-
+/**
+ * rb_tree_drag_dest_row_drop_possible:
+ * @drag_dest: a #RbTreeDragDest
+ * @dest_path: the #GtkTreePath on which the data may be dropped
+ * @pos: the drop position relative to the row identified by @dest
+ * @selection_data: a #GtkSelectionData containing the drag data
+ *
+ * Asks the #RbTreeDragDest whether data can be dropped on a particular
+ * row.  This should probably check based on the format and the row.
+ *
+ * Return value: %TRUE if the data can be dropped there
+ */
 gboolean
 rb_tree_drag_dest_row_drop_possible (RbTreeDragDest   *drag_dest,
 				     GtkTreePath       *dest_path,
@@ -246,6 +287,20 @@
 }
 
 
+/**
+ * rb_tree_drag_dest_row_drop_position:
+ * @drag_dest: a #RbTreeDragDest
+ * @dest_path: a #GtkTreePath describing a possible drop row
+ * @targets: a #GList containing possible drop target types
+ * @pos: returns the #GtkTreeViewDropPosition to use relative to the row
+ *
+ * Asks the #RbTreeDragDest which drop position to use relative to the specified row.
+ * The drag destination should decide which drop position to use based on the 
+ * target row and the list of drag targets.
+ *
+ * Return value: %TRUE if a drop position has been set, %FALSE if a drop should not be
+ *   allowed in the specified row
+ */
 gboolean
 rb_tree_drag_dest_row_drop_position (RbTreeDragDest   *drag_dest,
 				     GtkTreePath       *dest_path,
@@ -277,7 +332,7 @@
   g_free (priv_data);
 }
 
-RbTreeDndData *
+static RbTreeDndData *
 init_rb_tree_dnd_data (GtkWidget *widget)
 {
 	RbTreeDndData *priv_data;
@@ -369,13 +424,13 @@
 	rb_debug ("Setting path_list: index=%i", gtk_tree_path_get_indices(path_list->data)[0]);
 }
 
-GList *
+static GList *
 get_context_data (GdkDragContext *context)
 {
 	return g_object_get_data (G_OBJECT (context), "rb-tree-view-multi-source-row");
 }
 
-gboolean
+static gboolean
 filter_drop_position (GtkWidget *widget, GdkDragContext *context, GtkTreePath *path, GtkTreeViewDropPosition *pos)
 {
 	GtkTreeView *tree_view = GTK_TREE_VIEW (widget);
@@ -506,7 +561,7 @@
 
 static void
 remove_select_on_drag_timeout (GtkTreeView *tree_view)
- {
+{
 	RbTreeDndData *priv_data;
 
 	priv_data = g_object_get_data (G_OBJECT (tree_view), RB_TREE_DND_STRING);
@@ -904,13 +959,25 @@
 	return FALSE;
 }
 
-
+/**
+ * rb_tree_dnd_add_drag_source_support:
+ * @tree_view: a #GtkTreeView that wants to be a drag source
+ * @start_button_mask: a mask describing modifier keys to handle when dragging
+ * @targets: an array of #GtkTargetEntry structures describing drag data types
+ * @n_targets: the number of elements in @targets
+ * @actions: a mask describing drag actions that are allowed from this source
+ *
+ * Adds event handlers to perform multi-row drag and drop operations from the
+ * specified #GtkTreeView widget.  The model backing the #GtkTreeView must
+ * implement the #RbTreeDragSource interface.  This should be called immediately
+ * after the tree view is created.
+ */
 void
 rb_tree_dnd_add_drag_source_support (GtkTreeView *tree_view,
-				 GdkModifierType start_button_mask,
-				 const GtkTargetEntry *targets,
-				 gint n_targets,
-				 GdkDragAction actions)
+				     GdkModifierType start_button_mask,
+				     const GtkTargetEntry *targets,
+				     gint n_targets,
+				     GdkDragAction actions)
 {
 	RbTreeDndData *priv_data = NULL;
  	g_return_if_fail (GTK_IS_TREE_VIEW (tree_view));
@@ -938,16 +1005,24 @@
 	}
 }
 
-
-
-
-
+/**
+ * rb_tree_dnd_add_drag_dest_support:
+ * @tree_view: a #GtkTreeView that wants to be a drag destination
+ * @flags: #RbTreeDestFlags for this drag destination
+ * @targets: an array of #GtkTargetEntry structures describing the allowed drag targets
+ * @n_targets: the number of elements in @targets
+ * @actions: the allowable drag actions for this destination
+ *
+ * Adds event handlers to perform multi-row drag and drop operations to the specified
+ * #GtkTreeView.  The model backing the tree view should implement the #RbTreeDragDest
+ * interface.  This should be called immediately after the tree view is created.
+ */
 void
 rb_tree_dnd_add_drag_dest_support (GtkTreeView *tree_view,
-			       RbTreeDestFlag flags,
-			       const GtkTargetEntry *targets,
-			       gint n_targets,
-			       GdkDragAction actions)
+				   RbTreeDestFlag flags,
+				   const GtkTargetEntry *targets,
+				   gint n_targets,
+				   GdkDragAction actions)
 {
 	RbTreeDndData *priv_data = NULL;
 	g_return_if_fail (GTK_IS_TREE_VIEW (tree_view));
@@ -980,7 +1055,8 @@
 								 NULL);
 	  	priv_data->drag_data_received_handler = g_signal_connect (G_OBJECT (tree_view),
 									  "drag_data_received",
-									  G_CALLBACK (rb_tree_dnd_drag_data_received_cb), 										  NULL);
+									  G_CALLBACK (rb_tree_dnd_drag_data_received_cb),
+									  NULL);
 	}
-
 }
+

Modified: trunk/metadata/rb-metadata-common.c
==============================================================================
--- trunk/metadata/rb-metadata-common.c	(original)
+++ trunk/metadata/rb-metadata-common.c	Sun Mar 30 14:20:38 2008
@@ -69,6 +69,50 @@
 
 };
 
+/**
+ * RBMetaDataField:
+ * @RB_METADATA_FIELD_TITLE: Title of the recording
+ * @RB_METADATA_FIELD_ARTIST: Person(s) responsible for the recording
+ * @RB_METADATA_FIELD_ALBUM: Album containing the recording
+ * @RB_METADATA_FIELD_DATE: Release date of the album
+ * @RB_METADATA_FIELD_GENRE: Genre of the recording
+ * @RB_METADATA_FIELD_COMMENT: Free form comment on the recording
+ * @RB_METADATA_FIELD_TRACK_NUMBER: Track number inside a collection
+ * @RB_METADATA_FIELD_MAX_TRACK_NUMBER: Count of tracks inside the collection
+ * @RB_METADATA_FIELD_DISC_NUMBER: Disc number inside a collection
+ * @RB_METADATA_FIELD_MAX_DISC_NUMBER: Count of discs inside the collection
+ * @RB_METADATA_FIELD_DESCRIPTION: Short text describing the recording
+ * @RB_METADATA_FIELD_VERSION: Version of the recording
+ * @RB_METADATA_FIELD_ISRC: International Standard Recording Code
+ * @RB_METADATA_FIELD_ORGANIZATION: Organization responsible for the recording
+ * @RB_METADATA_FIELD_COPYRIGHT: Copyright notice on the recording
+ * @RB_METADATA_FIELD_CONTACT: Contact information
+ * @RB_METADATA_FIELD_LICENSE: License of the recording
+ * @RB_METADATA_FIELD_PERFORMER: Person(s) performing in the recording
+ * @RB_METADATA_FIELD_DURATION: Duration of the recording
+ * @RB_METADATA_FIELD_CODEC: Codec used to store the recording
+ * @RB_METADATA_FIELD_BITRATE: Exact or average encoding bitrate in bits/s
+ * @RB_METADATA_FIELD_TRACK_GAIN: Track gain in dB for replaygain
+ * @RB_METADATA_FIELD_TRACK_PEAK: Track peak volume level
+ * @RB_METADATA_FIELD_ALBUM_GAIN: Album gain in dB for replaygain
+ * @RB_METADATA_FIELD_ALBUM_PEAK: Album peak volume level
+ * @RB_METADATA_FIELD_LANGUAGE_CODE: Language code (ISO-639-1)
+ * @RB_METADATA_FIELD_MUSICBRAINZ_TRACKID: MusicBrainz track ID
+ * @RB_METADATA_FIELD_MUSICBRAINZ_ARTISTID: MusicBrainz artist ID
+ * @RB_METADATA_FIELD_MUSICBRAINZ_ALBUMID: MusicBrainz album ID
+ * @RB_METADATA_FIELD_MUSICBRAINZ_ALBUMARTISTID: MusicBrainz album artist ID
+ * @RB_METADATA_FIELD_ARTIST_SORTNAME: Person(s) responsible for the recording, as used for sorting
+ * @RB_METADATA_FIELD_LAST:  invalid field
+ *
+ * Metadata fields that can be read from and written to files.
+ */
+
+/**
+ * rb_metadata_get_field_type:
+ * @field: a #RBMetaDataField
+ *
+ * Return value: the #GType of the value for the metadata field
+ */
 GType
 rb_metadata_get_field_type (RBMetaDataField field)
 {
@@ -76,6 +120,12 @@
 	return field_info[field].type;
 }
 
+/**
+ * rb_metadata_get_field_name:
+ * @field: a #RBMetaDataField
+ *
+ * Return value: the name of the metadata field
+ */
 const char *
 rb_metadata_get_field_name (RBMetaDataField field)
 {

Modified: trunk/metadata/rb-metadata-dbus-client.c
==============================================================================
--- trunk/metadata/rb-metadata-dbus-client.c	(original)
+++ trunk/metadata/rb-metadata-dbus-client.c	Sun Mar 30 14:20:38 2008
@@ -38,6 +38,14 @@
  * we actually send it the request.
  */
 
+/**
+ * SECTION:rb-metadata
+ * @short_description: metadata reader and writer interface
+ *
+ * Provides a simple synchronous interface for metadata extraction and updating.
+ *
+ */
+
 #include <config.h>
 
 #include "rb-metadata.h"
@@ -111,6 +119,11 @@
 	G_OBJECT_CLASS (rb_metadata_parent_class)->finalize (object);
 }
 
+/**
+ * rb_metadata_new:
+ *
+ * Return value: new #RBMetaData instance
+ */
 RBMetaData *
 rb_metadata_new (void)
 {
@@ -322,6 +335,17 @@
 	g_free (error_message);
 }
 
+/**
+ * rb_metadata_load:
+ * @md: a #RBMetaData
+ * @uri: URI from which to load metadata
+ * @error: returns error information
+ *
+ * Reads metadata information from the specified URI.
+ * Once this has returned successfully (with *error == NULL),
+ * rb_metadata_get, rb_metadata_get_mime, rb_metadata_has_missing_plugins,
+ * and rb_metadata_get_missing_plugins can usefully be called.
+ */
 void
 rb_metadata_load (RBMetaData *md,
 		  const char *uri,
@@ -458,18 +482,50 @@
 	g_static_mutex_unlock (&conn_mutex);
 }
 
+/**
+ * rb_metadata_get_mime:
+ * @md: a #RBMetaData
+ *
+ * Returns the type of the file from which metadata was read.
+ * This isn't really a MIME type, but it looks like one.
+ *
+ * Return value: MIME type-ish string
+ */
 const char *
 rb_metadata_get_mime (RBMetaData *md)
 {
 	return md->priv->mimetype;
 }
 
+/**
+ * rb_metadata_has_missing_plugins:
+ * @md: a #RBMetaData
+ *
+ * If the metadata reader could not decode the file it was asked to
+ * because one or more media framework plugins (specifically, for the
+ * existing implementations, GStreamer plugins) required are missing,
+ * this will return TRUE.
+ *
+ * Return value: TRUE if required plugins are missing
+ */
 gboolean
 rb_metadata_has_missing_plugins (RBMetaData *md)
 {
 	return (md->priv->missing_plugins != NULL);
 }
 
+/**
+ * rb_metadata_get_missing_plugins:
+ * @md: a #RBMetaData
+ * @missing_plugins: returns machine-readable missing plugin information
+ * @plugin_descriptions: returns human-readable missing plugin descriptions
+ *
+ * This function returns the information used to request automatic
+ * installation of media framework plugins required to decode the target URI.
+ * Use g_strfreev() to free the returned information arrays.
+ *
+ * Return value: TRUE if missing plugin information was returned
+ */
 gboolean
 rb_metadata_get_missing_plugins (RBMetaData *md,
 				 char ***missing_plugins,
@@ -485,9 +541,19 @@
 }
 
 
+/**
+ * rb_metadata_get:
+ * @md: a #RBMetaData
+ * @field: the #RBMetaDataField to retrieve
+ * @val: returns the field value
+ *
+ * Retrieves the value of a metadata field extracted from the target URI.
+ * If the target URI contained no value for the field, returns FALSE.
+ *
+ * Return value: TRUE if a value was returned
+ */
 gboolean
-rb_metadata_get (RBMetaData *md, RBMetaDataField field,
-		 GValue *ret)
+rb_metadata_get (RBMetaData *md, RBMetaDataField field, GValue *ret)
 {
 	GValue *val;
 	if (!md->priv->metadata)
@@ -502,6 +568,17 @@
 	return FALSE;
 }
 
+/**
+ * rb_metadata_set:
+ * @md: a #RBMetaData
+ * @field: the #RBMetaDataField to set
+ * @val: the vaule to set
+ *
+ * Sets a metadata field value.  The value is only stored inside the
+ * #RBMetaData object until rb_metadata_save is called.
+ *
+ * Return value: TRUE if the field is valid
+ */
 gboolean
 rb_metadata_set (RBMetaData *md, RBMetaDataField field,
 		 const GValue *val)
@@ -521,6 +598,16 @@
 	return TRUE;
 }
 
+/**
+ * rb_metadata_can_save:
+ * @md: a #RBMetaData
+ * @mimetype: the MIME type-ish string to check
+ *
+ * Checks if the metadata writer is capable of updating file metadata
+ * for a given media type.
+ *
+ * Return value: TRUE if the file metadata for the given media type can be updated
+ */
 gboolean
 rb_metadata_can_save (RBMetaData *md, const char *mimetype)
 {
@@ -573,6 +660,14 @@
 	return can_save;
 }
 
+/**
+ * rb_metadata_save:
+ * @md: a #RBMetaData
+ * @error: returns error information
+ *
+ * Saves all metadata changes made with rb_metadata_set to the
+ * target URI.
+ */
 void
 rb_metadata_save (RBMetaData *md, GError **error)
 {

Modified: trunk/metadata/rb-metadata.h
==============================================================================
--- trunk/metadata/rb-metadata.h	(original)
+++ trunk/metadata/rb-metadata.h	Sun Mar 30 14:20:38 2008
@@ -89,19 +89,22 @@
 #define RB_IS_METADATA_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_METADATA))
 #define RB_METADATA_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_METADATA, RBMetaDataClass))
 
+typedef struct _RBMetaData RBMetaData;
+typedef struct _RBMetaDataClass RBMetaDataClass;
+
 typedef struct RBMetaDataPrivate RBMetaDataPrivate;
 
-typedef struct
+struct _RBMetaData
 {
 	GObject parent;
 
 	RBMetaDataPrivate *priv;
-} RBMetaData;
+};
 
-typedef struct
+struct _RBMetaDataClass
 {
 	GObjectClass parent_class;
-} RBMetaDataClass;
+};
 
 GType		rb_metadata_get_type	(void);
 

Modified: trunk/rhythmdb/rhythmdb-query-results.c
==============================================================================
--- trunk/rhythmdb/rhythmdb-query-results.c	(original)
+++ trunk/rhythmdb/rhythmdb-query-results.c	Sun Mar 30 14:20:38 2008
@@ -22,6 +22,17 @@
 
 #include "rhythmdb-query-results.h"
 
+/**
+ * SECTION:rhythmdb-query-results
+ * @short_description: interface for receiving query results from RhythmDB
+ *
+ * This is the interface that #RhythmDB uses to report results of database
+ * queries.  When running a query, it first calls rhythmdb_query_results_set_query,
+ * then passes entries matching the query to rhythmdb_query_results_add_results
+ * in batches, and finally calls rhythmdb_query_results_query_complete.
+ * There are no guarantees as to which threads the calls are made from.
+ */
+
 GType
 rhythmdb_query_results_get_type (void)
 {
@@ -46,6 +57,16 @@
 	return our_type;
 }
 
+/**
+ * rhythmdb_query_results_set_query:
+ * @results: the #RhythmDBQueryResults implementation
+ * @query: the new query
+ *
+ * When a new query is run, this method is invoked to give the
+ * object implementing this interface a chance to take a copy of the
+ * query criteria, so that it can evaluate the query for newly added
+ * or changed entries once the query is complete.
+ */
 void
 rhythmdb_query_results_set_query (RhythmDBQueryResults *results,
 				  GPtrArray *query)
@@ -55,6 +76,14 @@
 		iface->set_query (results, query);
 }
 
+/**
+ * rhythmdb_query_results_add_results:
+ * @results: the #RhythmDBQueryResults implementation
+ * @entries: #GPtrArray containing #RhythmDBEntry results
+ *
+ * Provides a new set of query results.  References must be taken on the
+ * entries.
+ */
 void
 rhythmdb_query_results_add_results (RhythmDBQueryResults *results,
 				    GPtrArray *entries)
@@ -64,6 +93,16 @@
 		iface->add_results (results, entries);
 }
 
+/**
+ * rhythmdb_query_results_query_complete:
+ * @results: the #RhythmDBQueryResults
+ *
+ * Called when the query is complete and all entries that match the query
+ * have been supplied to rhythmdb_query_results_add_results.  If the object
+ * implementing this interface needs to identify newly added or changed entries
+ * that match the query, it needs to use the entry-added, entry-deleted and
+ * entry-changed signals from #RhythmDB.
+ */
 void
 rhythmdb_query_results_query_complete (RhythmDBQueryResults *results)
 {

Modified: trunk/sources/rb-source-group.c
==============================================================================
--- trunk/sources/rb-source-group.c	(original)
+++ trunk/sources/rb-source-group.c	Sun Mar 30 14:20:38 2008
@@ -29,6 +29,16 @@
 
 #include "rb-source-group.h"
 
+/**
+ * SECTION:rb-source-group
+ * @short_description: Source list grouping
+ *
+ * Source groups define sections of the source list.  A source group
+ * consists of an internal name, a display name, and a category.
+ * The internal name can be used to locate a registered source group.
+ * The category is used to sort the source groups.
+ */
+
 G_LOCK_DEFINE_STATIC (source_groups);
 
 static GHashTable *source_groups_map;
@@ -47,6 +57,11 @@
 	shared_group = rb_source_group_register ("shared", _("Shared"), RB_SOURCE_GROUP_CATEGORY_TRANSIENT);
 }
 
+/**
+ * rb_source_group_init:
+ *
+ * Initializes source groups.
+ */
 void
 rb_source_group_init (void)
 {
@@ -73,6 +88,17 @@
 	return type;
 }
 
+/**
+ * RBSourcelistGroupType:
+ * @RB_SOURCE_GROUP_CATEGORY_FIXED: Fixed single instance sources (e.g., library)
+ * @RB_SOURCE_GROUP_CATEGORY_PERSISTENT: Persistent multiple-instance sources (e.g. playlists)
+ * @RB_SOURCE_GROUP_CATEGORY_REMOVABLE: Sources representing removable devices
+ * @RB_SOURCE_GROUP_CATEGORY_TRANSIENT: Transient sources (e.g. network shares)
+ *
+ * Predefined categories of source group. The order they're defined here is the order they
+ * appear in the source list.
+ */
+
 #define ENUM_ENTRY(NAME, DESC) { NAME, "" #NAME "", DESC }
 GType
 rb_source_group_category_get_type (void)
@@ -94,6 +120,15 @@
 	return etype;
 }
 
+/**
+ * rb_source_group_get_by_name:
+ * @name: name of source group to find
+ *
+ * Locates a source group by name.  If the source group has not been registered yet,
+ * returns NULL instead.
+ *
+ * Return value: existing source group, or NULL.
+ */
 RBSourceGroup *
 rb_source_group_get_by_name (const char *name)
 {
@@ -110,6 +145,17 @@
 	return group;
 }
 
+/**
+ * rb_source_group_register:
+ * @name: name of the source group (untranslated, used in code)
+ * @display_name: display name of the source group (translated)
+ * @category: category for the source group
+ *
+ * Registers and returns a new source group.  Registering a source group
+ * that already exists will probably do bad things.
+ *
+ * Return value: new source group
+ */
 RBSourceGroup *
 rb_source_group_register (const char           *name,
 			  const char           *display_name,
@@ -132,24 +178,44 @@
 	return group;
 }
 
+/**
+ * rb_source_group_library_get_type:
+ *
+ * Return value: the predefined library source group
+ */
 RBSourceGroup *
 rb_source_group_library_get_type (void)
 {
 	return library_group;
 }
 
+/**
+ * rb_source_group_playlists_get_type:
+ *
+ * Return value: the predefined playlists source group
+ */
 RBSourceGroup *
 rb_source_group_playlists_get_type (void)
 {
 	return playlists_group;
 }
 
+/**
+ * rb_source_group_devices_get_type:
+ *
+ * Return value: the predefined devices source group
+ */
 RBSourceGroup *
 rb_source_group_devices_get_type (void)
 {
 	return devices_group;
 }
 
+/**
+ * rb_source_group_shared_get_type:
+ *
+ * Return value: the predefined shared source group
+ */
 RBSourceGroup *
 rb_source_group_shared_get_type (void)
 {
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]