db_postgres: fix doxygen errors, small extensions and cleanups in comments

modules/db_postgres/km_pg_con.c

@@ -1,6 +1,4 @@
 /* 
- * $Id$
- *
  * Copyright (C) 2001-2004 iptel.org
  * Copyright (C) 2008 1&1 Internet AG
  *

modules/db_postgres/pg_cmd.h

@@ -1,8 +1,4 @@
 /* 
- * $Id$ 
- *
- * PostgreSQL Database Driver for SER
- *
  * Portions Copyright (C) 2001-2003 FhG FOKUS
  * Copyright (C) 2003 August.Net Services, LLC
  * Portions Copyright (C) 2005-2008 iptelorg GmbH
@@ -31,13 +27,15 @@
 #ifndef _PG_CMD_H
 #define _PG_CMD_H
 
-/** \addtogroup postgres
- * @{ 
- */
 
-/** \file 
- * Declaration of pg_cmd data structure that contains PostgreSQL specific data
+/*!
+ * \file
+ * \brief DB_POSTGRES :: * Declaration of pg_cmd data structure
+ * 
+ * Declaration of pg_cmd data structure  that contains PostgreSQL specific data
  * stored in db_cmd structures and related functions.
+ * \ingroup db_postgres
+ * Module: \ref db_postgres
  */
 
 #include "pg_oid.h"
@@ -90,6 +88,7 @@ int pg_cmd(db_cmd_t* cmd);
  * necessary.
  * @param res A pointer to (optional) result structure if the command returns
  *            a result.
+ * @param cmd executed command
  * @retval 0 if executed successfully
  * @retval A negative number if the database server failed to execute command
  * @retval A positive number if there was an error on client side (SER)
@@ -106,7 +105,7 @@ int pg_cmd_exec(db_res_t* res, db_cmd_t* cmd);
  * @param res A result set retrieved from PostgreSQL server.
  * @retval 0 If executed successfully.
  * @retval 1 If the result is empty.
- * @retival A negative number on error.
+ * @retval A negative number on error.
  */
 int pg_cmd_first(db_res_t* res);
 
@@ -120,7 +119,7 @@ int pg_cmd_first(db_res_t* res);
  * @param res A result set retrieved from PostgreSQL server.
  * @retval 0 If executed successfully.
  * @retval 1 If there are no more records in the result.
- * @retival A negative number on error.
+ * @retval A negative number on error.
  */
 int pg_cmd_next(db_res_t* res);
 
@@ -150,6 +149,4 @@ int pg_getopt(db_cmd_t* cmd, char* optname, va_list ap);
  */
 int pg_setopt(db_cmd_t* cmd, char* optname, va_list ap);
 
-/** @} */
-
 #endif /* _PG_CMD_H */

modules/db_postgres/pg_fld.c

@@ -1,8 +1,4 @@
 /* 
- * $Id$ 
- *
- * PostgreSQL Database Driver for SER
- *
  * Portions Copyright (C) 2001-2003 FhG FOKUS
  * Copyright (C) 2003 August.Net Services, LLC
  * Portions Copyright (C) 2005-2008 iptelorg GmbH
@@ -28,12 +24,12 @@
  * Temple Place, Suite 330, Boston, MA 02111-1307 USA
  */
 
-/** \addtogroup postgres
- * @{ 
- */
 
-/** \file 
- * Data field conversion and type checking functions.
+/*!
+ * \file
+ * \brief DB_POSTGRES :: Data field conversion and type checking functions.
+ * \ingroup db_postgres
+ * Module: \ref db_postgres
  */
 
 #include "pg_fld.h"
@@ -934,6 +930,3 @@ int pg_pg2fld(db_fld_t* dst, PGresult* src, int row,
 		type, dst[i].type);
 	return -1;
 }
-
-
-/** @} */

modules/db_postgres/pg_fld.h

@@ -1,8 +1,4 @@
 /* 
- * $Id$ 
- *
- * PostgreSQL Database Driver for SER
- *
  * Portions Copyright (C) 2001-2003 FhG FOKUS
  * Copyright (C) 2003 August.Net Services, LLC
  * Portions Copyright (C) 2005-2008 iptelorg GmbH
@@ -31,13 +27,14 @@
 #ifndef _PG_FLD_H
 #define _PG_FLD_H
 
-/** \addtogroup postgres
- * @{ 
- */
 
-/** \file 
- * Implementation of pg_fld data structure representing PostgreSQL fields and
- * related functions.
+/*!
+ * \file
+ * \brief DB_POSTGRES :: Implementation of pg_fld data structure
+ * 
+ * Implementation of pg_fld data structure representing PostgreSQL fields and related functions.
+ * \ingroup db_postgres
+ * Module: \ref db_postgres
  */
 
 #include "pg_oid.h"
@@ -75,8 +72,7 @@ struct pg_fld {
  * attaches the structure to the generic db_fld structure.
  * @param fld A generic db_fld structure to be exended.
  * @param table Name of the table on the server.
- * @retval 0 on success.
- * @retval A negative number on error.
+ * @return 0 on success, negative number on error.
  */
 int pg_fld(db_fld_t* fld, char* table);
 
@@ -89,15 +85,11 @@ int pg_resolve_result_oids(db_fld_t* fld, int n, PGresult* res);
 /** Converts arrays of db_fld fields to PostgreSQL parameters.
  * The function converts fields in SER db_fld format to parameters suitable
  * for PostgreSQL API functions.
- * @param values An array of pointers to values in PostgreSQL format. The
+ * @param dst An array of pointers to values in PostgreSQL format. The
  *               function will store pointers to converted values there.
- * @param lenghts An array of integers that will be filled with lenghts
- *                of values.
- * @param formats An array of value formats, see PostgreSQL API client
- *                library documentation for more detail.
- * @param oids Types of corresponding columns on the server.
+ * @param off offset 
  * @param types A type conversion table.
- * @param fld An array of db_fld fields to be converted.
+ * @param src An array of db_fld fields to be converted.
  * @param flags Connection flags controlling how values are converted.
  * @todo Implement support for bit fields with size bigger than 32 
  * @todo Implement support for varbit properly to remove leading zeroes
@@ -113,10 +105,11 @@ int pg_fld2pg(struct pg_params* dst, int off, pg_type_t* types,
  * The function converts fields from PostgreSQL result (PGresult structure)
  * into the internal format used in SER. The function converts one row at a
  * time.
- * @param fld The destination array of db_fld fields to be filled with converted
+ * @param dst The destination array of db_fld fields to be filled with converted
  *            values.
- * @param pres A PostgreSQL result structure to be converted into SER format.
+ * @param src A PostgreSQL result structure to be converted into SER format.
  * @param row Number of the row to be converted.
+ * @param types A type conversion table.
  * @param flags Connection flags controlling how values are converted.
  * @retval 0 on success
  * @retval A negative number on error.
@@ -129,20 +122,24 @@ int pg_pg2fld(db_fld_t* dst, PGresult* src, int row, pg_type_t* types,
 /** Checks if all db_fld fields have types compatible with corresponding field 
  * types on the server.
  * The functions checks whether all db_fld fields in the last parameter are
- * compatible with column types on the server.
- * @param oids An array of Oids of corresponding columns on the server.
- * @param lenghts An array of sizes of corresponding columns on the server.
- * @param types An array used to map internal field types to Oids.
+ * compatible with column types on the server, for conversion to postgres format.
  * @param fld An array of db_fld fields to be checked.
+ * @param types An array used to map internal field types to Oids.
  * @retval 0 on success
  * @retval A negative number on error.
  */
 int pg_check_fld2pg(db_fld_t* fld, pg_type_t* types);
 
-
+/** Checks if all db_fld fields have types compatible with corresponding field 
+ * types on the server.
+ * The functions checks whether all db_fld fields in the last parameter are
+ * compatible with column types on the server, for conversion to interal DB format.
+ * @param fld An array of db_fld fields to be checked.
+ * @param types An array used to map internal field types to Oids.
+ * @retval 0 on success
+ * @retval A negative number on error.
+ */
 int pg_check_pg2fld(db_fld_t* fld, pg_type_t* types);
 
 
-/** @} */
-
 #endif /* _PG_FLD_H */