addresses #686

add comments for read_row

git-svn-id: file:///svn/mysql/tokudb-engine/src@3543 c7de825b-a66e-492c-adef-691d508d4ae1

storage/tokudb/ha_tokudb.cc

@@ -1125,7 +1125,12 @@ int ha_tokudb::__close(int mutex_is_locked) {
     TOKUDB_DBUG_RETURN(free_share(share, table, hidden_primary_key, mutex_is_locked));
 }
 
-/* Reallocate buffer if needed */
+//
+// Reallocate record buffer (rec_buff) if needed
+// If not needed, does nothing
+// Parameters:
+//          length - size of buffer required for rec_buff
+//
 bool ha_tokudb::fix_rec_buff_for_blob(ulong length) {
     if (!rec_buff || length > alloced_rec_buff_length) {
         uchar *newptr;
@@ -1932,20 +1937,51 @@ int ha_tokudb::index_end() {
     TOKUDB_DBUG_RETURN(error);
 }
 
-/* What to do after we have read a row based on an index */
+//
+// The funtion read_row checks whether the row was obtained from the primary table or 
+// from an index table. If it was obtained from an index table, it further dereferences on
+// the main table. In the end, the read_row function will manage to return the actual row
+// of interest in the buf parameter.
+//
+// Parameters:
+//              error - result of preceding DB call
+//      [out]   buf - buffer for the row, in MySQL format
+//              keynr - index into key_file that represents DB we are currently operating on.
+//      [in]    row - the row that has been read from the preceding DB call
+//      [in]    found_key - key used to retrieve the row
+//              read_next - if true, DB_NOTFOUND and DB_KEYEMPTY map to HA_ERR_END_OF_FILE, 
+//                  else HA_ERR_KEY_NOT_FOUND, this is a bad parameter to have and this funcitonality
+//                  should not be here
+//
 int ha_tokudb::read_row(int error, uchar * buf, uint keynr, DBT * row, DBT * found_key, bool read_next) {
     TOKUDB_DBUG_ENTER("ha_tokudb::read_row");
+    //
+    // Disreputable error translation: this makes us all puke
+    //
     if (error) {
         if (error == DB_NOTFOUND || error == DB_KEYEMPTY)
             error = read_next ? HA_ERR_END_OF_FILE : HA_ERR_KEY_NOT_FOUND;
         table->status = STATUS_NOT_FOUND;
         TOKUDB_DBUG_RETURN(error);
     }
-    if (hidden_primary_key)
+    //
+    // TODO: figure out the most appropriate place to put this comment
+    // Autogenerated primary keys are are appended to the end of the row, and we extract
+    // its value into current_ident
+    //
+    if (hidden_primary_key) {
         memcpy_fixed(current_ident, (char *) row->data + row->size - TOKUDB_HIDDEN_PRIMARY_KEY_LENGTH, TOKUDB_HIDDEN_PRIMARY_KEY_LENGTH);
+    }
     table->status = 0;
+    //
+    // if the index shows that the table we read the row from was indexed on the primary key,
+    // that means we have our row and can skip
+    // this entire if clause. All that is required is to unpack row.
+    // if the index shows that what we read was from a table that was NOT indexed on the 
+    // primary key, then we must still retrieve the row, as the "row" value is indeed just
+    // a primary key, whose row we must still read
+    //
     if (keynr != primary_key) {
-        /* We only found the primary key.  Now we have to use this to find the row data */
         if (key_read && found_key) {
             // TOKUDB_DBUG_DUMP("key=", found_key->data, found_key->size);
             unpack_key(buf, found_key, keynr);
@@ -1955,12 +1991,17 @@ int ha_tokudb::read_row(int error, uchar * buf, uint keynr, DBT * row, DBT * fou
             }
             TOKUDB_DBUG_RETURN(0);
         }
+        //
+        // create a DBT that has the same data as row,
+        //
         DBT key;
         bzero((void *) &key, sizeof(key));
         key.data = key_buff;
         key.size = row->size;
         memcpy(key_buff, row->data, row->size);
-        /* Read the data into current_row */
+        //
+        // Read the data into current_row
+        //
         current_row.flags = DB_DBT_REALLOC;
         if ((error = file->get(file, transaction, &key, &current_row, 0))) {
             table->status = STATUS_NOT_FOUND;