From bce360bbd5a470dad67d98ea73b3f18360f846b6 Mon Sep 17 00:00:00 2001
From: Celine Mercier <celine.mercier@metabarcoding.org>
Date: Thu, 21 Apr 2016 15:08:40 +0200
Subject: [PATCH] Documentation for obiblob indexer API

---
 src/obiblob_indexer.c |  4 --
 src/obiblob_indexer.h | 85 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 84 insertions(+), 5 deletions(-)

diff --git a/src/obiblob_indexer.c b/src/obiblob_indexer.c
index f2a5e85..9669dfe 100644
--- a/src/obiblob_indexer.c
+++ b/src/obiblob_indexer.c
@@ -15,10 +15,6 @@
 
 #include "obiblob_indexer.h"
 #include "obidms.h"
-#include "obiavl.h"
-
-
-#define DEBUG_LEVEL 0	// TODO has to be defined somewhere else (cython compil flag?)
 
 
 inline int obi_indexer_exists(OBIDMS_p dms, const char* name);
diff --git a/src/obiblob_indexer.h b/src/obiblob_indexer.h
index dab9099..5d7335e 100644
--- a/src/obiblob_indexer.h
+++ b/src/obiblob_indexer.h
@@ -33,43 +33,126 @@ typedef OBIDMS_avl_group_p Obi_indexer_p; 		/**< Typedef to refer to the pointer
  	 	 	 	 	 	 	 	 	 	 	 	 */
 
 
-// TODO doc
+/**
+ * @brief Checks if an indexer already exists or not.
+ *
+ * @param dms The OBIDMS to which the indexer belongs.
+ * @param name The name of the indexer.
+ *
+ * @returns A value indicating whether the indexer exists or not.
+ * @retval 1 if the indexer exists.
+ * @retval 0 if the indexer does not exist.
+ * @retval -1 if an error occurred.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 inline int obi_indexer_exists(OBIDMS_p dms, const char* name)
 {
 	return obi_avl_exists(dms, name);
 }
 
 
+/**
+ * @brief Opens an indexer and creates it if it does not already exist.
+ *
+ * @param dms The OBIDMS to which the indexer belongs.
+ * @param name The name of the indexer.
+ *
+ * @returns A pointer to the indexer structure.
+ * @retval NULL if an error occurred.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 inline Obi_indexer_p obi_indexer(OBIDMS_p dms, const char* name)
 {
 	return obi_avl_group(dms, name);
 }
 
 
+/**
+ * @brief Creates an indexer.
+ *
+ * @param dms The OBIDMS to which the indexer belongs.
+ * @param name The name of the indexer.
+ *
+ * @returns A pointer to the AVL tree group structure.
+ * @retval NULL if an error occurred.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 inline Obi_indexer_p obi_create_indexer(OBIDMS_p dms, const char* name)
 {
 	return obi_create_avl_group(dms, name);
 }
 
 
+/**
+ * @brief Opens an indexer.
+ *
+ * @param dms The OBIDMS to which the indexer belongs.
+ * @param name The name of the indexer.
+ *
+ * @returns A pointer to the indexer structure.
+ * @retval NULL if an error occurred.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 inline Obi_indexer_p obi_open_indexer(OBIDMS_p dms, const char* name)
 {
 	return obi_open_avl_group(dms, name);
 }
 
 
+/**
+ * @brief Closes an indexer.
+ *
+ * @param indexer A pointer to the indexer structure to close and free.
+ *
+ * @retval 0 if the operation was successfully completed.
+ * @retval -1 if an error occurred.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 inline int obi_close_indexer(Obi_indexer_p indexer)
 {
 	return obi_close_avl_group(indexer);
 }
 
 
+/**
+ * @brief Indexes a blob in an indexer and returns the index referring to the blob.
+ *
+ * @param indexer A pointer to the indexer.
+ * @param value The blob to index.
+ *
+ * @returns The index of the blob newly added in the indexer.
+ * @retval -1 if an error occurred.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 inline index_t obi_indexer_add(Obi_indexer_p indexer, Obi_blob_p value)
 {
 	return obi_avl_group_add(indexer, value);
 }
 
 
+/**
+ * @brief Recovers a blob from an indexer.
+ *
+ * @param indexer A pointer to the indexer.
+ * @param index The index of the blob in the indexer.
+ *
+ * @returns A pointer to the blob recovered.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 inline Obi_blob_p obi_indexer_get(Obi_indexer_p indexer, index_t idx)
 {
 	return obi_avl_group_get(indexer, idx);