Updated the documentation for obidms functions

src/obidms.c

@@ -420,7 +420,7 @@ OBIDMS_p obi_open_dms(const char* dms_name)
 	dms->opened_columns = (Opened_columns_list_p) malloc(sizeof(Opened_columns_list_t));
 	(dms->opened_columns)->nb_opened_columns = 0;
 
-	// Initialize the list of opened indexers	// TODO should be handled somewhere else?
+	// Initialize the list of opened indexers
 	dms->opened_indexers = (Opened_indexers_list_p) malloc(sizeof(Opened_indexers_list_t));
 	(dms->opened_indexers)->nb_opened_indexers = 0;
 
@@ -463,7 +463,7 @@ int obi_close_dms(OBIDMS_p dms)
 			free(dms);
 			return -1;
 		}
-		if (closedir(dms->indexer_directory) < 0)		// TODO should be handled somewhere else?
+		if (closedir(dms->indexer_directory) < 0)
 		{
 			obi_set_errno(OBI_INDEXER_ERROR);
 			obidebug(1, "\nError closing an indexer directory");
@@ -488,10 +488,10 @@ int obi_dms_is_column_name_in_list(OBIDMS_p dms, const char* column_name)
 	{
 		if (!strcmp(((*((columns_list->columns)+i))->header)->name, column_name))
 		{	// Found it
-			return 0;
+			return 1;
 		}
 	}
-	return 1;
+	return 0;
 }
 
 
@@ -512,7 +512,7 @@ OBIDMS_column_p obi_dms_get_column_from_list(OBIDMS_p dms, const char* column_na
 }
 
 
-void obi_dms_list_column(OBIDMS_p dms, OBIDMS_column_p column)
+void obi_dms_list_column(OBIDMS_p dms, OBIDMS_column_p column)	// TODO add check if column already in list?
 {
 	*(((dms->opened_columns)->columns)+((dms->opened_columns)->nb_opened_columns)) = column;
 	((dms->opened_columns)->nb_opened_columns)++;
@@ -551,7 +551,7 @@ Obi_indexer_p obi_dms_get_indexer_from_list(OBIDMS_p dms, const char* indexer_na
 
 	for (i=0; i < (indexers_list->nb_opened_indexers); i++)
 	{
-		if (!strcmp(((indexers_list->indexers)[i])->name, indexer_name))	// TODO it references something in AVL_group struct
+		if (!strcmp(((indexers_list->indexers)[i])->name, indexer_name))	// TODO get_name function indexer
 		{	// Found the indexer already opened, return it
 			return (indexers_list->indexers)[i];
 		}
@@ -602,8 +602,8 @@ char* obi_dms_get_dms_path(OBIDMS_p dms)
 		return NULL;
 	}
 
-	if (getcwd(full_path, MAX_PATH_LEN) == NULL)	// TODO not sure at all about this because the DMS must be in the working directory.
-	{												// Maybe better to store when opening, but opening function seems to assume that too.
+	if (getcwd(full_path, MAX_PATH_LEN) == NULL)	// TODO store when opening
+	{
 		obi_set_errno(OBI_UTILS_ERROR);
 		obidebug(1, "\nError getting the path to a file or directory");
 		return NULL;

src/obidms.h

@@ -23,8 +23,7 @@
 #include <stdbool.h>
 
 #include "obierrno.h"
-//#include "obidmscolumn.h"
-//#include "obiblob_indexer.h"
+#include "obitypes.h"
 
 
 #define OBIDMS_MAX_NAME (2048) 	    			/**< The maximum length of an OBIDMS name.
@@ -42,26 +41,33 @@
  	 	 	 	 	 	 	 	 	 	 	 	 */
 
 
-typedef int32_t obiversion_t; 	/**< TODO put dans obitypes.h
-                                 */
+struct OBIDMS_column;							/**< Declarations to avoid circular dependencies. */
+typedef struct OBIDMS_column* OBIDMS_column_p;  /**< Declarations to avoid circular dependencies. */
 
-
-struct OBIDMS_column;		// TODO
-typedef struct OBIDMS_column* OBIDMS_column_p;
-
-typedef struct Opened_columns_list {		// TODO Handle the problem linked to columns with the same name + means only one version
-	int	 		 			nb_opened_columns;
-	OBIDMS_column_p		 	columns[MAX_NB_OPENED_COLUMNS];
+/**
+ * @brief Structure listing the columns opened in a DMS, identified by their name and version number.
+ */
+typedef struct Opened_columns_list {
+	int	 		 			nb_opened_columns;	  				/**< Number of opened columns.
+	 	   	   	   	   	   	   	   	   	   	   	   	   	   	   	 */
+	OBIDMS_column_p		 	columns[MAX_NB_OPENED_COLUMNS];	  	/**< Array of pointers on the opened columns.
+ 	   	   	   	   	   	   	 	 	 	 	 	 	 	 	 	 */
 } Opened_columns_list_t, *Opened_columns_list_p;
 
 
-struct OBIDMS_avl_group;		// TODO
-typedef struct OBIDMS_avl_group* OBIDMS_avl_group_p;
-typedef OBIDMS_avl_group_p Obi_indexer_p;
+// TODO Need to find a way to not refer to AVLs specifically
+struct OBIDMS_avl_group;								/**< Declarations to avoid circular dependencies. */
+typedef struct OBIDMS_avl_group* OBIDMS_avl_group_p;	/**< Declarations to avoid circular dependencies. */
+typedef OBIDMS_avl_group_p Obi_indexer_p;				/**< Declarations to avoid circular dependencies. */
 
+/**
+ * @brief Structure listing the indexers opened in a DMS, identified by their name.
+ */
 typedef struct Opened_indexers_list {
-	int		 		 		nb_opened_indexers;
-	Obi_indexer_p		    indexers[MAX_NB_OPENED_INDEXERS];
+	int		 		 		nb_opened_indexers;					/**< Number of opened indexers.
+	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
+	Obi_indexer_p		    indexers[MAX_NB_OPENED_INDEXERS];	/**< Array of pointers on the opened indexers.
+	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 */
 } Opened_indexers_list_t, *Opened_indexers_list_p;
 
 
@@ -81,10 +87,10 @@ typedef struct OBIDMS {
 	int     				dir_fd;								/**< The file descriptor of the directory entry
 																 *   usable to refer and scan the database directory.
 																 */
-	DIR*					indexer_directory;						/**< A directory entry usable to
+	DIR*					indexer_directory;					/**< A directory entry usable to
 																 *   refer and scan the indexer directory.
 																 */
-	int						indexer_dir_fd;							/**< The file descriptor of the directory entry
+	int						indexer_dir_fd;						/**< The file descriptor of the directory entry
 																 *   usable to refer and scan the indexer directory.
 																 */
 	bool					little_endian;						/**< Endianness of the database.
@@ -101,7 +107,7 @@ typedef struct OBIDMS {
  *
  * @param dms_name A pointer to a C string containing the name of the database.
  *
- * @returns An integer value indicating the status of the database
+ * @returns An integer value indicating the status of the database.
  * @retval 1 if the database exists.
  * @retval 0 if the database does not exist.
  * @retval -1 if an error occurred.
@@ -186,60 +192,138 @@ OBIDMS_p obi_dms(const char* dms_name);
 int obi_close_dms(OBIDMS_p dms);
 
 
-// TODO doc
+/**
+ * @brief Checks if a column with a given name is in the list of opened columns.
+ *
+ * @warning: Checking only the name means that the column can be of any version.
+ *
+ * @param dms The OBIDMS.
+ * @param column_name The column name that should be looked for.
+ *
+ * @returns An integer value indicating whether there is at least one column with that name
+ * 			in the list of opened columns.
+ * @retval 0 if there is at least one column with that name in the list of opened columns.
+ * @retval 1 if there is no column with that name in the list of opened columns.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 int obi_dms_is_column_name_in_list(OBIDMS_p dms, const char* column_name);
 
 
+/**
+ * @brief Returns a column identified by its name and its version number from the list of opened columns.
+ *
+ * @param dms The OBIDMS.
+ * @param column_name The column name that should be looked for.
+ * @param version The version number of the column that should be looked for.
+ *
+ * @returns A pointer on the column if it was found in the list of opened columns.
+ * @retval NULL if the column was not found in the list of opened columns.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 OBIDMS_column_p obi_dms_get_column_from_list(OBIDMS_p dms, const char* column_name, obiversion_t version);
 
 
+/**
+ * @brief Adds a column identified by its name and its version number in the list of opened columns.
+ *
+ * @param dms The OBIDMS.
+ * @param column A pointer on the column that should be added in the list of opened columns.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 void obi_dms_list_column(OBIDMS_p dms, OBIDMS_column_p column);
 
 
+/**
+ * @brief Removes a column identified by its name and its version number from the list of opened columns.
+ *
+ * @param dms The OBIDMS.
+ * @param column A pointer on the column that should be removed from the list of opened columns.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 int obi_dms_unlist_column(OBIDMS_p dms, OBIDMS_column_p column);
 
 
+/**
+ * @brief Returns an indexer identified by its name from the list of opened indexers.
+ *
+ * @param dms The OBIDMS.
+ * @param indexer_name The indexer name that should be looked for.
+ *
+ * @returns A pointer on the indexer if it was found in the list of opened indexers.
+ * @retval NULL if the indexer was not found in the list of opened indexers.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 Obi_indexer_p obi_dms_get_indexer_from_list(OBIDMS_p dms, const char* indexer_name);
 
 
+/**
+ * @brief Adds an indexer identified by its name in the list of opened indexers.
+ *
+ * @param dms The OBIDMS.
+ * @param indexer A pointer on the indexer that should be added in the list of opened indexers.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 void obi_dms_list_indexer(OBIDMS_p dms, Obi_indexer_p indexer);
 
 
+/**
+ * @brief Removes an indexer identified by its name from the list of opened indexers.
+ *
+ * @param dms The OBIDMS.
+ * @param column A pointer on the indexer that should be removed from the list of opened indexers.
+ *
+ * @since April 2016
+ * @author Celine Mercier (celine.mercier@metabarcoding.org)
+ */
 int obi_dms_unlist_indexer(OBIDMS_p dms, Obi_indexer_p indexer);
 
 
+/**
+ * Function meant to disappear soon
+ */
 char* obi_dms_get_path(OBIDMS_p dms);
 
 
-/**	TODO
- * @brief Internal function getting the full path of a file or a directory from its
- *        path relative to a directory file descriptor.
+/**
+ * @brief Gets the full path of a file or a directory from its
+ *        path relative to the DMS.
  *
  * @warning The returned pointer has to be freed by the caller.
  *
- * @param directory_file_descriptor The file descriptor for the directory to which
- * 									path_name is relative.
- * @param path_name The path name for the file or directory, relative to directory_file_descriptor.
+ * @param dms The DMS to which path_name is relative.
+ * @param path_name The path name for the file or directory, relative to the DMS.
  *
  * @returns A pointer to the full path.
  * @retval NULL if an error occurred.
  *
- * @since June 2015
+ * @since April 2016
  * @author Celine Mercier (celine.mercier@metabarcoding.org)
  */
 char* obi_dms_get_full_path(OBIDMS_p dms, const char* path_name);
 
 
 /**
- * @brief Replacement function for opendirat() : open a directory relative to a directory file descriptor.
+ * @brief Opens a directory relative to the DMS.
  *
- * @param directory_file_descriptor The file descriptor for the directory in which the directory should be opened.
- * @param path_name The path name for the directory to be opened, relative to directory_file_descriptor.
+ * @param dms The DMS to which path_name is relative.
+ * @param path_name The path name for the directory to be opened, relative to the DMS.
  *
- * @returns The file descriptor of the opened directory.
+ * @returns The directory stream of the opened directory.
  * @retval NULL if an error occurred.
  *
- * @since June 2015
+ * @since April 2016
  * @author Celine Mercier (celine.mercier@metabarcoding.org)
  */
 DIR* opendir_in_dms(OBIDMS_p dms, const char* path_name);