#3052 document the indexer object relationships and API closes[t:3052]

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

src/indexer.c

@@ -215,9 +215,7 @@ toku_indexer_set_error_callback(DB_INDEXER *indexer,
     return 0;
 }
 
-// returns TRUE  if right of le_cursor
-// returns FALSE if left or equal to le_cursor
-int
+BOOL
 toku_indexer_is_key_right_of_le_cursor(DB_INDEXER *indexer, DB *db, const DBT *key) {
     return is_key_right_of_le_cursor(indexer->i->lec, key, db);
 }

src/indexer.h

 #ifndef TOKU_INDEXER_H
 #define TOKU_INDEXER_H
 
-#if defined(__cplusplus)
-extern "C" {
-#endif
-
-
 /* Copyright (c) 2007-2010 Tokutek Inc.  All rights reserved.
  *
  * The technology is licensed by the Massachusetts Institute of Technology, 
@@ -14,6 +9,32 @@ extern "C" {
  * Serial No. 11/760379 and to the patents and/or patent applications resulting from it.
  */
 
+#if defined(__cplusplus)
+extern "C" {
+#endif
+
+
+// The indexer populates multiple destination db's from the contents of one source db.
+// While the indexes are being built by the indexer, the application may continue to 
+// change the contents of the soruce db.  The changes will be reflected into the destination
+// db's by the indexer.
+//
+// Each indexer references one source db.
+// A source db may have multiple indexers referencing it.
+// Each indexer references one or more destination db's.
+// Each destination db references the one and only indexer that is building it.
+//
+// env must be set to the YDB environment
+// txn must be set to the transaction under which the indexer will run
+// *indexer is set to the address of the indexer object returned by the create function
+// src_db is the source db
+// N is the number of destination db's
+// dest_dbs is an array of pointers to destination db's
+// db_flags is currently unused
+// indexer_flags is currently unused
+//
+// Returns 0 if the indexer has been created and sets *indexer to the indexer object.
+// If an error occurred while creating the indexer object, a non-zero error is returned.
 int toku_indexer_create_indexer(DB_ENV *env,
                                 DB_TXN *txn,
                                 DB_INDEXER **indexer,
@@ -23,21 +44,28 @@ int toku_indexer_create_indexer(DB_ENV *env,
                                 uint32_t db_flags[N],
                                 uint32_t indexer_flags) __attribute__((__visibility__("default")));
 
+// Set the indexer poll function
 int toku_indexer_set_poll_function(DB_INDEXER *indexer,
                                    int (*poll_function)(void *poll_extra,
                                                         float progress),
                                    void *poll_extra);
 
+// Set the indexer error callback
 int toku_indexer_set_error_callback(DB_INDEXER *indexer,
                                     void (*error_cb)(DB *db, int i, int err,
                                                      DBT *key, DBT *val,
                                                      void *error_extra),
                                     void *error_extra);
 
-int toku_indexer_is_key_right_of_le_cursor(DB_INDEXER *indexer, DB *db, const DBT *key);
+// Is the key right of the indexer's leaf entry cursor?
+// Returns TRUE  if right of le_cursor
+// Returns FALSE if left or equal to le_cursor
+BOOL toku_indexer_is_key_right_of_le_cursor(DB_INDEXER *indexer, DB *db, const DBT *key);
 
+// Get the indexer's source db
 DB *toku_indexer_get_src_db(DB_INDEXER *indexer);
 
+// TEST set the indexer's test flags
 void toku_indexer_set_test_only_flags(DB_INDEXER *indexer, int flags) __attribute__((__visibility__("default")));
 
 #define INDEXER_TEST_ONLY_ERROR_CALLBACK 1