vlib/diglib: doxygen update

use const / size_t


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

include/vect/dig_externs.h

@@ -177,7 +177,7 @@ void dig_spidx_free_areas(struct Plus_head *);
 void dig_spidx_free_isles(struct Plus_head *);
 void dig_spidx_free(struct Plus_head *);
 int dig_write_spidx(GVFILE *, struct Plus_head *);
-int dig_dump_spidx(FILE *, struct Plus_head *);
+int dig_dump_spidx(FILE *, const struct Plus_head *);
 int dig_read_spidx(GVFILE *, struct Plus_head *);
 
 /* category index */

lib/vector/Vlib/cindex.c

@@ -1,7 +1,7 @@
 /*!
  * \file Vlib/cindex.c
  *
- * \brief Vector library - Category index.
+ * \brief Vector library - category index.
  *
  * Higher level functions for reading/writing/manipulating vectors.
  *
@@ -432,7 +432,7 @@ int Vect_cidx_dump(const struct Map_info *Map, FILE * out)
 }
 
 /*!
-   \brief Save category index
+   \brief Save category index to file (cidx)
 
    \param Map vector map
 

lib/vector/Vlib/sindex.c

@@ -1,5 +1,5 @@
 /*!
-   \file sindex.c
+   \file Vlib/sindex.c
 
    \brief Vector library - spatial index
 
@@ -11,6 +11,7 @@
    (>=v2).  Read the file COPYING that comes with GRASS for details.
 
    \author Radim Blazek
+   \author Martin Landa <landa.martin gmail.com> (storing sidx to file)
  */
 
 #include <stdlib.h>
@@ -21,7 +22,7 @@
 #include <grass/glocale.h>
 
 /*!
-   \brief Init spatial index
+   \brief Initialize spatial index structure
 
    \param si pointer to spatial index structure
 
@@ -51,7 +52,7 @@ void Vect_spatial_index_destroy(SPATIAL_INDEX *si)
 }
 
 /*!
-   \brief Add a new item to spatial index
+   \brief Add a new item to spatial index structure
 
    \param[in,out] si pointer to spatial index structure
    \param id item identifier
@@ -75,7 +76,7 @@ void Vect_spatial_index_add_item(SPATIAL_INDEX *si, int id, const BOUND_BOX *box
 }
 
 /*!
-   \brief Delete item from spatial index
+   \brief Delete item from spatial index structure
 
    \param[in,out] si pointer to spatial index structure
    \param id item identifier
@@ -112,8 +113,7 @@ void Vect_spatial_index_del_item(SPATIAL_INDEX * si, int id)
    Map must be opened on level 2.
 
    \param[in,out] Map pointer to vector map
-   \param out print progress here
-
+   
    \return 0 OK
    \return 1 error
  */
@@ -121,7 +121,7 @@ int Vect_build_spatial_index(struct Map_info *Map)
 {
     if (Map->level < 2) {
 	G_fatal_error(_("Unable to build spatial index from topology, "
-			"vector map is not opened at topo level 2"));
+			"vector map is not opened at topology level 2"));
     }
     if (!(Map->plus.Spidx_built)) {
 	return (Vect_build_sidx_from_topo(Map));
@@ -130,7 +130,7 @@ int Vect_build_spatial_index(struct Map_info *Map)
 }
 
 /*!
-   \brief Create spatial index from topo if necessary
+   \brief Create spatial index from topology if necessary
 
    \param Map pointer to vector map
 
@@ -243,7 +243,7 @@ static int _add_item(int id, struct ilist *list)
 
    \param si pointer to spatial index structure
    \param box bounding box
-   \param list pointer to list where selected items are stored
+   \param[out] list pointer to list where selected items are stored
 
    \return number of selected items
  */
@@ -255,7 +255,7 @@ Vect_spatial_index_select(const SPATIAL_INDEX * si, const BOUND_BOX * box,
 
     G_debug(3, "Vect_spatial_index_select()");
 
-    list->n_values = 0;
+    Vect_reset_list(list);
 
     rect.boundary[0] = box->W;
     rect.boundary[1] = box->S;
@@ -266,5 +266,7 @@ Vect_spatial_index_select(const SPATIAL_INDEX * si, const BOUND_BOX * box,
     RTreeSearch(si->root, &rect, (void *)_add_item, list);
 
     G_debug(3, "  %d items selected", list->n_values);
+
     return (list->n_values);
 }
+

lib/vector/diglib/file.c

@@ -1,7 +1,7 @@
 /*!
    \file diglib/file.c
 
-   \brief Vector library (diglib) - file management
+   \brief Vector library - file management (lower level functions)
 
    Lower level functions for reading/writing/manipulating vectors.
 

lib/vector/diglib/port_init.c

@@ -1,61 +1,86 @@
-/*
- ****************************************************************************
- *
- * MODULE:       Vector library 
- *              
- * AUTHOR(S):    Original author CERL, probably Dave Gerdes.
- *               Update to GRASS 5.7 Radim Blazek.
- *
- * PURPOSE:      Lower level functions for reading/writing/manipulating vectors.
- *
- * COPYRIGHT:    (C) 2001 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.
- *
- *****************************************************************************/
+/*!
+   \file diglib/port_init.c
+
+   \brief Vector library - portability (lower level functions)
+
+   Lower level functions for reading/writing/manipulating vectors.
+
+   This code is a quick hack to allow the writing of portable
+   binary data files.
+   The approach is to take known values and compare them against
+   the current machine's internal representation.   A cross reference
+   table is then built, and then all file reads and writes must go
+   through these routines to correct the numbers if need be.
+
+   As long as the byte switching is symetrical, the conversion routines
+   will work both directions.
+   
+   The integer test patterns are quite simple, and their choice was
+   arbitrary, but the float and double valued were more critical.
+
+   I did not have a specification for IEEE to go by, so it is possible
+   that I have missed something.  My criteria were:
+
+   First, true IEEE numbers had to be chosen to avoid getting an FPE.
+   Second, every byte in the test pattern had to be unique.   And
+   finally, the number had to not be sensitive to rounding by the 
+   specific hardware implementation.
+   
+   By experimentation it was found that the number  1.3333  met
+   all these criteria for both floats and doubles
+
+   See the discourse at the end of this file for more information
+   
+   The 3.0 dig, and dig_plus files are inherently non-portable.  This 
+   can be seen in moving files between a SUN 386i and other SUN machines.
+   The recommended way to transport files was always to convert to ASCII
+   (b.a.vect) and copy the ASCII files:  dig_ascii and dig_att to the 
+   destination machine.
+
+   The problem lies in the way that different architectures internally
+   represent data.   If a number is internally store as  0x01020304 on
+   a 680x0 family machine, the same number will be stored as
+   0x04030201 on an 80386 class machine.
+
+   The CERL port of GRASS to the Compaq 386 already has code to deal
+   with this incompatibility.  This code converts all files that are written
+   out to conform to the 680x0 standard.  These binary files can then be 
+   shared between machines without conversion.
+   This code is designed to work with the majority of computers in use
+   today that fit the following requirements:
+   byte     ==  8 bits
+   int      ==  4 bytes
+   long     ==  4 bytes
+   double   ==  IEEE standard 64 bit
+   float    ==  IEEE standard 32 bit
+   
+   bytes can be swapped around in any reasonable way, but bits within each
+   byte must be maintained in normal high to low ordering:  76543210
+   is this a problem?
+
+   If this ability is desired on a SUN 386i, for example, you simply
+   define the compiler flag  CERL_PORTABLE in the src/CMD/makehead  file
+   and recompile all of the mapdev programs.
+   needs update, makehead/mapdev no longer exist
+
+   Binary DLG files are NOT supported by this code, and will continue to
+   be non-portable between different architectures.
+   applies to the files coor/topo/cidx, needs testing
+   
+   (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 Original author CERL, probably Dave Gerdes
+   \author Update to GRASS 5.7 Radim Blazek
+*/
+
 #include <grass/config.h>
 #include <stdio.h>
 #include <sys/types.h>
 #include <grass/Vect.h>
-
-/*
- **  Written by Dave Gerdes  9/1988
- **  US Army Construction Engineering Research Lab
- */
-
-
-/* 
- ** 
- **  This code is a quick hack to allow the writing of portable
- **  binary data files.
- **  The approach is to take known values and compare them against
- **  the current machine's internal representation.   A cross reference
- **  table is then built, and then all file reads and writes must go
- **  through these routines to correct the numbers if need be.
- **
- **  As long as the byte switching is symetrical, the conversion routines
- **  will work both directions.
-
- **  The integer test patterns are quite simple, and their choice was
- **  arbitrary, but the float and double valued were more critical.
-
- **  I did not have a specification for IEEE to go by, so it is possible
- **  that I have missed something.  My criteria were:
- **
- **  First, true IEEE numbers had to be chosen to avoid getting an FPE.
- **  Second, every byte in the test pattern had to be unique.   And
- **  finally, the number had to not be sensitive to rounding by the 
- **  specific hardware implementation.
- **
- **  By experimentation it was found that the number  1.3333  met
- **  all these criteria for both floats and doubles
-
- **  See the discourse at the end of this file for more information
- **  
- **
- */
+#include <grass/glocale.h>
 
 #define TEST_PATTERN 1.3333
 #define OFF_T_TEST 0x0102030405060708
@@ -106,7 +131,6 @@ unsigned char shrt_cnvrt[sizeof(short)];
  * match search_value against each char in basis. 
  * return offset or -1 if not found
  */
-
 static int find_offset(const unsigned char *basis, unsigned char search_value,
 		       int size)
 {
@@ -130,7 +154,7 @@ static int find_offsets(const void *pattern, unsigned char *cnvrt,
 	int off = find_offset(pattern, cmpr[i], nat_size);
 
 	if (off < 0)
-	    G_fatal_error("could not find '%x' in %s", cmpr[i], typename);
+	    G_fatal_error(_("Unable to find '%x' in %s"), cmpr[i], typename);
 
 	cnvrt[i] = off;
     }
@@ -153,6 +177,9 @@ static int find_offsets(const void *pattern, unsigned char *cnvrt,
     return ENDIAN_OTHER;
 }
 
+/*!
+  \brief Initialize structures
+*/
 void port_init(void)
 {
     static int done;
@@ -202,46 +229,3 @@ void port_init(void)
 	find_offsets(&u_s, shrt_cnvrt, shrt_cmpr, PORT_SHORT, nat_shrt,
 		     "short");
 }
-
-/*
-    comment copied from port_test.c
-    MM Feb 2009
-
-   The 3.0 dig, and dig_plus files are inherently non-portable.  This 
-   can be seen in moving files between a SUN 386i and other SUN machines.
-   The recommended way to transport files was always to convert to ASCII
-   (b.a.vect) and copy the ASCII files:  dig_ascii and dig_att to the 
-   destination machine.
-
-   The problem lies in the way that different architectures internally
-   represent data.   If a number is internally store as  0x01020304 on
-   a 680x0 family machine, the same number will be stored as
-   0x04030201 on an 80386 class machine.
-
-   The CERL port of GRASS to the Compaq 386 already has code to deal
-   with this incompatibility.  This code converts all files that are written
-   out to conform to the 680x0 standard.  These binary files can then be 
-   shared between machines without conversion.
-   This code is designed to work with the majority of computers in use
-   today that fit the following requirements:
-   byte     ==  8 bits
-   int      ==  4 bytes
-   long     ==  4 bytes
-   double   ==  IEEE standard 64 bit
-   float    ==  IEEE standard 32 bit
-   
-   bytes can be swapped around in any reasonable way, but bits within each
-   byte must be maintained in normal high to low ordering:  76543210
-   is this a problem?
-
-   If this ability is desired on a SUN 386i, for example, you simply
-   define the compiler flag  CERL_PORTABLE in the src/CMD/makehead  file
-   and recompile all of the mapdev programs.
-   needs update, makehead/mapdev no longer exist
-
-   Binary DLG files are NOT supported by this code, and will continue to
-   be non-portable between different architectures.
-   applies to the files coor/topo/cidx, needs testing
-
-   -dave gerdes
- */

lib/vector/diglib/portable.c

@@ -1,7 +1,7 @@
 /*!
    \file diglib/file.c
 
-   \brief Vector library (diglib) - portability
+   \brief Vector library - portability (lower level functions)
 
    Lower level functions for reading/writing/manipulating vectors.
    

lib/vector/diglib/spindex.c

@@ -1,18 +1,18 @@
-
-/**
- * \file spindex.c
- *
- * \brief Vector library - spatial index (lower level functions)
- *
- * Lower level functions for reading/writing/manipulating vectors.
- *
- * (C) 2001 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 CERL (probably Dave Gerdes), Radim Blazek
- */
+/*!
+  \file diglib/spindex.c
+ 
+  \brief Vector library - spatial index (lower level functions)
+  
+  Lower 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 Original author CERL, probably Dave Gerdes
+  \author Update to GRASS 5.7 Radim Blazek
+*/
 
 #include <stdlib.h>
 #include <string.h>

lib/vector/diglib/spindex_rw.c

@@ -1,28 +1,37 @@
-/*
- ****************************************************************************
- *
- * MODULE:       Vector library 
- *              
- * AUTHOR(S):    Radim Blazek.
- *
- * PURPOSE:      Lower level functions for reading/writing/manipulating vectors.
- *
- * COPYRIGHT:    (C) 2001 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.
- *
- *****************************************************************************/
+/*!
+  \file diglib/spindex.c
+ 
+  \brief Vector library - spatial index - read/write (lower level functions)
+  
+  Lower 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 Original author CERL, probably Dave Gerdes
+  \author Update to GRASS 5.7 Radim Blazek
+*/
+
 #include <grass/config.h>
 #include <sys/types.h>
 #include <stdlib.h>
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/Vect.h>
-
-
-int dig_Wr_spindx_head(GVFILE * fp, struct Plus_head *ptr)
+#include <grass/glocale.h>
+
+/*!
+  \brief Write spatial index to the file
+  
+  \param[in,out] fp pointer to GVFILE
+  \param ptr pointer to Plus_head structure
+
+  \return 0 on success
+  \return -1 on error
+*/
+static int dig_Wr_spindx_head(GVFILE * fp, struct Plus_head *ptr)
 {
     unsigned char buf[5];
     long length = 42;
@@ -36,7 +45,7 @@ int dig_Wr_spindx_head(GVFILE * fp, struct Plus_head *ptr)
     buf[2] = GV_SIDX_EARLIEST_MAJOR;
     buf[3] = GV_SIDX_EARLIEST_MINOR;
     buf[4] = ptr->spidx_port.byte_order;
-    if (0 >= dig__fwrite_port_C(buf, 5, fp))
+    if (0 >= dig__fwrite_port_C((const char *)buf, 5, fp))
 	return (-1);
 
     /* get required offset size */
@@ -60,7 +69,7 @@ int dig_Wr_spindx_head(GVFILE * fp, struct Plus_head *ptr)
 
     /* byte 10 : dimension 2D or 3D */
     buf[0] = ptr->spidx_with_z;
-    if (0 >= dig__fwrite_port_C(buf, 1, fp))
+    if (0 >= dig__fwrite_port_C((const char*) buf, 1, fp))
 	return (-1);
 
     /* bytes 11 - 38 (large files 11 - 66) : Offsets */
@@ -79,30 +88,38 @@ int dig_Wr_spindx_head(GVFILE * fp, struct Plus_head *ptr)
     if (0 >= dig__fwrite_port_O(&(ptr->Hole_spidx_offset), 1, fp, ptr->off_t_size))
 	return (-1);
 
-    G_debug(3, "spidx offset node = %ld line = %ld, area = %ld isle = %ld",
-	    ptr->Node_spidx_offset, ptr->Line_spidx_offset,
-	    ptr->Area_spidx_offset, ptr->Isle_spidx_offset);
+    G_debug(3, "spidx offset node = %lu line = %lu, area = %lu isle = %lu",
+	    (long unsigned) ptr->Node_spidx_offset, (long unsigned) ptr->Line_spidx_offset,
+	    (long unsigned) ptr->Area_spidx_offset, (long unsigned) ptr->Isle_spidx_offset);
 
     /* bytes 39 - 42 (large files 67 - 74) : Offsets */
     if (0 >= dig__fwrite_port_O(&(ptr->coor_size), 1, fp, ptr->off_t_size))
 	return (-1);
 
-    G_debug(2, "spidx body offset %ld", dig_ftell(fp));
+    G_debug(2, "spidx body offset %lu", (long unsigned) dig_ftell(fp));
 
     return (0);
 }
 
+/*!
+  \brief Read spatial index to the file
+  
+  \param fp pointer to GVFILE
+  \param[in,out] ptr pointer to Plus_head structure
 
-int dig_Rd_spindx_head(GVFILE * fp, struct Plus_head *ptr)
+  \return 0 on success
+  \return -1 on error
+*/
+static int dig_Rd_spindx_head(GVFILE * fp, struct Plus_head *ptr)
 {
     unsigned char buf[5];
     int byte_order;
-    long coor_size;
+    off_t coor_size;
 
     dig_rewind(fp);
 
     /* bytes 1 - 5 */
-    if (0 >= dig__fread_port_C(buf, 5, fp))
+    if (0 >= dig__fread_port_C((char*) buf, 5, fp))
 	return (-1);
     ptr->spidx_Version_Major = buf[0];
     ptr->spidx_Version_Minor = buf[1];
@@ -110,8 +127,7 @@ int dig_Rd_spindx_head(GVFILE * fp, struct Plus_head *ptr)
     ptr->spidx_Back_Minor = buf[3];
     byte_order = buf[4];
 
-    G_debug(2,
-	    "Sidx header: file version %d.%d , supported from GRASS version %d.%d",
+    G_debug(2, "Sidx header: file version %d.%d , supported from GRASS version %d.%d",
 	    ptr->spidx_Version_Major, ptr->spidx_Version_Minor,
 	    ptr->spidx_Back_Major, ptr->spidx_Back_Minor);
 
@@ -125,17 +141,17 @@ int dig_Rd_spindx_head(GVFILE * fp, struct Plus_head *ptr)
 	if (ptr->spidx_Back_Major > GV_SIDX_VER_MAJOR ||
 	    ptr->spidx_Back_Minor > GV_SIDX_VER_MINOR) {
 	    /* This version of GRASS lib is lower than the oldest which can read this format */
-	    G_fatal_error
-		("Spatial index format version %d.%d is not supported by this release."
-		 " Try to rebuild topology or upgrade GRASS.",
-		 ptr->spidx_Version_Major, ptr->spidx_Version_Minor);
+	    G_fatal_error(_("Spatial index format version %d.%d is not "
+			    "supported by this release."
+			    " Try to rebuild topology or upgrade GRASS."),
+			    ptr->spidx_Version_Major, ptr->spidx_Version_Minor);
 	    return (-1);
 	}
 
-	G_warning
-	    ("Your GRASS version does not fully support spatial index format %d.%d of the vector."
-	     " Consider to rebuild topology or upgrade GRASS.",
-	     ptr->spidx_Version_Major, ptr->spidx_Version_Minor);
+	G_warning(_("Your GRASS version does not fully support "
+		    "spatial index format %d.%d of the vector."
+		    " Consider to rebuild topology or upgrade GRASS."),
+		  ptr->spidx_Version_Major, ptr->spidx_Version_Minor);
     }
 
     dig_init_portable(&(ptr->spidx_port), byte_order);
@@ -147,7 +163,7 @@ int dig_Rd_spindx_head(GVFILE * fp, struct Plus_head *ptr)
     G_debug(2, "  header size %ld", ptr->spidx_head_size);
 
     /* byte 10 : dimension 2D or 3D */
-    if (0 >= dig__fread_port_C(buf, 1, fp))
+    if (0 >= dig__fread_port_C((char *)buf, 1, fp))
 	return (-1);
     ptr->spidx_with_z = buf[0];
     G_debug(2, "  with_z %d", ptr->spidx_with_z);
@@ -181,19 +197,28 @@ int dig_Rd_spindx_head(GVFILE * fp, struct Plus_head *ptr)
     /* bytes 39 - 42 (large files 67 - 74) : Offsets */
     if (0 >= dig__fread_port_O(&coor_size, 1, fp, ptr->off_t_size))
 	return (-1);
-    G_debug(2, "  coor size %ld", coor_size);
+    G_debug(2, "  coor size %lu", (long unsigned) coor_size);
 
     dig_fseek(fp, ptr->spidx_head_size, SEEK_SET);
 
     return (0);
 }
 
-int rtree_dump_node(FILE * fp, struct Node *n, int with_z);
+static int rtree_dump_node(FILE *, const struct Node *, int);
 
-/* Dump RTree branch to file */
-int rtree_dump_branch(FILE * fp, struct Branch *b, int with_z, int level)
+/*!
+  \brief Dump R-tree branch to the file
+
+  \param fp pointer to FILE
+  \param b pointer to Branch structure
+  \param with_z non-zero value for 3D vector data
+  \param level level value
+
+  \return 0
+*/
+static int rtree_dump_branch(FILE * fp, const struct Branch *b, int with_z, int level)
 {
-    struct Rect *r;
+    const struct Rect *r;
 
     r = &(b->rect);
 
@@ -209,8 +234,16 @@ int rtree_dump_branch(FILE * fp, struct Branch *b, int with_z, int level)
     return 0;
 }
 
-/* Dump RTree node to file */
-int rtree_dump_node(FILE * fp, struct Node *n, int with_z)
+/*!
+  \brief Dump R-tree node to the file
+
+  \param fp pointer to FILE
+  \param n pointer to Node structure
+  \param with_z non-zero value for 3D vector data
+
+  \return 0
+*/
+int rtree_dump_node(FILE * fp, const struct Node *n, int with_z)
 {
     int i, nn;
 
@@ -231,12 +264,22 @@ int rtree_dump_node(FILE * fp, struct Node *n, int with_z)
     return 0;
 }
 
-int rtree_write_node(GVFILE * fp, struct Node *n, int with_z);
+static int rtree_write_node(GVFILE *, const struct Node *, int);
+
+/*!
+  \brief Write R-tree node to the file
 
-/* Write RTree branch to file */
-int rtree_write_branch(GVFILE * fp, struct Branch *b, int with_z, int level)
+  \param fp pointer to GVFILE
+  \param b pointer to Branch structure
+  \param with_z non-zero value for 3D vector data
+  \param level level value
+
+  \return -1 on error
+  \return 0 on success
+*/
+static int rtree_write_branch(GVFILE * fp, const struct Branch *b, int with_z, int level)
 {
-    struct Rect *r;
+    const struct Rect *r;
     int i;
 
     r = &(b->rect);
@@ -263,8 +306,17 @@ int rtree_write_branch(GVFILE * fp, struct Branch *b, int with_z, int level)
     return 0;
 }
 
-/* Write RTree node to file */
-int rtree_write_node(GVFILE * fp, struct Node *n, int with_z)
+/*!
+  \brief Write R-tree node to the file
+
+  \param fp pointer to GVFILE
+  \param n pointer to Node structure
+  \param with_z non-zero value for 3D vector data
+  
+  \return -1 on error
+  \return 0 on success
+*/
+int rtree_write_node(GVFILE * fp, const struct Node *n, int with_z)
 {
     int i, nn;
 
@@ -289,10 +341,20 @@ int rtree_write_node(GVFILE * fp, struct Node *n, int with_z)
     return 0;
 }
 
-int rtree_read_node(GVFILE * fp, struct Node *n, int with_z);
+static int rtree_read_node(GVFILE * fp, struct Node *n, int with_z);
 
-/* Read RTree branch from file */
-int rtree_read_branch(GVFILE * fp, struct Branch *b, int with_z, int level)
+/*!
+  \brief Read R-tree branch from the file
+
+  \param fp pointer to GVFILE
+  \param b pointer to Branch structure
+  \param with_z non-zero value for 3D vector data
+  \param level level value
+
+  \return -1 on error
+  \return 0 on success
+*/
+static int rtree_read_branch(GVFILE * fp, struct Branch *b, int with_z, int level)
 {
     struct Rect *r;
     int i;
@@ -328,7 +390,17 @@ int rtree_read_branch(GVFILE * fp, struct Branch *b, int with_z, int level)
     return 0;
 }
 
-/* Read RTree node from file */
+/*!
+  \brief Read R-tree node from the file
+
+  \param fp pointer to GVFILE
+  \param n pointer to Node structure
+  \param with_z non-zero value for 3D vector data
+  \param level level value
+
+  \return -1 on error
+  \return 0 on success
+*/
 int rtree_read_node(GVFILE * fp, struct Node *n, int with_z)
 {
     int level, count, i;
@@ -353,7 +425,14 @@ int rtree_read_node(GVFILE * fp, struct Node *n, int with_z)
     return 0;
 }
 
-/* Write spatial index */
+/*!
+  \brief Write spatial index to the file
+
+  \param[out] fp pointer to GVFILE
+  \param Plus pointer to Plus_head structure
+
+  \return 0
+*/
 int dig_write_spidx(GVFILE * fp, struct Plus_head *Plus)
 {
     dig_set_cur_port(&(Plus->spidx_port));
@@ -379,7 +458,14 @@ int dig_write_spidx(GVFILE * fp, struct Plus_head *Plus)
     return 0;
 }
 
-/* Read spatial index file */
+/*!
+  \brief Read spatial index from the file
+
+  \param fp pointer to GVFILE
+  \param[in,out] Plus pointer to Plus_head structure
+
+  \return 0
+*/
 int dig_read_spidx(GVFILE * fp, struct Plus_head *Plus)
 {
     G_debug(1, "dig_read_spindx()");
@@ -406,8 +492,15 @@ int dig_read_spidx(GVFILE * fp, struct Plus_head *Plus)
     return 0;
 }
 
-/* Dump spatial index */
-int dig_dump_spidx(FILE * fp, struct Plus_head *Plus)
+/*!
+  \brief Dump spatial index
+
+  \param[out] fp pointe to FILE
+  \param Plus pointer to Plus_head structure
+
+  \return 0
+*/
+int dig_dump_spidx(FILE * fp, const struct Plus_head *Plus)
 {
 
     fprintf(fp, "Nodes\n");