GNOME.org
 

rhythmbox r5629 - in trunk: . doc/reference rhythmdb widgets

Author: jmatthew
Date: Wed Mar 19 12:52:24 2008
New Revision: 5629
URL: http://svn.gnome.org/viewvc/rhythmbox?rev=5629&view=rev

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

	* rhythmdb/rhythmdb.h:
	* rhythmdb/rhythmdb-import-job.h:
	* rhythmdb/rhythmdb-private.h:
	* rhythmdb/rhythmdb-property-model.h:
	* widgets/rb-uri-dialog.h:
	Rearrange struct/typedef bits so gtk-doc likes them
	(I'll probably end up doing this for every single class..)

	* rhythmdb/rhythmdb-import-job.c:
	* rhythmdb/rhythmdb-property-model.c:
	Add gtk-doc stuff for RhythmDBImportJob and RhythmDBPropertyModel

	* doc/reference/rhythmbox-sections.txt:
	Update this a bit


Modified:
   trunk/ChangeLog
   trunk/doc/reference/rhythmbox-sections.txt
   trunk/rhythmdb/rhythmdb-import-job.c
   trunk/rhythmdb/rhythmdb-import-job.h
   trunk/rhythmdb/rhythmdb-private.h
   trunk/rhythmdb/rhythmdb-property-model.c
   trunk/rhythmdb/rhythmdb-property-model.h
   trunk/rhythmdb/rhythmdb.h
   trunk/widgets/rb-uri-dialog.h

Modified: trunk/doc/reference/rhythmbox-sections.txt
==============================================================================
--- trunk/doc/reference/rhythmbox-sections.txt	(original)
+++ trunk/doc/reference/rhythmbox-sections.txt	Wed Mar 19 12:52:24 2008
@@ -621,6 +621,9 @@
 
 <SECTION>
 <FILE>rhythmdb-property-model</FILE>
+<TITLE>RhythmDBPropertyModel</TITLE>
+RHythmDBPropertyModel
+RhythmDBPropertyModelClass
 RhythmDBPropertyModelColumn
 RhythmDBPropertyModelPrivate
 rhythmdb_property_model_new
@@ -1291,3 +1294,43 @@
 rb_rating_install_rating_property
 </SECTION>
 
+<SECTION>
+<FILE>rhythmdb-import-job</FILE>
+<TITLE>RhythmDBImportJob</TITLE>
+RhythmDBImportJob
+RhythmDBImportJobClass
+RhythmDBImportJobPrivate
+rhythmdb_import_job_new
+rhythmdb_import_job_add_uri
+rhythmdb_import_job_start
+rhythmdb_import_job_cancel
+rhythmdb_import_job_complete
+rhythmdb_import_job_scan_complete
+rhythmdb_import_job_get_total
+rhythmdb_import_job_get_imported
+<SUBSECTION Standard>
+RHYTHMDB_IMPORT_JOB
+RHYTHMDB_IS_IMPORT_JOB
+RHYTHMDB_TYPE_IMPORT_JOB
+rhythmdb_import_job_get_type
+RHYTHMDB_IMPORT_JOB_CLASS
+RHYTHMDB_IS_IMPORT_JOB_CLASS
+RHYTHMDB_IMPORT_JOB_GET_CLASS
+</SECTION>
+
+<SECTION>
+<FILE>rb-uri-dialog</FILE>
+<TITLE>RBURIDialog</TITLE>
+RBURIDialog
+RBURIDialogClass
+RBURIDialogPrivate
+rb_uri_dialog_new
+<SUBSECTION Standard>
+RB_URI_DIALOG
+RB_IS_URI_DIALOG
+RB_TYPE_URI_DIALOG
+rb_uri_dialog_get_type
+RB_URI_DIALOG_CLASS
+RB_IS_URI_DIALOG_CLASS
+RB_URI_DIALOG_GET_CLASS
+</SECTION>

Modified: trunk/rhythmdb/rhythmdb-import-job.c
==============================================================================
--- trunk/rhythmdb/rhythmdb-import-job.c	(original)
+++ trunk/rhythmdb/rhythmdb-import-job.c	Wed Mar 19 12:52:24 2008
@@ -70,6 +70,32 @@
 
 G_DEFINE_TYPE (RhythmDBImportJob, rhythmdb_import_job, G_TYPE_OBJECT)
 
+/**
+ * SECTION:rhythmdb-import-job
+ * @short_description: batch import job
+ *
+ * Tracks the addition to the database of files under a set of 
+ * directories, providing status information.
+ *
+ * The entry types to use for the database entries added by the import
+ * job are specified on creation.
+ */
+
+/**
+ * rhythmdb_import_job_new:
+ * @db: the #RhythmDB object
+ * @entry_type: the #RhythmDBEntryType to use for normal entries
+ * @ignore_type: the #RhythmDBEntryType to use for ignored files
+ *   (or RHYTHMDB_ENTRY_TYPE_INVALID to not create ignore entries)
+ * @error_type: the #RhythmDBEntryType to use for import error
+ *   entries (or RHYTHMDB_ENTRY_TYPE_INVALID for none)
+ *
+ * Creates a new import job with the specified entry types.
+ * Before starting the job, the caller must add one or more
+ * paths to import.
+ *
+ * Return value: new #RhythmDBImportJob object.
+ */
 RhythmDBImportJob *
 rhythmdb_import_job_new (RhythmDB *db,
 			 RhythmDBEntryType entry_type,
@@ -87,6 +113,14 @@
 	return RHYTHMDB_IMPORT_JOB (obj);
 }
 
+/**
+ * rhythmdb_import_job_add_uri:
+ * @job: a #RhythmDBImportJob
+ * @uri: the URI to import
+ *
+ * Adds a URI to import.  All files under the specified
+ * URI will be imported.
+ */
 void
 rhythmdb_import_job_add_uri (RhythmDBImportJob *job, const char *uri)
 {
@@ -187,6 +221,14 @@
 	g_static_mutex_unlock (&job->priv->lock);
 }
 
+/**
+ * rhythmdb_import_job_start:
+ * @job: the #RhythmDBImportJob
+ *
+ * Starts the import job.  After this method has been called,
+ * no more URIs may be added to the import job.  May only be
+ * called once for a given import job.
+ */
 void
 rhythmdb_import_job_start (RhythmDBImportJob *job)
 {
@@ -202,30 +244,67 @@
 	next_uri (g_object_ref (job));
 }
 
+/**
+ * rhythmdb_import_job_get_total:
+ * @job: the #RhythmDBImportJob
+ *
+ * Returns the total number of files that will be processed by
+ * this import job.  This increases as the import directories are
+ * scanned.
+ *
+ * Return value: the total number of files to be processed
+ */
 int
 rhythmdb_import_job_get_total (RhythmDBImportJob *job)
 {
 	return job->priv->total;
 }
 
+/**
+ * rhythmdb_import_job_get_imported:
+ * @job: the #RhythmDBImportJob
+ *
+ * Return value: the number of files processed so far 
+ */
 int
 rhythmdb_import_job_get_imported (RhythmDBImportJob *job)
 {
 	return job->priv->imported;
 }
 
+/**
+ * rhythmdb_import_job_scan_complete:
+ * @job: the #RhythmDBImportJob
+ *
+ * Return value: TRUE if the directory scan is complete
+ */
 gboolean
 rhythmdb_import_job_scan_complete (RhythmDBImportJob *job)
 {
 	return job->priv->scan_complete;
 }
 
+/**
+ * rhythmdb_import_job_complete:
+ * @job: the #RhythmDBImportJob
+ *
+ * Return value: TRUE if the import job is complete.
+ */
 gboolean
 rhythmdb_import_job_complete (RhythmDBImportJob *job)
 {
 	return job->priv->complete;
 }
 
+/**
+ * rhythmdb_import_job_cancel:
+ * @job: the #RhythmDBImportJob
+ *
+ * Cancels the import job.  The job will cease as soon
+ * as possible.  More directories may be scanned and 
+ * more files may be imported before the job actually
+ * ceases.
+ */
 void
 rhythmdb_import_job_cancel (RhythmDBImportJob *job)
 {
@@ -398,6 +477,14 @@
 							     RHYTHMDB_TYPE_ENTRY_TYPE,
 							     G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RhythmDBImportJob::entry-added:
+	 * @job: the #RhythmDBImportJob
+	 * @entry: the newly added #RhythmDBEntry
+	 *
+	 * Emitted when an entry has been added to the database by the
+	 * import job.
+	 */
 	signals [ENTRY_ADDED] =
 		g_signal_new ("entry-added",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -407,6 +494,14 @@
 			      g_cclosure_marshal_VOID__BOXED,
 			      G_TYPE_NONE,
 			      1, RHYTHMDB_TYPE_ENTRY);
+	/**
+	 * RhythmDBImportJob::status-changed:
+	 * @job: the #RhythmDBImportJob
+	 * @total: the current total number of files to process
+	 * @imported: the current count of files imported
+	 *
+	 * Emitted when the status of the import job has changed.
+	 */
 	signals [STATUS_CHANGED] =
 		g_signal_new ("status-changed",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -416,6 +511,14 @@
 			      rb_marshal_VOID__INT_INT,
 			      G_TYPE_NONE,
 			      2, G_TYPE_INT, G_TYPE_INT);
+	/**
+	 * RhythmDBImportJob::scan-complete:
+	 * @job: the #RhythmDBImportJob
+	 *
+	 * Emitted when the directory scan is complete.  Once
+	 * the scan is complete, the total number of files to
+	 * be processed will not change.
+	 */
 	signals[SCAN_COMPLETE] =
 		g_signal_new ("scan-complete",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -425,6 +528,12 @@
 			      g_cclosure_marshal_VOID__INT,
 			      G_TYPE_NONE,
 			      1, G_TYPE_INT);
+	/**
+	 * RhythmDBImportJob::complete:
+	 * @job: the #RhythmDBImportJob
+	 *
+	 * Emitted when the whole import job is complete.
+	 */
 	signals[COMPLETE] =
 		g_signal_new ("complete",
 			      G_OBJECT_CLASS_TYPE (object_class),

Modified: trunk/rhythmdb/rhythmdb-import-job.h
==============================================================================
--- trunk/rhythmdb/rhythmdb-import-job.h	(original)
+++ trunk/rhythmdb/rhythmdb-import-job.h	Wed Mar 19 12:52:24 2008
@@ -34,15 +34,18 @@
 #define RHYTHMDB_IS_IMPORT_JOB_CLASS(k)		(G_TYPE_CHECK_CLASS_TYPE ((k), RHYTHMDB_TYPE_IMPORT_JOB))
 #define RHYTHMDB_IMPORT_JOB_GET_CLASS(o)	(G_TYPE_INSTANCE_GET_CLASS ((o), RHYTHMDB_TYPE_IMPORT_JOB, RhythmDBImportJobClass))
 
+typedef struct _RhythmDBImportJob 	RhythmDBImportJob;
+typedef struct _RhythmDBImportJobClass 	RhythmDBImportJobClass;
+
 typedef struct _RhythmDBImportJobPrivate RhythmDBImportJobPrivate;
 
-typedef struct
+struct _RhythmDBImportJob
 {
 	GObject parent;
 	RhythmDBImportJobPrivate *priv;
-} RhythmDBImportJob;
+};
 
-typedef struct
+struct _RhythmDBImportJobClass
 {
 	GObjectClass parent_class;
 
@@ -51,7 +54,7 @@
 	void (*status_changed) (RhythmDBImportJob *job, int total, int imported);
 	void (*scan_complete) (RhythmDBImportJob *job, int total);
 	void (*complete) (RhythmDBImportJob *job, int total);
-} RhythmDBImportJobClass;
+};
 
 GType		rhythmdb_import_job_get_type		(void);
 

Modified: trunk/rhythmdb/rhythmdb-private.h
==============================================================================
--- trunk/rhythmdb/rhythmdb-private.h	(original)
+++ trunk/rhythmdb/rhythmdb-private.h	Wed Mar 19 12:52:24 2008
@@ -120,7 +120,7 @@
 	RBRefString *playback_error;
 };
 
-struct RhythmDBPrivate
+struct _RhythmDBPrivate
 {
 	char *name;
 

Modified: trunk/rhythmdb/rhythmdb-property-model.c
==============================================================================
--- trunk/rhythmdb/rhythmdb-property-model.c	(original)
+++ trunk/rhythmdb/rhythmdb-property-model.c	Wed Mar 19 12:52:24 2008
@@ -182,6 +182,19 @@
 
 static guint rhythmdb_property_model_signals[LAST_SIGNAL] = { 0 };
 
+/**
+ * SECTION:rhythmdb-property-model
+ * @short_description:  tree model grouping entries from a query model by property values
+ *
+ * A RhythmDBPropertyModel groups the entries in a #RhythmDBQueryModel by
+ * the value of a property.  For example, a RhythmDBPropertyModel using
+ * the RHYTHMDB_PROP_ARTIST property can be used as the model for a 
+ * #GtkTreeView that will list the artists present in the query model.
+ *
+ * The album/artist/genre browsers displayed in the library and other sources are
+ * populated using a RhythmDBPropertyModel for each property.
+ */
+
 static void
 rhythmdb_property_model_class_init (RhythmDBPropertyModelClass *klass)
 {
@@ -210,6 +223,11 @@
 	object_class->dispose = rhythmdb_property_model_dispose;
 	object_class->finalize = rhythmdb_property_model_finalize;
 
+	/**
+	 * RhythmDBPropertyModel::pre-row-deletion:
+	 *
+	 * Emitted just before a row is deleted from the model.
+	 */
 	rhythmdb_property_model_signals[PRE_ROW_DELETION] =
 		g_signal_new ("pre-row-deletion",
 			      G_OBJECT_CLASS_TYPE (object_class),
@@ -220,6 +238,11 @@
 			      G_TYPE_NONE,
 			      0);
 
+	/**
+	 * RhythmDBPropertyModel:db:
+	 *
+	 * The #RhythmDB object the model is associated with.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_RHYTHMDB,
 					 g_param_spec_object ("db",
@@ -228,6 +251,11 @@
 							      RHYTHMDB_TYPE,
 							      G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
 
+	/**
+	 * RhythmDBPropertyModel:prop:
+	 *
+	 * The property that this property model indexes.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_PROP,
 					 g_param_spec_int ("prop",
@@ -236,6 +264,12 @@
 							   0, RHYTHMDB_NUM_PROPERTIES,
 							   RHYTHMDB_PROP_TYPE,
 							   G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY));
+
+	/**
+	 * RhythmDBPropertyModel:query-model:
+	 *
+	 * The query model that this property model indexes.
+	 */
 	g_object_class_install_property (object_class,
 					 PROP_QUERY_MODEL,
 					 g_param_spec_object ("query-model",
@@ -491,6 +525,15 @@
 	G_OBJECT_CLASS (rhythmdb_property_model_parent_class)->finalize (object);
 }
 
+/**
+ * rhythmdb_property_model_new:
+ * @db: the #RhythmDB object
+ * @propid: the property to index
+ *
+ * Creates a new property model for the specified property ID.
+ *
+ * Return value: the new #RhythmDBPropertyModel
+ */
 RhythmDBPropertyModel *
 rhythmdb_property_model_new (RhythmDB *db,
 			     RhythmDBPropType propid)
@@ -680,6 +723,16 @@
 	g_free (prop);
 }
 
+/**
+ * rhythmdb_property_model_iter_from_string:
+ * @model: the #RhythmDBPropertyModel
+ * @name: the property value to find
+ * @iter: a #GtkTreeIter to point to the row
+ *
+ * Locates the row in the model for a property value.
+ *
+ * Return value: TRUE if the value was found.
+ */
 gboolean
 rhythmdb_property_model_iter_from_string (RhythmDBPropertyModel *model,
 					  const char *name,
@@ -1136,6 +1189,15 @@
 	return TRUE;
 }
 
+/**
+ * rhythmdb_property_model_enable_drag:
+ * @model: the #RhythmDBPropertyModel.
+ * @view: the #GtkTreeView from which to enable drag and drop
+ *
+ * Enables drag and drop from a specified #GtkTreeView that is
+ * backed by the #RhythmDBPropertyModel.  Drag targets are
+ * determined by the indexed property.
+ */
 void
 rhythmdb_property_model_enable_drag (RhythmDBPropertyModel *model,
 				     GtkTreeView *view)

Modified: trunk/rhythmdb/rhythmdb-property-model.h
==============================================================================
--- trunk/rhythmdb/rhythmdb-property-model.h	(original)
+++ trunk/rhythmdb/rhythmdb-property-model.h	Wed Mar 19 12:52:24 2008
@@ -50,21 +50,23 @@
 GType rhythmdb_property_model_column_get_type (void);
 #define RHYTHMDB_TYPE_PROPERTY_MODEL_COLUMN (rhythmdb_property_model_column_get_type ())
 
+typedef struct _RhythmDBPropertyModel RhythmDBPropertyModel;
+typedef struct _RhythmDBPropertyModelClass RhythmDBPropertyModelClass;
 typedef struct RhythmDBPropertyModelPrivate RhythmDBPropertyModelPrivate;
 
-typedef struct
+struct _RhythmDBPropertyModel
 {
 	GObject parent;
 
 	RhythmDBPropertyModelPrivate *priv;
-} RhythmDBPropertyModel;
+};
 
-typedef struct
+struct _RhythmDBPropertyModelClass
 {
 	GObjectClass parent;
 
 	void (*pre_row_deletion) (RhythmDBPropertyModel *model);
-} RhythmDBPropertyModelClass;
+};
 
 GType			rhythmdb_property_model_get_type	(void);
 

Modified: trunk/rhythmdb/rhythmdb.h
==============================================================================
--- trunk/rhythmdb/rhythmdb.h	(original)
+++ trunk/rhythmdb/rhythmdb.h	Wed Mar 19 12:52:24 2008
@@ -34,8 +34,8 @@
 
 G_BEGIN_DECLS
 
-struct RhythmDB_;
-typedef struct RhythmDB_ RhythmDB;
+typedef struct _RhythmDB RhythmDB;
+typedef struct _RhythmDBClass RhythmDBClass;
 
 #define RHYTHMDB_TYPE      (rhythmdb_get_type ())
 #define RHYTHMDB(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), RHYTHMDB_TYPE, RhythmDB))
@@ -258,16 +258,16 @@
 
 GQuark rhythmdb_error_quark (void);
 
-typedef struct RhythmDBPrivate RhythmDBPrivate;
+typedef struct _RhythmDBPrivate RhythmDBPrivate;
 
-struct RhythmDB_
+struct _RhythmDB
 {
 	GObject parent;
 
 	RhythmDBPrivate *priv;
 };
 
-typedef struct
+struct _RhythmDBClass
 {
 	GObjectClass parent;
 
@@ -336,7 +336,7 @@
 							 RBRefString *keyword);
 	GList*		(*impl_entry_keywords_get)	(RhythmDB *db,
 							 RhythmDBEntry *entry);
-} RhythmDBClass;
+};
 
 GType		rhythmdb_get_type	(void);
 

Modified: trunk/widgets/rb-uri-dialog.h
==============================================================================
--- trunk/widgets/rb-uri-dialog.h	(original)
+++ trunk/widgets/rb-uri-dialog.h	Wed Mar 19 12:52:24 2008
@@ -34,22 +34,24 @@
 #define RB_IS_URI_DIALOG_CLASS(k)  (G_TYPE_CHECK_CLASS_TYPE ((k), RB_TYPE_URI_DIALOG))
 #define RB_URI_DIALOG_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), RB_TYPE_URI_DIALOG, RBURIDialogClass))
 
+typedef struct _RBURIDialog RBURIDialog;
+typedef struct _RBURIDialogClass RBURIDialogClass;
 typedef struct RBURIDialogPrivate RBURIDialogPrivate;
 
-typedef struct
+struct _RBURIDialog
 {
 	GtkDialog parent;
 
 	RBURIDialogPrivate *priv;
-} RBURIDialog;
+};
 
-typedef struct
+struct _RBURIDialogClass
 {
 	GtkDialogClass parent_class;
 
         void (*location_added) (RBURIDialog *dialog,
 				const char  *uri);
-} RBURIDialogClass;
+};
 
 GType      rb_uri_dialog_get_type (void);
 GtkWidget* rb_uri_dialog_new      (const char *title,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]