From b21c17ae91e94625b0fe24717261e92bb9218be0 Mon Sep 17 00:00:00 2001
From: Zardosht Kasheff <zardosht@tokutek.com>
Date: Wed, 17 Apr 2013 00:01:41 -0400
Subject: [PATCH] addresses #686 add comments to understand how rnd_pos and
 position relate to each other and how they work

git-svn-id: file:///svn/mysql/tokudb-engine/src@3638 c7de825b-a66e-492c-adef-691d508d4ae1
---
 storage/tokudb/ha_tokudb.cc | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/storage/tokudb/ha_tokudb.cc b/storage/tokudb/ha_tokudb.cc
index de8fd130f83..8aa7856e270 100644
--- a/storage/tokudb/ha_tokudb.cc
+++ b/storage/tokudb/ha_tokudb.cc
@@ -2123,7 +2123,6 @@ return END_OF_FILE instead of just NOT_FOUND
 // specified in keynr. Fetches the row if any
 // Parameters:
 //      [out]       buf - buffer for the  returned row
-//                    keynr - index to use
 //      [in]         key - key value, according to InnoDB, if NULL, 
 //                              position cursor at start or end of index,
 //                              not sure if this is done now
@@ -2415,12 +2414,15 @@ DBT *ha_tokudb::get_pos(DBT * to, uchar * pos) {
 }
 
 //
-// Retrieves a row with based on the reference pos
+// Retrieves a row with based on the primary key saved in pos
+// rnd_pos(), along ha_tokudb::with position(), is used for non-sequential queries.
+// the format of pos is such that position() saves a primary key in the format,
+// and rnd_pos extracts the primary key in that format
+// After extracting the primery key, rnd_pos proceeds to do a query
 // Parameters:
 //      [out]   buf - buffer for the row
-//      [in]    pos - primary key value of the row, according to 
-//                    Understanding MySQL Internals, interpretation of pos is 
-//                    up to the storage engine
+//      [in]    pos - primary key value of the row, this buffer is created
+//                      in ha_tokudb::position()
 // Returns:
 //      0 on success
 //      HA_ERR_KEY_NOT_FOUND if not found
@@ -2456,6 +2458,14 @@ int ha_tokudb::rnd_pos(uchar * buf, uchar * pos) {
   nothing
 */
 
+//
+// Saves the primary key in a format that will be interpreted by rnd_pos()
+// rnd_pos(), along ha_tokudb::with position(), is used for non-sequential queries.
+// the format of pos is such that position() saves a primary key in the format,
+// and rnd_pos extracts the primary key in that format
+// Parameters:
+//      [out]   record - buffer storing the primary key
+//
 void ha_tokudb::position(const uchar * record) {
     TOKUDB_DBUG_ENTER("ha_tokudb::position");
     DBT key;