doxygen backports: trunk https://trac.osgeo.org/grass/changeset/66138,r66143,r66146,r66155

git-svn-id: https://svn.osgeo.org/grass/grass/branches/releasebranch_7_0@66247 15284696-431f-4ddb-bdfa-cd5b030d7da7

grasslib.dox

@@ -64,24 +64,24 @@ href="http://grass.osgeo.org">http://grass.osgeo.org</a>
 
 \subsection displaylibs Display Libraries and Drivers
 
- - display:	\ref displaylib (general displaylibrary)
- - cairodriver: \ref cairodriver (cairo graphics driver)
+ - display:	\ref displaylib (general display library)
+ - cairodriver: \ref cairodriver
  - %driver:     Graphics monitor driver
  - htmldriver:  \ref htmldriverlib (HTML graphics driver)
- - pngdriver:   \ref pngdriverlib (PNG graphics driver)
- - psdriver:    \ref psdriverlib (Postscript graphics driver)
+ - pngdriver:   \ref pngdriverlib
+ - psdriver:    \ref psdriverlib
 
-\subsection statslibs Math and Statisctics Libraries
+\subsection statslibs Math and Statistics Libraries
 
  - arraystats:  \ref arraystatslib (library of statistics for arrays of doubles)
- - cdhc:	\ref cdhclib (library for testing normality and exponentiality)
+ - cdhc:	\ref cdhclib
  - gmath: 	\ref gmathlib (generic mathematical functions and BLAS/LAPACK library wrapper)
- - gpde:        \ref gpdelib (partial differential equations library)
+ - gpde:        \ref gpdelib
 
 \subsection rasteribs Raster Libraries
 
  - raster:	\ref rasterlib (2D raster library)
- - raster3d:	\ref raster3dlib (3D raster library - voxels)
+ - raster3d:	\ref raster3dlib (3D raster aka voxels or volumes)
  - rowio:	\ref rowiolib (library for reading/writing raster rows)
  - rst:	        \ref rstlib (library for interpolation with regularized splines with tension)
  - segment:	\ref segmentlib (segment library for segmented raster reading)
@@ -95,10 +95,16 @@ href="http://grass.osgeo.org">http://grass.osgeo.org</a>
 \subsection vectoribs Vector Libraries
 
  - %vector: \ref vectorlib (architecture description)
-  - dglib:  \ref dglib (directed graph library)
+  - dglib:  \ref dglib
   - vedit:  \ref veditlib (vector editing library)
-  - neta:   \ref netalib (network analysis library)
-  - rtree:  \ref rtree (R search tree library)
+  - neta:   \ref netalib
+  - rtree:  \ref rtree.h (R search tree library)
+
+\subsection treelibs Search tree libraries
+
+ - btree: \ref btree.h
+ - btree2: \ref btree2
+ - rtree:  \ref rtree.h (R search tree library)
 
 \subsection dblibs Database Management Libraries
 
@@ -117,14 +123,14 @@ href="http://grass.osgeo.org">http://grass.osgeo.org</a>
 
  - proj:	\ref projlib (wrapper to PROJ4 projection library)
 
-\subsection misclibs Misc Libraries
+\subsection misclibs Miscellaneous Libraries
 
  - datetime:	\ref datetime (DateTime library) 
  - external:	\ref external (External libraries from other projects such as shapelib and \ref ccmathlib)
  - fonts:	\ref fonts (GRASS fonts library)
  - init:	\ref init (GRASS initialization code + scripts)
  - iostream:	\ref iostream (fast I/O library)
- - lidar:	\ref lidar (LiDAR data related library)
+ - lidar:	\ref lidar.h (LiDAR data related library)
  - linkm:	\ref linkm (linked list memory manager)
  - manage:      \ref managelib
  - symbol:	\ref symbol (Drawing symbols for %point %vector data library)

lib/gis/gislib.dox

@@ -1,4 +1,4 @@
-/*! \page gislib GRASS GIS Library
+/*! \page gislib GRASS GIS General Library (aka GIS Library)
 <!-- doxygenized from "GRASS 5 Programmer's Manual" 
      by M. Neteler 2/2004, 2005, 2006
   -->

lib/rst/data/DESCRIPTION.DATA

@@ -1,135 +0,0 @@
-/* updated by Mitasova Nov. 96 */
-
-DATA STRUCTURES:
-----------------
-
-#define NW   1
-#define NE   2
-#define SW   3
-#define SE   4
-
-/* added sm for spatially variable smoothing by Mitasova  10.96 */
-struct triple   {
-  double x;
-  double y;
-  double z;
-  double sm; 
-};
-
-struct quaddata {
-  double x_orig;
-  double y_orig;
-  double xmax;
-  double ymax;
-  int    n_rows;
-  int    n_cols;
-  int    n_points;
-  struct triple  *points;
-};
-
-
-
-
-FUNCTIONS:
-----------
-
-struct triple  *
-quad_point_new (x, y, z, sm)
-    double          x;
-    double          y;
-    double          z;
-    double          sm;
-/* Initializes POINT structure with given arguments,
-s was added for variable smoothing 10.96 helena */
-
-
-
-
-struct quaddata *
-quad_data_new(x_or,y_or,xmax,ymax,rows,cols,n_points,kmax)
-    double          x_or;
-    double          y_or;
-    double          xmax;
-    double          ymax;
-    int             rows;
-    int             cols;
-    int             n_points;
-/* Initializes QUADDATA structure with given arguments*/
-
-
-
-
-
-
-int 
-quad_compare (point, data)
-    struct triple  *point;
-    struct quaddata *data;
-/* returns the quadrant the point should be inserted in */
-/* called by divide() */
-
-
-
-
-
-
-int 
-quad_add_data (point, data, dmin)
-    struct triple  *point;
-    struct quaddata *data;
-    double           dmin;
-/* Adds POINT to a given DATA . Called by tree function insert_quad() */
-/* and by data function quad_divide_data() */
-
-
-
-
-
-
-int 
-quad_intersect (data_inter, data)
-    struct quaddata *data_inter;
-    struct quaddata *data;
-/* Checks if region defined by DATA intersects the region defined
-  by data_inter. Called by tree function MT_region_data() */
-
-
-
-
-
-int quad_division_check(data,kmax)
- struct quaddata *data;
- int              kmax;
-/* Checks if DATA needs to be divided. If data->points is empty,
-  returns -1; if its not empty but there aren't enough points
-  in DATA for division returns 0. Othervise (if its not empty and
-  there are too many points) returns 1. Called by MT_insert() */
-
-
-
-
-
-
-struct quaddata **quad_divide_data(data,kmax,dmin)
- struct quaddata *data;
- int              kmax;
- double           dmin;
-/* Divides DATA into 4 new datas reinserting data->points in
- them by calling data function quad_compare() to detrmine
- were to insert. Called by MT_divide(). Returns array of 4 new datas */
-
-
-
-
-
-
-
-int quad_get_points(data_inter,data,MAX)
- struct quaddata *data_inter;
- struct quaddata *data;
- int    MAX;
-/* Gets such points from DATA that lie within region determined by
- data_inter. Called by tree function region_data(). */
-
-
-

lib/rst/data/dataquad.c

@@ -1,22 +1,41 @@
-
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993
- * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1993, H. Mitasova (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+/*!
+ * \file qtree.c
  *
- * Modified by H.Mitasova November 1996 to include variable smoothing
- * 
+ * \author
+ * H. Mitasova, I. Kosinovsky, D. Gerdes, Fall 1993,
+ * University of Illinois and
+ * US Army Construction Engineering Research Lab
+ *
+ * \author H. Mitasova (University of Illinois),
+ * \author I. Kosinovsky, (USA-CERL)
+ * \author D.Gerdes (USA-CERL)
+ *
+ * \author modified by H. Mitasova, November 1996 (include variable smoothing)
+ *
+ * \copyright
+ * (C) 1993-1996 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
 
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <grass/dataquad.h>
 
-/* sm added to point structure */
+
+/*!
+ * Initialize point structure with given arguments
+ *
+ * This is a constructor of the point structure and it allocates memory.
+ *
+ * \note
+ * Smoothing is part of the point structure
+ */
 struct triple *quad_point_new(double x, double y, double z, double sm)
-/* Initializes POINT structure with given arguments */
 {
     struct triple *point;
 
@@ -33,10 +52,16 @@ struct triple *quad_point_new(double x, double y, double z, double sm)
 }
 
 
+/*!
+ * Initialize quaddata structure with given arguments
+ * 
+ * This is a constructor of the quaddata structure and it allocates memory.
+ * It also creates (and allocates memory for) the given number of points
+ * (given by *kmax*). The point attributes are set to zero.
+ */
 struct quaddata *quad_data_new(double x_or, double y_or, double xmax,
 			       double ymax, int rows, int cols, int n_points,
 			       int kmax)
-/* Initializes QUADDATA structure with given arguments */
 {
     struct quaddata *data;
     int i;
@@ -67,12 +92,10 @@ struct quaddata *quad_data_new(double x_or, double y_or, double xmax,
 }
 
 
-
-
-
+/*!
+ * Return the quadrant the point should be inserted in
+ */
 int quad_compare(struct triple *point, struct quaddata *data)
-/* returns the quadrant the point should be inserted in */
-/* called by divide() */
 {
     int cond1, cond2, cond3, cond4, rows, cols;
     double ew_res, ns_res;
@@ -114,9 +137,10 @@ int quad_compare(struct triple *point, struct quaddata *data)
 }
 
 
+/*!
+ * Add point to a given *data*.
+ */
 int quad_add_data(struct triple *point, struct quaddata *data, double dmin)
-/* Adds POINT to a given DATA . Called by tree function insert_quad() */
-/* and by data function quad_divide_data() */
 {
     int n, i, cond;
     double xx, yy, r;
@@ -147,11 +171,13 @@ int quad_add_data(struct triple *point, struct quaddata *data, double dmin)
 }
 
 
-
-
+/*!
+ * Check intersection of two quaddata structures
+ * 
+ * Checks if region defined by *data* intersects the region defined
+ * by *data_inter*.
+ */
 int quad_intersect(struct quaddata *data_inter, struct quaddata *data)
-/* Checks if region defined by DATA intersects the region defined
-   by data_inter. Called by tree function MT_region_data() */
 {
     double xmin, xmax, ymin, ymax;
 
@@ -178,13 +204,19 @@ int quad_intersect(struct quaddata *data_inter, struct quaddata *data)
 }
 
 
-
-
+/*!
+ * Check if *data* needs to be divided
+ * 
+ * Checks if *data* needs to be divided. If `data->points` is empty,
+ * returns -1; if its not empty but there aren't enough points
+ * in *data* for division returns 0. Otherwise (if its not empty and
+ * there are too many points) returns 1.
+ * 
+ * \returns 1 if division is needed
+ * \returns 0 if division is not needed
+ * \returns -1 if there are no points
+ */
 int quad_division_check(struct quaddata *data, int kmax)
-/* Checks if DATA needs to be divided. If data->points is empty,
-   returns -1; if its not empty but there aren't enough points
-   in DATA for division returns 0. Othervise (if its not empty and
-   there are too many points) returns 1. Called by MT_insert() */
 {
     if (data->points == NULL)
 	return -1;
@@ -195,12 +227,15 @@ int quad_division_check(struct quaddata *data, int kmax)
 }
 
 
-
+/*!
+ * Divide *data* into four new ones
+ *
+ * Divides *data* into 4 new datas reinserting `data->points` in
+ * them by calling data function `quad_compare()` to determine
+ * were to insert. Returns array of 4 new datas (allocates memory).
+ */
 struct quaddata **quad_divide_data(struct quaddata *data, int kmax,
 				   double dmin)
-/* Divides DATA into 4 new datas reinserting data->points in
-   them by calling data function quad_compare() to detrmine
-   were to insert. Called by MT_divide(). Returns array of 4 new datas */
 {
     struct quaddata **datas;
     int cols1, cols2, rows1, rows2, i;	/*j1, j2, jmin = 0; */
@@ -280,12 +315,12 @@ struct quaddata **quad_divide_data(struct quaddata *data, int kmax,
 }
 
 
-
-
+/*!
+ * Gets such points from *data* that lie within region determined by
+ * *data_inter*. Called by tree function `region_data()`.
+ */
 int
 quad_get_points(struct quaddata *data_inter, struct quaddata *data, int MAX)
-/* Gets such points from DATA that lie within region determined by
-   data_inter. Called by tree function region_data(). */
 {
     int i, ind;
     int n = 0;

lib/rst/data/dataquad.h

@@ -1,12 +1,24 @@
-
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1992
- * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1992, H. Mitasova (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+/*!
+ * \file qtree.c
+ *
+ * \author
+ * H. Mitasova, I. Kosinovsky, D. Gerdes, Fall 1993,
+ * University of Illinois and
+ * US Army Construction Engineering Research Lab
+ *
+ * \author H. Mitasova (University of Illinois),
+ * \author I. Kosinovsky, (USA-CERL)
+ * \author D.Gerdes (USA-CERL)
+ *
+ * \author modified by H. Mitasova, November 1996 (include variable smoothing)
  *
- * Modified by H.Mitasova November 1996 to include variable smoothing
+ * \copyright
+ * (C) 1993-1996 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
 
 
@@ -19,12 +31,18 @@
 #define SW   3
 #define SE   4
 
+
+/*!
+ * Point structure to keep coordinates
+ *
+ * It also contains smoothing for the given point.
+ */
 struct triple
 {
     double x;
     double y;
     double z;
-    double sm;			/* structure extended to incl. variable smoothing */
+    double sm;  /*!< variable smoothing */
 };
 
 struct quaddata

lib/rst/interp_float/DESCRIPTION.INTERP

@@ -1,318 +0,0 @@
-        DESCRIPTION OF INTERPOLATION LIBRARY
-
-  written by Irina Kosinovsky 1993
-  updated by Mitasova Nov. 96
-  NEEDS UPDATE FOR spatially variable smoothing and other changes 
-  done by Helena in 1997
-
-Note by Irina in 1993: Below is the collection of functions 
-needed for interpolation programs. It should be 
-divided into several libraries to provide better 
-functionality.
-
-
-DATA STRUCTURES:
-----------------  
-
-struct interp_params 
-{
-   double zmult;       /* multiplier for z-values */
-   FILE *fdinp;         /* input stream */
-   int kmin;           /* min number of points per segment for interpolation */
-   int kmax;           /* max number of points per segment */ 
-   char *maskmap;       /* name of mask */
-   int nsizr,nsizc;     /* number of rows and columns */
-   double *az,*adx,*ady,*adxx,*adyy,*adxy;  /* array for interpolated values */
-   double fi;                               /* tension */
-   int    KMAX2;                            /* max num. of points for interp.*/
-   int    scik1,scik2,scik3;                /* multipliers for interp. values*/
-   double        rsm;          /* smoothing, for rsm<0 use variable smooth from sites */
-   char   *elev,*slope,*aspect,*pcurv,*tcurv,*mcurv; /* output files */
-   double dmin;                             /* min distance between points */
-   double x_orig, y_orig;                   /* origin */
-   int    deriv;                            /* 1 if compute partial derivs */
-   FILE   *Tmp_fd_z,*Tmp_fd_dx,*Tmp_fd_dy,  /* temp files for writing interp.*/
-          *Tmp_fd_xx,*Tmp_fd_yy,*Tmp_fd_xy; /* values */
-   FILE   *fddevi;     /* pointer to deviations file */
-
-   int    (*grid_calc) ();                  /*calculates grid for given segm*/
-   int    (*matrix_create) ();              /*creates matrix for a given segm*/
-   int    (*check_points) ();               /*checks interp. func. at points */
-   int    (*secpar) ();                     /* calculates aspect,slope,curv. */
-   double (*interp) ();                     /* radial basis function */
-   int    (*interpder) ();                  /* derivatives of radial basis function */
-   int    (*wr_temp) ();                    /* writes temp files */
-   int c,                                   /* cross validation */
-   char *wheresql                           /* SQL WHERE */
-};
-
-
-FUNCTIONS:
-----------
-
-void 
-IL_init_params_2d(params,inp,zm,k1,k2,msk,rows,cols,ar1,ar2,ar3,ar4,ar5,ar6,
-                 tension,k3,sc1,sc2,sc3,sm,f1,f2,f3,f4,f5,f6,dm,x_or,y_or,
-                 der,t1,t2,t3,t4,t5,t6,dev)
-
-   struct interp_params *params;
-   FILE *inp;         /* input stream */
-   double zm;       /* multiplier for z-values */
-   int k1;           /* min number of points per segment for interpolation */
-   int k2;           /* max number of points per segment */ 
-   char *msk;       /* name of mask */
-   int rows,cols;     /* number of rows and columns */
-   double *ar1,*ar2,*ar3,*ar4,*ar5,*ar6;  /* arrays for interpolated values */
-   double tension;                              /* tension */
-   int    k3;                            /* max num. of points for interp.*/
-   int    sc1,sc2,sc3;                /* multipliers for interp. values*/
-   double        sm;               /* smoothing, if sm<0 take it from sites file input */
-   char   *f1,*f2,*f3,*f4,*f5,*f6;          /*output files */
-   double dm;                             /* min distance between points */
-   double x_or, y_or;                   /* origin */
-   int    der;                            /* 1 if compute partial derivs */
-   FILE   *t1,*t2,*t3,*t4,*t5,*t6;  /* temp files for writing interp. values */
-   FILE   *dev;     /* pointer to deviations file */
-
-Initializes parameters called by the library 
-
-
-void 
-IL_init_func_2d(params,grid_f,matr_f,point_f,secp_f,interp_f,
-                                                   interpder_f,temp_f)
-
-   struct interp_params *params;
-   int    (*grid_f) ();             /*calculates grid for given segm*/
-   int    (*matr_f) ();             /*creates matrix for a given segm*/
-   int    (*point_f) ();            /*checks interp. func. at points */
-   int    (*secp_f) ();             /* calculates aspect,slope,curv. */
-   double (*interp_f) ();           /* radial basis function*/
-   int    (*interpder_f) ();        /* derivatives of radial basis fucntion */
-   int    (*temp_f) ();             /* writes temp files */
-
-Initializes functions called by the library 
-
-
-
-
-double 
-IL_crst (r,fi)
-   double r;  /* distance squared*/
-   double fi; /* tension */
-
-Radial basis function - regularized spline with tension (d=2)
-
-
-int 
-IL_crstg (r, fi, gd1, gd2)
-    double r;  /* distance squared*/
-    double fi; /* tension */
-    double         *gd1;
-    double         *gd2;
-
-Derivatives of radial basis function - regularized spline with tension(d=2)
-
-
-int 
-IL_input_data_2d(params,info,xmin,xmax,ymin,ymax,zmin,zmax,MAXPOINTS,n_points)
-   struct interp_params *params;
-   struct tree_info *info;  /* quadtree info */
-   double *xmin,*xmax,*ymin,*ymax,*zmin,*zmax;  
-   int maxpoints;      /* max number of points per segment for interpolation */
-   int *n_points;      /* number of points used for interpolation */
-
-Inserts input data inside the region into a quad tree.
-Also translates data.
-Returns number of segments in the quad tree.
-
-
-
-
-int IL_vector_input_data_2d(params,Map,dmax,cats,iselev,info,xmin,
-                     xmax,ymin,ymax,zmin,zmax,n_points)
-
-   struct interp_params *params;
-   struct Map_info *Map;    /* input vector file */
-   double dmax;             /* max distance between points */
-   struct Categories *cats; /* Cats file */
-   int    iselev;           /* do zeroes represent elevation? */
-   struct tree_info *info;  /* quadtree info */
-   double *xmin,*xmax,*ymin,*ymax,*zmin,*zmax;
-   int *n_points;      /* number of points used for interpolation */
-
-Inserts input data inside the region into a quad tree.
-Also translates data.
-Returns number of segments in the quad tree.
-
-
-
-
-
-
-
-struct BM *
-IL_create_bitmask(params)
-  struct interp_params *params;
-
-Creates a bitmap mask from maskmap raster file and/or current MASK if
-present and returns a pointer to the bitmask. If no mask is in force returns
-NULL.
-
-
-
-int 
-IL_grid_calc_2d(params,data,bitmask,zmin,zmax,zminac,zmaxac,gmin,gmax,
-                              c1min,c1max,c2min,c2max,ertot,b,offset1)
-    struct interp_params *params;
-    struct quaddata *data;                   /* given segment */
-    struct BM *bitmask;                      /* bitmask */
-    double zmin,zmax;                        /* min and max input z-values */
-    double *zminac,*zmaxac,                  /* min and max interp. z-values */
-           *gmin,*gmax,                      /* min and max inperp. slope val.*/
-           *c1min,*c1max,*c2min,*c2max;      /* min and max interp. curv. val.*/
-    double *ertot;                           /* rms deviation of the interpolated surface */
-    double *b;                               /* solutions of linear equations */
-    int    offset1;                          /* offset for temp file writing */
-
-Calculates grid for the given segment represented by data (contains n_rows,
-n_cols, ew_res,ns_res, and all points inside + overlap) using solutions of
-system of lin. equations and interpolating functions interp() and interpder().
-Also calls secpar() to compute slope, aspect and curvatures if required.
-
-
-
-
-int 
-IL_matrix_create(params,points,n_points,matrix,indx)
-    struct interp_params *params;
-    struct triple *points;           /* points for interpolation */
-    int           n_points;          /* number of points */
-    double       **matrix;           /* matrix */
-    int           *indx;
-
-Creates system of linear equations represented by matrix using given points
-and interpolating function interp()
-
-
-
-
- 
-int 
-IL_check_at_points_2d (params,n_points,points,b,ertot,zmin)
-    struct interp_params *params;
-    int           n_points;    /* number of points */ 
-    struct triple *points;     /* points for interpolation */
-    double        *b;          /* solution of linear equations */
-    double        *ertot;      /* rms deviation of the interpolated surface */
-    double        zmin;        /* min z-value */
-
-Checks if interpolating function interp() evaluates correct z-values at given
-points. If smoothing is used calculate the maximum and rms deviation caused by smoothing.
-
-
-
-
-
-
-int 
-IL_secpar_loop_2d(params,ngstc,nszc,k,bitmask,gmin,gmax,c1min,c1max,c2min,
-                                                         c2max,cond1,cond2)
-    struct interp_params *params;
-    int    ngstc;       /* starting column */
-    int    nszc;        /* ending column */
-    int    k;           /* current row */
-    struct BM *bitmask;
-    double *gmin,*gmax,*c1min,*c1max,*c2min,*c2max; /* min,max interp. values */
-    int    cond1,cond2; /*determine if particular values need to be computed*/
-
-Computes slope, aspect and curvatures (depending on cond1, cond2) for derivative
-arrays adx,...,adxy between columns ngstc and nszc.
-
-
-
-int 
-IL_write_temp_2d(params,ngstc,nszc,offset2)
-    struct interp_params *params;
-    int    ngstc,nszc,offset2;  /* begin. and end. column, offset */
-
-Writes az,adx,...,adxy into appropriate place (depending on ngstc, nszc and
-offset) in corresponding temp file */
-
-
-
-
-int 
-IL_interp_segments_2d (params,info,tree,bitmask,zmin,zmax,zminac,zmaxac,
-               gmin,gmax,c1min,c1max,c2min,c2max,ertot,totsegm,offset1,dnorm)
-    struct interp_params *params;
-    struct tree_info *info;    /* info for the quad tree */
-    struct multtree *tree;    /* current leaf of the quad tree */
-    struct BM *bitmask;                      /* bitmask */
-    double zmin,zmax;                        /* min and max input z-values */
-    double *zminac,*zmaxac,                  /* min and max interp. z-values */
-           *gmin,*gmax,                      /* min and max inperp. slope val.*/
-           *c1min,*c1max,*c2min,*c2max;      /* min and max interp. curv. val.*/
-    double *ertot;                           /* rms deviation of the interpolated surface*/
-    int    totsegm;                          /* total number of segments */
-    int    offset1;                          /* offset for temp file writing */
-    double dnorm;                            /* normalization factor */
-
-Recursively processes each segment in a tree by
-  a) finding points from neighbouring segments so that the total number of
-     points is between KMIN and KMAX2 by calling tree function MT_get_region().
-  b) creating and solving the system of linear equations using these points
-     and interp() by calling matrix_create() and G_ludcmp().
-  c) checking the interpolated values at given points by calling
-     check_points().
-  d) computing grid for this segment using points and interp() by calling
-     grid_calc().
-    
-int 
-IL_interp_segments_new_2d (params,info,tree,bitmask,
-         zmin,zmax,zminac,zmaxac,gmin,gmax,c1min,c1max,
-         c2min,c2max,ertot,totsegm,offset1,dnorm)
-
-    struct interp_params *params;
-    struct tree_info *info;    /* info for the quad tree */
-    struct multtree *tree;    /* current leaf of the quad tree */
-    struct BM *bitmask;                      /* bitmask */
-    double zmin,zmax;                        /* min and max input z-values */
-    double *zminac,*zmaxac,                  /* min and max interp. z-values */
-           *gmin,*gmax,                      /* min and max inperp. slope val.*/
-           *c1min,*c1max,*c2min,*c2max;      /* min and max interp. curv. val.*/
-    double *ertot;                           /* rms deviation of the interpolated surface*/
-    int    totsegm;                          /* total number of segments */
-    int    offset1;                          /* offset for temp file writing */
-    double dnorm;                            /* normalization factor */
-
-The difference between this function and IL_interp_segments_2d() is making
-sure that additional points are taken from all directions, i.e. it finds
-equal number of points from neigbouring segments in each of 8 neigbourhoods.
-
-Recursively processes each segment in a tree by
-  a) finding points from neighbouring segments so that the total number of
-     points is between KMIN and KMAX2 by calling tree function MT_get_region().
-  b) creating and solving the system of linear equations using these points
-     and interp() by calling matrix_create() and G_ludcmp().
-  c) checking the interpolated function values at points by calling
-     check_points().
-  d) computing grid for this segment using points and interp() by calling
-     grid_calc().
-
-
-    
-int 
-IL_output_2d (params,cellhd,zmin,zmax,zminac,zmaxac,c1min,c1max,c2min,c2max,
-                                               gmin,gmax,ertot,dnorm)
-    struct interp_params *params;
-    struct Cell_head *cellhd;   /* current region */
-    double zmin,zmax,           /* min,max input z-values */
-           zminac,zmaxac,c1min,c1max,  /* min,max interpolated values */
-           c2min,c2max,gmin,gmax;
-    double *ertot;                           /* rms deviation of the interpolated surface*/
-    double dnorm;                            /* normalization factor */
-
-Creates output files as well as history files  and color tables for them.
-
-
-

lib/rst/interp_float/func2d.c

@@ -1,36 +1,53 @@
 
-/*-
+/*!
+ * \file func2d.c
+ * 
+ * \author
+ * Lubos Mitas (original program and various modifications)
  *
- * Original program and various modifications:
- * Lubos Mitas 
- *
- * GRASS4.1 version of the program and GRASS4.2 modifications:
+ * \author
  * H. Mitasova,
- * I. Kosinovsky, D. Gerdes
- * D. McCauley 
+ * I. Kosinovsky, D. Gerdes,
+ * D. McCauley
+ * (GRASS4.1 version of the program and GRASS4.2 modifications)
  *
- * Copyright 1993, 1995:
+ * \author
  * L. Mitas ,
  * H. Mitasova ,
  * I. Kosinovsky, 
  * D.Gerdes 
- * D. McCauley 
+ * D. McCauley (1993, 1995)
+ *
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995, Nov. 1996
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995, Nov. 1996  
+ * \copyright
+ * (C) 1993-1999 by Lubos Mitas and the GRASS Development Team
  *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS
+ * for details.
  */
 
+
 #include <stdio.h>
 #include <math.h>
 #include <grass/gis.h>
 #include <grass/interpf.h>
 
-double IL_crst(double r, double fi)
-/*
- * Radial basis function - completely regularized spline with
- * tension (d=2)
+
+/* parameter description from DESCRIPTION.INTERP */
+/*!
+ * Radial basis function
+ *
+ * Radial basis function - completely regularized spline with tension (d=2)
+ *
  */
+double IL_crst(double r,  /**< distance squared */
+               double fi  /**< tension */
+               )
 {
     double rfsta2 = fi * fi * r / 4.;
 
@@ -81,15 +98,16 @@ double IL_crst(double r, double fi)
 }
 
 
-
-int IL_crstg(double r, double fi, double *gd1,	/* G1(r) */
-	     double *gd2	/* G2(r) */
-    )
-
-
-/*
+/*!
  * Function for calculating derivatives (d=2)
+ *
+ * Derivatives of radial basis function - regularized spline with tension(d=2)
  */
+int IL_crstg(double r,  /**< distance squared */
+             double fi,  /**< tension */
+             double *gd1,  /**< G1(r) */
+             double *gd2  /**< G2(r) */
+             )
 {
     double r2 = r;
     double rfsta2 = fi * fi * r / 4.;

lib/rst/interp_float/init2d.c

@@ -1,12 +1,22 @@
 
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993
- * Copyright 1993, H. Mitasova ,
- * I. Kosinovsky, and D.Gerdes   
+/*!
+ * \file init2d.c
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995  
- * modified by Brown in June 1999 - added elatt & smatt 
+ * \brief Initialization of interpolation library data structures
+ *
+ * \author H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993 (original authors)
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995
+ * \author modified by Brown in June 1999 - added elatt & smatt
+ *
+ * \copyright
+ * (C) 1993-1999 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS
+ * for details.
  *
  */
 
@@ -16,41 +26,38 @@
 #include <grass/gis.h>
 #include <grass/interpf.h>
 
-void IL_init_params_2d(
-    /* initialize parameters */
-    struct interp_params *params,
-    FILE * inp,			/* input stream */
-    int elatt,			/* which fp att in sites file? 1 = first */
-    int smatt,			/* which fp att in sites file to use for 
-				 * smoothing? (if zero use sm) 1 = first */
-    double zm,			/* multiplier for z-values */
-    int k1,			/* min number of points per segment for
-				 * interpolation */
-    int k2,			/* max number of points per segment */
-    char *msk,			/* name of mask */
-    int rows, int cols, 	/* number of rows and columns */
-    DCELL * ar1, DCELL * ar2,
-    DCELL * ar3, DCELL * ar4,
-    DCELL * ar5, DCELL * ar6,	/* arrays for interpolated values */
-    double tension,		/* tension */
-    int k3,			/* max num. of points for interp. */
-    int sc1, int sc2, int sc3,	/* multipliers for interp. values */
-    double sm,			/* smoothing */
-    char *f1, char *f2,
-    char *f3, char *f4,
-    char *f5, char *f6,		/* output files */
-    double dm,			/* min distance between points */
-    double x_or, double y_or,	/* origin */
-    int der,			/* 1 if compute partial derivs */
-    double tet,			/* anisotropy angle, 0=East,counter-clockwise */
-    double scl,			/* anisotropy scaling factor */
-    FILE * t1, FILE * t2,
-    FILE * t3, FILE * t4,
-    FILE * t5, FILE * t6,	/* temp files for writing interp. values */
-    FILE * dev,			/* pointer to deviations file */
-    struct TimeStamp *ts,
-    int c,			/* cross validation */
-    const char *wheresql	/* SQL WHERE */
+
+/*! Initializes parameters used by the library */
+void IL_init_params_2d(struct interp_params *params,
+                       FILE * inp,  /*!< input stream */
+                       int elatt,  /*!< which fp att in sites file? 1 = first */
+                       int smatt,  /*!< which fp att in sites file to use for 
+                                         * smoothing? (if zero use sm) 1 = first */
+                       double zm,  /*!< multiplier for z-values */
+                       int k1,  /*!< min number of points per segment for interpolation */
+                       int k2,  /*!< max number of points per segment */
+                       char *msk,  /*!< name of mask */
+                       int rows, int cols,  /*!< number of rows and columns */
+                       DCELL * ar1, DCELL * ar2, DCELL * ar3, DCELL * ar4, DCELL * ar5,
+                       DCELL * ar6,  /*!< arrays for interpolated values (ar1-ar6) */
+                       double tension,  /*!< tension */
+                       int k3,  /*!< max number of points for interpolation */
+                       int sc1, int sc2, int sc3,  /*!< multipliers for interpolation values */
+                       double sm,  /*!< smoothing */
+                       char *f1, char *f2, char *f3, char *f4, char *f5,
+                       char *f6,  /*!< output files (f1-f6) */
+                       double dm,  /*!< min distance between points */
+                       double x_or,  /*!< x of origin */
+                       double y_or,  /*!< y of origin */
+                       int der,  /*!< 1 if compute partial derivatives */
+                       double tet,  /*!< anisotropy angle (0 is East, counter-clockwise) */
+                       double scl,  /*!< anisotropy scaling factor */
+                       FILE * t1, FILE * t2, FILE * t3, FILE * t4, FILE * t5,
+                       FILE * t6,  /*!< temp files for writing interp. values (t1-t6) */
+                       FILE * dev,  /*!< pointer to deviations file */
+                       struct TimeStamp *ts,
+                       int c,  /*!< cross validation */
+                       const char *wheresql     /*!< SQL WHERE statement */
     )
 {
     params->fdinp = inp;
@@ -98,16 +105,16 @@ void IL_init_params_2d(
     params->wheresql = wheresql;
 }
 
+/*! Initializes functions used by the library  */
 void IL_init_func_2d(struct interp_params *params,
-		     grid_calc_fn *grid_f,	/* calculates grid for given segm */
-		     matrix_create_fn *matr_f,	/* creates matrix for a given segm */
-		     check_points_fn *point_f,	/* checks interp. func. at points */
-		     secpar_fn *secp_f,		/* calculates aspect,slope,curv. */
-		     interp_fn *interp_f,	/* radial  basis function */
-		     interpder_fn *interpder_f,	/* derivatives of radial basis func. */
-		     wr_temp_fn *temp_f		/* writes temp files */
+                     grid_calc_fn * grid_f,  /*!< calculates grid for given segment */
+                     matrix_create_fn * matr_f,  /*!< creates matrix for a given segment */
+                     check_points_fn * point_f,  /*!< checks interpolation function at points */
+                     secpar_fn * secp_f,  /*!< calculates aspect, slope, curvature */
+                     interp_fn * interp_f,  /*!< radial basis function */
+                     interpder_fn * interpder_f,  /*!< derivatives of radial basis function */
+                     wr_temp_fn * temp_f        /*!< writes temp files */
     )
-/* initialize functions */
 {
     params->grid_calc = grid_f;
     params->matrix_create = matr_f;
@@ -118,5 +125,3 @@ void IL_init_func_2d(struct interp_params *params,
     params->wr_temp = temp_f;
 
 }
-
-

lib/rst/interp_float/input2d.c

@@ -1,16 +1,20 @@
 
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993
- * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1993, H. Mitasova (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+/*!
+ * \file input2d.c
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995  
- * modified by Mitasova in November 1996 to include variable smoothing
- * modified by Brown in June 1999 - added elatt & smatt
+ * \author H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993 (original authors)
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995
+ * \author modified by Brown in June 1999 - added elatt & smatt
  *
+ * \copyright
+ * (C) 1993-1999 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS
+ * for details.
  */
 
 
@@ -25,9 +29,15 @@
 #include <grass/interpf.h>
 #include <grass/glocale.h>
 
-struct BM *IL_create_bitmask(struct interp_params *params)
 
-/** Creates a bitmap mask from given raster map **/
+/*!
+ * Creates a bitmap mask from given raster map
+ *
+ * Creates a bitmap mask from maskmap raster file and/or current MASK if
+ * present and returns a pointer to the bitmask. If no mask is in force
+ * returns NULL.
+ */
+struct BM *IL_create_bitmask(struct interp_params *params)
 {
     int i, j, cfmask = -1, irev, MASKfd;
     const char *mapsetm;

lib/rst/interp_float/interp2d.c

@@ -1,25 +1,38 @@
 
-/*-
+/*!
+ * \file interp2d.c
  *
- * Original program and various modifications:
- * Lubos Mitas 
+ * \author
+ * Lubos Mitas (original program and various modifications)
  *
- * GRASS4.1 version of the program and GRASS4.2 modifications:
+ * \author
  * H. Mitasova,
- * I. Kosinovsky, D. Gerdes
- * D. McCauley 
+ * I. Kosinovsky, D. Gerdes,
+ * D. McCauley
+ * (GRASS4.1 version of the program and GRASS4.2 modifications)
  *
- * Copyright 1993, 1995:
- * L. Mitas ,
+ * \author
+ * L. Mitas,
  * H. Mitasova,
  * I. Kosinovsky,
- * D.Gerdes 
+ * D.Gerdes,
  * D. McCauley
+ * (1993, 1995)
+ *
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995, Nov. 1996
+ * \author
+ * bug fixes(mask) and modification for variable smoothing
+ * Mitasova (Jan 1997)
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995, Nov. 1996
- * bug fixes(mask) and modif. for variable smoothing Mitasova Jan 1997
+ * \copyright
+ * (C) 1993-1999 by Lubos Mitas and the GRASS Development Team
  *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS
+ * for details.
  */
 
 
@@ -38,24 +51,29 @@
 #define CEULER .57721566
 
 
-int IL_grid_calc_2d(struct interp_params *params, struct quaddata *data,	/* given segment */
-		    struct BM *bitmask,	/* bitmask */
-		    double zmin, double zmax,	/* min and max input z-values */
-		    double *zminac, double *zmaxac,	/* min and max interp. z-values */
-		    double *gmin, double *gmax,	/* min and max inperp. slope val. */
-		    double *c1min, double *c1max, double *c2min, double *c2max,	/* min and max interp. curv. val. */
-		    double *ertot,	/* total interplating func. error */
-		    double *b,	/* solutions of linear equations */
-		    off_t offset1,	/* offset for temp file writing */
-		    double dnorm)
-
-/*
+/*!
+ * Calculates grid values for a given segment
+ *
  * Calculates grid for the given segment represented by data (contains
  * n_rows, n_cols, ew_res,ns_res, and all points inside + overlap) using
- * solutions of system of lin. equations and interpolating functions
+ * solutions of system of linear equations and interpolating functions
  * interp() and interpder(). Also calls secpar() to compute slope, aspect
  * and curvatures if required.
+ * 
+ * *ertot* can be also called *RMS deviation of the interpolated surface*
  */
+int IL_grid_calc_2d(struct interp_params *params,
+                    struct quaddata *data,  /*!< given segment */
+                    struct BM *bitmask,  /*!< bitmask */
+                    double zmin, double zmax,  /*!< min and max input z-values */
+                    double *zminac, double *zmaxac,  /*!< min and max interp. z-values */
+                    double *gmin, double *gmax,  /*!< min and max interp. slope val. */
+                    double *c1min, double *c1max,  /*!< min and max interp. curv. val. */
+                    double *c2min, double *c2max,  /*!< min and max interp. curv. val. */
+                    double *ertot,  /*!< total interpolating func. error */
+                    double *b,  /*!< solutions of linear equations */
+                    off_t offset1,  /*!< offset for temp file writing */
+                    double dnorm)
 {
 
     /*

lib/rst/interp_float/interpf.h

@@ -67,41 +67,41 @@ typedef int wr_temp_fn(struct interp_params *, int, int, off_t);
 
 struct interp_params
 {
-    double zmult;		/* multiplier for z-values */
-    FILE *fdinp;		/* input stream */
-    int elatt;			/* which floating point attr to use? first = 1, second = 2, etc */
-    int smatt;			/* which floating point attr to use for smoothing? first = 1, second = 2, etc */
-    int kmin;			/* min number of points per segment for interpolation */
-    int kmax;			/* max number of points per segment */
-    char *maskmap;		/* name of mask */
-    int nsizr, nsizc;		/* number of rows and columns */
+    double zmult;		/**< multiplier for z-values */
+    FILE *fdinp;		/**< input stream */
+    int elatt;			/**< which floating point attr to use? first = 1, second = 2, etc */
+    int smatt;			/**< which floating point attr to use for smoothing? first = 1, second = 2, etc */
+    int kmin;			/**< min number of points per segment for interpolation */
+    int kmax;			/**< max number of points per segment */
+    char *maskmap;		/**< name of mask */
+    int nsizr, nsizc;		/**< number of rows and columns */
     DCELL *az, *adx, *ady,
-	*adxx, *adyy, *adxy;	/* array for interpolated values */
-    double fi;			/* tension */
-    int KMAX2;			/* max num. of points for interp. */
-    int scik1, scik2, scik3;	/* multipliers for interp. values */
-    double rsm;			/* smoothing */
+	*adxx, *adyy, *adxy;	/**< array for interpolated values */
+    double fi;			/**< tension */
+    int KMAX2;			/**< max num. of points for interp. */
+    int scik1, scik2, scik3;	/**< multipliers for interp. values */
+    double rsm;			/**< smoothing */
     char *elev, *slope, *aspect,
-	*pcurv, *tcurv, *mcurv;	/* output files */
-    double dmin;		/* min distance between points */
-    double x_orig, y_orig;	/* origin */
-    int deriv, cv;		/* 1 if compute partial derivs */
-    double theta;		/* anisotropy angle, 0=East,counter-clockwise */
-    double scalex;		/* anisotropy scaling factor */
-    struct TimeStamp *ts;	/* timestamp for raster files */
+	*pcurv, *tcurv, *mcurv;	/**< output files */
+    double dmin;		/**< min distance between points */
+    double x_orig, y_orig;	/**< origin */
+    int deriv, cv;		/**< 1 if compute partial derivs */
+    double theta;		/**< anisotropy angle, 0=East,counter-clockwise */
+    double scalex;		/**< anisotropy scaling factor */
+    struct TimeStamp *ts;	/**< timestamp for raster files */
     FILE *Tmp_fd_z, *Tmp_fd_dx,
 	*Tmp_fd_dy, *Tmp_fd_xx,
-	*Tmp_fd_yy, *Tmp_fd_xy;	/* temp files for writing interp. values */
-    FILE *fddevi;		/* pointer to deviations file */
-
-    grid_calc_fn *grid_calc;	/*calculates grid for given segm */
-    matrix_create_fn *matrix_create;	/*creates matrix for a given segm */
-    check_points_fn *check_points;	/*checks interp. func. at points */
-    secpar_fn *secpar;		/* calculates aspect,slope,curv. */
-    interp_fn *interp;		/* radial  based interp. function */
-    interpder_fn *interpder;	/* interp. func. for derivatives */
-    wr_temp_fn *wr_temp;	/* writes temp files */
-    const char *wheresql;	/* SQL statement to select input points */
+	*Tmp_fd_yy, *Tmp_fd_xy;	/**< temp files for writing interp. values */
+    FILE *fddevi;		/**< pointer to deviations file */
+
+    grid_calc_fn *grid_calc;	/**< calculates grid for given segm */
+    matrix_create_fn *matrix_create;	/**< creates matrix for a given segm */
+    check_points_fn *check_points;	/**< checks interp. func. at points */
+    secpar_fn *secpar;		/**< calculates aspect,slope,curv. */
+    interp_fn *interp;		/**< radial  based interp. function */
+    interpder_fn *interpder;	/**< interp. func. for derivatives */
+    wr_temp_fn *wr_temp;	/**< writes temp files */
+    const char *wheresql;	/**< SQL statement to select input points */
 };
 
 /* distance.c */

lib/rst/interp_float/matrix.c

@@ -1,23 +1,33 @@
-/*
- * Original program and various modifications:
- * Lubos Mitas 
+/*!
+ * \author
+ * Lubos Mitas (original program and various modifications)
  *
- * GRASS4.1 version of the program and GRASS4.2 modifications:
+ * \author
  * H. Mitasova,
- * I. Kosinovsky, D. Gerdes
- * D. McCauley 
+ * I. Kosinovsky, D. Gerdes,
+ * D. McCauley
+ * (GRASS4.1 version of the program and GRASS4.2 modifications)
  *
- * Copyright 1993, 1995:
- * L. Mitas ,
- * H. Mitasova ,
+ * \author
+ * L. Mitas,
+ * H. Mitasova,
  * I. Kosinovsky,
- * D.Gerdes 
- * D. McCauley 
+ * D.Gerdes,
+ * D. McCauley
+ * (1993, 1995)
+ *
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995, Nov. 1996
+ * 
+ * \copyright
+ * (C) 1993-1996 by Lubos Mitas and the GRASS Development Team
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995, Nov. 1996
+ * \copyright
+ * This program is free software under the  GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
 
+
 #include <stdio.h>
 #include <math.h>
 #include <unistd.h>
@@ -25,6 +35,7 @@
 #include <grass/interpf.h>
 #include <grass/gmath.h>
 
+
 /*!
  * \brief Creates system of linear equations from interpolated points
  *
@@ -32,9 +43,10 @@
  * points and interpolating function interp()
  *
  * \param params struct interp_params *
- * \param points struct triple * :  points for interpolation
- * \param n_points int :  number of points
- * \param matrix double **
+ * \param points points for interpolation as struct triple
+ * \param n_points number of points
+ * \param[out] matrix the matrix
+ * \param indx
  *
  * \return -1 on failure, 1 on success
  */
@@ -43,10 +55,6 @@ int IL_matrix_create(struct interp_params *params,
 		     int n_points,	/* number of points */
 		     double **matrix,	/* matrix */
 		     int *indx)
-/*
-   Creates system of linear equations represented by matrix using given points
-   and interpolating function interp()
- */
 {
     double xx, yy;
     double rfsta2, r;

lib/rst/interp_float/output2d.c

@@ -1,18 +1,22 @@
-
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Summer 1992
- * Copyright 1992, H. Mitasova 
- * I. Kosinovsky,  and D.Gerdes    
+/*!
+ * \file output2d.c
+ *
+ * \author H. Mitasova, I. Kosinovsky, D. Gerdesm, Summer 1992 (original authors)
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995  
+ * \author modified by Mitasova in August 1999 (fix for elev color)
+ * \author modified by Brown in September 1999 (fix for Timestamps)
+ * \author modified by Mitasova in Nov. 1999 (write given tension into hist)
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995  
- * modified by Mitasova in August 1999 (fix for elev color)
- * modified by Brown in September 1999 (fix for Timestamps)
- * Modified by Mitasova in Nov. 1999 (write given tension into hist)
- * Last modification: 2006-12-13
+ * \copyright
+ * (C) 1992-2006 by Helena Mitasova and the GRASS Development Team
  *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
-
+ 
 #include <stdio.h>
 #include <math.h>
 
@@ -46,17 +50,24 @@ static void do_history(const char *name, int vect, const char *input,
     Rast_free_history(&hist);
 }
 
-int IL_output_2d(struct interp_params *params, struct Cell_head *cellhd,	/* current region */
-		 double zmin, double zmax,	/* min,max input z-values */
-		 double zminac, double zmaxac, double c1min, double c1max,	/* min,max interpolated values */
-		 double c2min, double c2max, double gmin, double gmax, double ertot,	/* total interplating func. error */
-		 char *input,	/* input file name */
-		 double dnorm, int dtens, int vect, int n_points)
 
-/*
- * Creates output files as well as history files  and color tables for
- * them.
+/*!
+ * Creates output files as well as history files and color tables for them.
+ * 
+ * *ertot* can be also called *RMS deviation of the interpolated surface*.
  */
+int IL_output_2d(struct interp_params *params,
+                 struct Cell_head *cellhd,  /*!< current region */
+                 double zmin, double zmax,  /*!< min,max input z-values */
+                 double zminac, double zmaxac,
+                 double c1min, double c1max,  /*!< min,max interpolated values */
+                 double c2min, double c2max,
+                 double gmin, double gmax,
+                 double ertot,  /*!< total interpolating func. error */
+                 char *input,  /*!< input file name */
+                 double dnorm,  /*!< normalization factor */
+                 int dtens, int vect, int n_points
+                 )
 {
     FCELL *cell1;
     int cf1 = -1, cf2 = -1, cf3 = -1, cf4 = -1, cf5 = -1, cf6 = -1;

lib/rst/interp_float/point2d.c

@@ -1,24 +1,26 @@
-
-/*-
- *
- * Original program and various modifications:
- * Lubos Mitas 
+/*!
+ * \file point2d.c
  *
- * GRASS4.1 version of the program and GRASS4.2 modifications:
- * H. Mitasova
- * I. Kosinovsky, D. Gerdes
- * D. McCauley 
+ * \author
+ * Lubos Mitas (original program and various modifications)
  *
- * Copyright 1993, 1995:
- * L. Mitas ,
- * H. Mitasova ,
- * I. Kosinovsky, ,
- * D.Gerdes 
+ * \author
+ * H. Mitasova,
+ * I. Kosinovsky,
+ * D. Gerdes,
  * D. McCauley
+ * (GRASS4.1 version of the program and GRASS4.2 modifications)
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995, Nov. 1996
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995, Nov. 1996
  *
+ * \copyright
+ * (C) 1993-2006 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
 
 
@@ -37,17 +39,25 @@
 #undef hz
 #endif
 
-int IL_check_at_points_2d(struct interp_params *params, struct quaddata *data,	/* current region */
-			  double *b,	/* solution of linear equations */
-			  double *ertot,	/* total error */
-			  double zmin,	/* min z-value */
-			  double dnorm, struct triple skip_point)
-
-/*
+/*!
  * Checks if interpolating function interp() evaluates correct z-values at
  * given points. If smoothing is used calculate the maximum error caused
  * by smoothing.
+ * 
+ * *ertot* is a RMS deviation of the interpolated surface.
+ * 
+ * \todo
+ * Alternative description:
+ * ...calculate the maximum and RMS deviation caused by smoothing.
  */
+int IL_check_at_points_2d(struct interp_params *params,
+                          struct quaddata *data,  /*!< current region */
+                          double *b,  /*!< solution of linear equations */
+                          double *ertot,  /*!< total error */
+                          double zmin,  /*!< min z-value */
+                          double dnorm,
+                          struct triple skip_point
+                          )
 {
     int n_points = data->n_points;	/* number of points */
     struct triple *points = data->points;	/* points for interpolation */

lib/rst/interp_float/secpar2d.c

@@ -1,17 +1,27 @@
 
-/*-
- * Written by H. Mitasova, L. Mitas, I. Kosinovsky, D. Gerdes Fall 1994
- * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1994, H. Mitasova (University of Illinois),
- * L. Mitas (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+/*!
+ * \file secpar2d.c
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995  
+ * \author H. Mitasova, L. Mitas, I. Kosinovsky, D. Gerdes Fall 1994 (original authors)
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995
+ * \author H. Mitasova (University of Illinois)
+ * \author L. Mitas (University of Illinois)
+ * \author I. Kosinovsky, (USA-CERL)
+ * \author D.Gerdes (USA-CERL)   
+ *
+ * \copyright
+ * (C) 1994-1995 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS
+ * for details.
  *
  */
 
+
 #include <stdio.h>
 #include <math.h>
 #include <unistd.h>
@@ -19,19 +29,24 @@
 #include <grass/bitmap.h>
 #include <grass/interpf.h>
 
-int IL_secpar_loop_2d(struct interp_params *params, int ngstc,	/* starting column */
-		      int nszc,	/* ending column */
-		      int k,	/* current row */
-		      struct BM *bitmask, double *gmin, double *gmax, double *c1min, double *c1max, double *c2min, double *c2max,	/* min,max interp.
-																	 * values */
-		      int cond1, int cond2	/* determine if particular values need to
-						 * be computed */
-    )
 
-/*
+/*!
+ * Compute slope aspect and curvatures
+ *
  * Computes slope, aspect and curvatures (depending on cond1, cond2) for
  * derivative arrays adx,...,adxy between columns ngstc and nszc.
  */
+int IL_secpar_loop_2d(struct interp_params *params,
+                      int ngstc,  /*!< starting column */
+                      int nszc,  /*!< ending column */
+                      int k,  /*!< current row */
+                      struct BM *bitmask,
+                      double *gmin, double *gmax,
+                      double *c1min, double *c1max,
+                      double *c2min, double *c2max,  /*!< min,max interp. values */
+                      int cond1,
+                      int cond2  /*!< determine if particular values need to be computed */
+    )
 {
     double dnorm1, ro,		/* rad to deg conv */
       dx2 = 0, dy2 = 0, grad2 = 0,	/* gradient squared */

lib/rst/interp_float/segmen2d.c

@@ -1,8 +1,20 @@
-/*
- **  Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993 
- **  Copyright  H. Mitasova, I. Kosinovsky, D.Gerdes  
+/*!
+ * \file segmen2d.c
+ *
+ * \author H. Mitasova, I. Kosinovsky, D. Gerdes
+ *
+ * \copyright
+ * (C) 1993 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS
+ * for details.
+ *
  */
 
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <math.h>
@@ -14,34 +26,39 @@
 static double smallest_segment(struct multtree *, int);
 
 
-/*
+/*!
+ * Interpolate recursively a tree of segments
  *
  *  Recursively processes each segment in a tree by:
- *
- *  a) finding points from neighbouring segments so that the total number of
- *  points is between KMIN and KMAX2 by calling tree function MT_get_region().
- *
- *  b) creating and solving the system of linear equations using these points
- *  and interp() by calling matrix_create() and G_ludcmp().
- *
- *  c) checking the interpolating function values at points by calling
- *  check_points().
- *
- *  d) computing grid for this segment using points and interp() by calling
- *  grid_calc().
- *
+ *  - finding points from neighbouring segments so that the total number of
+ *    points is between KMIN and KMAX2 by calling tree function MT_get_region().
+ *  - creating and solving the system of linear equations using these points
+ *    and interp() by calling matrix_create() and G_ludcmp().
+ *  - checking the interpolating function values at points by calling
+ *    check_points().
+ *  - computing grid for this segment using points and interp() by calling
+ *    grid_calc().
+ * 
+ * \todo
+ * Isn't this in fact the updated version of the function (IL_interp_segments_new_2d)?
+ * The function IL_interp_segments_new_2d has the following, better behavior:
+ * The difference between this function and IL_interp_segments_2d() is making
+ * sure that additional points are taken from all directions, i.e. it finds
+ * equal number of points from neighboring segments in each of 8 neighborhoods.
  */
-int IL_interp_segments_2d(struct interp_params *params, struct tree_info *info,	/* info for the quad tree */
-			  struct multtree *tree,	/* current leaf of the quad tree */
-			  struct BM *bitmask,	/* bitmask */
-			  double zmin, double zmax,	/* min and max input z-values */
-			  double *zminac, double *zmaxac,	/* min and max interp. z-values */
-			  double *gmin, double *gmax,	/* min and max inperp. slope val. */
-			  double *c1min, double *c1max, double *c2min, double *c2max,	/* min and max interp. curv. val. */
-			  double *ertot,	/* total interplating func. error */
-			  int totsegm,		/* total number of segments */
-			  off_t offset1,	/* offset for temp file writing */
-			  double dnorm)
+int IL_interp_segments_2d(struct interp_params *params,
+                          struct tree_info *info,  /*!< info for the quad tree */
+                          struct multtree *tree,  /*!< current leaf of the quad tree */
+                          struct BM *bitmask,  /*!< bitmask */
+                          double zmin, double zmax,  /*!< min and max input z-values */
+                          double *zminac, double *zmaxac,  /*!< min and max interp. z-values */
+                          double *gmin, double *gmax,  /*!< min and max inperp. slope val. */
+                          double *c1min, double *c1max,  /*!< min and max interp. curv. val. */
+                          double *c2min, double *c2max,  /*!< min and max interp. curv. val. */
+                          double *ertot,  /*!< total interplating func. error */
+                          int totsegm,  /*!< total number of segments */
+                          off_t offset1,  /*!< offset for temp file writing */
+                          double dnorm)
 {
     double xmn, xmx, ymn, ymx, distx, disty, distxp, distyp, temp1, temp2;
     int i, npt, nptprev, MAXENC;

lib/rst/interp_float/vinput2d.c

@@ -1,15 +1,28 @@
 
-/*-
+/*!
+ * \file vinput2d.c
+ *
+ * \author
  * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993
  * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1993, H. Mitasova (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+ * US Army Construction Engineering Research Lab
+ * 
+ * \author
+ * Mitasova (University of Illinois),
+ * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)
+ *
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995
+ * \author modofied by Mitasova in Nov 1999 (dmax fix)
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995  
- * modofied by Mitasova in Nov 1999 (dmax fix)
+ * \copyright
+ * (C) 1993-1999 by Helena Mitasova and the GRASS Development Team
  *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS
+ * for details.
  */
 
 #include <stdio.h>
@@ -24,21 +37,29 @@
 
 #include <grass/interpf.h>
 
-int IL_vector_input_data_2d(struct interp_params *params, struct Map_info *Map,	/* input vector map */
-			    /* as z values may be used: 1) z coordinates in 3D file -> field = 0
-			     *                          2) categories -> field > 0, zcol = NULL
-			     *                          3) attributes -> field > 0, zcol != NULL */
-			    int field,	/* category field number */
-			    char *zcol,	/* name of the column containing z values */
-			    char *scol,	/* name of the column containing smooth values */
-			    struct tree_info *info,	/* quadtree info */
-			    double *xmin, double *xmax, double *ymin, double *ymax, double *zmin, double *zmax, int *n_points,	/* number of points used for interpolation */
-			    double *dmax)
-
-/*
+/*!
+ * Insert into a quad tree
+ *
  * Inserts input data inside the region into a quad tree. Also translates
  * data. Returns number of segments in the quad tree.
+ *
+ * As z values may be used (in *Map*):
+ * - z coordinates in 3D file -> field = 0
+ * - categories -> field > 0, zcol = NULL
+ * - attributes -> field > 0, zcol != NULL
  */
+int IL_vector_input_data_2d(struct interp_params *params, /*!< interpolation parameters */
+                            struct Map_info *Map,  /*!< input vector map */
+                            int field,  /*!< category field number */
+                            char *zcol,  /*!< name of the column containing z values */
+                            char *scol,  /*!< name of the column containing smooth values */
+                            struct tree_info *info,  /*!< quadtree info */
+                            double *xmin, double *xmax,
+                            double *ymin, double *ymax,
+                            double *zmin, double *zmax,
+                            int *n_points,  /*!< number of points used for interpolation */
+                            double *dmax  /*!< max distance between points */
+                            )
 {
     double dmax2;		/* max distance between points squared */
     double c1, c2, c3, c4;

lib/rst/interp_float/write2d.c

@@ -1,16 +1,23 @@
-
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993
- * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1993, H. Mitasova (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+/*!
+ * \file secpar2d.c
+ *
+ * \author H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993 (original authors)
+ * \author modified by McCauley in August 1995
+ * \author modified by Mitasova in August 1995
+ * \author H. Mitasova (University of Illinois)
+ * \author I. Kosinovsky, (USA-CERL)
+ * \author D.Gerdes (USA-CERL)   
  *
- * modified by McCauley in August 1995
- * modified by Mitasova in August 1995  
+ * \copyright
+ * (C) 1993-1995 by Helena Mitasova and the GRASS Development Team
  *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
 
+
 #include <grass/config.h>
 #include <stdio.h>
 #include <math.h>
@@ -20,11 +27,17 @@
 #include <grass/glocale.h>
 #include <grass/interpf.h>
 
-/*
+
+/* parameter descriptions takes from a strange comment */
+/*!
  * Writes az,adx,...,adxy into appropriate place (depending on ngstc, nszc
  * and offset) in corresponding temp file
  */
-int IL_write_temp_2d(struct interp_params *params, int ngstc, int nszc, off_t offset2)	/* begin. and end. column, offset */
+int IL_write_temp_2d(struct interp_params *params,
+                     int ngstc,  /*!< begin. column */
+                     int nszc,  /*!<  end. column */
+                     off_t offset2  /*!< offset */
+                     )
 {
     int j;
     static FCELL *array_cell = NULL;

lib/rst/qtree/DESCRIPTION.TREE

@@ -1,128 +0,0 @@
-/* updated by Mitasova Nov. 96, no changes necessary */
-
-DATa STRUCTURES:
-----------------
-
-#define VOID_T char
-
-struct multfunc { 
-    int (*compare) ();
-    VOID_T **(*divide_data) ();
-    int (*add_data) ();
-    int (*intersect) ();
-    int (*division_check) ();
-    int (*get_points) ();
-};
-
-struct tree_info {
-  struct multfunc *functions;
-  double dmin;
-  int kmax;
-  struct multtree *root;
-};
-
-struct multtree {
-  VOID_T *data;
-  struct multtree **leafs;
-  struct multtree *parent;
-  int    multant;
-};
-
-
-
-
-FUNCTIONS:
-----------
-
-struct multfunc * MT_functions_new(compare,divide_data,add_data,
-                          intersect,division_check,get_points)  
-    int (*compare) ();
-    VOID_T **(*divide_data) ();
-    int (*add_data) ();
-    int (*intersect) ();
-    int (*division_check) ();
-    int (*get_points) ();
-/* Initializes FUNCTIONS structure with given arguments*/
-
-
-
-
-struct tree_info * MT_tree_info_new (root,functions,dmin,kmax)
-    struct multtree *root;
-    struct multfunc *functions; 
-    double dmin;
-    int    kmax;
-/*Initializes TREE_INFO using given arguments*/
-
-
-
-
-
-struct multtree * MT_tree_new (data, leafs, parent, multant)
-    VOID_T *data;
-    struct multtree **leafs;
-    struct multtree *parent;
-    int             multant;
-/*Initializes TREE using given arguments*/
-
-
-
-
-
-
-int 
-MT_insert (point,info,tree,n_leafs)
-    VOID_T  *point;
-    struct tree_info *info;
-    struct multtree *tree;
-    int    n_leafs;
-/*First checks for dividing cond. (if n_points>=KMAX) and TREE is a leaf
-  by calling one of tree's functions (division_check()).
-  If TREE is not a leaf (is a node) uses function compare to determine
-   into which "son" we need to insert the point and calls MT_insert()
-   with this son as a n argument.
-  If TREE is a leaf but we don't need to divide it (n_points<KMAX) then
-   calls function add_data(POINT) to add POINT to the data of TREE and
-   returns the result of add_data() (which returns 1 if the point is
-   inserted and 0 if its ignored (when its too dense)).
-  If Division_check returns true, calls MT_divide(TREE) and then calls
-   insert_quad() to insert the POINT into divided TREE and returns the
-   result of MT_divide(). */
-
-
-
-
-
-
-
-int 
-MT_divide (info,tree,n_leafs)
-    struct tree_info *info;
-    struct multtree *tree;
-    int      n_leafs;
-/* Divides the tree by calling one of tree's functions (divide_data())
-   and returns the result of divide_data() */
-
-
-
-
-
-
-
-int 
-MT_region_data (info, tree, data, MAX, n_leafs)
-    struct tree_info *info;
-    struct multtree *tree;
-    VOID_T   *data;
-    int             MAX;	/* max number of points we can add (KMAX2) */
-    int             n_leafs;
- /* Gets points inside the region defined by DATA from TREE and
-adds them to DATA. If the number of eligible
-point is more than MAX returns MAX+1 othervise returns number of points added
-to DATA.
-  Uses tree's functions intersect() to find leafs that intersect given region
-and get_points() to get points from such leafs. */
-
-
-
-

lib/rst/qtree/qtree.c

@@ -1,12 +1,24 @@
-
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993
- * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1993, H. Mitasova (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+/*!
+ * \file qtree.c
+ *
+ * \author
+ * H. Mitasova, I. Kosinovsky, D. Gerdes, Fall 1993,
+ * University of Illinois and
+ * US Army Construction Engineering Research Lab
+ *
+ * \author H. Mitasova (University of Illinois),
+ * \author I. Kosinovsky, (USA-CERL)
+ * \author D.Gerdes (USA-CERL)
+ *
+ * \author updated/checked by Mitasova Nov. 96 (no changes necessary)
  *
- *  updated by Mitasova Nov. 96, no changes necessary 
+ * \copyright
+ * (C) 1993-1996 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
 
 #include <stdio.h>
@@ -16,6 +28,7 @@
 #include <grass/dataquad.h>
 #include <grass/qtree.h>
 
+/*! Initializes multfunc structure with given arguments */
 struct multfunc
     *MT_functions_new(int (*compare) (struct triple *, struct quaddata *),
 		      struct quaddata **(*divide_data) (struct quaddata *,
@@ -26,7 +39,6 @@ struct multfunc
 		      int (*division_check) (struct quaddata *, int),
 		      int (*get_points) (struct quaddata *, struct quaddata *,
 					 int))
-/* Initializes FUNCTIONS structure with given arguments */
 {
     struct multfunc *functions;
     if (!(functions = (struct multfunc *)malloc(sizeof(struct multfunc)))) {
@@ -41,10 +53,10 @@ struct multfunc
     return functions;
 }
 
+/*! Initializes tree_info using given arguments */
 struct tree_info *MT_tree_info_new(struct multtree *root,
 				   struct multfunc *functions, double dmin,
 				   int kmax)
-/*Initializes TREE_INFO using given arguments */
 {
     struct tree_info *info;
     if (!(info = (struct tree_info *)malloc(sizeof(struct tree_info)))) {
@@ -57,10 +69,10 @@ struct tree_info *MT_tree_info_new(struct multtree *root,
     return info;
 }
 
+/** Initializes multtree using given arguments */
 struct multtree *MT_tree_new(struct quaddata *data,
 			     struct multtree **leafs, struct multtree *parent,
 			     int multant)
-/*Initializes TREE using given arguments */
 {
     struct multtree *tree;
     if (!(tree = (struct multtree *)malloc(sizeof(struct multtree)))) {
@@ -74,21 +86,24 @@ struct multtree *MT_tree_new(struct quaddata *data,
 }
 
 
-
+/*!
+ * First checks for dividing cond. (if n_points>=KMAX) and tree
+ * is a leaf by calling one of tree's functions (`division_check()`).
+ * If tree is not a leaf (is a node) uses function compare to determine
+ * into which "son" we need to insert the point and calls MT_insert()
+ * with this son as a n argument.
+ *
+ * If TREE is a leaf but we don't need to divide it (n_points<KMAX) then
+ * calls function `add_data(point, ...)` to add point to the data of tree
+ * and returns the result of `add_data()` (which returns 1 if the point is
+ * inserted and 0 if its ignored (when its too dense)).
+ *
+ * If `division_check()` returns true, calls MT_divide() and then calls
+ * MT_insert() to insert the point into divided tree and returns the
+ * result of MT_divide().
+ */
 int MT_insert(struct triple *point,
 	      struct tree_info *info, struct multtree *tree, int n_leafs)
-/*First checks for dividing cond. (if n_points>=KMAX) and TREE is a leaf
-   by calling one of tree's functions (division_check()).
-   If TREE is not a leaf (is a node) uses function compare to determine
-   into which "son" we need to insert the point and calls MT_insert()
-   with this son as a n argument.
-   If TREE is a leaf but we don't need to divide it (n_points<KMAX) then
-   calls function add_data(POINT) to add POINT to the data of TREE and
-   returns the result of add_data() (which returns 1 if the point is
-   inserted and 0 if its ignored (when its too dense)).
-   If Division_check returns true, calls MT_divide(TREE) and then calls
-   insert_quad() to insert the POINT into divided TREE and returns the
-   result of MT_divide(). */
 {
     int j = 0, i, k, comp;
 
@@ -134,9 +149,13 @@ int MT_insert(struct triple *point,
 }
 
 
+/*!
+ * Divide a tree
+ * 
+ * Divides the tree by calling one of tree's functions (divide_data())
+ * and returns the result of divide_data()
+ */
 int MT_divide(struct tree_info *info, struct multtree *tree, int n_leafs)
-/* Divides the tree by calling one of tree's functions (divide_data())
-   and returns the result of divide_data() */
 {
     int i;
     struct quaddata **datas;
@@ -161,15 +180,22 @@ int MT_divide(struct tree_info *info, struct multtree *tree, int n_leafs)
 
 
 
-
-int MT_region_data(struct tree_info *info, struct multtree *tree, struct quaddata *data, int MAX,	/* max number of points we can add (KMAX2) */
-		   int n_leafs)
- /* Gets points inside the region defined by DATA from TREE and
-    adds them to DATA. If the number of eligible
-    point is more than MAX returns MAX+1 othervise returns number of points added
-    to DATA.
-    Uses tree's functions intersect() to find leafs that intersect given region
-    and get_points() to get points from such leafs. */
+/*!
+ * Get points inside a region from a tree
+ *
+ * Gets points inside the region defined by DATA from TREE and
+ * adds them to DATA. If the number of eligible
+ * point is more than MAX returns MAX+1 otherwise returns number of points added
+ * to DATA.
+ *
+ * Uses tree's functions intersect() to find leafs that intersect given region
+ * and get_points() to get points from such leafs.
+ */
+int MT_region_data(struct tree_info *info, struct multtree *tree,
+                   struct quaddata *data,
+                   int MAX,  /*!< max number of points we can add (KMAX2) */
+                   int n_leafs
+                   )
 {
     int n = 0, j;
 

lib/rst/qtree/qtree.h

@@ -1,12 +1,24 @@
-
-/*-
- * Written by H. Mitasova, I. Kosinovsky, D. Gerdes Fall 1993
- * University of Illinois
- * US Army Construction Engineering Research Lab  
- * Copyright 1993, H. Mitasova (University of Illinois),
- * I. Kosinovsky, (USA-CERL), and D.Gerdes (USA-CERL)   
+/*!
+ * \file qtree.c
+ *
+ * \author
+ * H. Mitasova, I. Kosinovsky, D. Gerdes, Fall 1993,
+ * University of Illinois and
+ * US Army Construction Engineering Research Lab
+ *
+ * \author H. Mitasova (University of Illinois),
+ * \author I. Kosinovsky, (USA-CERL)
+ * \author D.Gerdes (USA-CERL)
+ *
+ * \author updated/checked by Mitasova Nov. 96 (no changes necessary)
  *
- * updated by Mitasova Nov. 96, no changes necessary 
+ * \copyright
+ * (C) 1993-1996 by Helena Mitasova and the GRASS Development Team
+ *
+ * \copyright
+ * This program is free software under the
+ * GNU General Public License (>=v2).
+ * Read the file COPYING that comes with GRASS for details.
  */
 
 
@@ -17,6 +29,12 @@
 #define VOID_T char
 
 
+/*!
+ * Function table for a tree
+ *
+ * From object oriented point of view, this structure represents
+ * a class or a virtual table of functions/methods for a class.
+ */
 struct multfunc
 {
     int (*compare) ();

lib/rst/rstlib.dox

@@ -0,0 +1,66 @@
+/*! \page rstlib GRASS Library for interpolation with regularized splines with tension
+
+\tableofcontents
+
+
+Including and linking
+=====================
+
+Include interpf.h, qtree.h and dataquad.h header files according
+to which you need:
+
+    #include <grass/interpf.h>
+    #include <grass/qtree.h>
+    #include <grass/dataquad.h>
+
+Extend `LIBES` and `DEPENDENCIES` in your `Makefile` by the following:
+
+    LIBES = $(INTERPFLLIB) $(GMATHLIB)
+    DEPENDENCIES = $(INTERPFLDEP) $(GMATHDEP)
+
+
+Main functions and structures
+=============================
+
+Main functions include:
+- IL_init_params_2d()
+- IL_init_func_2d()
+- IL_vector_input_data_2d()
+- IL_create_bitmask()
+- IL_resample_interp_segments_2d()
+- IL_resample_output_2d()
+- IL_output_2d()
+
+Main data structures include:
+- interp_params
+- tree_info
+- \ref multtree
+
+
+Example usages
+==============
+
+- \gmod{v.surf.rst}
+- \gmod{r.resamp.rst}
+
+
+References
+==========
+
+The methods are described in the following papers.
+Please, use these papers as references in your publications when you
+used the library or derived modules.
+
+- Mitasova, H., and  Mitas, L., 1993,
+    Interpolation by Regularized Spline with Tension:
+    I. Theory  and  implementation.  Mathematical Geology, 25, 641-55.
+- Mitasova, H., and Hofierka, L., 1993
+    Interpolation by Regularized Spline with Tension: 
+    II. Application to terrain modeling and surface geometry  analysis.
+    Mathematical Geology, 25, 657-69.
+- Mitasova, H., Mitas, L., Brown, W.M., Gerdes, D.P., Kosinovsky, I.,
+    Baker, T., 1995, Modeling spatially and temporally
+    distributed phenomena: New methods and tools for GRASS GIS. 
+    International Journal of Geographic Information Systems,9(4), 433-46.
+
+*/

lib/vector/dglib/dglib.dox

@@ -1,4 +1,4 @@
-/*! \page dglib Directed Graph Library
+/*! \page dglib GRASS Directed Graph Library
 
 by GRASS Development Team (http://grass.osgeo.org)