- small doxygen updates (group, syntax), small docs update

- patch provided from Olle E. Johansson, closes #2025079


git-svn-id: https://openser.svn.sourceforge.net/svnroot/openser/trunk@4505 689a6050-402a-0410-94f2-e92a70836424

lib/srdb1/db.c

@@ -29,8 +29,11 @@
 
 /**
  * \file db/db.c
+ * \ingroup db
  * \brief Generic Database Interface
  *
+ */
+/*! \defgroup db DB: The OpenSER generic database interface
  * This is a generic database interface for modules that need to utilize a
  * database. The interface should be used by all modules that access database.
  * The interface will be independent of the underlying database server.
@@ -41,6 +44,17 @@
  *
  * If you want to see more complicated examples of how the API could be used,
  * take a look at the sources of the usrloc or auth modules.
+ * - \ref usrloc
+ * - \ref auth
+ *
+ * Implemented modules
+ * - \ref db_berkeley
+ * - \ref db_flatstore
+ * - \ref db_text
+ * - \ref db_mysql
+ * - \ref db_oracle
+ * - \ref db_postgres
+ * - \ref db_unixodbc
  */
 
 #include "../dprint.h"
@@ -52,8 +66,7 @@
 #include "db_pool.h"
 #include "db.h"
 
-/** maximal length of a SQL URL */
-static unsigned int MAX_URL_LENGTH = 255;
+static unsigned int MAX_URL_LENGTH = 255;	/*!< maximum length of a SQL URL */
 
 
 int db_check_api(db_func_t* dbf, char *mname)
@@ -127,9 +140,9 @@ error:
 	return -1;
 }
 
-/* fills mydbf with the corresponding db module callbacks
- * returns 0 on success, -1 on error
- * on error mydbf will contain only 0s */
+/*! \brief fills mydbf with the corresponding db module callbacks
+ * \return returns 0 on success, -1 on error
+ * \note on error mydbf will contain only 0s */
 int db_bind_mod(const str* mod, db_func_t* mydbf)
 {
 	char* tmp, *p;
@@ -222,9 +235,9 @@ error:
 }
 
 
-/*
+/*! \brief
  * Initialize database module
- * No function should be called before this
+ * \note No function should be called before this
  */
 db_con_t* db_do_init(const str* url, void* (*new_connection)())
 {
@@ -242,7 +255,7 @@ db_con_t* db_do_init(const str* url, void* (*new_connection)())
 	}
 	if (url->len > MAX_URL_LENGTH)
 	{
-		LM_ERR("SQL URL too long\n");
+		LM_ERR("The configured db_url is too long\n");
 		return 0;
 	}
 	
@@ -285,9 +298,9 @@ db_con_t* db_do_init(const str* url, void* (*new_connection)())
 }
 
 
-/*
+/*! \brief
  * Shut down database module
- * No function should be called after this
+ * \note No function should be called after this
  */
 void db_do_close(db_con_t* _h, void (*free_connection)())
 {
@@ -308,9 +321,9 @@ void db_do_close(db_con_t* _h, void (*free_connection)())
 
 
 
-/*
+/*! \brief
  * Get version of a table
- * If there is no row for the given table, return version 0
+ * \return If there is no row for the given table, return version 0
  */
 int db_table_version(const db_func_t* dbf, db_con_t* connection, const str* table)
 {
@@ -373,7 +386,7 @@ int db_table_version(const db_func_t* dbf, db_con_t* connection, const str* tabl
 	return ret;
 }
 
-/*
+/*! \brief
  * Check the table version
  * 0 means ok, -1 means an error occured
  */
@@ -384,13 +397,13 @@ int db_check_table_version(db_func_t* dbf, db_con_t* dbh, const str* table, cons
 		LM_ERR("querying version for table %.*s\n", table->len, table->s);
 		return -1;
 	} else if (ver != version) {
-		LM_ERR("invalid version %d for table %.*s found, espected %d\n", ver, table->len, table->s, version);
+		LM_ERR("invalid version %d for table %.*s found, expected %d (check table structure and table \"version\")\n", ver, table->len, table->s, version);
 		return -1;
 	}
 	return 0;
 }
 
-/*
+/*! \brief
  * Store name of table that will be used by
  * subsequent database functions
  */

lib/srdb1/db.h

@@ -23,6 +23,8 @@
 
 /**
  * \file db/db.h
+ * \ingroup db
+ * \ref db.c
  * \brief Generic Database Interface
  *
  * This is a generic database interface for modules that need to utilize a

lib/srdb1/db_cap.h

@@ -21,8 +21,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/**
+/*!
  * \file db_cap.h
+ * \ingroup db
  * \brief Data structures that represents capabilities in the database.
  *
  * This file defines data structures that represents certain database
@@ -34,31 +35,31 @@
 #define DB_CAP_H
 
 
-/**
+/*! \brief
  * Represents the capabilities that a database driver supports.
  */
 typedef enum db_cap {
-	DB_CAP_QUERY =     1 << 0,  /**< driver can perform queries                                     */
-	DB_CAP_RAW_QUERY = 1 << 1,  /**< driver can perform raw queries                                 */
-	DB_CAP_INSERT =    1 << 2,  /**< driver can insert data                                         */
-	DB_CAP_DELETE =    1 << 3,  /**< driver can delete data                                         */
-	DB_CAP_UPDATE =    1 << 4,  /**< driver can update data                                         */
-	DB_CAP_REPLACE =   1 << 5,  /**< driver can replace (also known as INSERT OR UPDATE) data       */
-	DB_CAP_FETCH   =   1 << 6,  /**< driver supports fetch result queries                           */
-	DB_CAP_LAST_INSERTED_ID = 1 << 7,  /**< driver can return the ID of the last insert operation   */
- 	DB_CAP_INSERT_UPDATE = 1 << 8 /**< driver can insert data into database and update on duplicate */
+	DB_CAP_QUERY =     1 << 0,  /*!< driver can perform queries                                     */
+	DB_CAP_RAW_QUERY = 1 << 1,  /*!< driver can perform raw queries                                 */
+	DB_CAP_INSERT =    1 << 2,  /*!< driver can insert data                                         */
+	DB_CAP_DELETE =    1 << 3,  /*!< driver can delete data                                         */
+	DB_CAP_UPDATE =    1 << 4,  /*!< driver can update data                                         */
+	DB_CAP_REPLACE =   1 << 5,  /*!< driver can replace (also known as INSERT OR UPDATE) data       */
+	DB_CAP_FETCH   =   1 << 6,  /*!< driver supports fetch result queries                           */
+	DB_CAP_LAST_INSERTED_ID = 1 << 7,  /*!< driver can return the ID of the last insert operation   */
+ 	DB_CAP_INSERT_UPDATE = 1 << 8 /*!< driver can insert data into database and update on duplicate */
 
 } db_cap_t;
 
 
-/**
+/*! \brief
  * All database capabilities except raw_query, replace, insert_update and 
  * last_inserted_id which should be checked separately when needed
  */
 #define DB_CAP_ALL (DB_CAP_QUERY | DB_CAP_INSERT | DB_CAP_DELETE | DB_CAP_UPDATE)
 
 
-/**
+/*! \brief
  * Returns true if all the capabilities in cpv are supported by module
  * represented by dbf, false otherwise
  */

lib/srdb1/db_con.h

@@ -21,8 +21,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/**
+/*!
  * \file db/db_con.h
+ * \ingroup db
  * \brief Type that represents a database connection
  */
 
@@ -32,13 +33,13 @@
 #include "../str.h"
 
 
-/**
+/*! \brief
  * This structure represents a database connection, pointer to this structure
  * are used as a connection handle from modules uses the db API.
  */
 typedef struct {
-	const str* table;      /**< Default table that should be used              */
-	unsigned long tail;    /**< Variable length tail, database module specific */
+	const str* table;      /*!< Default table that should be used              */
+	unsigned long tail;    /*!< Variable length tail, database module specific */
 } db_con_t;
 
 

lib/srdb1/db_id.c

@@ -23,6 +23,7 @@
 
 /**
  * \file db/db_id.c
+ * \ingroup db
  * \brief Functions for parsing a database URL and work with db identifier.
  */
 

lib/srdb1/db_id.h

@@ -21,8 +21,9 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/**
+/*!
  * \file db/db_id.h
+ * \ingroup db
  * \brief Functions for parsing a database URL and works with db identifier.
  */
 

lib/srdb1/db_key.h

@@ -23,6 +23,7 @@
 
 /**
  * \file db/db_key.h
+ * \ingroup db
  * \brief Type that represents a database key.
  */
 

lib/srdb1/db_op.h

@@ -24,6 +24,7 @@
 /**
  * \file db/db_op.h
  * \brief Type that represents a expression operator.
+ * \ingroup db
  */
 
 #ifndef DB_OP_H

lib/srdb1/db_pool.c

@@ -24,6 +24,7 @@
 /**
  * \file db/db_pool.c
  * \brief Functions for managing a pool of database connections.
+ * \ingroup db
  */
 
 #include "../dprint.h"

lib/srdb1/db_pool.h

@@ -24,6 +24,7 @@
 /**
  * \file db/db_pool.h
  * \brief Functions for managing a pool of database connections.
+ * \ingroup db
  */
 
 #ifndef _DB_POOL_H

lib/srdb1/db_query.c

@@ -24,6 +24,7 @@
 /**
  * \file db/db_query.c
  * \brief Query helper for database drivers
+ * \ingroup db
  *
  * This helper methods for database queries are used from the database
  * SQL driver to do the actual work. Each function uses some functions from

lib/srdb1/db_query.h

@@ -24,6 +24,7 @@
 /**
  * \file db/db_query.h
  * \brief Query helper for database drivers
+ * \ingroup db
  *
  * This helper methods for database queries are used from the database
  * SQL driver to do the actual work. Each function uses some functions from

lib/srdb1/db_res.c

@@ -24,6 +24,7 @@
 /**
  * \file db/db_res.c
  * \brief Functions to manage result structures
+ * \ingroup db
  *
  * Provides some convenience macros and some memory management
  * functions for result structures.

lib/srdb1/db_res.h

@@ -28,6 +28,7 @@
  * Data structure that represents a result from a database query,
  * it also provides some convenience macros and some memory management
  * functions for result structures.
+ * \ingroup db
  */
 
 #ifndef DB_RES_H

lib/srdb1/db_row.c

@@ -27,6 +27,7 @@
  *
  * This file holds a type that represents a row in a database, some convenience
  * macros and a function for memory managements.
+ * \ingroup db
  */
 
 #include "db_row.h"

lib/srdb1/db_row.h

@@ -27,6 +27,7 @@
  *
  * This file holds a type that represents a row in a database, some convenience
  * macros and a function for memory managements.
+ * \ingroup db
  */
 
 

lib/srdb1/db_ut.c

@@ -27,6 +27,7 @@
  *
  * This utility methods are used from the database SQL driver to convert
  * values and print SQL queries from the internal API representation.
+ * \ingroup db
  */
 
 #include "db_ut.h"

lib/srdb1/db_ut.h

@@ -27,6 +27,7 @@
  *
  * This utility methods are used from the database SQL driver to convert
  * values and print SQL queries from the internal API representation.
+ * \ingroup db
 */
 
 #ifndef DB_UT_H

lib/srdb1/db_val.h

@@ -29,6 +29,7 @@
  * Several datatypes are recognized and converted by the database API.
  * Available types: DB_INT, DB_DOUBLE, DB_STRING, DB_STR, DB_DATETIME, DB_BLOB and DB_BITMAP
  * It also provides some macros for convenient access to this values.
+ * \ingroup db
  */