vlib:cindex.c: cosmetics in doxygen strings

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

lib/vector/Vlib/cindex.c

@@ -1,17 +1,17 @@
 /*!
- * \file lib/vector/Vlib/cindex.c
- *
- * \brief Vector library - category index.
- *
- * Higher level functions for reading/writing/manipulating vectors.
- *
- * (C) 2001-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 Radim Blazek
- */
+  \file lib/vector/Vlib/cindex.c
+  
+  \brief Vector library - category index.
+  
+  Higher level functions for reading/writing/manipulating vectors.
+  
+  (C) 2001-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 Radim Blazek
+*/
 
 #include <stdlib.h>
 #include <string.h>
@@ -30,26 +30,28 @@ static void check_status(const struct Map_info *Map)
 }
 
 /*!
-   \brief Get number of layer in category index
-
-   \param Map vector map
-
-   \return number of layers
+  \brief Get number of layers in category index
+  
+  \param Map pointer to Map_info structure
+  
+  \return number of layers
  */
 int Vect_cidx_get_num_fields(const struct Map_info *Map)
 {
     check_status(Map);
 
-    return (Map->plus.n_cidx);
+    return Map->plus.n_cidx;
 }
 
 /*!
-   \brief Get layer number for given index 
+  \brief Get layer number for given index 
 
-   \param Map vector map
-   \param index layer index: from 0 to Vect_cidx_get_num_fields() - 1
+  G_fatal_error() is called when index not found.
+  
+  \param Map pointer to Map_info structure
+  \param index layer index: from 0 to Vect_cidx_get_num_fields() - 1
 
-   \return layer number 
+  \return layer number 
  */
 int Vect_cidx_get_field_number(const struct Map_info *Map, int index)
 {
@@ -58,17 +60,17 @@ int Vect_cidx_get_field_number(const struct Map_info *Map, int index)
     if (index >= Map->plus.n_cidx)
 	G_fatal_error(_("Invalid layer index (index >= number of layers)"));
 
-    return (Map->plus.cidx[index].field);
+    return Map->plus.cidx[index].field;
 }
 
 /*!
-   \brief Get layer index for given layer number
-
-   \param Map vector map
-   \param field layer number 
+  \brief Get layer index for given layer number
+  
+  \param Map pointer to Map_info structure
+  \param field layer number 
 
-   \return layer index
-   \return -1 if not found 
+  \return layer index
+  \return -1 if not found 
  */
 int Vect_cidx_get_field_index(const struct Map_info *Map, int field)
 {
@@ -85,17 +87,19 @@ int Vect_cidx_get_field_index(const struct Map_info *Map, int field)
 	    return i;
     }
 
-    return (-1);
+    return -1;
 }
 
 /*!
-   \brief Get number of unique categories for given layer index 
-
-   \param Map vector map
-   \param index layer number
-
-   \return number of unique categories
-   \return -1 on error
+  \brief Get number of unique categories for given layer index 
+  
+  G_fatal_error() is called when index not found.
+  
+  \param Map pointer to Map_info structure
+  \param index layer number
+  
+  \return number of unique categories
+  \return -1 on error
  */
 int Vect_cidx_get_num_unique_cats_by_index(const struct Map_info *Map, int index)
 {
@@ -104,17 +108,17 @@ int Vect_cidx_get_num_unique_cats_by_index(const struct Map_info *Map, int index
     if (index < 0 || index >= Map->plus.n_cidx)
 	G_fatal_error(_("Invalid layer index (index < 0 or index >= number of layers)"));
 
-    return (Map->plus.cidx[index].n_ucats);
+    return Map->plus.cidx[index].n_ucats;
 }
 
 /*!
-   \brief Get number of categories for given layer index 
-
-   \param Map vector map
-   \param index layer index
-
-   \return number of categories
-   \return -1 on error
+  \brief Get number of categories for given layer index 
+  
+  \param Map pointer to Map_info structure
+  \param index layer index
+  
+  \return number of categories
+  \return -1 on error
  */
 int Vect_cidx_get_num_cats_by_index(const struct Map_info *Map, int index)
 {
@@ -122,17 +126,19 @@ int Vect_cidx_get_num_cats_by_index(const struct Map_info *Map, int index)
     if (index >= Map->plus.n_cidx)
 	G_fatal_error(_("Invalid layer index (index >= number of layers)"));
 
-    return (Map->plus.cidx[index].n_cats);
+    return Map->plus.cidx[index].n_cats;
 }
 
 /*!
-   \brief Get number of types for given layer index 
-
-   \param Map vector map
-   \param field_index layer index
-
-   \return number of types
-   \return -1 on error
+  \brief Get number of types for given layer index 
+  
+  G_fatal_error() is called when index not found.
+  
+  \param Map pointer to Map_info structure
+  \param field_index layer index
+  
+  \return number of types
+  \return -1 on error
  */
 int Vect_cidx_get_num_types_by_index(const struct Map_info *Map, int field_index)
 {
@@ -140,24 +146,23 @@ int Vect_cidx_get_num_types_by_index(const struct Map_info *Map, int field_index
     if (field_index >= Map->plus.n_cidx)
 	G_fatal_error(_("Invalid layer index (index >= number of layers)"));
 
-    return (Map->plus.cidx[field_index].n_types);
+    return Map->plus.cidx[field_index].n_types;
 }
 
 /*!
-   \brief Get type count field index and type index
-
-   \param Map vector map
-   \param field_index layer index
-   \param type_index type index
-   \param[out] type feature type
-   \param[out] count number of items
-
-   \return 1 on success
-   \return 0 on error
- */
-int
-Vect_cidx_get_type_count_by_index(const struct Map_info *Map, int field_index,
-				  int type_index, int *type, int *count)
+  \brief Get type count field index and type index
+  
+  \param Map pointer to Map_info structure
+  \param field_index layer index
+  \param type_index type index
+  \param[out] type feature type
+  \param[out] count number of items
+  
+  \return 1 on success
+  \return 0 on error
+*/
+int Vect_cidx_get_type_count_by_index(const struct Map_info *Map, int field_index,
+				      int type_index, int *type, int *count)
 {
     check_status(Map);
     if (field_index >= Map->plus.n_cidx)
@@ -170,14 +175,14 @@ Vect_cidx_get_type_count_by_index(const struct Map_info *Map, int field_index,
 }
 
 /*!
-   \brief Get count of features of certain type by layer and type
-
-   \param Map vector map
-   \param field layer number
-   \param type feature type
-
-   \return feature count
-   \return 0 if no features, no such field or no such type in cidx
+  \brief Get count of features of certain type by layer and type
+  
+  \param Map pointer to Map_info structure
+  \param field layer number
+  \param type feature type
+  
+  \return feature count
+  \return 0 if no features, no such field or no such type in cidx
  */
 int Vect_cidx_get_type_count(const struct Map_info *Map, int field, int type)
 {
@@ -203,25 +208,24 @@ int Vect_cidx_get_type_count(const struct Map_info *Map, int field, int type)
 	G_debug(3, "%d tp = %d, cnt= %d count = %d", i, tp, cnt, count);
     }
 
-    return (count);
+    return count;
 }
 
 /*!
-   \brief Get number of categories for given field and category index 
-
-   \param Map vector map
-   \param field_index layer index
-   \param cat_index category index
-   \param[out] cat category number
-   \param[out] type feature type
-   \param[out] id feature id
-
-   \return 1 on success
-   \return 0 on error
- */
-int
-Vect_cidx_get_cat_by_index(const struct Map_info *Map, int field_index,
-			   int cat_index, int *cat, int *type, int *id)
+  \brief Get number of categories for given field and category index 
+  
+  \param Map pointer to Map_info structure
+  \param field_index layer index
+  \param cat_index category index
+  \param[out] cat category number
+  \param[out] type feature type
+  \param[out] id feature id
+  
+  \return 1 on success
+  \return 0 on error
+*/
+int Vect_cidx_get_cat_by_index(const struct Map_info *Map, int field_index,
+			       int cat_index, int *cat, int *type, int *id)
 {
     check_status(Map);		/* This check is slow ? */
 
@@ -250,22 +254,21 @@ static int cmp_cat(const void *pa, const void *pb)
 }
 
 /*!
-   \brief Find next line/area id for given category, start_index and type_mask 
-
-   \param Map vector map
-   \param field_index layer index
-   \param cat category number
-   \param type_mask requested type
-   \param start_index start search at this index (0 - whole category index)
-   \param[out] type returned type
-   \param[out] id returned line/area id
-
-   \return index to array
-   \return -1 not found
- */
-int
-Vect_cidx_find_next(const struct Map_info *Map, int field_index, int cat,
-		    int type_mask, int start_index, int *type, int *id)
+  \brief Find next line/area id for given category, start_index and type_mask 
+  
+  \param Map pointer to Map_info structure
+  \param field_index layer index
+  \param cat category number
+  \param type_mask requested type
+  \param start_index start search at this index (0 - whole category index)
+  \param[out] type returned type
+  \param[out] id returned line/area id
+  
+  \return index to array
+  \return -1 not found
+*/
+int Vect_cidx_find_next(const struct Map_info *Map, int field_index, int cat,
+			int type_mask, int start_index, int *type, int *id)
 {
     int *catp, cat_index;
     struct Cat_index *ci;
@@ -327,16 +330,14 @@ Vect_cidx_find_next(const struct Map_info *Map, int field_index, int cat,
 
 
 /*!
-   \brief Gind all line/area id's for given category
-
-   \param Map vector map
-   \param layer layer number
-   \param type_mask type of objects to search for
-   \param cat category number
-   \param[out] lines array of ids of found lines/points
-
-   \return 
- */
+  \brief Gind all line/area id's for given category
+  
+  \param Map pointer to Map_info structure
+  \param layer layer number
+  \param type_mask type of objects to search for
+  \param cat category number
+  \param[out] lines array of ids of found lines/points
+*/
 void Vect_cidx_find_all(const struct Map_info *Map, int layer, int type_mask,
 			int cat, struct ilist *lines)
 {
@@ -375,14 +376,14 @@ void Vect_cidx_find_all(const struct Map_info *Map, int layer, int type_mask,
 #define SEP "------------------------------------------------------------------------------------------\n"
 
 /*!
-   \brief Write category index in text form to file
-
-   \param Map vector map
-   \param[out] out output file
-
-   \return 1 on success
-   \return 0 on error
- */
+  \brief Write category index in text form to file
+  
+  \param Map pointer to Map_info structure
+  \param[out] out output file
+  
+  \return 1 on success
+  \return 0 on error
+*/
 int Vect_cidx_dump(const struct Map_info *Map, FILE * out)
 {
     int i, field, nfields, ntypes;
@@ -404,7 +405,8 @@ int Vect_cidx_dump(const struct Map_info *Map, FILE * out)
 	ntypes = Vect_cidx_get_num_types_by_index(Map, i);
 
 	fprintf(out,
-		"Layer %6d  number of unique cats: %7d  number of cats: %7d  number of types: %d\n",
+		"Layer %6d  number of unique cats: %7d  number of "
+		"cats: %7d  number of types: %d\n",
 		field, nucats, ncats, ntypes);
 	fprintf(out, SEP);
 
@@ -431,12 +433,12 @@ int Vect_cidx_dump(const struct Map_info *Map, FILE * out)
 }
 
 /*!
-   \brief Save category index to file (cidx)
+  \brief Save category index to file (cidx)
 
-   \param Map vector map
-
-   \return 0 on success
-   \return 1 on error
+  \param Map pointer to Map_info structure
+  
+  \return 0 on success
+  \return 1 on error
  */
 int Vect_cidx_save(struct Map_info *Map)
 {
@@ -473,14 +475,14 @@ int Vect_cidx_save(struct Map_info *Map)
 }
 
 /*!
-   \brief Read category index from file if exists
-
-   \param Map pointer to Map_info structure
-   \param head_only read only header
-
-   \return 0 on success 
-   \return 1 if file does not exist
-   \return -1 error, file exists but cannot be read
+  \brief Read category index from file if exists
+  
+  \param Map pointer to Map_info structure
+  \param head_only read only header
+  
+  \return 0 on success 
+  \return 1 if file does not exist
+  \return -1 error, file exists but cannot be read
  */
 int Vect_cidx_open(struct Map_info *Map, int head_only)
 {