Updated AVL documentation

src/obiavl.c

@@ -6,7 +6,7 @@
  * @file obiavl.c
  * @author Celine Mercier
  * @date December 3rd 2015
- * @brief Functions handling AVL trees for storing and retrieving bit arrays.
+ * @brief Functions handling AVL trees for storing and retrieving blobs.
  */
 
 

src/obiavl.h

@@ -6,7 +6,7 @@
  * @file obiavl.h
  * @author Celine Mercier
  * @date December 3rd 2015
- * @brief Header file for handling AVL trees for storing and retrieving blobs (i.e. coding for character strings).
+ * @brief Header file for handling AVL trees for storing and retrieving blobs.
  */
 
 
@@ -120,14 +120,13 @@ typedef struct OBIDMS_avl_header {
 	time_t		creation_date;			    	    /**< Date of creation of the file.
 												     */
 	bloom_t 	bloom_filter;			    	    /**< Bloom filter associated with the AVL tree, enabling to know if a value
-													 *   might already be stored in the data associated with the tree.
+													 *   might already be stored in the data referred to by the tree.
      	 	 	 	 	 	 	 	 	 	 	 	 */
 } OBIDMS_avl_header_t, *OBIDMS_avl_header_p;
 
 
 /**
  * @brief OBIDMS AVL tree structure.
- * 		  TODO doc
  */
 typedef struct OBIDMS_avl {
 	OBIDMS_p                	dms;			 			/**< A pointer to the OBIDMS structure to which the AVL tree belongs.
@@ -195,7 +194,7 @@ int obi_avl_exists(OBIDMS_p dms, const char* avl_name);
  * @brief Creates an AVL tree. Fails if it already exists.
  *
  * Note: An AVL tree is made of two files (referred to by two structures).
- * 		 One file contains the indices referring to the data, and the other
+ * 		 One file contains the tree referring to the data, and the other
  * 		 file contains the data itself. The AVL tree as a whole is referred
  * 		 to via the OBIDMS_avl structure. An AVL tree is stored in a directory
  * 		 with the same name, or with the base name of the AVL group if it is
@@ -203,7 +202,8 @@ int obi_avl_exists(OBIDMS_p dms, const char* avl_name);
  *
  * @param dms The OBIDMS to which the AVL tree belongs.
  * @param avl_name The name of the AVL tree.
- * @param avl_idx The index of the AVL tree if it is part of an AVL group.
+ * @param avl_idx The index of the AVL tree if it is part of an AVL group,
+ *        or -1 if it is not part of an AVL group.
  *
  * @returns A pointer to the newly created AVL tree structure.
  * @retval NULL if an error occurred.
@@ -215,16 +215,17 @@ OBIDMS_avl_p obi_create_avl(OBIDMS_p dms, const char* avl_name, int avl_idx);
 
 
 /**
- * @brief Opens an AVL tree. Fails if it does not already exist.
+ * @brief Opens an AVL tree in read-only mode. Fails if it does not already exist.
  *
  * Note: An AVL tree is made of two files (referred to by two structures).
- * 		 One file contains the indices referring to the data, and the other
+ * 		 One file contains the tree referring to the data, and the other
  * 		 file contains the data itself. The AVL tree as a whole is referred
  * 		 to via the OBIDMS_avl structure.
  *
  * @param dms The OBIDMS to which the AVL tree belongs.
  * @param avl_name The name of the AVL tree.
- * @param avl_idx The index of the AVL tree if it is part of an AVL group.
+ * @param avl_idx The index of the AVL tree if it is part of an AVL group,
+ *        or -1 if it is not part of an AVL group.
  *
  * @returns A pointer to the AVL tree structure.
  * @retval NULL if an error occurred.
@@ -272,7 +273,7 @@ OBIDMS_avl_group_p obi_create_avl_group(OBIDMS_p dms, const char* avl_name);
 
 
 /**
- * @brief Opens an AVL tree group.
+ * @brief Opens an AVL tree group in read-only mode.
  *
  * Note: An AVL tree group is composed of multiple AVL trees that all have the
  *       same base name, and an index differentiating them.
@@ -321,6 +322,7 @@ int obi_close_avl_group(OBIDMS_avl_group_p avl_group);
  * @brief Recovers a value (blob) in an AVL tree.
  *
  * @warning The blob recovered must be decoded to get the original value.
+ * @warning The blob recovered is mapped in memory.
  *
  * @param avl A pointer to the AVL tree.
  * @param index The index of the value in the data array.
@@ -334,9 +336,10 @@ Obi_blob_p obi_avl_get(OBIDMS_avl_p avl, index_t index);
 
 
 /**
- * @brief Adds a value (blob) in an AVL tree NOT checking first if it is already in it.		// TODO to discuss
+ * @brief Adds a value (blob) in an AVL tree.
  *
  * @warning The value given must be already be encoded into a blob structure (Obi_blob_t).
+ * @warning If the value is already in the AVL tree, an error will be triggered.		// TODO to discuss
  *
  * @param avl A pointer to the AVL tree.
  * @param value The blob to add in the AVL tree.
@@ -371,6 +374,7 @@ index_t obi_avl_find(OBIDMS_avl_p avl, Obi_blob_p value);
  * @brief Recovers a value (blob) in an AVL tree.
  *
  * @warning The blob recovered must be decoded to get the original value.
+ * @warning The blob recovered is mapped in memory.
  *
  * @param avl_group A pointer to the AVL tree.
  * @param index The index of the value in the data array.