vlib: doxygen cosmetics

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

lib/vector/Vlib/write.c

@@ -6,10 +6,10 @@
    Higher level functions for reading/writing/manipulating vectors.
 
    Operations:
-    - Add feature
+    - Write new feature
     - Rewrite feature
     - Delete feature
-    - Restore feature
+    - Restore deleted feature
 
    (C) 2001-2010, 2012 by the GRASS Development Team
 
@@ -158,19 +158,20 @@ static int (*Vect_restore_line_array[][3]) () = {
 };
 
 /*!
-   \brief Writes new feature to the end of file
+   \brief Writes new feature
 
-   Vector map topology is not required.
-
-   The function calls G_fatal_error() on error.
+   New feature is written to the end of file (in the case of native
+   format). Vector map topology is not required.
 
+   Calls G_fatal_error() when vector map is not opened.
+   
    \param Map pointer to Map_info structure
-   \param type feature type (GV_POINT, GV_LINE, ...)
-   \param points feature geometry
-   \param cats feature categories
+   \param type feature type (see dig_defines.h for supported types)
+   \param points ointer to line_pnts structure (feature geometry)
+   \param cats pointer to line_cats structure (feature categories)
 
-   \return new feature id (level 2)
-   \return offset into file where the feature starts (level 1)
+   \return new feature id (on level 2)
+   \return offset into file where the feature starts (on level 1)
    \return -1 on error
  */
 off_t Vect_write_line(struct Map_info *Map, int type,
@@ -196,7 +197,9 @@ off_t Vect_write_line(struct Map_info *Map, int type,
     if (offset == -1)
 	G_fatal_error(_("Unable to write feature (negative offset)"));
     */
-    /* NOTE: returns new line id on level 2 and file offset on level 1 */
+    
+    /* note: returns new feature id on level 2 and file offset on
+       level 1 */
     return offset;
 }
 
@@ -232,7 +235,7 @@ off_t Vect_rewrite_line(struct Map_info *Map, int line, int type,
     }
 
     offset = Map->plus.Line[line]->offset;
-    G_debug(3, "Vect_rewrite_line(): name = %s, line = %d offset = %llu",
+    G_debug(3, "Vect_rewrite_line(): name = %s, line = %d offset = %lu",
 	    Map->name, line, offset);
     ret = (*Vect_rewrite_line_array[Map->format][Map->level]) (Map, line, type,
 							       offset,

lib/vector/Vlib/write_ogr.c

@@ -220,8 +220,8 @@ off_t V1_write_line_ogr(struct Map_info *Map, int type,
   \param Map pointer to Map_info structure
   \param offset feature offset
   \param type feature type (see V1_write_line_ogr() for supported types)
-  \param points feature geometry
-  \param cats feature categories
+  \param points pointer to line_pnts structure (feature geometry)
+  \param cats pointer to line_cats structure (feature categories)
   
   \return feature offset (rewriten feature)
   \return -1 on error

lib/vector/Vlib/write_sfa.c

@@ -1,7 +1,7 @@
 /*!
    \file lib/vector/Vlib/write_sfa.c
 
-   \brief Vector library - write vector feature - simple feature access
+   \brief Vector library - write vector feature - simple feature access (level 2)
 
    Higher level functions for reading/writing/manipulating vectors.
 
@@ -30,14 +30,14 @@ void V2__add_line_to_topo_sfa(struct Map_info *, int, const struct line_pnts *,
 #endif
 
 /*!
-  \brief Writes feature on level 2 (OGR/PostGIS interface)
+  \brief Writes feature on level 2 (OGR/PostGIS interface, pseudo-topological level)
 
   \param Map pointer to Map_info structure
-  \param type feature type (GV_POINT, GV_LINE, ...)
+  \param type feature type (see V1_write_line_ogr() for list of supported types)
   \param points pointer to line_pnts structure (feature geometry) 
   \param cats pointer to line_cats structure (feature categories)
   
-  \return feature offset into file
+  \return feature index in offset array (related to pseudo-topology)
   \return -1 on error
 */
 off_t V2_write_line_sfa(struct Map_info *Map, int type,
@@ -124,14 +124,15 @@ off_t V2_write_line_sfa(struct Map_info *Map, int type,
 }
 
 /*!
-  \brief Rewrites feature to 'coor' file (topology level) - internal use only
+  \brief Rewrites feature at the given offset on level 2 (OGR/PostGIS
+  interface, pseudo-topological level)
   
   \param Map pointer to Map_info structure
-  \param line feature id
-  \param type feature type (GV_POINT, GV_LINE, ...)
-  \param offset unused
-  \param points feature geometry
-  \param cats feature categories
+  \param line feature id to be rewritten
+  \param type feature type (see V1_write_line_ogr() for supported types)
+  \param offset unused (kept for consistency)
+  \param points pointer to line_pnts structure (feature geometry)
+  \param cats pointer to line_cats structure feature categories
   
   \return offset where line was rewritten
   \return -1 on error
@@ -139,7 +140,7 @@ off_t V2_write_line_sfa(struct Map_info *Map, int type,
 off_t V2_rewrite_line_sfa(struct Map_info *Map, int line, int type, off_t offset,
 			  const struct line_pnts *points, const struct line_cats *cats)
 {
-    G_debug(3, "V2_rewrite_line_sfa(): line=%d type=%d offset=%llu",
+    G_debug(3, "V2_rewrite_line_sfa(): line=%d type=%d offset=%lu",
 	    line, type, offset);
 
 #if defined HAVE_OGR || defined HAVE_POSTGRES
@@ -158,12 +159,12 @@ off_t V2_rewrite_line_sfa(struct Map_info *Map, int line, int type, off_t offset
 }
 
 /*!
-  \brief Deletes feature (topology level) -- internal use only
+  \brief Deletes feature on level 2 (OGR/PostGIS interface)
   
   \todo Update fidx
   
   \param pointer to Map_info structure
-  \param line feature id
+  \param line feature id to be deleted
   
   \return 0 on success
   \return -1 on error
@@ -250,8 +251,8 @@ int V2_delete_line_sfa(struct Map_info *Map, int line)
 
   \param Map pointer to Map_info structure
   \param line feature id
-  \param points pointer to line_pnts structure (feature's geometry)
-  \param cats pointer to line_cats structure (feature's categories)
+  \param points pointer to line_pnts structure (feature geometry)
+  \param cats pointer to line_cats structure (feature categories)
 */
 void V2__add_line_to_topo_sfa(struct Map_info *Map, int line,
 			      const struct line_pnts *points,