Commit 043e70ff by Celine Mercier

Updated AVL documentation

parent 66021367
......@@ -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.
*/
......
......@@ -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.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment