veditlib: doxygen updates

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

lib/grasslib.dox

@@ -95,6 +95,9 @@ from GRASS 5 Programmer's manual) or are simply undocumented.</I>
 <li>symbol:	Drawing symbols for %point %vector data library - \ref symbol
 <li>vask:	Cursor management library - \ref vask
 <li>%vector:	\ref Vector_Library (GRASS Vector and Direct Graph Library)
+<ul>
+<li>vedit: \ref Vedit_Library - %vector editing
+</ul>
 <li>nviz:       \ref nvizlib (used by wxGUI Nviz extension and CLI-based Nviz module)
 </ul>
 <!--<li>image3:	extra imagery library (mainly still unused) - \ref image3lib-->

lib/vector/vedit/Makefile

@@ -9,5 +9,9 @@ EXTRA_CFLAGS = $(VECT_CFLAGS)
 EXTRA_LIBS = $(VECTLIB) $(DBMILIB) $(GISLIB)
 
 include $(MODULE_TOPDIR)/include/Make/Lib.make
+include $(MODULE_TOPDIR)/include/Make/Doxygen.make
 
 default: lib
+
+# doxygen
+DOXNAME=vedit

lib/vector/vedit/cats.c

@@ -1,16 +1,15 @@
 /**
-   \file cats.c
+   \file vector/vedit/cats.c
 
    \brief Vedit library - category manipulation
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2006-2008 by the GRASS Development Team
 
-   \author (C) 2006-2008 by the GRASS Development Team
-   Jachym Cepicky <jachym.cepicky gmail.com>
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Jachym Cepicky <jachym.cepicky gmail.com>
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2006-2008
 */
@@ -18,15 +17,15 @@
 #include <grass/vedit.h>
 
 /**
-   \brief Add/remove categories of selected vector features
+   \brief Add / remove categories
 
-   \param[in] Map vector map
-   \param[in] List list of selected features
-   \param[in] layer layer number
-   \param[in] del action (non-zero for delete otherwise add)
-   \param[in] cats_list list of category numbers
+   \param Map vector map
+   \param List list of selected primitives
+   \param layer layer number
+   \param del action (non-zero for delete otherwise add)
+   \param cats_list list of category numbers
 
-   \return number of modified features
+   \return number of modified primitives
    \return -1 on error
 */
 int Vedit_modify_cats (struct Map_info *Map, struct ilist *List,

lib/vector/vedit/chtype.c

@@ -1,25 +1,37 @@
 /**
-   \file chtype.c
+   \file vector/vedit/chtype.c
 
-   \brief Vedit library - change feature type
+   \brief Vedit library - change primitives type
 
-   Supported conversions:
-    - point<->centroid
-    - line<->boundary
+    (C) 2008 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 (C) 2008 by the GRASS Development Team
-   Martin Landa <landa.martin gmail.com>
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2008
 */
 
 #include <grass/vedit.h>
 
+/**
+   \brief Change primitive type
+
+   Supported conversions:
+    - point <-> centroid
+    - line <-> boundary
+
+    \param Map vector map
+    \param List list of selected primitives
+    \param[out] npoints number of points after conversion
+    \param[out] ncentroids number of centroids after conversion
+    \param[out] nlines number of lines after conversion
+    \param[out] nboundaries number of boundaries after conversion
+
+    \return number of modified primitives
+    \return -1 on error
+*/
 int Vedit_chtype_lines(struct Map_info *Map, struct ilist *List,
 		       int *npoints, int *ncentroids,
 		       int *nlines, int *nboundaries)

lib/vector/vedit/copy.c

@@ -1,16 +1,15 @@
 /**
-   \file copy.c
+   \file vector/vedit/copy.c
 
-   \brief Vedit library - copy features
+   \brief Vedit library - copy primitives
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2007-2008 by the GRASS Development Team
 
-   \author (C) 2007-2008 by the GRASS Development Team
-   Jachym Cepicky <jachym.cepicky gmail.com>
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Jachym Cepicky <jachym.cepicky gmail.com>
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2007-2008
 */
@@ -18,13 +17,13 @@
 #include <grass/vedit.h>
 
 /**
-   \brief Copy selected features
+   \brief Copy selected primitives
 
-   \param[in] Map vector map copy to
-   \param[in] FromMap vector map copy from (if not given use Map)
-   \param[in] List list of selected features (to be copied)
+   \param Map vector map copy to
+   \param FromMap vector map copy from (if not given use Map)
+   \param List list of selected primitives (to be copied)
 
-   \return number of copied features
+   \return number of copied primitives
    \return -1 on error 
  */
 int Vedit_copy_lines (struct Map_info *Map, struct Map_info *FromMap,

lib/vector/vedit/delete.c

@@ -1,15 +1,14 @@
 /**
-   \file delete.c
+   \file vector/vedit/delete.c
 
-   \brief Vedit library - delete features
+   \brief Vedit library - delete primitives
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2007-2008 by the GRASS Development Team
 
-   \author (C) 2007-2008 by the GRASS Development Team
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2007-2008
 */
@@ -17,12 +16,12 @@
 #include <grass/vedit.h>
 
 /**
-   \brief Delete selected features
+   \brief Delete selected primitives
 
-   \param[in] Map vector map
-   \param[in] List list of features to be deleted
+   \param Map vector map
+   \param List list of primitives to be deleted
 
-   \return number of deleted features
+   \return number of deleted primitives
    \return -1 on on error
  */
 int Vedit_delete_lines(struct Map_info *Map, struct ilist *List)

lib/vector/vedit/distance.c

@@ -1,15 +1,13 @@
 /**
-   \file distance.c
+   \file vector/vedit/distance.c
 
    \brief Vedit library - distance calculation
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
-
    (C) 2007-2008 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 Martin Landa <landa.martin gmail.com>
 
    \date 2007-2008
@@ -20,10 +18,10 @@
 /**
    \brief Calculate distances between two lines
  
-   TODO: LL projection
+   \todo LL projection
 
-   \param[in] Points1 first line
-   \param[in] Points2 second line
+   \param Points1 first line geometry
+   \param Points2 second line geometry
    \param[out] index of minimal distance
 
    \return minimal distance betwen two lines (their nodes)

lib/vector/vedit/flip.c

@@ -1,15 +1,14 @@
 /**
-   \file flip.c
+   \file vector/vedit/flip.c
 
-   \brief Vedit library - lines flipping
+   \brief Vedit library - flip lines
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2007-2008 by the GRASS Development Team
 
-   \author (C) 2007-2008 by the GRASS Development Team
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2007-2008
 */
@@ -17,10 +16,10 @@
 #include <grass/vedit.h>
 
 /**
-   \brief Flip direction of selected vector lines
+   \brief Flip direction of selected lines
 
-   \param[in] Map vector map
-   \param[in] List list of selected lines
+   \param Map vector map
+   \param List list of selected lines
 
    \return number of modified lines
    \return -1 on error

lib/vector/vedit/merge.c

@@ -1,16 +1,15 @@
 /**
-   \file merge.c
+   \file vector/vedit/merge.c
 
    \brief Vedit library - merge lines
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2006-2008 by the GRASS Development Team
 
-   \author (C) 2006-2008 by the GRASS Development Team
-   Jachym Cepicky <jachym.cepicky gmail.com>
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Jachym Cepicky <jachym.cepicky gmail.com>
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2006-2008
 */
@@ -24,9 +23,9 @@
    b : Points2/Cats2
    merged line : Points/Cats
    
-   \param[in] Points1,Cats1 first line
-   \param[in] Points2,Cats2 second line
-   \param[in] thresh threshold value
+   \param Points1,Cats1 first line
+   \param Points2,Cats2 second line
+   \param thresh threshold value
    \param[out] Points result line
 
    \return 1 on success
@@ -41,8 +40,8 @@ static int merge_lines (struct line_pnts *Points1, struct line_cats *Cats1,
  
    At least two lines need to be given.
 
-   \param[in] Map vector map
-   \param[in] List list of selected features
+   \param Map vector map
+   \param List list of selected lines
 
    \return number of merged lines
    \return -1 on error

lib/vector/vedit/move.c

@@ -1,16 +1,15 @@
 /**
-   \file move.c
+   \file vector/vedit/move.c
 
-   \brief Vedit library - snapping
+   \brief Vedit library - move primitives
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2007-2008 by the GRASS Development Team
 
-   \author (C) 2007-2008 by the GRASS Development Team
-   Martin Landa <landa.martin gmail.com>
-   Jachym Cepicky <jachym.cepicky gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Martin Landa <landa.martin gmail.com>
+   \author Jachym Cepicky <jachym.cepicky gmail.com>
 
    \date 2007-2008
 */
@@ -18,15 +17,15 @@
 #include <grass/vedit.h>
 
 /**
-   \brief Move selected features
+   \brief Move selected primitives
    
-   \param[in] Map vector map
-   \param[in] BgMap, nbgmaps list of background vector maps for snapping   
-   \param[in] List list of features to be moved
-   \param[in] move_x,move_y,move_z direction (move_z used only if map is 3D)
-   \param[in] snap enable snapping (see globals.h)
+   \param Map vector map
+   \param BgMap, nbgmaps list of background vector maps used for snapping   
+   \param List list of primitives to be moved
+   \param move_x,move_y,move_z direction (move_z used only if map is 3D)
+   \param snap enable snapping (see globals.h)
 
-   \return number of modified features
+   \return number of modified primitives
    \return -1 on error
 */
 int Vedit_move_lines(struct Map_info *Map, struct Map_info **BgMap, int nbgmaps,

lib/vector/vedit/select.c

@@ -1,13 +1,14 @@
 /**
-   \brief Vedit library - select vector features (by query)
+   \file vector/vedit/select.c
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   \brief Vedit library - select primitives by query
 
-   \author (C) 2007-2008 by the GRASS Development Team
-   Martin Landa <landa.martin gmail.com>
+   (C) 2007-2008 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 Martin Landa <landa.martin gmail.com>
 
    \date 2007-2008
 */
@@ -20,23 +21,23 @@ static int select_by_query(struct Map_info *, int, int, double,
 static int merge_lists (struct ilist* alist, struct ilist* blist);
 
 /**
-   \brief Select features by query (based on geometry properties)
+   \brief Select primitives by query (based on geometry properties)
 
    Currently supported:
-    - QUERY_LENGTH, select all features longer than threshold (or shorter if threshold is < 0)
+    - QUERY_LENGTH, select all lines longer than threshold (or shorter if threshold is < 0)
     - QUERY_DANGLE, select all dangles longer than threshold (or shorter if threshold is < 0)
 
    Perform global query if <i>List</i> is empty otherwise query only
    selected vector objects.
 
-   \param[in] Map vector map
-   \param[in] type feature type
-   \param[in] layer layer number
-   \param[in] thresh threshold value (< 0 for 'shorter', > 0 for 'longer')
-   \param[in] query query (length, dangle, ...)
+   \param Map vector map
+   \param type feature type
+   \param layer layer number
+   \param thresh threshold value (< 0 for 'shorter', > 0 for 'longer')
+   \param query query (length, dangle, ...)
    \param[in,out] List list of selected features
  
-   \return number of selected lines
+   \return number of selected primitives
 */
 int Vedit_select_by_query(struct Map_info *Map,
 			  int type, int layer, double thresh, int query,
@@ -122,7 +123,7 @@ int Vedit_select_by_query(struct Map_info *Map,
 }
 
 /**
-   \brief Query given feature
+   \brief Query selected primitive
 
    \return 1 line test positive 
    \return 0 line test negative
@@ -237,7 +238,7 @@ int select_by_query(struct Map_info *Map, int line, int type, double thresh,
    \brief Merge two lists, i.e. store only duplicate items
 
    \param[in,out] alist list to be merged
-   \param[in] blist list used for merging
+   \param blist list used for merging
 
    \return result number of items
 */

lib/vector/vedit/snap.c

@@ -1,15 +1,14 @@
 /**
-   \file snap.c
+   \file vector/vedit/snap.c
 
    \brief Vedit library - snapping
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2007-2008 by the GRASS Development Team
 
-   \author (C) 2007-2008 by the GRASS Development Team
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2007-2008
 */
@@ -17,13 +16,13 @@
 #include <grass/vedit.h>
 
 /**
-   \brief Snap given point to the nearest feature
+   \brief Snap given point to the nearest primitive
    
-   \param[in] Map vector map
-   \param[in] line line to be excluded (point on line)
-   \param[in] x,y,z point on line to be snapped
-   \param[in] thresh snapping threshold (>0)
-   \param[in] vertex snap also to vertex
+   \param Map vector map
+   \param line line to be excluded (point on line)
+   \param x,y,z point on line to be snapped
+   \param thresh snapping threshold (>0)
+   \param vertex snap also to vertex (non-zero)
 
    \return 1 snapped
    \return 0 not snapped
@@ -86,17 +85,15 @@ int Vedit_snap_point(struct Map_info *Map,
 }
 
 /**
-   \brief Snap lines/boudaries to the nearest feature
+   \brief Snap selected primitive to its nearest primitive
    
-   If 'line' > 0, given line is snapped and rewritten.
-
-   \param[in] Map pointer to vector map
-   \param[in] BgMap,nbgmaps list of background maps used for snapping
-   \param[in] line line to be snapped (if already written, otherwise -1)
-   \param[in] Points line geometry
-   \param[in] layer layer number
-   \param[in] thresh threshold value used for snapping (>0)
-   \param[in] to_vertex allow snapping also to vertex
+   \param Map vector map
+   \param BgMap,nbgmaps list of background maps used for snapping
+   \param line line id to be snapped (if already written, otherwise -1)
+   \param Points line geometry
+   \param layer layer number
+   \param thresh threshold value used for snapping (>0)
+   \param to_vertex allow snapping also to vertex
 
    \return 1 line snapped
    \return 0 line not snapped
@@ -165,14 +162,14 @@ int Vedit_snap_line(struct Map_info *Map, struct Map_info **BgMap, int nbgmaps,
 }
 
 /**
-   \brief Snap lines/boudaries to the nearest feature
+   \brief Snap lines/boundaries
    
-   \param[in] Map vector map
-   \param[in] BgMap,nbgmaps List of background maps
-   \param[in] List list of lines to be snapped
-   \param[in] layer layer number
-   \param[in] thresh threshold value used for snapping (>0)
-   \param[in] to_vertex allow snapping also to vertex
+   \param Map vector map
+   \param BgMap,nbgmaps list of background maps used for snapping
+   \param List list of lines to be snapped
+   \param layer layer number
+   \param thresh threshold value used for snapping (>0)
+   \param to_vertex allow snapping also to vertex
 
    \return number of snapped lines
    \return -1 on error

lib/vector/vedit/veditlib.dox

@@ -0,0 +1,68 @@
+/*! \page Vedit_Library GRASS Vedit Library
+
+by GRASS Development Team
+
+http://grass.osgeo.org
+
+\section veditIntro Introduction to Vedit Library
+
+This library contains higher level functions to edit %vector primitives
+geometry (see \ref Vector_Library). Currently only 2D primitives are
+supported (points, lines, boundaries and centroids).
+
+<p>
+The library is currently used by v.edit module and wxGUI %vector digitizer.
+
+\section veditFn Functions
+
+\subsection veditModify Modify lines/boundaries
+
+ - int Vedit_split_lines()
+
+ - int Vedit_connect_lines()
+
+ - int Vedit_chtype_lines()
+
+ - int Vedit_delete_lines()
+
+ - int Vedit_flip_lines()
+
+ - int Vedit_merge_lines()
+
+ - int Vedit_move_lines()
+
+\subsection veditCats Manipulate feature categories
+
+ - int Vedit_modify_cats()
+
+\subsection veditCopy Copy primitives
+
+ - int Vedit_copy_lines()
+
+\subsection veditSelect Select primitives
+
+ - int Vedit_select_by_query()
+
+\subsection veditSnap Snapping
+
+ - int Vedit_snap_point()
+
+ - int Vedit_snap_line()
+
+ - int Vedit_snap_lines()
+
+\subsection veditVertex Vertex manipulation
+
+ - int Vedit_move_vertex()
+
+ - int Vedit_add_vertex()
+
+ - int Vedit_remove_vertex()
+
+\subsection veditMisc Miscellaneous
+
+ - double Vedit_get_min_distance()
+
+ - int Vedit_bulk_labeling()
+
+*/

lib/vector/vedit/vertex.c

@@ -1,16 +1,15 @@
 /**
-   \file vertex.c
+   \file vector/vedit/vertex.c
 
    \brief Vedit library - vertex manipulation
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2006-2008 by the GRASS Development Team
 
-   \author (C) 2006-2008 by the GRASS Development Team
-   Jachym Cepicky <jachym.cepicky gmail.com>
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Jachym Cepicky <jachym.cepicky gmail.com>
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2006-2008
 */
@@ -20,15 +19,15 @@
 /**
    \brief Move all vertices in bounding box(es)
 
-   \param[in] Map vector map
-   \param[in] BgMap, nbgmaps list of background vector maps for snapping
-   \param[in] List list of selected features
-   \param[in] coord points location
-   \param[in] thresh_coords threshold value for selecting vector feature
-   \param[in] thresh_snap threshold value used for snapping
-   \param[in] move_x,move_y,move_z direction (move_z is used when map is 3D)
-   \param[in] move_first move only first vertex found in the bounding box
-   \param[in] snap snapping mode (see vedit.h)
+   \param Map vector map
+   \param BgMap, nbgmaps list of background vector maps for snapping
+   \param List list of selected lines
+   \param coord points location
+   \param thresh_coords threshold value for selecting lines
+   \param thresh_snap threshold value used for snapping
+   \param move_x,move_y,move_z direction (move_z is used when map is 3D)
+   \param move_first move only first vertex found in the bounding box
+   \param snap snapping mode (see vedit.h)
 
    \return number of moved verteces
    \return -1 on error
@@ -172,16 +171,16 @@ int Vedit_move_vertex(struct Map_info *Map, struct Map_info **BgMap, int nbgmaps
 }
 
 /**
-   \brief Add new vertex to line.
+   \brief Add new vertex to line
 
    Shape of line is not changed.
 
-   TODO: 3D
+   \todo 3D
 
-   \param[in] Map vector map
-   \param[in] List list of features
-   \param[in] coord points location
-   \param[in] thresh find line in given threshold
+   \param Map vector map
+   \param List list of lines
+   \param coord points location
+   \param thresh find line in given threshold
 
    \return number of add verteces
    \return -1 on error
@@ -262,12 +261,12 @@ int Vedit_add_vertex(struct Map_info *Map, struct ilist *List,
 /**
    \brief Remove vertex from line
 
-   TODO: 3D
+   \todo 3D
 
-   \param[in] Map vector map
-   \param[in] List list of selected features
-   \param[in] coord points location
-   \param[in] thresh threshold value to find a line
+   \param Map vector map
+   \param List list of selected lines
+   \param coord points location
+   \param thresh threshold value to find a line
 
    \return number of removed vertices
    \return -1 on error

lib/vector/vedit/zbulk.c

@@ -1,15 +1,15 @@
 /**
-   \file zbulk.c
+   \file vector/vedit/zbulk.c
 
-   \brief Vedit library - Bulk labeling (automated labeling of vector features)
+   \brief Vedit library - Bulk labeling (automated labeling of vector
+   features)
 
-   This program is free software under the
-   GNU General Public License (>=v2).
-   Read the file COPYING that comes with GRASS
-   for details.
+   (C) 2007-2008 by the GRASS Development Team
 
-   \author (C) 2007-2008 by the GRASS Development Team
-   Martin Landa <landa.martin gmail.com>
+   This program is free software under the GNU General Public License
+   (>=v2).  Read the file COPYING that comes with GRASS for details.
+
+   \author Martin Landa <landa.martin gmail.com>
 
    \date 2007-2008
 */
@@ -18,15 +18,15 @@
 #include <grass/vedit.h>
 
 /**
-   \brief Z bulk-labeling.
+   \brief Lines z-bulk labeling
 
-   Automated labeling (z coordinate assignment) of vector lines (contours).
+   Automated labeling (z coordinate assignment) of vector lines (iso-lines).
 
-   \param[in] Map vector map
-   \param[in] List list of selected features
-   \param[in] point_start_end staring and ending point
-   \param[in] start starting value
-   \param[in] step step
+   \param Map vector map
+   \param List list of selected lines
+   \param point_start_end staring and ending point
+   \param start starting value
+   \param step step value
 
    \return number of modified features
    \return -1 on error