[sr-dev] git:master: db_postgres: fix doxygen errors, small extensions and cleanups in comments

Module: sip-router Branch: master Commit: 34db39d95f9fcb03d5624ee6fb15b8542295a2f5 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=34db39d… Author: Henning Westerholt <henning.westerholt(a)1und1.de> Committer: Henning Westerholt <henning.westerholt(a)1und1.de> Date: Mon Aug 8 22:42:19 2011 +0200 db_postgres: fix doxygen errors, small extensions and cleanups in comments --- modules/db_postgres/km_pg_con.c | 2 - modules/db_postgres/pg_cmd.h | 23 +++++++--------- modules/db_postgres/pg_fld.c | 17 +++--------- modules/db_postgres/pg_fld.h | 53 ++++++++++++++++++-------------------- 4 files changed, 40 insertions(+), 55 deletions(-) diff --git a/modules/db_postgres/km_pg_con.c b/modules/db_postgres/km_pg_con.c index 98dbb43..472e8de 100644 --- a/modules/db_postgres/km_pg_con.c +++ b/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 * diff --git a/modules/db_postgres/pg_cmd.h b/modules/db_postgres/pg_cmd.h index 1398d16..c48c31e 100644 --- a/modules/db_postgres/pg_cmd.h +++ b/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 */ diff --git a/modules/db_postgres/pg_fld.c b/modules/db_postgres/pg_fld.c index 685d73b..fe64217 100644 --- a/modules/db_postgres/pg_fld.c +++ b/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; } - - -/** @} */ diff --git a/modules/db_postgres/pg_fld.h b/modules/db_postgres/pg_fld.h index 917f22d..09b9926 100644 --- a/modules/db_postgres/pg_fld.h +++ b/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 */