comments updated

diff --git a/ston/ston_ht.h b/ston/ston_ht.h
index 1bd310d..6ab03e7 100644 (file)
--- a/ston/ston_ht.h
+++ b/ston/ston_ht.h
@@ -304,32 +304,34 @@ typedef struct ston_dht_t
   void*      bucket_root;
   size_t     rowsize, bucketsize;
 }* ston_dht;
-
+/* STON DHT API
+   Primary functions for creating hashtables, retrieving pointers to values,
+   iterating over all keys and values, and destroying hashtables. */
 STON_FUNC
 ston_dht  ston_dht_new(uint16_t,uint8_t,void*(*)(size_t),void(*)(void*));
 STON_FUNC
+void*     ston_dht_val(ston_dht,void*);
+STON_FUNC
 ston_dht  ston_dht_free(ston_dht);
 STON_FUNC
-void*     ston_dht_val(ston_dht,void*);
+void      ston_dht_iterate(ston_dht,void(*)(void*,void*,void*),void*);
+/* Recursive functions intended to be called by other functions, above */
 STON_FUNC_STATIC
 STON_FUNC_NOINLINE
 void      ston_dht_free_bucket(ston_dht,void*);
-STON_FUNC
-void      ston_dht_iterate(ston_dht,void(*)(void*,void*,void*),void*);
 STON_FUNC_STATIC
 STON_FUNC_NOINLINE
 void      ston_dht_iterate_r(ston_dht,void*);
-
-// Compatibility macros
+// Compatibility macros - Deprecated
 #define ston_dht32_new(_COL,_ALOC,_FRE) (ston_dht_new(4 * _COL, 4, _ALOC, _FRE))
 #define ston_dht32_row(_HT,_K) ((uint32_t*)((uint8_t*)ston_dht_val(_HT,&(_K)) - 4))
 #define ston_dht32_insertx(_HT,_K,_VP,_OFFS,_N) \
   memcpy((uint32_t*)((uint8_t*)ston_dht_val(_HT,&(_K)) + ((_OFFS - 1) * 4)),_VP,_N * 4)
 
-/* Creates a new bucketted hash table, provided a memory allocation function
-   that takes a single size_t bytes, a memory free function, a column count, and
-   a row count which determines the size of the buckets.
-*/
+/* New dynamic hashtable, provided value bytes, key bytes, allocator function,
+   and free function.  Value bytes and key bytes are respectively constrained to
+   uint16 and uint8 so they can be aligned to hashtables encoded for
+   streaming */
 STON_FUNC
 ston_dht ston_dht_new
 ( uint16_t val_bytes,
@@ -397,7 +399,8 @@ void* ston_dht_val
   return (void*) row + sizeof(void*) + key_bytes;
 }
 
-/* Free the dynamic hash table */
+/* Recursively frees all memory stored in the hashtable, and the hashtable
+   itself */
 STON_FUNC
 struct ston_dht_t* ston_dht_free
 ( struct ston_dht_t* ht )
@@ -409,7 +412,7 @@ struct ston_dht_t* ston_dht_free
   return ht;
 }
 
-/* Recursively free pages by lookup */
+/* Recursive free function for nested buckets */
 STON_FUNC_STATIC
 STON_FUNC_NOINLINE
 void ston_dht_free_bucket
@@ -426,8 +429,10 @@ void ston_dht_free_bucket
   ht->ht_free(bucket);
 }
 
-/* Iterate over each key/value pair and execut 'fn' with key and value as
-   arguments */
+/* Iterate over each key/value pair and execut 'fn' with key, value and
+   user_data as its arguments.  user_data may be anything, even NULL, and is
+   expected to be referenced inside the body of 'fn' as the third argument of
+   'fn' */
 STON_FUNC
 void ston_dht_iterate
 ( struct ston_dht_t* ht,