libgis: doxygen docs update (key_value_[1|2|3].c)

	use G_zero() when initializing Key_Value structure


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

lib/gis/key_value1.c

@@ -1,14 +1,12 @@
 /*!
-   \file key_value1.c
+   \file lib/gis/key_value1.c
 
-   \brief Key_Value management.
+   \brief Subroutines for Key/Value management.
 
-   (C) 2001-2008 by the GRASS Development Team
+   (C) 2001-2008, 2012 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.
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
 
    \author CERL
  */
@@ -25,23 +23,18 @@
 struct Key_Value *G_create_key_value(void)
 {
     struct Key_Value *kv = G_malloc(sizeof(struct Key_Value));
-
-    kv->nitems = 0;
-    kv->nalloc = 0;
-    kv->key = NULL;
-    kv->value = NULL;
-
+    G_zero(kv, sizeof(struct Key_Value));
+    
     return kv;
 }
 
 /*!
    \brief Set value for given key
 
-   \param[in] key key to be set up
-   \param[in] value value for given key
+   \param key key to be set up
+   \param value value for given key
    \param[in,out] kv Key_value structure to be modified
  */
-
 void G_set_key_value(const char *key, const char *value, struct Key_Value *kv)
 {
     int n;
@@ -80,10 +73,10 @@ void G_set_key_value(const char *key, const char *value, struct Key_Value *kv)
 }
 
 /*!
-   \brief Find given key
+   \brief Find given key (case sensitive)
 
-   \param[in] key key to be found
-   \param[in] kv Key_value structure
+   \param key key to be found
+   \param kv pointer to Key_value structure
 
    \return poiter to value of key
    \return NULL if no key found
@@ -105,9 +98,7 @@ const char *G_find_key_value(const char *key, const struct Key_Value *kv)
 /*!
    \brief Free allocated Key_Value structure
 
-   \param[in] kv Key_Value structure
-
-   \return
+   \param[in] kv Key_Value structure to be freed
  */
 void G_free_key_value(struct Key_Value *kv)
 {

lib/gis/key_value2.c

@@ -1,14 +1,12 @@
 /*!
-   \file key_value2.c
+   \file lib/gis/key_value2.c
 
    \brief Read/write Key_Value from/to file.
 
-   (C) 2001-2008 by the GRASS Development Team
+   (C) 2001-2008, 2012 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.
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
 
    \author CERL
  */
@@ -19,7 +17,7 @@
    \brief Write key/value pairs to file
 
    \param[in,out] fd file to write to
-   \param[in]     kv Key_Value structure
+   \param         kv pointer Key_Value structure
 
    \return 0 success
    \return -1 error writing
@@ -43,7 +41,7 @@ int G_fwrite_key_value(FILE * fd, const struct Key_Value *kv)
 
    Allocated memory must be freed G_free_key_value().
 
-   \param[in] fd file to read key/values from
+   \param fd file to read key/values from
 
    \return pointer to allocated Key_Value structure
    \return NULL on error

lib/gis/key_value3.c

@@ -1,14 +1,12 @@
 /*!
-   \file key_value3.c
+   \file lib/gis/key_value3.c
 
    \brief Key_Value management.
 
-   (C) 2001-2008 by the GRASS Development Team
+   (C) 2001-2008, 2012 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.
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
 
    \author CERL
  */
@@ -19,13 +17,12 @@
 /*!
    \brief Write key/value pairs to file
 
-   \param[in]  file filename for writing
-   \param[in]  kv   Key_Value structure
+   \param  file filename for writing
+   \param  kv   pointer Key_Value structure
 
    \return 0 success
    \return 1 error writing
  */
-
 void G_write_key_value_file(const char *file,
 			    const struct Key_Value *kv)
 {
@@ -43,10 +40,10 @@ void G_write_key_value_file(const char *file,
 /*!
    \brief Read key/values pairs from file
 
-   Allocated memory must be freed G_free_key_value().
+   Allocated memory must be freed G_free_key_value(). Call
+   G_fatal_error() when unable to read key/value items from the file.
 
    \param[in]  file filename for reading
-   \param[out] stat status (0 ok, -1 cannot open file, -2 error writing key/value)
 
    \return poiter to allocated Key_Value structure
    \return NULL on error