[tracker/urho-sync] Added some code comments

[Philip Van Hoof <pvanhoof src gnome org>]

commit 2b6623eae4c52c232d05ae01ab77bdaca0f9d1ba
Author: Philip Van Hoof <philip codeminded be>
Date:   Mon Aug 24 16:29:11 2009 +0200

    Added some code comments

 src/libtracker-data/tracker-data-backup.c |    4 ++++
 src/libtracker-db/tracker-db-backup.c     |    2 ++
 src/libtracker-db/tracker-db-manager.c    |   20 ++++++++++++++++++++
 src/tracker-store/tracker-backup.c        |   17 ++++++++++++++++-
 4 files changed, 42 insertions(+), 1 deletions(-)
---
diff --git a/src/libtracker-data/tracker-data-backup.c b/src/libtracker-data/tracker-data-backup.c
index 4b2c6f9..fc2ddc3 100644
--- a/src/libtracker-data/tracker-data-backup.c
+++ b/src/libtracker-data/tracker-data-backup.c
@@ -165,8 +165,10 @@ tracker_data_backup_save (GFile *destination,
 	info->file = tracker_db_backup_file (NULL, TRACKER_DB_BACKUP_META_FILENAME);
 
 	if (g_file_query_exists (info->file, NULL)) {
+		/* Making a backup just means copying meta-backup.db */
 		save_copy_procedure (info);
 	} else {
+		/* If we don't have a meta-backup.db yet, we first make one */
 		tracker_db_backup_save (on_backup_finished, 
 		                        info, NULL);
 	}
@@ -244,6 +246,8 @@ tracker_data_backup_restore (GFile *backup,
 
 	info->file = tracker_db_backup_file (NULL, TRACKER_DB_BACKUP_META_FILENAME);
 
+	/* This is all synchronous, blocking the mainloop indeed */
+
 	restore_copy_procedure (info);
 
 	tracker_db_journal_open ();
diff --git a/src/libtracker-db/tracker-db-backup.c b/src/libtracker-db/tracker-db-backup.c
index 052ec58..e278eef 100644
--- a/src/libtracker-db/tracker-db-backup.c
+++ b/src/libtracker-db/tracker-db-backup.c
@@ -217,6 +217,8 @@ tracker_db_backup_save (TrackerDBBackupFinished callback,
 	BackupInfo *info = g_new0 (BackupInfo, 1);
 	GFile *file;
 
+	/* This procedure makes a meta-backup.db using sqlite3_backup API */
+
 	info->callback = callback;
 	info->user_data = user_data;
 	info->destroy = destroy;
diff --git a/src/libtracker-db/tracker-db-manager.c b/src/libtracker-db/tracker-db-manager.c
index c22f48d..32e078f 100644
--- a/src/libtracker-db/tracker-db-manager.c
+++ b/src/libtracker-db/tracker-db-manager.c
@@ -1062,6 +1062,9 @@ check_meta_backup (gboolean *did_copy)
 		GFile *file;
 
 		file = g_file_new_for_path (meta_filename);
+
+		/* (more) Checks for a healthy meta.db should happen here */
+
 		if (!g_file_query_exists (file, NULL)) {
 			GFile *backup;
 
@@ -1070,6 +1073,10 @@ check_meta_backup (gboolean *did_copy)
 			if (g_file_query_exists (backup, NULL)) {
 				GError *error = NULL;
 
+				/* Note that we leave meta-backup.db as is, it'll
+				 * be overwritten first-next time tracker-store.c's
+				 * sync_idle_handler will instruct this. */
+
 				g_file_copy (backup, file, G_FILE_COPY_OVERWRITE,
 				             NULL, NULL, NULL, &error);
 
@@ -1080,6 +1087,12 @@ check_meta_backup (gboolean *did_copy)
 				g_clear_error (&error);
 			}
 
+			/* We always play the journal in case meta.db wasn't
+			 * healthy. Also if meta-backup.db didn't exist: that
+			 * just means that tracker-store.c's sync_idle_handler
+			 * didn't yet ran (meanwhile a first log-file is yet
+			 * already being made) */
+
 			retval = TRUE;
 
 			g_object_unref (backup);
@@ -1203,6 +1216,9 @@ tracker_db_manager_init (TrackerDBManagerFlags	flags,
 	}
 
 	if (need_journal) {
+		/* That did_copy is used for called db_manager_remove_all, we
+		 * don't want it to also remove our freshly copied meta.db file. */
+
 		*need_journal = check_meta_backup (&did_copy);
 	}
 
@@ -1238,6 +1254,10 @@ tracker_db_manager_init (TrackerDBManagerFlags	flags,
 		 * will cause errors and do nothing.
 		 */
 		g_message ("Cleaning up database files for reindex");
+
+		/* Remove all but the meta.db in case of did_copy, else remove
+		 * all (only in case meta-backup.db was not restored) */
+
 		db_manager_remove_all (FALSE, did_copy);
 
 		/* In cases where we re-init this module, make sure
diff --git a/src/tracker-store/tracker-backup.c b/src/tracker-store/tracker-backup.c
index 007e5a3..50d7f67 100644
--- a/src/tracker-store/tracker-backup.c
+++ b/src/tracker-store/tracker-backup.c
@@ -100,6 +100,10 @@ on_batch_commit (gpointer user_data)
 {
 	TrackerDBusMethodInfo *info = user_data;
 
+	/* At this point no transactions are left open, we can now start the
+	 * sqlite3_backup API, which will run itself as a GSource within the
+	 * mainloop after it got initialized (which will reopen the mainloop) */
+
 	tracker_data_backup_save (info->destination, info->journal,
 	                          backup_callback,
 	                          info, destroy_method_info);
@@ -121,7 +125,6 @@ tracker_backup_save (TrackerBackup          *object,
 	                          "DBus request to save backup into '%s'",
 	                          destination_uri);
 
-
 	info = g_new0 (TrackerDBusMethodInfo, 1);
 
 	info->request_id = request_id;
@@ -130,6 +133,11 @@ tracker_backup_save (TrackerBackup          *object,
 	info->destination = g_file_new_for_uri (destination_uri);
 	info->journal = g_file_new_for_uri (journal_uri);
 
+	/* The sqlite3_backup API apparently doesn't much like open transactions,
+	 * this queue_commit will first call the currently open transaction
+	 * of the open batch (if any), and then in the callback we'll idd 
+	 * continue with making the backup itself (using sqlite3_backup's API) */
+
 	tracker_store_queue_commit (on_batch_commit, info, NULL);
 }
 
@@ -159,6 +167,13 @@ tracker_backup_restore (TrackerBackup          *object,
 	info->context = context;
 	info->play_journal = TRUE;
 
+	/* This call is mostly synchronous, because we want to block the 
+	 * mainloop during a restore procedure (you're switching the active
+	 * database here, let's not allow queries during this time) 
+	 *
+	 * No need for commits or anything. Whatever is in the current db will
+	 * be eliminated in favor of the data in `backup_uri` and `journal_uri`. */
+
 	tracker_data_backup_restore (destination, journal,
 	                             backup_callback,
 	                             info, destroy_method_info);