Add some function documentation and clarifying comments.

1 files changed, 23 insertions, 6 deletions

diff --git a/c_src/permdb.c b/c_src/permdb.c
index 2c22f98..2e9f2e2 100644
--- a/c_src/permdb.c
+++ b/c_src/permdb.c
@@ -48,7 +48,7 @@ static const node_object errornode = {{NODE_ENTRY_ERROR_NODE,
 struct nodecache {
         node_object value;
         ps_string *key;
-        UT_hash_handle hh;
+        UT_hash_handle hh;      /* Magic name, used by HASH_SORT. */
 };
 
 static node_object
@@ -177,9 +177,9 @@ datafile_add_header(buffered_file *file)
 {
         dprintf(WRITE, (stderr, "adding header to %s\n", bf_name(file)));
         bf_add(file, &data_file_cookie, sizeof(data_file_cookie));
-        bf_add_be32(file, 4096);
-        bf_add_be32(file, 2);
-        bf_add_be32(file, 32);
+        bf_add_be32(file, 4096); /* Parameter 'blocksize'. */
+        bf_add_be32(file, 2);    /* Parameter 'q'. */
+        bf_add_be32(file, 32);   /* Parameter 'keylength'. */
         bf_flush(file);
 }
 
@@ -990,6 +990,18 @@ string_length_comparison(struct nodecache *a, struct nodecache *b) {
         }
 }
 
+/*
+ * Commits outstanding data to disk by
+ * 1. sorting the dirtynodes list on decreasing key length
+ * 2. verifying that the last node is the root node (key "")
+ * 3. iterating over all nodes from last node to root, writing each
+ * node to the index file while updating the parent node to reflect
+ * the new child offset
+ * 4. writing commit trailer to the data file
+ * 5. writing commit trailer to the index file
+ *
+ * Returns 0 on success, -1 on failure.
+ */
 int
 committree(permdb_object *state)
 {
@@ -1017,9 +1029,14 @@ committree(permdb_object *state)
                 assert(get_entry_in_node(node->value, 1)!=NODE_ENTRY_DIRTY_NODE);
                 assert(get_entry_in_node(node->value, 2)!=NODE_ENTRY_DIRTY_NODE);
                 assert(get_entry_in_node(node->value, 3)!=NODE_ENTRY_DIRTY_NODE);
+
                 node_offset offset = writenode(state, node->value, node->key);
+
                 size_t keylength = node->key->length;
                 if (keylength != 0) {
+                        /* Since q is 2, parent is easily found by
+                         * stripping last octet from ASCII
+                         * representation of key (4 bits). */
                         ps_string *parent =
                                 ps_resize(node->key, node->key->length - 1);
                         unsigned int entrynumber = (unsigned int)
@@ -1044,7 +1061,7 @@ committree(permdb_object *state)
         bf_add_be32(state->datafile,
                     bf_total_length(state->datafile)
                     - bf_lastcommit(state->datafile)
-                    + sizeof(uint32_t));
+                    + sizeof(uint32_t)); /* Including the length field. */
         bf_sha256(state->datafile, data_commit_checksum);
         bf_add(state->datafile, data_commit_checksum, SHA256_DIGEST_SIZE);
         bf_add(state->datafile, &data_commit_end_cookie,
@@ -1065,7 +1082,7 @@ committree(permdb_object *state)
         uint64_t index_commit_length =
                 bf_total_length(state->indexfile)
                 - bf_lastcommit(state->indexfile)
-                + sizeof(uint64_t);
+                + sizeof(uint64_t); /* Including the length field. */
         unsigned char index_commit_checksum[SHA256_DIGEST_SIZE];
         bf_add_host64(state->indexfile, index_commit_length);
         bf_sha256(state->indexfile, index_commit_checksum);