[tracker/binary-log-2: 35/56] Added comments to the journal code and improved var names in places

[Jürg Billeter <juergbi src gnome org>]

commit 7d1c8be42750d68fd310f7b91b9a81bc2bf41dc6
Author: Martyn Russell <martyn lanedo com>
Date:   Wed Jan 6 10:26:09 2010 +0000

    Added comments to the journal code and improved var names in places

 src/libtracker-db/tracker-db-journal.c |   65 +++++++++++++++++++++++++++----
 1 files changed, 56 insertions(+), 9 deletions(-)
---
diff --git a/src/libtracker-db/tracker-db-journal.c b/src/libtracker-db/tracker-db-journal.c
index 8552f93..01bda30 100644
--- a/src/libtracker-db/tracker-db-journal.c
+++ b/src/libtracker-db/tracker-db-journal.c
@@ -477,17 +477,23 @@ tracker_db_journal_commit_transaction (void)
 	size = sizeof (guint32);
 	offset = sizeof (guint32) * 3;
 
+	/* Expand by uint32 for the size check at the end of the entry */
 	cur_block_maybe_expand (size);
 
 	writer.cur_block_len += size;
 
+	/* Write size and amount */
 	cur_setnum (writer.cur_block, &begin_pos, writer.cur_block_len);
 	cur_setnum (writer.cur_block, &begin_pos, writer.cur_entry_amount);
 
+	/* Write size check to end of current journal data */
 	cur_setnum (writer.cur_block, &writer.cur_pos, writer.cur_block_len);
 
-	/* CRC is calculated from entries until appended amount int */
-
+	/* Calculate CRC from entry triples start (i.e. without size,
+	 * amount and crc) until the end of the entry block.
+	 *
+	 * NOTE: the size check at the end is included in the CRC!
+	 */
 	crc = tracker_crc32 (writer.cur_block + offset, writer.cur_block_len - offset);
 	cur_setnum (writer.cur_block, &begin_pos, crc);
 
@@ -496,7 +502,10 @@ tracker_db_journal_commit_transaction (void)
 		return FALSE;
 	}
 
+	/* FIX: WHAT DOES THIS DO? */
 	writer.cur_size += writer.cur_block_len;
+
+	/* Clean up for next transaction */
 	cur_block_kill ();
 
 	return TRUE;
@@ -610,19 +619,48 @@ tracker_db_journal_reader_next (GError **error)
 {
 	g_return_val_if_fail (reader.file != NULL, FALSE);
 
+	/*
+	 * Visual layout of the data in the binary journal:
+	 *
+	 * [
+	 *  [magic]
+	 *  [version]
+	 *  [
+	 *   [entry 
+	 *    [size]
+	 *    [amount]
+	 *    [crc]
+	 *    [id id id]
+	 *    [id id string]
+	 *    [id ...]
+	 *    [size]
+	 *   ]
+	 *   [entry...]
+	 *   [entry...]
+	 *  ]
+	 * ]
+	 *
+	 * Note: We automatically start at the first entry, upon init
+	 * of the reader, we move past the [magic] and the [version].
+	 */
+
 	if (reader.type == TRACKER_DB_JOURNAL_START ||
 	    reader.type == TRACKER_DB_JOURNAL_END_TRANSACTION) {
-		/* expect new transaction or end of file */
+		/* Expect new transaction or end of file */
 		guint32 entry_size;
+		guint32 entry_size_check;
 		guint32 crc32;
-		guint32 read_size;
 
+		/* Check the end is not before where we currently are */
 		if (reader.current >= reader.end) {
 			g_set_error (error, TRACKER_DB_JOURNAL_ERROR, 0, 
 			             "End of journal reached");
 			return FALSE;
 		}
 
+		/* Check the end is not smaller than the first uint32
+		 * for reading the entry size.
+		 */
 		if (reader.end - reader.current < sizeof (guint32)) {
 			g_set_error (error, TRACKER_DB_JOURNAL_ERROR, 0, 
 			             "Damaged journal entry, %d < sizeof(guint32) at start/end of journal",
@@ -630,27 +668,36 @@ tracker_db_journal_reader_next (GError **error)
 			return FALSE;
 		}
 
-		reader.entry_begin = reader.current;
+		/* Read the first uint32 which contains the size */
 		entry_size = read_uint32 (reader.current);
+
+		/* Set the bounds for the entry */
+		reader.entry_begin = reader.current;
 		reader.entry_end = reader.entry_begin + entry_size;
 
+		/* Check the end of the entry does not exceed the end
+		 * of the journal.
+		 */
 		if (reader.end < reader.entry_end) {
 			g_set_error (error, TRACKER_DB_JOURNAL_ERROR, 0, 
 			             "Damaged journal entry, end < entry end");
 			return FALSE;
 		}
 
+		/* Move the current potision of the journal past the
+		 * entry size we read earlier.
+		 */
 		reader.current += 4;
 
 		/* compare with entry_size at end */
-		read_size = read_uint32 (reader.entry_end - 4);
+		entry_size_check = read_uint32 (reader.entry_end - 4);
 
-		if (entry_size != read_size) {
+		if (entry_size != entry_size_check) {
 			/* damaged journal entry */
 			g_set_error (error, TRACKER_DB_JOURNAL_ERROR, 0, 
-			             "Damaged journal entry, %d != %d (size != size read)", 
+			             "Damaged journal entry, %d != %d (entry size != entry size check)", 
 			             entry_size, 
-			             read_size);
+			             entry_size_check);
 			return FALSE;
 		}