- 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

modules/db_mysql/km_README

@@ -12,8 +12,8 @@ Daniel-Constantin Mierla
 
    Copyright © 2006 voice-system.ro
    Revision History
-   Revision $Revision$ $Date: 2008-03-19 21:31:30 +0200
-                              (Wed, 19 Mar 2008) $
+   Revision $Revision$ $Date: 2008-03-19 20:31:30 +0100
+                              (Mi, 19 Mär 2008) $
      __________________________________________________________
 
    Table of Contents
@@ -59,15 +59,15 @@ Chapter 1. Admin Guide
 
    The following libraries or applications must be installed
    before running OpenSER with this module loaded:
-     * libmysqlclient-dev - the development libraries of
-       mysql-client.
+     * mysql - the development libraries forthe Mysql database. In
+       some Linux distributions named "libmysqlclient-dev".
 
 1.3. Exported Parameters
 
 1.3.1. ping_interval (integer)
 
-   Time interval to send ping messages to MySQL server in order to
-   keep the connection open.
+   Time interval in seconds to send ping messages to MySQL server
+   in order to keep the connection open.
 
    Default value is 300 (5 min).
 
@@ -78,14 +78,14 @@ modparam("db_mysql", "ping_interval", 600)
 
 1.3.2. timeout_interval (integer)
 
-   Time interval after that an connection attempt, read or write
-   request is aborted. The value counts three times, as several
-   retries are done from the driver before it gives up.
+   Time interval (in seconds) after that an connection attempt,
+   read or write request is aborted. The value counts three times,
+   as several retries are done from the driver before it gives up.
 
-   The read timeout parameter is ignored on driver versions prior
-   to "5.1.12", "5.0.25" and "4.1.22". The write timeout parameter
-   is ignored on version prior to "5.1.12" and "5.0.25", the "4.1"
-   release don't support it at all.
+   The read timeout parameter is ignored on MySQL driver versions
+   prior to "5.1.12", "5.0.25" and "4.1.22". The write timeout
+   parameter is ignored on versions prior to "5.1.12" and
+   "5.0.25", the "4.1" release don't support it at all.
 
    Default value is 2 (6 sec).
 
@@ -96,8 +96,8 @@ modparam("db_mysql", "timeout_interval", 2)
 
 1.3.3. auto_reconnect (integer)
 
-   Configure the module to auto reconnect to MySQL server if the
-   connection was lost.
+   Configure whether the module should automatically reconnect to
+   MySQL server if the connection was lost.
 
    Default value is 1 (1 - on / 0 - off).
 
@@ -113,8 +113,8 @@ modparam("auto_reconnect", "auto_reconnect", 0)
 1.5. Installation
 
    Because it dependes on an external library, the mysql module is
-   not compiled and installed by default. You can use one of the
-   next options.
+   not compiled and installed by default. You can use one of these
+   options.
      * - edit the "Makefile" and remove "db_mysql" from
        "excluded_modules" list. Then follow the standard procedure
        to install OpenSER: "make all; make install".

modules/db_mysql/km_db_mysql.c

@@ -29,6 +29,18 @@
  *  2003-03-16  flags export parameter added (janakj)
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Core
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+/*! \defgroup db_mysql DB_MYSQL :: the MySQL driver for OpenSER
+ *  \brief The OpenSER database interface to the MySQL database
+ *  - http://www.mysql.org
+ *
+ */
+
 #include "../../sr_module.h"
 #include "../../db/db.h"
 #include "dbase.h"
@@ -46,7 +58,7 @@ MODULE_VERSION
 
 int db_mysql_bind_api(db_func_t *dbb);
 
-/*
+/*! \brief
  * MySQL database module interface
  */
 static cmd_export_t cmds[] = {
@@ -55,7 +67,7 @@ static cmd_export_t cmds[] = {
 };
 
 
-/*
+/*! \brief
  * Exported parameters
  */
 static param_export_t params[] = {

modules/db_mysql/km_db_mysql.h

@@ -28,6 +28,13 @@
  *  2003-03-16  flags export parameter added (janakj)
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Core
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 #ifndef DB_MOD_H
 #define DB_MOD_H
 

modules/db_mysql/km_dbase.c

@@ -23,12 +23,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/**
+/*!
  * \file
  * \brief Implementation of core functions for the MySQL driver.
  *
  * This file contains the implementation of core functions for the MySQL
  * database driver, for example to submit a query or fetch a result.
+ * \ingroup db_mysql
+ *  Module: \ref db_mysql
  */
 
 #include <stdio.h>

modules/db_mysql/km_dbase.h

@@ -23,6 +23,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Core
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 
 #ifndef DBASE_H
 #define DBASE_H
@@ -35,25 +42,25 @@
 #include "../../db/db_val.h"
 #include "../../str.h"
 
-/*
+/*! \brief
  * Initialize database connection
  */
 db_con_t* db_mysql_init(const str* _sqlurl);
 
 
-/*
+/*! \brief
  * Close a database connection
  */
 void db_mysql_close(db_con_t* _h);
 
 
-/*
+/*! \brief
  * Free all memory allocated by get_result
  */
 int db_mysql_free_result(db_con_t* _h, db_res_t* _r);
 
 
-/*
+/*! \brief
  * Do a query
  */
 int db_mysql_query(const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
@@ -61,32 +68,32 @@ int db_mysql_query(const db_con_t* _h, const db_key_t* _k, const db_op_t* _op,
 	     const db_key_t _o, db_res_t** _r);
 
 
-/*
+/*! \brief
  * fetch rows from a result
  */
 int db_mysql_fetch_result(const db_con_t* _h, db_res_t** _r, const int nrows);
 
 
-/*
+/*! \brief
  * Raw SQL query
  */
 int db_mysql_raw_query(const db_con_t* _h, const str* _s, db_res_t** _r);
 
 
-/*
+/*! \brief
  * Insert a row into table
  */
 int db_mysql_insert(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v, const int _n);
 
 
-/*
+/*! \brief
  * Delete a row from table
  */
 int db_mysql_delete(const db_con_t* _h, const db_key_t* _k, const 
 	db_op_t* _o, const db_val_t* _v, const int _n);
 
 
-/*
+/*! \brief
  * Update a row in table
  */
 int db_mysql_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
@@ -94,24 +101,24 @@ int db_mysql_update(const db_con_t* _h, const db_key_t* _k, const db_op_t* _o,
 	const int _un);
 
 
-/*
+/*! \brief
  * Just like insert, but replace the row if it exists
  */
 int db_mysql_replace(const db_con_t* handle, const db_key_t* keys, const db_val_t* 	vals, const int n);
 
-/*
+/*! \brief
  * Returns the last inserted ID
  */
 int db_last_inserted_id(const db_con_t* _h);
 
-/*
+/*! \brief
  * Insert a row into table, update on duplicate key
  */
 int db_insert_update(const db_con_t* _h, const db_key_t* _k, const db_val_t* _v,
 	const int _n);
 
 
-/*
+/*! \brief
  * Store name of table that will be used by
  * subsequent database functions
  */

modules/db_mysql/km_doc/db_mysql_admin.xml

@@ -35,7 +35,7 @@
 			<itemizedlist>
 			<listitem>
 			<para>
-				<emphasis>libmysqlclient-dev</emphasis> - the development libraries of mysql-client.
+				<emphasis>mysql</emphasis> - the development libraries forthe Mysql database. In some Linux distributions named "libmysqlclient-dev".
 			</para>
 			</listitem>
 			</itemizedlist>
@@ -47,7 +47,7 @@
 	<section>
 		<title><varname>ping_interval</varname> (integer)</title>
 		<para>
-		Time interval to send ping messages to MySQL server in order to keep
+		Time interval in seconds to send ping messages to MySQL server in order to keep
 		the connection open.
 		</para>
 		<para>
@@ -67,14 +67,14 @@ modparam("db_mysql", "ping_interval", 600)
 		<section>
 		<title><varname>timeout_interval</varname> (integer)</title>
 		<para>
-		Time interval after that an connection attempt, read or write request
+		Time interval (in seconds) after that an connection attempt, read or write request
 		is aborted. The value counts three times, as several retries are done
 		from the driver before it gives up.
 		</para>
 		<para>
-		The read timeout parameter is ignored on driver versions prior to
+		The read timeout parameter is ignored on MySQL driver versions prior to
 		<quote>5.1.12</quote>, <quote>5.0.25</quote> and <quote>4.1.22</quote>.
-		The write timeout parameter is ignored on version prior to <quote>5.1.12</quote>
+		The write timeout parameter is ignored on versions prior to <quote>5.1.12</quote>
 		and <quote>5.0.25</quote>, the <quote>4.1</quote> release don't support it at all.
 		</para>
 		<para>
@@ -94,7 +94,7 @@ modparam("db_mysql", "timeout_interval", 2)
 	<section>
 		<title><varname>auto_reconnect</varname> (integer)</title>
 		<para>
-		Configure the module to auto reconnect to MySQL server if the
+		Configure whether the module should automatically reconnect to MySQL server if the
 		connection was lost.
 		</para>
 		<para>
@@ -122,7 +122,7 @@ modparam("auto_reconnect", "auto_reconnect", 0)
 	<title>Installation</title>
 		<para>
 		Because it dependes on an external library, the mysql module is not
-		compiled and installed by default. You can use one of the next options.
+		compiled and installed by default. You can use one of these options.
 		</para>
 		<itemizedlist>
 			<listitem>

modules/db_mysql/km_my_con.c

@@ -21,6 +21,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Connections
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 #include "my_con.h"
 #include "db_mysql.h"
 #include <mysql/mysql_version.h>
@@ -29,7 +36,7 @@
 #include "../../ut.h"
 
 
-/**
+/*! \brief
  * Create a new connection structure,
  * open the MySQL connection and set reference count to 1
  */
@@ -104,7 +111,7 @@ struct my_con* db_mysql_new_connection(const struct db_id* id)
 }
 
 
-/**
+/*! \brief
  * Close the connection and release memory
  */
 void db_mysql_free_connection(struct pool_con* con)

modules/db_mysql/km_my_con.h

@@ -21,6 +21,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Core
+ *  \ref my_con.c
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 #ifndef MY_CON_H
 #define MY_CON_H
 
@@ -32,14 +40,14 @@
 
 
 struct my_con {
-	struct db_id* id;        /* Connection identifier */
-	unsigned int ref;        /* Reference count */
-	struct pool_con* next;   /* Next connection in the pool */
+	struct db_id* id;        /*!< Connection identifier */
+	unsigned int ref;        /*!< Reference count */
+	struct pool_con* next;   /*!< Next connection in the pool */
 
-	MYSQL_RES* res;          /* Actual result */
-	MYSQL* con;              /* Connection representation */
-	MYSQL_ROW row;           /* Actual row in the result */
-	time_t timestamp;        /* Timestamp of last query */
+	MYSQL_RES* res;          /*!< Actual result */
+	MYSQL* con;              /*!< Connection representation */
+	MYSQL_ROW row;           /*!< Actual row in the result */
+	time_t timestamp;        /*!< Timestamp of last query */
 };
 
 
@@ -52,14 +60,14 @@ struct my_con {
 #define CON_TIMESTAMP(db_con)  (((struct my_con*)((db_con)->tail))->timestamp)
 
 
-/*
+/*! \brief
  * Create a new connection structure,
  * open the MySQL connection and set reference count to 1
  */
 struct my_con* db_mysql_new_connection(const struct db_id* id);
 
 
-/*
+/*! \brief
  * Close the connection and release memory
  */
 void db_mysql_free_connection(struct pool_con* con);

modules/db_mysql/km_res.c

@@ -24,6 +24,13 @@
  */
 
 
+/*! \file
+ *  \brief DB_MYSQL :: Result related functions
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 #include <string.h>
 #include <mysql/mysql.h>
 #include "../../db/db_res.h"
@@ -34,7 +41,7 @@
 #include "res.h"
 
 
-/**
+/*! \brief
  * Get and convert columns from a result
  */
 int db_mysql_get_columns(const db_con_t* _h, db_res_t* _r)
@@ -130,7 +137,7 @@ int db_mysql_get_columns(const db_con_t* _h, db_res_t* _r)
 }
 
 
-/**
+/*! \brief
  * Convert rows from mysql to db API representation
  */
 static inline int db_mysql_convert_rows(const db_con_t* _h, db_res_t* _r)
@@ -177,7 +184,7 @@ static inline int db_mysql_convert_rows(const db_con_t* _h, db_res_t* _r)
 }
 
 
-/**
+/*! \brief
  * Fill the structure with data from database
  */
 int db_mysql_convert_result(const db_con_t* _h, db_res_t* _r)

modules/db_mysql/km_res.h

@@ -23,6 +23,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Result related functions
+ *  \ref res.c
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 #ifndef RES_H
 #define RES_H
 

modules/db_mysql/km_row.c

@@ -23,6 +23,11 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Row related functions
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
 
 #include "../../dprint.h"
 #include "../../mem/mem.h"
@@ -32,8 +37,7 @@
 #include "val.h"
 #include "row.h"
 
-
-/**
+/*! \brief
  * Convert a row from result into db API representation
  */
 int db_mysql_convert_row(const db_con_t* _h, db_res_t* _res, db_row_t* _r)

modules/db_mysql/km_row.h

@@ -23,6 +23,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Row related functions
+ *  \ref row.c
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 #ifndef ROW_H
 #define ROW_H
 

modules/db_mysql/km_val.c

@@ -21,6 +21,11 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Data conversion
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
 
 #include "../../dprint.h"
 #include "../../db/db_ut.h"
@@ -31,7 +36,7 @@
 #include <stdio.h>
 
 
-/*
+/*! \brief
  * Convert str to db value, does not copy strings
  */
 int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int _l)
@@ -127,7 +132,7 @@ int db_mysql_str2val(const db_type_t _t, db_val_t* _v, const char* _s, const int
 }
 
 
-/*
+/*! \brief
  * Used when converting result from a query
  */
 int db_mysql_val2str(const db_con_t* _c, const db_val_t* _v, char* _s, int* _len)

modules/db_mysql/km_val.h

@@ -21,6 +21,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ *  \brief DB_MYSQL :: Conversions
+ *  \ref val.c
+ *  \ingroup db_mysql
+ *  Module: \ref db_mysql
+ */
+
+
 #ifndef VAL_H
 #define VAL_H