Added comments to sqlite.[ch]

1 files changed, 71 insertions, 27 deletions

diff --git a/database/sqlite/sqlite.h b/database/sqlite/sqlite.h
index 67b231d..ce482e4 100644
--- a/database/sqlite/sqlite.h
+++ b/database/sqlite/sqlite.h
@@ -19,6 +19,15 @@
  *
  */
 
+/**
+ * @file   sqlite.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief  Generic functions to simplify the SQLite3 integration.
+ *
+ */
+
 #ifndef   	SQLITE_H_
 # define   	SQLITE_H_
 
@@ -28,49 +37,85 @@
 #endif
 #include <eurephiadb_mapping.h>
 
+/**
+ *  Defines XML field types, used when extracting SQLite3 results directly into an xmlNode
+ */
 typedef enum _xmlFieldType { XML_ATTR, XML_NODE } xmlFieldType;
 
+/**
+ * Contains information about all fields/columns in an SQLite3 result.
+ * It also keeps track over the length of the longest record/field value in the given field.
+ *
+ * This struct is built up as a dual-way chain pointer ring.  So you need to keep an eye
+ * on the fieldid value to know if you have gone one round or not.
+ */
 typedef struct __sqlite_header {
-        unsigned int fieldid;
-        char *name;
+        unsigned int fieldid;   /**< Numeric field ID, starts at 1 and increases */
+        char *name;             /**< Name of the field/column */
         // char *type;
-        size_t namelength;
-        size_t maxvaluelength;
-        struct __sqlite_header *next;
-        struct __sqlite_header *prev;
+        size_t namelength;      /**< Length of the field name */
+        size_t maxvaluelength;  /**< Length of the longest record in this column */
+        struct __sqlite_header *next; /**< Pointer to the next field */
+        struct __sqlite_header *prev; /**< Pointer to the previous field */
 } _sqlite_header;
 
 
+/**
+ * Contains information about a particular data cell.  That means one specific record
+ * in one specific column.
+ *
+ * This struct is built up as a dual-way chain pointer ring.  So you need to keep an eye
+ * on the fieldid and/or tupleid value to know if you have gone one round or not.
+ */
 typedef struct __sqlite_tuples {
-        unsigned int tupleid;
-        unsigned int fieldid;
-        char *value;
-        size_t length;
-        _sqlite_header *header;
-        struct __sqlite_tuples *nextfield;
-        struct __sqlite_tuples *prevfield;
-        struct __sqlite_tuples *nexttuple;
-        struct __sqlite_tuples *prevtuple;
+        unsigned int tupleid;   /**< Defines the "record number" */
+        unsigned int fieldid;   /**< Defines the field ID this record belongs to */
+        char *value;            /**< Pointer to the value of this field */
+        size_t length;          /**< Length of the value of this field */
+        _sqlite_header *header; /**< A pointer to the header record with more info about this field/column */
+        struct __sqlite_tuples *nextfield; /**< Pointer to the same record, but the next field in it */
+        struct __sqlite_tuples *prevfield; /**< Pointer to the same record, but the previous field in it */
+        struct __sqlite_tuples *nexttuple; /**< Pointer to the same field, but the next record */
+        struct __sqlite_tuples *prevtuple; /**< Pointer to the same field, but the previous record */
 } _sqlite_tuples;
 
 
+/**
+ * The main definition of the dbresult strucutre.  This structure keeps the
+ * complete information about both fields and values of all records from a query.
+ *
+ * This structure keeps to "search" pointers.  This is used when the sqlite_get_value() or
+ * sqlite_xml_value() functions are called.  These pointers will point at the last record being looked
+ * up, so that if you do sequencial look ups, it will not loop through the whole chain from the start.
+ * Even if you go a little bit back an forth, it will find the quickest way to avoid as many iterations
+ * as possible.
+ */
 typedef struct __sqlite_dbresult {
-        // start of the chains
-        _sqlite_tuples *tuples;
-        _sqlite_header *headerrec;
-        size_t num_tuples;
-        size_t num_fields;
-        sqlite_int64 last_insert_id;
-	int affected_rows;
+        // Query results
+        _sqlite_tuples *tuples;       /**< Pointer to the chains which contains field values */
+        _sqlite_header *headerrec;    /**< Pointer to the chains with info about the field/columns */
+        size_t num_tuples;            /**< Number of records received in the SELECT query */
+        size_t num_fields;            /**< Number of fields for each record */
+        sqlite_int64 last_insert_id;  /**< Reference to the last record from a INSERT INTO statement */
+	int affected_rows;            /**< How many records where INSERTed, UPDATEd or DELETEd */
 
-        // Used for search functions
-        _sqlite_tuples *srch_tuples;
-        _sqlite_header *srch_headerrec;
+        // "Search" pointers
+        _sqlite_tuples *srch_tuples;    /**< "Cache" of the last record being looked up */
+        _sqlite_header *srch_headerrec; /**< "Cache" of the last header record being looked up */
 } dbresult;
 
+
+/**
+ * Enumeration of suported SQL queries via the sqlite_query_mapped() API
+ */
 typedef enum _SQLqueryType { SQL_SELECT, SQL_INSERT, SQL_UPDATE, SQL_DELETE } SQLqueryType;
 
-#ifndef SQLITE_C
+/**
+ * Free up a dbresult structure.  This is the public interface for the
+ * internal function _sqlite_free_results()
+ *
+ * @param r Pointer to the dbresult to be freed
+ */
 #define sqlite_free_results(r) { _sqlite_free_results(r); r = NULL; }
 void _sqlite_free_results(dbresult *);
 dbresult *sqlite_query(eurephiaCTX *ctx, const char *, ...);
@@ -83,6 +128,5 @@ xmlNodePtr sqlite_xml_value(xmlNodePtr node, xmlFieldType xmltyp, char *name, db
 void sqlite_dump_result(FILE *, dbresult *);
 int sqlite_get_numtuples(dbresult *);
 int sqlite_get_affected_rows(dbresult *);
-#endif
 
 #endif 	    /* !SQLITE_H_ */