doxygen update

git-svn-id: https://svn.osgeo.org/grass/grass/trunk@38550 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/db/dbmi_base/string.c

@@ -1,12 +1,26 @@
+/*!
+  \file db/dbmi_base/string.c
+  
+  \brief DBMI Library (base) - string management
+  
+  (C) 1999-2009 by the GRASS Development Team
+  
+  This program is free software under the GNU General Public License
+  (>=v2). Read the file COPYING that comes with GRASS for details.
+  
+  \author Joel Jones (CERL/UIUC)
+  \author Upgraded to GRASS 5.7 by Radim Blazek
+*/
+
 #include <string.h>
 #include <stdlib.h>
+#include <grass/gis.h>
 #include <grass/dbmi.h>
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+   \brief Initialize dbString 
+
+   \param[in,out] x pointer to dbString
  */
 void db_init_string(dbString * x)
 {
@@ -14,32 +28,30 @@ void db_init_string(dbString * x)
     x->nalloc = 0;
 }
 
-
+static int set_string(dbString * x, char *s, int copy);
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
-/* db_set_string(dbString *x, char *s, int copy)
- *  inserts 's' into 'x'
- *   if 'copy' is true, then memory is allocated to copy into
- *   else 'x' is made to point to 's'
- * returns DB_OK or DB_MEMORY_ERR
- */
-static int set_string(dbString * x, char *s, int copy);
+  \brief Inserts string to dbString (enlarge string)
+  
+  \param[in,out] x pointer to dbString
+  \param s string to be inserted
 
+  \return DB_OK on success
+  \return DB_MEMORY_ERR on error
+ */
 int db_set_string(dbString * x, const char *s)
 {
     return set_string(x, (char *)s, 1);
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Inserts string to dbString (overwrite current value)
+  
+  \param[in,out] x pointer to dbString
+  \param s string to be inserted
+
+  \return DB_OK on success
+  \return DB_MEMORY_ERR on error
  */
 int db_set_string_no_copy(dbString * x, char *s)
 {
@@ -47,12 +59,13 @@ int db_set_string_no_copy(dbString * x, char *s)
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Get string size
+
+  \param x pointer to dbString
+
+  \return string size
  */
-unsigned int db_sizeof_string(dbString * x)
+unsigned int db_sizeof_string(const dbString * x)
 {
     if (x->nalloc < 0)
 	return 0;
@@ -60,22 +73,15 @@ unsigned int db_sizeof_string(dbString * x)
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Zero string
+
+  \param x pointer to dbString
  */
 void db_zero_string(dbString * x)
 {
     db_zero((void *)db_get_string(x), db_sizeof_string(x));
 }
 
-/*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
 static int set_string(dbString * x, char *s, int copy)
 {
     int len;
@@ -103,10 +109,13 @@ static int set_string(dbString * x, char *s, int copy)
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+   \brief Enlarge dbString
+
+   \param x pointer to dbString
+   \param len requested string size
+
+   \return DB_OK on success
+   \return DB_MEMORY_ERR on error
  */
 int db_enlarge_string(dbString * x, int len)
 {
@@ -122,53 +131,53 @@ int db_enlarge_string(dbString * x, int len)
 }
 
 /*!
-   \fn
-   \brief
-   \return
-   \param
- */
+  \brief Get string
 
-char *db_get_string(dbString * x)
+  \param x pointer to dbString
+
+  \return pointer to buffer containg string
+*/
+char *db_get_string(const dbString * x)
 {
     return x->string;
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
+  \brief Free allocated space
+
+  \param x poiter to dbString
+*/
 void db_free_string(dbString * x)
 {
     if (x->nalloc > 0)
-	free(x->string);
+	G_free(x->string);
     db_init_string(x);
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Free allocated dbString array
+
+  \param a pointer to 1st dbString in the array
+  \param n number of items in array
  */
-void db_free_string_array(dbString * a, int n)
+void db_free_string_array(dbString *a, int n)
 {
     int i;
 
     if (a) {
 	for (i = 0; i < n; i++)
 	    db_free_string(&a[i]);
-	free(a);
+	G_free(a);
     }
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
- */
+  \brief Allocate dbString array
+
+  \param count number of items to be allocated
+
+  \return pointer to 1st dbString in the array
+*/
 dbString *db_alloc_string_array(int count)
 {
     int i;
@@ -185,10 +194,13 @@ dbString *db_alloc_string_array(int count)
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Append string to dbString
+
+  \param x pointer to dbString
+  \param s string to be appended
+
+  \return DB_OK on success
+  \return otherwise error code is returned
  */
 int db_append_string(dbString * x, const char *s)
 {
@@ -204,22 +216,24 @@ int db_append_string(dbString * x, const char *s)
 }
 
 /*!
-   \fn 
-   \brief 
-   \return 
-   \param 
+  \brief Copy dbString
+
+  \param dst destination dbString
+  \param src source dbString
+
+  \return DB_OK on success
+  \return DB_ERR code on error
  */
-int db_copy_string(dbString * dst, dbString * src)
+int db_copy_string(dbString * dst, const dbString * src)
 {
     return db_set_string(dst, db_get_string(src));
 }
 
 /*!
-   \fn 
-   \brief each ' is replaced by ''
-   \return 
-   \param 
- */
+  \brief Replace each ' is replaced by ''
+
+  \param src pointer to dbString
+*/
 void db_double_quote_string(dbString * src)
 {
     char *ptra, *ptrb, buf[2];