documentation: some doxygen comments were added

some initial doxygen comments were added to be able to test the documentation
toolchain

diff --git a/src/murphy-db/include/murphy-db/mqi-types.h b/src/murphy-db/include/murphy-db/mqi-types.h
index a324cd1..154b489 100644 (file)
--- a/src/murphy-db/include/murphy-db/mqi-types.h
+++ b/src/murphy-db/include/murphy-db/mqi-types.h
@@ -4,12 +4,21 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/** maximum number of rows a query can produce */
 #define MQI_QUERY_RESULT_MAX   8192
+/** the maximum number columns a table can have */
 #define MQI_COLUMN_MAX         ((int)(sizeof(mqi_bitfld_t) * 8))
+/** maximum length of a condition table (i.e. array of mqi_cond_entry_t) */
 #define MQI_COND_MAX           64
 #define MQL_PARAMETER_MAX      16
+/** maximum depth for nested transactions */
 #define MQI_TXDEPTH_MAX        16
 
+/**
+ * mqi_handle_t value for nonexisting handle. Zero is a valid handle
+ * thus casting a zero to mqi_handle_t will produce a valid handle
+ * (remeber this when using static mqi_handle_t).
+ */ 
 #define MQI_HANDLE_INVALID     (~((mqi_handle_t)0))
 
 #define MQI_DIMENSION(array)  \

diff --git a/src/murphy-db/include/murphy-db/mql-result.h b/src/murphy-db/include/murphy-db/mql-result.h
index 1cda3a5..c886534 100644 (file)
--- a/src/murphy-db/include/murphy-db/mql-result.h
+++ b/src/murphy-db/include/murphy-db/mql-result.h
@@ -7,22 +7,38 @@
 typedef enum mql_result_type_e  mql_result_type_t;
 typedef struct mql_result_s     mql_result_t;
 
+/** types of mql_result_t structure */
 enum mql_result_type_e {
-    mql_result_error = -1,
+    mql_result_error = -1, /**< error code + error message */
     mql_result_unknown = 0,
-    mql_result_dontcare = mql_result_unknown,
+    mql_result_dontcare = mql_result_unknown, /**< will default */
     mql_result_event,
-    mql_result_columns,
-    mql_result_rows,
-    mql_result_string,
-    mql_result_list,
+    mql_result_columns,    /**< column description of a table */
+    mql_result_rows,       /**< select'ed rows */
+    mql_result_string,     /**< zero terminated ASCII string  */
+    mql_result_list,       /**< array of basic types, (integer, string, etc) */
 };
 
+
+/**
+ * @brief generic return type of MQL opertaions.
+ *
+ * mql_result_type_t is the generic return type  of mql_exec_string()
+ * and mql_exec_statement(). It is either the return status of the
+ * MQL operation or the resulting data. For instance, executing an
+ * insert statement will return a status (ie. mql_result_error type),
+ * while the execution of a select statement will return the selected
+ * rows (ie. mql_result_rows or mql_result_string depending on what
+ * type was requested by mql_exec_string() or mql_exec_statement())
+ *
+ * To access the opaque data use the mql_result_xxx() functions
+ */
 struct mql_result_s {
-    mql_result_type_t  type;
-    uint8_t            data[0];
+    mql_result_type_t  type;       /**< type of the result */
+    uint8_t            data[0];    /**< opaque result data */
 };
 
+
 int              mql_result_is_success(mql_result_t *);
 
 int              mql_result_error_get_code(mql_result_t *);

diff --git a/src/murphy-db/include/murphy-db/mql.h b/src/murphy-db/include/murphy-db/mql.h
index e324d97..60c3bbb 100644 (file)
--- a/src/murphy-db/include/murphy-db/mql.h
+++ b/src/murphy-db/include/murphy-db/mql.h
@@ -4,9 +4,128 @@
 #include <murphy-db/mql-statement.h>
 #include <murphy-db/mql-trigger.h>
 
-int mql_exec_file(const char *);
-mql_result_t *mql_exec_string(mql_result_type_t, const char *);
-mql_statement_t *mql_precompile(const char *);
+/**
+ * @brief execute a series of MQL statements stored in a file
+ *
+ * This function is to execute a series of MQL statements stored in a file.
+ * The MQL statements supposed to separated with ';'. No ';' shall follow
+ * the last statement. In case of an error the the execution of the statements
+ * will stop, errno is set and the function will return -1. Error messages
+ * will be written to stderr. Currently there is no programmatic way to figure
+ * out what statement failed and how many statement were sucessfully executed.
+ *
+ * @param [in] file  is the path of the file, eg. "~/mql/create_table.mql"
+ *
+ * @return If the execution failed mql_exec_file() returns -1 and errno is
+ *         set. It returns 0 if all the statements in the file were
+ *         successfully executed.
+ */
+int mql_exec_file(const char *file);
+
+/**
+ * @brief execute an MQL statement
+ *
+ * This function is to execute a single MQL statement. The result of the
+ * operation is returned in a data structure. The returned result can be
+ * either the type of the requested result or an error result. It is
+ * recommended that the returned result will be checked first by calling
+ * mql_result_is_success() function.
+ *
+ * To process a result the relevant mql_result_xxx() functions are to use.
+ * Values returned by the mql_result_xxx() functions are valid till the
+ * next MQL commit or rollback. For instance accessing the returned strings
+ * after a commit might lead to segfaults.
+ *
+ * The returned result should be freed by mql_result_free().
+ *
+ * @param [in] result_type   specifies the expected type of the returned
+ *                           result. However, if the execution failed for
+ *                           some reason the returned result will have
+ *                           mql_result_error type.
+ *
+ * @param [in] statement     is the string of the MQL statement to execute
+ *
+ * @code
+ *    #include <stdio.h>
+ *    #include <murphy-db/mql.h>
+ *
+ *    const char *statement = "SELECT * FROM persons WHERE name = 'murphy'";
+ *    mql_result_t *r = mql_exec_string(mql_result_type_string, statement);
+ *
+ *    if (mql_result_is_success(r))
+ *      printf("the result of the query:\n%s\n", r->mql_result_string_get(r));
+ * @endcode
+ */
+mql_result_t *mql_exec_string(mql_result_type_t result_type, 
+                              const char *statement);
+
+/**
+ * @brief precompile an MQL statement
+ *
+ * @param [in] statement     is the string of the MQL statement to execute
+ *
+ * For performance optimisation purposes the execution of MQL statements
+ * can be done in a precompilation and an execution phase. This allows
+ * a single first phase for frequently executed MQL statements followed
+ * by a series of second phase.
+ *
+ * Precompilation is the parsing of the ASCII MQL statement, making all the
+ * necessary lookups, generating the data structures what the the underlying
+ * MQI interface needs for the execution and packing all these information
+ * into a dynamically allocated memory block.
+ *
+ * mql_bind_value() can be used to assign values for parameters of the
+ * preecompiled statement, if any.
+ *
+ * A precompiled statement can be executed by mql_exec_statement().
+ *
+ * Precompiled statements should be freed by mql_statement_free() when they
+ * are not needed any more.
+ *
+ * @return mql_precompile() returns a pointer to the precompile statement in
+ *         case the precompilation succeeded or NULL if the precompilation
+ *         failed. In the later case errno is set to give a clue what went
+ *         wrong.
+ *         
+ *         Note that a successfull precompilation do not garantie the
+ *         successfull execution of the precompiled statement. For instance
+ *         a successfully precompiled of a SELECT statement will fail
+ *         if the table, it tries to operate on, was meanwhile deleted.
+ * @code
+ *    #include <stdio.h>
+ *    #include <string.h>
+ *    #include <errno.h>
+ *    #include <murphy-db/mql.h>
+ *
+ *    const char *group[] = {"joe", "jack", "murphy", NULL};
+ *    const char *query = "SELECT name, email FROM persons WHERE name = %s";
+ *    mql_statement_t *stmnt;
+ *    mql_result_t *r;
+ *    char *person;
+ *    int i;
+ *
+ *    if ((stmnt = mql_precompilation(query)) == NULL)
+ *      printf("precompilation failed (%d): %s\n", errno, strerror(errno));
+ *    else {
+ *      for (i = 0;  (person = group[i]) != NULL;  i++) {
+ *        if (mql_bind_value(stmnt, 0,mqi_varchar, person) < 0)
+ *          printf("bindig failed (%d): %s\n", errno, strerror(errno));
+ *        else {
+ *          r = mql_exec_statement(mql_result_string, stmnt);
+ *          if (!mql_result_is_success(r))
+ *            printf("exec failed %d: %s\n",
+ *                   mql_result_error_get_code(r),
+ *                   mql_result_erro_get_message(r));
+ *          else
+ *            printf("query %d\n%s\n", i, mql_result_string_get(r));
+ *        }
+ *      }
+ *    }
+ *
+ *    mql_statement_free(stmnt);
+ * @endcode
+ */
+mql_statement_t *mql_precompile(const char *statement);
 
 
 #endif  /* __MQL_MQL_H__ */

diff --git a/src/murphy-db/mql/mql-parser.y b/src/murphy-db/mql/mql-parser.y
index 87d3e64..cb4b9f2 100644 (file)
--- a/src/murphy-db/mql/mql-parser.y
+++ b/src/murphy-db/mql/mql-parser.y
@@ -1325,7 +1325,7 @@ int mql_exec_file(const char *path)
     mode   = mql_mode_parser;
     rtype  = mql_result_unknown;
     mqlbuf = NULL;
-    mqlout = stdout;
+    mqlout = stderr;
     
     if (!path) {
         mqlin = fileno(stdin);