Lock tree, range tree documentation.

git-svn-id: file:///svn/tokudb@2331 c7de825b-a66e-492c-adef-691d508d4ae1

src/range_tree/rangetree.h

@@ -30,8 +30,6 @@ typedef struct __toku_point toku_point;
 
 /** \brief Range with value
     Represents a range of data with an associated value.
-    Parameters are never modified on failure with the exception of
-    buf and buflen.
  */
 typedef struct {
 	toku_point* left;  /**< Left end-point */
@@ -39,6 +37,9 @@ typedef struct {
 	DB_TXN*     data;  /**< Data associated with the range */
 } toku_range;
 
+/** \brief Parameters are never modified on failure with the exception of
+    buf and buflen.
+ */
 struct __toku_range_tree;
 
 /** Export the internal representation to a sensible name */
@@ -62,7 +63,7 @@ int toku_rt_get_allow_overlaps(toku_range_tree* tree, BOOL* allowed);
     \param ptree            Points to the new range tree if create is successful 
     \param end_cmp          User provided function to compare end points.
                             Return value conforms to cmp in qsort(3). 
-                          It must be commutative.
+                            It is assumed to define a total order.
     \param data_cmp         User provided function to compare data values.
                             Return value conforms to cmp in qsort(3). 
     \param allow_overlaps   Whether ranges in this range tree are permitted 
@@ -84,11 +85,14 @@ int toku_rt_create(toku_range_tree** ptree,
 
 /**
     Destroys and frees a range tree.
+
+    \param tree             The range tree to close.
+    
     \return
     - 0:                    Success.
     - EINVAL:               If tree is NULL.
  */
-int toku_rt_close(toku_range_tree* tree  /**< The range tree to free */);
+int toku_rt_close(toku_range_tree* tree);
 
 /**
     Finds ranges in the range tree that overlap a query range.
@@ -103,9 +107,10 @@ int toku_rt_close(toku_range_tree* tree  /**< The range tree to free */);
                     NOTE: buf must have been dynamically allocated i.e. via 
                     malloc(3), calloc(3), etc.
                     The buffer will not be modified unless it is too small.
-   \param buflen   A pointer to the lenfth of the buffer.  
+    \param buflen   A pointer to the current length of the buffer.  
                     If the buffer is increased, then buflen will be updated. 
-   \param numfound The number of ranges found. This will necessarily be <= k.
+    \param numfound The number of ranges found. This will necessarily be <= k
+                    unless k == 0.
                     If k != 0 && numfound == k, there may be additional
                     ranges that overlap the queried range but were skipped
                     to accomodate the request of k. 
@@ -114,8 +119,8 @@ int toku_rt_close(toku_range_tree* tree  /**< The range tree to free */);
     - 0:             Success.
     - EINVAL:        If any pointer argument is NULL. If range.data != NULL.
                      If buflen == 0.
-   - Other exit codes may be forwarded from underlying system calls but only
-     if buf is not large enough.
+    - Other exit codes may be forwarded from underlying system calls if buf is
+     not large enough.
 
     Growth direction: It may be useful in the future to add an extra out 
     parameter to specify whether more elements exist in the tree that overlap 
@@ -134,8 +139,8 @@ int toku_rt_find(toku_range_tree* tree,toku_range* query, u_int32_t k,
     \return
     - 0:            Success.
     - EINVAL:       If any pointer argument is NULL.
-    - EDOM:           If the exact range (left, right, and data) already
-                      exists in the tree.
+    - EDOM:         If an equivalent range (left, right, and data according to
+                    end_cmp and data_cmp) already exists in the tree.
                     If an overlapping range exists in the tree and
                     allow_overlaps == FALSE.
     - Other exit codes may be forwarded from underlying system calls.