major gislib.dox update (still not complete)

various minor doxygen fixes


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

lib/gis/align_window.c

@@ -1,39 +1,38 @@
-
-/**
- * \file align_window.c
+/*!
+ * \file gis/align_window.c
  *
  * \brief GIS Library - Window alignment functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <stdio.h>
 #include <math.h>
 #include <grass/gis.h>
 
-
-/**
+/*!
  * \brief Align two regions.
  *
- * Modifies the input <b>window</b> to align to
- * <b>ref</b> region. The resolutions in <b>window</b> are set to match those
- * in <b>ref</b> and the <b>window</b> edges (north, south, east, west) are
- * modified to align with the grid of the <b>ref</b> region.
- * The <b>window</b> may be enlarged if necessary to achieve the alignment.
- * The north is rounded northward, the south southward, the east eastward and the
- * west westward. Lon-lon constraints are taken into consideration
- * to make sure that the north doesn't go above 90 degrees (for lat/lon)
- * or that the east does "wrap" past the west, etc.
+ * Modifies the input <i>window</i> to align to <i>ref</i> region. The
+ * resolutions in <i>window</i> are set to match those in <i>ref</i>
+ * and the <i>window</i> edges (north, south, east, west) are modified
+ * to align with the grid of the <i>ref</i> region.
+ *
+ * The <i>window</i> may be enlarged if necessary to achieve the
+ * alignment.  The north is rounded northward, the south southward,
+ * the east eastward and the west westward. Lon-lon constraints are
+ * taken into consideration to make sure that the north doesn't go
+ * above 90 degrees (for lat/lon) or that the east does "wrap" past
+ * the west, etc.
+ *
+ * \param[in,out] window pointer to Cell_head to be modified
+ * \param ref pointer to Cell_head
  *
- * \param[in,out] window
- * \param[in] ref
  * \return NULL on success
  * \return Pointer to an error string on failure
  */

lib/gis/alloc.c

@@ -1,34 +1,32 @@
-
-/**
- * \file alloc.c
+/*!
+ * \file fis/alloc.c
  *
  * \brief GIS Library - Memory allocation routines.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <stdlib.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
-
-/**
+/*!
  * \brief Memory allocation.
  *
- * Allocates a block of
- * memory at least <b>n</b> bytes which is aligned properly for all data
- * types. A pointer to the aligned block is returned.<br>
+ * Allocates a block of memory at least <i>n</i> bytes which is
+ * aligned properly for all data types. A pointer to the aligned block
+ * is returned.
+ *
  * Dies with error message on memory allocation fail.
  *
- * \param[in] n
- * \return void * 
+ * \param file file name
+ * \param line line number
+ * \param t number of elements
  */
 
 void *G__malloc(const char *file, int line, size_t n)
@@ -46,20 +44,22 @@ void *G__malloc(const char *file, int line, size_t n)
     return buf;
 }
 
-/**
+/*!
  * \brief Memory allocation.
  *
- * Allocates a
- * properly aligned block of memory <b>n</b>*<b>m</b> bytes in length,
- * initializes the allocated memory to zero, and returns a pointer to the
- * allocated block of memory.<br>
- * Dies with error message on memory allocation fail.<br>
- * <b>Note:</b> Allocating memory for reading and writing raster maps is
- * discussed in Allocating_Raster_I_O_Buffers.
+ * Allocates a properly aligned block of memory <i>n</i>*<i>m</i>
+ * bytes in length, initializes the allocated memory to zero, and
+ * returns a pointer to the allocated block of memory.
  *
- * \param[in] n number of elements
- * \param[in] m element size
- * \return void * 
+ * Dies with error message on memory allocation fail.
+ *
+ * <b>Note:</b> Allocating memory for reading and writing raster maps
+ * is discussed in \ref Allocating_Raster_I_O_Buffers.
+ *
+ * \param file fine name
+ * \param line line number
+ * \param m element size
+ * \param n number of elements
  */
 
 void *G__calloc(const char *file, int line, size_t m, size_t n)
@@ -80,26 +80,27 @@ void *G__calloc(const char *file, int line, size_t m, size_t n)
 }
 
 
-/**
+/*!
  * \brief Memory reallocation.
  *
- * Changes the
- * <b>size</b> of a previously allocated block of memory at <b>ptr</b> and
- * returns a pointer to the new block of memory. The <b>size</b> may be larger
- * or smaller than the original size. If the original block cannot be extended
- * "in place", then a new block is allocated and the original block copied to the
- * new block.<br>
- * <b>Note:</b> If <b>buf</b> is NULL, then this routine simply allocates a
- * block of <b>n</b> bytes else <b>buf</b> must point to memory that has been dynamically
- * allocated by <i>G_malloc()</i>, <i>G_calloc()</i>, <i>G_realloc()</i>,
- * malloc(3), alloc(3), or realloc(3).. This routine works around broken realloc( )
- * routines, which do not handle a NULL <b>buf</b>.
+ * Changes the <i>size</i> of a previously allocated block of memory
+ * at <i>ptr</i> and returns a pointer to the new block of memory. The
+ * <i>size</i> may be larger or smaller than the original size. If the
+ * original block cannot be extended "in place", then a new block is
+ * allocated and the original block copied to the new block.
  *
+ * <b>Note:</b> If <i>buf</i> is NULL, then this routine simply
+ * allocates a block of <i>n</i> bytes else <i>buf</i> must point to
+ * memory that has been dynamically allocated by G_malloc(),
+ * G_calloc(), G_realloc(), malloc(3), alloc(3), or realloc(3).. This
+ * routine works around broken realloc() routines, which do not
+ * handle a NULL <i>buf</i>.
+ *
+ * \param file file name
+ * \param line line number
  * \param[in,out] buf buffer holding original data
  * \param[in] n array size
- * \return void * 
  */
-
 void *G__realloc(const char *file, int line, void *buf, size_t n)
 {
     if (n <= 0)
@@ -118,7 +119,7 @@ void *G__realloc(const char *file, int line, void *buf, size_t n)
 }
 
 
-/**
+/*!
  * \brief Free allocated memory.
  *
  * \param[in,out] buf buffer holding original data

lib/gis/area.c

@@ -1,17 +1,14 @@
-
-/**
- * \file area.c
+/*!
+ * \file gis/area.c
  *
  * \brief GIS Library - Area calculation functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <grass/gis.h>
@@ -32,17 +29,14 @@ static struct state {
 
 static struct state *st = &state;
 
-/**
+/*!
  * \brief Begin cell area calculations.
  *
  * This routine must be called once before any call to
- * <i>G_area_of_cell_at_row()</i>. It perform all inititalizations 
- * needed to do area calculations for grid cells, based on the current 
- * window "projection" field. It can be used in either planimetric
+ * G_area_of_cell_at_row(). It perform all inititalizations needed to
+ * do area calculations for grid cells, based on the current window
+ * "projection" field. It can be used in either planimetric
  * projections or the latitude-longitude projection.
- * <br>
- * If the return value is 1 or 0, all the grid cells in the map have 
- * the same area. Otherwise, the area of a grid cell varies with the row.
  *
  * \return 0 if the projection is not measurable (ie. imagery or xy)
  * \return 1 if the projection is planimetric (ie. UTM or SP)
@@ -79,18 +73,17 @@ int G_begin_cell_area_calculations(void)
     }
 }
 
-
-/**
- * \brief Cell area in specified <b>row</b>.
+/*!
+ * \brief Cell area in specified row.
  *
  * This routine returns the area in square meters of a cell in the
- * specified <b>row</b>. This value is constant for planimetric grids 
+ * specified <i>row</i>. This value is constant for planimetric grids 
  * and varies with the row if the projection is latitude-longitude.
  *
- * \param[in] row
- * \return double
+ * \param row row number
+ *
+ * \return cell area
  */
-
 double G_area_of_cell_at_row(int row)
 {
     double south_value;
@@ -114,18 +107,16 @@ double G_area_of_cell_at_row(int row)
     return cell_area;
 }
 
-
-/**
+/*!
  * \brief Begin polygon area calculations.
  *
- * This initializes the polygon area calculation routines. It is used 
+ * This initializes the polygon area calculation routines. It is used
  * both for planimetric and latitude-longitude projections.
  *
  * \return 0 if the projection is not measurable (ie. imagery or xy)
  * \return 1 if the projection is planimetric (ie. UTM or SP)
  * \return 2 if the projection is non-planimetric (ie. latitude-longitude)
  */
-
 int G_begin_polygon_area_calculations(void)
 {
     double a, e2;
@@ -145,29 +136,29 @@ int G_begin_polygon_area_calculations(void)
     return 0;
 }
 
-
-/**
+/*!
  * \brief Area in square meters of polygon.
  *
  * Returns the area in square meters of the polygon described by the 
- * <b>n</b> pairs of <b>x,y</b> coordinate vertices. It is used both for 
+ * <i>n</i> pairs of <i>x,y</i> coordinate vertices. It is used both for 
  * planimetric and latitude-longitude projections.
- * <br>
- * Returns the area in coordinate units of the polygon described by the
- * <b>n</b> pairs of <b>x,y</b> coordinate vertices for planimetric grids.
- * If the units for <b>x,y</b> are meters, then the area is in square meters.
- * If the units are feet, then the area is in square feet, and so on.
- * <br>
+ * 
+ * Returns the area in coordinate units of the polygon described by
+ * the <i>n</i> pairs of <i>x,y</i> coordinate vertices for
+ * planimetric grids.  If the units for <i>x,y</i> are meters, then
+ * the area is in square meters.  If the units are feet, then the area
+ * is in square feet, and so on.
+ * 
  * <b>Note:</b> If the database is planimetric with the non-meter grid, 
  * this routine performs the required unit conversion to produce square 
  * meters.
  *
- * \param[in] x array of x coordinates
- * \param[in] y array of y coordinates
- * \param[in] n number of x,y coordinate pairs
+ * \param x array of x coordinates
+ * \param y array of y coordinates
+ * \param n number of x,y coordinate pairs
+ *
  * \return area in coordinate units of the polygon
  */
-
 double G_area_of_polygon(const double *x, const double *y, int n)
 {
     double area;

lib/gis/area_ellipse.c

@@ -1,17 +1,14 @@
-
-/**
- * \file area_ellipse.c
+/*!
+ * \file gis/area_ellipse.c
  *
  * \brief GIS Library - Ellipse area routines.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <math.h>
@@ -30,42 +27,39 @@ static struct state *st = &state;
  * code will fail if e2==0 (sphere)
  */
 
-/**
+/*!
  * \brief Begin area calculations for ellipsoid.
  *
- * Initializes raster area calculations for an ellipsoid, where <b>a</b> 
- * is the semi-major axis of the ellipse (in meters), <b>e2</b> is the 
- * ellipsoid eccentricity squared, and <b>s</b> is a scale factor to 
- * allow for calculations of part of the zone (<b>s</b>=1.0 is full 
- * zone, <b>s</b>=0.5 is half the zone, and <b>s</b>=360/ew_res is for a 
+ * Initializes raster area calculations for an ellipsoid, where <i>a</i> 
+ * is the semi-major axis of the ellipse (in meters), <i>e2</i> is the 
+ * ellipsoid eccentricity squared, and <i>s</i> is a scale factor to 
+ * allow for calculations of part of the zone (<i>s</i>=1.0 is full 
+ * zone, <i>s</i>=0.5 is half the zone, and <i>s</i>=360/ew_res is for a 
  * single grid cell).
- * <br>
- * <b>Note:</b> <b>e2</b> must be positive. A negative value makes no 
+ * 
+ * <b>Note:</b> <i>e2</i> must be positive. A negative value makes no 
  * sense, and zero implies a sphere.
  *
- * \param[in] a semi-major axis
- * \param[in] e2 ellipsoid eccentricity
- * \param[in] s scale factor
- * \return
+ * \param a semi-major axis
+ * \param e2 ellipsoid eccentricity
+ * \param s scale factor
  */
-
 void G_begin_zone_area_on_ellipsoid(double a, double e2, double s)
 {
     st->E = sqrt(e2);
     st->M = s * a * a * M_PI * (1 - e2) / st->E;
 }
 
-
-/**
+/*!
  * \brief Calculate integral for area between two latitudes.
  *
  * This routine is part of the integral for the area between two 
  * latitudes.
  *
- * \param[in] lat
- * \return double
+ * \param lat latitude
+ *
+ * \return cell area
  */
-
 double G_darea0_on_ellipsoid(double lat)
 {
     double x;
@@ -75,24 +69,23 @@ double G_darea0_on_ellipsoid(double lat)
     return (st->M * (x / (1.0 - x * x) + 0.5 * log((1.0 + x) / (1.0 - x))));
 }
 
-
-/**
+/*!
  * \brief Calculates area between latitudes.
  *
  * This routine shows how to calculate area between two lats, but
- * isn't efficient for row by row since <i>G_darea0_on_ellipsoid()</i> 
- * will be called twice for the same lat, once as a <b>south</b> then 
- * again as a <b>north</b>.
- * <br>
- * Returns the area between latitudes <b>north</b> and <b>south</b> 
- * scaled by the factor <b>s</b> passed to
- * <i>G_begin_zone_area_on_ellipsoid()</i>.
+ * isn't efficient for row by row since G_darea0_on_ellipsoid() 
+ * will be called twice for the same lat, once as a <i>south</i> then 
+ * again as a <i>north</i>.
+ * 
+ * Returns the area between latitudes <i>north</i> and <i>south</i>
+ * scaled by the factor <i>s</i> passed to
+ * G_begin_zone_area_on_ellipsoid().
  *
- * \param[in] north
- * \param[in] south
- * \return double
+ * \param north north coordinate
+ * \param south south coordinate
+ *
+ * \return cell area
  */
-
 double G_area_for_zone_on_ellipsoid(double north, double south)
 {
     return (G_darea0_on_ellipsoid(north) - G_darea0_on_ellipsoid(south));

lib/gis/area_poly1.c

@@ -1,24 +1,20 @@
-
-/**
- * \file area_poly1.c
+/*!
+ * \file gis/area_poly1.c
  *
  * \brief GIS Library - Polygon area calculation routines.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <math.h>
 #include <grass/gis.h>
 #include "pi.h"
 
-
 #define TWOPI M_PI + M_PI
 
 static struct state {
@@ -51,17 +47,15 @@ static double Qbar(double x)
     return cosx * (st->QbarA + cosx2 * (st->QbarB + cosx2 * (st->QbarC + cosx2 * st->QbarD)));
 }
 
-
-/**
+/*!
  * \brief Begin area calculations.
  *
  * This initializes the polygon area calculations for the
- * ellipsoid with semi-major axis <b>a</b> (in meters) and ellipsoid
- * eccentricity squared <b>e2</b>.
+ * ellipsoid with semi-major axis <i>a</i> (in meters) and ellipsoid
+ * eccentricity squared <i>e2</i>.
  *
- * \param[in] a semi-major axis
- * \param[in] e2 ellipsoid eccentricity
- * \return
+ * \param a semi-major axis
+ * \param e2 ellipsoid eccentricity
  */
 
 void G_begin_ellipsoid_polygon_area(double a, double e2)
@@ -88,23 +82,22 @@ void G_begin_ellipsoid_polygon_area(double a, double e2)
 	st->E = -st->E;
 }
 
-
-/**
+/*!
  * \brief Area of lat-long polygon.
  *
  * Returns the area in square meters of the polygon described by the 
- * <b>n</b> pairs of <b>lat,long</b> vertices for latitude-longitude 
+ * <i>n</i> pairs of <i>lat,long</i> vertices for latitude-longitude 
  * grids.
- * <br>
+ *
  * <b>Note:</b> This routine assumes grid lines on the connecting the 
  * vertices (as opposed to geodesics).
  *
- * \param[in] lon array of longitudes
- * \param[in] lat array of latitudes
- * \param[in] n number of lat,lon pairs
- * \return double Area in square meters
+ * \param lon array of longitudes
+ * \param lat array of latitudes
+ * \param n number of lat,lon pairs
+ *
+ * \return area in square meters
  */
-
 double G_ellipsoid_polygon_area(const double *lon, const double *lat, int n)
 {
     double x1, y1, x2, y2, dx, dy;

lib/gis/area_poly2.c

@@ -1,31 +1,27 @@
-
-/**
- * \file area_poly2.c
+/*!
+ * \file gis/area_poly2.c
  *
  * \brief GIS Library - Planimetric polygon area calculation routines.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <grass/gis.h>
 
-
-/**
+/*!
  * \brief Calculates planimetric polygon area.
  *
- * \param[in] x array of x values
- * \param[in] y array of y values
- * \param[in] n number of x,y pairs
- * \return double
- */
+ * \param x array of x values
+ * \param y array of y values
+ * \param n number of x,y pairs
 
+ * \return polygon area in map units
+ */
 double G_planimetric_polygon_area(const double *x, const double *y, int n)
 {
     double x1, y1, x2, y2;

lib/gis/area_sphere.c

@@ -1,17 +1,14 @@
-
-/**
- * \file area_sphere.c
+/*!
+ * \file gis/area_sphere.c
  *
  * \brief GIS Library - Sphereical area calculation routines.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <math.h>
@@ -25,55 +22,47 @@ static struct state {
 
 static struct state *st = &state;
 
-/*
- * r is radius of sphere, s is a scaling factor
- */
-
-/**
+/*!
  * \brief Initialize calculations for sphere.
  *
  * Initializes raster area calculations for a sphere.
- * The radius of the sphere is <b>r</b> and <b>s</b> is a scale factor to
+ * The radius of the sphere is <i>r</i> and <i>s</i> is a scale factor to
  * allow for calculations of a part of the zone (see
- * <i>G_begin_zone_area_on_ellipsoid()</i>).
+ * G_begin_zone_area_on_ellipsoid()).
  *
- * \param[in] r radius of sphere
- * \param[in] s scale factor
- * \return
+ * \param r radius of sphere
+ * \param s scale factor
  */
-
 void G_begin_zone_area_on_sphere(double r, double s)
 {
     st->M = s * 2.0 * r * r * M_PI;
 }
 
-
-/**
+/*!
  * \brief Calculates integral for area between two latitudes.
  *
- * \param[in] lat latitude
- * \return double
+ * \param lat latitude
+ *
+ * \return area value
  */
-
 double G_darea0_on_sphere(double lat)
 {
     return (st->M * sin(Radians(lat)));
 }
 
-
-/**
+/*!
  * \brief Calculates area between latitudes.
  *
  * This routine shows how to calculate area between two lats, but
- * isn't efficient for row by row since <i>G_darea0_on_sphere()</i> will 
- * be called twice for the same lat, once as a <b>south</b> then 
- * again as a <b>north</b>.
- * <br>
- * Returns the area between latitudes <b>north</b> and <b>south</b> 
- * scaled by the factor <b>s</b> passed to 
- * <i>G_begin_zone_area_on_sphere()</i>.
+ * isn't efficient for row by row since G_darea0_on_sphere() will 
+ * be called twice for the same lat, once as a <i>south</i> then 
+ * again as a <i>north</i>.
+ *
+ * Returns the area between latitudes <i>north</i> and <i>south</i>
+ * scaled by the factor <i>s</i> passed to
+ * G_begin_zone_area_on_sphere().
  *
- * \param[in] north
+ * \param north
  * \param[in] south
  * \return double
  */

lib/gis/bres_line.c

@@ -1,5 +1,5 @@
 /*
- * \file bres_line.c
+ * \file gis/bres_line.c
  *
  * \brief GIS Library - Bresenham line routines.
  *
@@ -8,33 +8,25 @@
  * This program is free software under the GNU General Public License
  * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- * \author GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <grass/gis.h>
 
-
-/**
+/*!
  * \brief Bresenham line algorithm.
  *
- * Draws a line from <b>x1,y1</b> to <b>x2,y2</b> using Bresenham's 
+ * Draws a line from <i>x1,y1</i> to <i>x2,y2</i> using Bresenham's 
  * algorithm. A routine to plot points must be provided, as is defined 
  * as: point(x, y) plot a point at x,y.
  *
- * This routine does not require a previous call to 
- * <i>G_setup_plot()</i> to function correctly, and is independent of 
- * all following routines.
+ * This routine does not require a previous call to G_setup_plot() to
+ * function correctly, and is independent of all following routines.
  *
- * \param[in] x0
- * \param[in] y0
- * \param[in] x1
- * \param[in] y1
- * \param[in] point pointer to point plotting function
- * \return
+ * \param x0,y0 first point
+ * \param x1,y1 end point
+ * \param point pointer to point plotting function
  */
-
 void G_bresenham_line(int x0, int y0, int x1, int y1, int (*point) (int, int))
 {
     int dx, dy;

lib/gis/date.c

@@ -1,32 +1,28 @@
-
-/**
- * \file date.c
+/*!
+ * \file gis/date.c
  *
  * \brief GIS Library - Date functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <time.h>
 #include <grass/gis.h>
 
-
-/**
+/*!
  * \brief Current date and time.
  *
- * Returns a pointer to a string which is the current date and time. The 
- * format is the same as that produced by the UNIX <i>date</i> command.
+ * Returns a pointer to a string which is the current date and
+ * time. The format is the same as that produced by the UNIX
+ * <tt>date</tt> command.
  *
- * \return Pointer to a string holding date/time
+ * \return pointer to a string holding date/time
  */
-
 const char *G_date(void)
 {
     static int initialized;

lib/gis/distance.c

@@ -1,6 +1,5 @@
-
-/**
- * \file distance.c
+/*!
+ * \file gis/distance.c
  *
  * \brief GIS Library - Distance calculation functions.
  *
@@ -8,14 +7,12 @@
  * including calling sequences to any of the functions
  * defined here.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2006
+ * \author Original author CERL
  */
 
 #include <math.h>
@@ -32,7 +29,7 @@ static struct state {
 
 static struct state *st = &state;
 
-/**
+/*!
  * \brief Begin distance calculations.
  *
  * Initializes the distance calculations. It is used both for the
@@ -64,19 +61,19 @@ int G_begin_distance_calculations(void)
 }
 
 
-/**
+/*!
  * \brief Returns distance in meters.
  *
  * This routine computes the distance, in meters, from
- * <b>x1</b>,<b>y1</b> to <b>x2</b>,<b>y2</b>. If the projection is
- * latitude-longitude, this distance is measured along the geodesic. Two
- * routines perform geodesic distance calculations.
+ * <i>x1</i>,<i>y1</i> to <i>x2</i>,<i>y2</i>. If the projection is
+ * latitude-longitude, this distance is measured along the
+ * geodesic. Two routines perform geodesic distance calculations.
  *
- * \param[in] e1,n1 east-north coordinates of first point
- * \param[in] e2,n2 east-north coordinates of second point
+ * \param e1,n1 east-north coordinates of first point
+ * \param e2,n2 east-north coordinates of second point
+ 
  * \return distance
  */
-
 double G_distance(double e1, double n1, double e2, double n2)
 {
     if (st->projection == PROJECTION_LL)
@@ -85,20 +82,18 @@ double G_distance(double e1, double n1, double e2, double n2)
 	return st->factor * hypot(e1 - e2, n1 - n2);
 }
 
-
-/**
+/*!
  * \brief Returns distance between two line segments in meters.
  *
- * \param[in] ax1,ay2,ax2,ay2 first segment
- * \param[in] bx1,by2,bx2,by2 second segment
- * \return double
+ * \param ax1,ay2,ax2,ay2 first segment
+ * \param bx1,by2,bx2,by2 second segment
+ *
+ * \return distance value
  */
-
-double
-G_distance_between_line_segments(double ax1, double ay1,
-				 double ax2, double ay2,
-				 double bx1, double by1,
-				 double bx2, double by2)
+double G_distance_between_line_segments(double ax1, double ay1,
+					double ax2, double ay2,
+					double bx1, double by1,
+					double bx2, double by2)
 {
     double ra, rb;
     double x, y;
@@ -115,20 +110,19 @@ G_distance_between_line_segments(double ax1, double ay1,
 	);
 }
 
-
-/**
+/*!
  * \brief Returns distance between a point and line segment in meters.
  *
- * \param[in] xp,yp point coordinates
- * \param[in] x1,x1 segment point coordinates
- * \param[in] x2,y2 segment point coordinates
+ * \param xp,yp point coordinates
+ * \param x1,x1 segment point coordinates
+ * \param x2,y2 segment point coordinates
+ *
  * \return distance
  */
-
-double G_distance_point_to_line_segment(double xp, double yp,	/* the point */
+double G_distance_point_to_line_segment(double xp, double yp,
 					double x1, double y1, double x2,
 					double y2)
-{				/* the line segment */
+{
     double dx, dy;
     double x, y;
     double xq, yq, ra, rb;

lib/gis/endian.c

@@ -1,23 +1,19 @@
-
-/**
- * \file endian.c
+/*!
+ * \file gis/endian.c
  *
  * \brief GIS Library - Functions to determine architecture endian.
  *
  * This endian test was taken from ./src.contrib/GMSL/NVIZ2.2/TOGL/apps/image.c.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 Markus Neteler
- *
- * \date 2001-2008
  */
 
-
-/**
+/*!
  * \brief Tests for little ENDIAN.
  *
  * Test if machine is little or big endian.
@@ -25,7 +21,6 @@
  * \return 1 little endian
  * \return 0 big endian
  */
-
 int G_is_little_endian(void)
 {
     union

lib/gis/env.c

@@ -1,15 +1,15 @@
-/**
-   \file lib/gis/env.c
-
-   \brief GIS library - environment routines
-   
-   (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
-   \author Updated for GRASS7 by Glynn Clements
+/*!
+  \file gis/env.c
+
+  \brief GIS library - environment routines
+  
+  (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
+  \author Updated for GRASS7 by Glynn Clements
 */
 
 #include <signal.h>
@@ -49,35 +49,33 @@ static const char *get_env(const char *, int);
 static void write_env(int);
 static FILE *open_env(const char *, int);
 
-/**
-   \brief Set where to find/store variables
-
-   Modes:
-    - G_GISRC_MODE_FILE
-    - G_GISRC_MODE_MEMORY 
+/*!
+  \brief Set where to find/store variables
+  
+  Modes:
+   - G_GISRC_MODE_FILE
+   - G_GISRC_MODE_MEMORY 
 
    \param mode mode to find/store variables (G_GISRC_MODE_FILE by default)
-
-   \return
 */
 void G_set_gisrc_mode(int mode)
 {
     st->varmode = mode;
 }
 
-/**
-   \brief Get info where variables are stored
-
-   \return mode
+/*!
+  \brief Get info where variables are stored
+  
+  \return mode
 */
 int G_get_gisrc_mode(void)
 {
     return (st->varmode);
 }
 
-/**
+/*!
   \brief Initialize variables
-
+  
   \return
 */
 void G_init_env(void)
@@ -275,14 +273,14 @@ static FILE *open_env(const char *mode, int loc)
     return fopen(buf, mode);
 }
 
-/**
-   \brief Get environment variable
-
-   Calls G_fatal_error() if name not set.
-
-   \param name variable name
-
-   \return char pointer to value for name
+/*!
+  \brief Get environment variable
+  
+  Calls G_fatal_error() if name not set.
+  
+  \param name variable name
+  
+  \return char pointer to value for name
 */
 const char *G_getenv(const char *name)
 {
@@ -295,20 +293,20 @@ const char *G_getenv(const char *name)
     return NULL;
 }
 
-/**
-   \brief Read variable from specific place
-
-   Locations:
-    - G_VAR_GISRC
-    - G_VAR_MAPSET
-
-   G_fatal_error() is called when variable is not found.
-
-   \param name variable name
-   \param loc location id
-
-   \return variable value
-   \return NULL if not found
+/*!
+  \brief Read variable from specific place
+  
+  Locations:
+   - G_VAR_GISRC
+   - G_VAR_MAPSET
+
+  G_fatal_error() is called when variable is not found.
+  
+  \param name variable name
+  \param loc location id
+   
+  \return variable value
+  \return NULL if not found
 */
 const char *G_getenv2(const char *name, int loc)
 {
@@ -321,13 +319,13 @@ const char *G_getenv2(const char *name, int loc)
     return NULL;
 }
 
-/**
-   \brief Get environment variable
-
-   \param name variable name
-   
-   \return char pointer to value for name
-   \return NULL if name not set
+/*!
+  \brief Get environment variable
+  
+  \param name variable name
+  
+  \return char pointer to value for name
+  \return NULL if name not set
 */
 const char *G__getenv(const char *name)
 {
@@ -339,14 +337,14 @@ const char *G__getenv(const char *name)
     return get_env(name, G_VAR_GISRC);
 }
 
-/**
-   \brief Get environment variable from specific place
-
-   \param name variable name
-   \param loc location id
-   
-   \return char pointer to value for name
-   \return NULL if name not set
+/*!
+  \brief Get environment variable from specific place
+  
+  \param name variable name
+  \param loc location id
+  
+  \return char pointer to value for name
+  \return NULL if name not set
 */
 const char *G__getenv2(const char *name, int loc)
 {
@@ -358,16 +356,14 @@ const char *G__getenv2(const char *name, int loc)
     return get_env(name, loc);
 }
 
-/**
-   \brief Set environment variable
+/*!
+  \brief Set environment variable
 
-   If value is NULL, becomes an G_unsetenv().
-   Updates .gisrc
-
-   \param name variable name
-   \param value variable value
-
-   \return
+  If value is NULL, becomes an G_unsetenv().
+  Updates .gisrc
+  
+  \param name variable name
+  \param value variable value
 */
 void G_setenv(const char *name, const char *value)
 {
@@ -376,17 +372,15 @@ void G_setenv(const char *name, const char *value)
     write_env(G_VAR_GISRC);
 }
 
-/**
-   \brief Set environment variable from specific place
-
-   If value is NULL, becomes an G_unsetenv().
-   Updates .gisrc
-
-   \param name variable name
-   \param value variable value
-   \param loc location id
-
-   \return
+/*!
+  \brief Set environment variable from specific place
+  
+  If value is NULL, becomes an G_unsetenv().
+  Updates .gisrc
+  
+  \param name variable name
+  \param value variable value
+  \param loc location id
 */
 void G_setenv2(const char *name, const char *value, int loc)
 {
@@ -395,13 +389,11 @@ void G_setenv2(const char *name, const char *value, int loc)
     write_env(loc);
 }
 
-/**
-   \brief Set environment name to value
-
-   \param name variable name
-   \param value variable value
-
-   \return
+/*!
+  \brief Set environment name to value
+  
+  \param name variable name
+  \param value variable value
 */
 void G__setenv(const char *name, const char *value)
 {
@@ -409,14 +401,12 @@ void G__setenv(const char *name, const char *value)
     set_env(name, value, G_VAR_GISRC);
 }
 
-/**
-   \brief Set environment name to value from specific place
-
-   \param name variable name
-   \param value variable value
-   \param loc location id
-
-   \return
+/*!
+  \brief Set environment name to value from specific place
+  
+  \param name variable name
+  \param value variable value
+  \param loc location id
 */
 void G__setenv2(const char *name, const char *value, int loc)
 {
@@ -424,14 +414,12 @@ void G__setenv2(const char *name, const char *value, int loc)
     set_env(name, value, loc);
 }
 
-/**
-   \brief Remove name from environment
-
-   Updates .gisrc
-
-   \param name variable name
-
-   \return
+/*!
+  \brief Remove name from environment
+  
+  Updates .gisrc
+  
+  \param name variable name
 */
 void G_unsetenv(const char *name)
 {
@@ -440,15 +428,13 @@ void G_unsetenv(const char *name)
     write_env(G_VAR_GISRC);
 }
 
-/**
-   \brief Remove name from environment from specific place
-
-   Updates .gisrc
-
-   \param name variable name
-   \param loc location id
-   
-   \return
+/*!
+  \brief Remove name from environment from specific place
+  
+  Updates .gisrc
+  
+  \param name variable name
+  \param loc location id
 */
 void G_unsetenv2(const char *name, int loc)
 {
@@ -457,10 +443,8 @@ void G_unsetenv2(const char *name, int loc)
     write_env(loc);
 }
 
-/**
-   \brief Writes current environment to .gisrc
-
-   \return
+/*!
+  \brief Writes current environment to .gisrc
 */
 void G__write_env(void)
 {
@@ -468,20 +452,21 @@ void G__write_env(void)
 	write_env(G_VAR_GISRC);
 }
 
-/**
-   \brief Get variable name for index n.
+/*!
+  \brief Get variable name for index n.
+  
+  For example:
 
-   For example:
-   \code
+  \code
    for (n = 0; ; n++)
       if ((name = G__env_name(n)) == NULL)
         break;
-   \endcode
-
-   \param n index of variable
+  \endcode
 
-   \return pointer to variable name
-   \return NULL not found
+  \param n index of variable
+  
+  \return pointer to variable name
+  \return NULL not found
 */
 const char *G__env_name(int n)
 {
@@ -495,20 +480,16 @@ const char *G__env_name(int n)
     return NULL;
 }
 
-/**
-   \brief Initialize init array for G_VAR_GISRC.
-
-   \return
+/*!
+  \brief Initialize init array for G_VAR_GISRC.
 */
 void G__read_env(void)
 {
     st->init[G_VAR_GISRC] = 0;
 }
 
-/**
-   \brief Set up alternative environment variables
-
-   \return
+/*!
+  \brief Set up alternative environment variables
 */
 void G__create_alt_env(void)
 {
@@ -528,10 +509,8 @@ void G__create_alt_env(void)
     }
 }
 
-/**
-   \brief Switch environments
-
-   \return
+/*!
+  \brief Switch environments
 */
 void G__switch_env(void)
 {

lib/gis/error.c

@@ -1,9 +1,9 @@
 /*!
  * \file error.c
  * 
- * \brief GIS Library: Error messages functions
+ * \brief GIS Library - Error messages functions
  *
- * (C) 1999-2008 by the GRASS Development Team
+ * (C) 1999-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
@@ -198,9 +198,13 @@ int G_suppress_warnings(int flag)
 /*!
  * \brief Turn on/off no_sleep flag
  * 
- * \param flag if non-zero/zero value is given G_sleep() will be activated/deactivated
+ * If <em>flag</em> is 0, then no pause will occur after printing an
+ * error or warning message. Otherwise the pause will occur.
+ * 
+ * \param flag if non-zero/zero value is given G_sleep() will be
+ * activated/deactivated
  *
- * \return previous flag
+ * \return previous no_sleep value
  */
 int G_sleep_on_error(int flag)
 {

lib/gis/find_file.c

@@ -1,9 +1,9 @@
 /*!
-   \file find_file.c
+   \file gis/find_file.c
 
-   \brief GIS library - find GRASS data base files
+   \brief GIS library - Find GRASS data base files
 
-   (C) 2001-2008 by the GRASS Development Team
+   (C) 2001-2009 by the GRASS Development Team
 
    This program is free software under the 
    GNU General Public License (>=v2). 
@@ -133,70 +133,94 @@ static const char *find_file1(
 }
 
 /*!
- * \brief searches for a file from the mapset search list
- *      or in a specified mapset.
- *      returns the mapset name where the file was found.
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset.
  *
- *  notes:
+ * Returns the mapset name where the file was found.
  *
- *      If the user specifies a fully qualified element (<i>name@mapset</i>)
- *      which exists, then <i>G_find_file()</i> modifies <b>name</b>
- *      by removing the "@<i>mapset</i>" part.
+ * If the user specifies a fully qualified element (<i>name@mapset</i>)
+ * which exists, then G_find_file() modifies <i>name</i>
+ * by removing the "@<i>mapset</i>" part.
  *
- *      Rejects all names that begin with "."
+ * Rejects all names that begin with "."
  *
- *      If <b>name</b> is of the form nnn in ppp then only mapset ppp
- *      is searched.
+ * If <i>name</i> is of the form nnn in ppp then only mapset ppp
+ * is searched.
  *
- *  \param const char *element   database element (eg, "cell", "cellhd", "colr", etc)
- *  \param char *name            file name to look for
- *  \param const char *mapset    mapset to search. if mapset is ""
- *                               will search in mapset search list
+ * \param element database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name    file name to look for
+ * \param mapset  mapset to search. if mapset is "" will search in mapset search list
  *
- *  \return char *  pointer to a string with name of mapset
- *              where file was found, or NULL if not found
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
  */
-
 const char *G_find_file(const char *element, char *name, const char *mapset)
 {
     return find_file1(0, NULL, element, name, mapset);
 }
 
+/*!
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset.
+ *
+ * Returns the mapset name where the file was found.
+ *
+ * \param dir     file directory
+ * \param element database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name    file name to look for
+ * \param mapset  mapset to search. if mapset is "" will search in mapset search list
+ *
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
+ */
 const char *G_find_file_misc(const char *dir,
-		       const char *element, char *name, const char *mapset)
+			     const char *element, char *name, const char *mapset)
 {
     return find_file1(1, dir, element, name, mapset);
 }
 
-
 /*!
- * \brief searches for a file from the mapset search list
- *      or in a specified mapset. (look but don't touch)
- *      returns the mapset name where the file was found.
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset. (look but don't touch)
  *
- *      Exactly the same as G_find_file() except that if <b>name</b> is in
- *      the form "<i>name@mapset</i>", and is found, G_find_file2() will not
- *      alter <b>name</b> by removing the "@<i>mapset</i>" part.
+ * Returns the mapset name where the file was found.
  *
- *  note:
- *      rejects all names that begin with "."
+ * Exactly the same as G_find_file() except that if <i>name</i> is in
+ * the form "<i>name@mapset</i>", and is found, G_find_file2() will
+ * not alter <i>name</i> by removing the "@<i>mapset</i>" part.
  *
- *  \param char *element    database element (eg, "cell", "cellhd", "colr", etc)
- *  \param char *name       file name to look for
- *  \param char *mapset     mapset to search. if mapset is ""
- *                         will search in mapset search list
+ * Rejects all names that begin with "."
  *
- *  \return char *  pointer to a string with name of mapset
- *              where file was found, or NULL if not found
+ * \param element    database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name       file name to look for
+ * \param mapset     mapset to search. if mapset is "" will search in mapset search list
+ *
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
  */
 const char *G_find_file2(const char *element, const char *name, const char *mapset)
 {
     return find_file(0, NULL, element, name, mapset);
 }
 
+/*!
+ * \brief Searches for a file from the mapset search list or in a
+ * specified mapset. (look but don't touch)
+ *
+ * Returns the mapset name where the file was found.
+ *
+ *
+ * \param dir        file directory
+ * \param element    database element (eg, "cell", "cellhd", "colr", etc)
+ * \param name       file name to look for
+ * \param mapset     mapset to search. if mapset is "" will search in mapset search list
+ *
+ * \return pointer to a string with name of mapset where file was
+ * found, or NULL if not found
+ */
 const char *G_find_file2_misc(const char *dir,
-			const char *element,
-			const char *name, const char *mapset)
+			      const char *element,
+			      const char *name, const char *mapset)
 {
     return find_file(1, dir, element, name, mapset);
 }

lib/gis/geodist.c

@@ -1,33 +1,29 @@
-
-/**
- * \file geodist.c
+/*!
+ * \file gis/geodist.c
  *
  * \brief GIS Library - Geodesic distance routines.
  *
  * Distance from point to point along a geodesic code from Paul
- * D. Thomas, 1970<br> "Spheroidal Geodesics, Reference Systems, and
- * Local Geometry"<br> U.S. Naval Oceanographic Office, p. 162<br>
- * Engineering Library 526.3 T36s
+ * D. Thomas, 1970 "Spheroidal Geodesics, Reference Systems, and Local
+ * Geometry" U.S. Naval Oceanographic Office, p. 162 Engineering
+ * Library 526.3 T36s
  * http://stinet.dtic.mil/oai/oai?&verb=getRecord&metadataPrefix=html&identifier=AD0703541
  *
  * <b>WARNING:</b> this code is preliminary and may be changed,
  * including calling sequences to any of the functions defined here.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <math.h>
 #include <grass/gis.h>
 #include "pi.h"
 
-
 static struct state {
     double boa;
     double f;
@@ -38,18 +34,17 @@ static struct state {
 
 static struct state *st = &state;
 
-/**
+/*!
  * \brief Begin geodesic distance.
  *
  * Initializes the distance calculations for the ellipsoid with
- * semi-major axis <b>a</b> (in meters) and ellipsoid eccentricity squared
- * <b>e2</b>. It is used only for the latitude-longitude projection.
- * <br>
+ * semi-major axis <i>a</i> (in meters) and ellipsoid eccentricity squared
+ * <i>e2</i>. It is used only for the latitude-longitude projection.
+ *
  * <b>Note:</b> Must be called once to establish the ellipsoid.
  *
- * \param[in] a semi-major axis in meters
- * \param[in] e2 ellipsoid eccentricity
- * \return
+ * \param a semi-major axis in meters
+ * \param e2 ellipsoid eccentricity
  */
 
 void G_begin_geodesic_distance(double a, double e2)
@@ -60,16 +55,14 @@ void G_begin_geodesic_distance(double a, double e2)
     st->ff64 = st->f * st->f / 64;
 }
 
-
-
-/**
+/*!
  * \brief Sets geodesic distance lat1.
  *
  * Set the first latitude.
  *
  * <b>Note:</b> Must be called first.
  *
- * \param[in] lat1 first latitude
+ * \param lat1 first latitude
  * \return
  */
 
@@ -78,18 +71,15 @@ void G_set_geodesic_distance_lat1(double lat1)
     st->t1r = atan(st->boa * tan(Radians(lat1)));
 }
 
-
-/**
+/*!
  * \brief Sets geodesic distance lat2.
  *
  * Set the second latitude.
  *
  * <b>Note:</b> Must be called second.
  *
- * \param[in] lat2 second latitidue
- * \return
+ * \param lat2 second latitidue
  */
-
 void G_set_geodesic_distance_lat2(double lat2)
 {
     double stm, ctm, sdtm, cdtm;
@@ -115,20 +105,19 @@ void G_set_geodesic_distance_lat2(double lat2)
     st->t4 = cdtm * cdtm - stm * stm;
 }
 
-
-/**
+/*!
  * \brief Calculates geodesic distance.
  *
- * Calculates the geodesic distance from <b>lon1,lat1</b> to 
- * <b>lon2,lat2</b> in meters where <b>lat1</b> was the latitude passed 
- * to <i>G_set_geodesic_distance_latl()</i> and <b>lat2</b> was the 
- * latitude passed to <i>G_set_geodesic_distance_lat2()</i>.
+ * Calculates the geodesic distance from <i>lon1,lat1</i> to
+ * <i>lon2,lat2</i> in meters where <i>lat1</i> was the latitude
+ * passed to G_set_geodesic_distance_latl() and <i>lat2</i> was the
+ * latitude passed to G_set_geodesic_distance_lat2().
+ *
+ * \param lon1 first longitude
+ * \param lon2 second longitude
  *
- * \param[in] lon1 first longitude
- * \param[in] lon2 second longitude
  * \return double distance in meters
  */
-
 double G_geodesic_distance_lon_to_lon(double lon1, double lon2)
 {
     double a, cd, d, e,		/*dl, */
@@ -190,20 +179,20 @@ double G_geodesic_distance_lon_to_lon(double lon1, double lon2)
 					+ y * (-2 * d + e * y) + d * x * y));
 }
 
-
-/**
+/*!
  * \brief Calculates geodesic distance.
  *
- * Calculates the geodesic distance from <b>lon1,lat1</b> to 
- * <b>lon2,lat2</b> in meters.
- * <br>
- * <b>Note:</b> The calculation of the geodesic distance is fairly costly.
+ * Calculates the geodesic distance from <i>lon1,lat1</i> to 
+ * <i>lon2,lat2</i> in meters.
+ * 
+ * <b>Note:</b> The calculation of the geodesic distance is fairly
+ * costly.
+ *
+ * \param lon1,lat1 longitude,latitude of first point
+ * \param lon2,lat2 longitude,latitude of second point
  *
- * \param[in] lon1,lat1 longitude,latitude of first point
- * \param[in] lon2,lat2 longitude,latitude of second point
  * \return distance in meters
  */
-
 double G_geodesic_distance(double lon1, double lat1, double lon2, double lat2)
 {
     G_set_geodesic_distance_lat1(lat1);

lib/gis/get_ellipse.c

@@ -1,21 +1,22 @@
 /*!
-   \file get_ellipse.c
+  \file gis/get_ellipse.c
 
-   \brief Getting ellipsoid parameters from the database.
+  \brief GIS Library - Getting ellipsoid parameters from the database.
 
-   This routine returns the ellipsoid parameters from the database.
-   If the PROJECTION_FILE exists in the PERMANENT mapset, read info
-   from that file, otherwise return WGS 84 values.
+  This routine returns the ellipsoid parameters from the database.
+  If the PROJECTION_FILE exists in the PERMANENT mapset, read info
+  from that file, otherwise return WGS 84 values.
 
-   Returns: 1 ok, 0 default values used.
-   Dies with diagnostic if there is an error
+  New 05/2000 by al: for datum shift the f parameter is needed too.
+  This all is not a clean design, but it keeps backward-
+  compatibility. 
+  Looks up ellipsoid in ellipsoid table and returns the
+  a, e2 and f parameters for the ellipsoid
+  
+  (C) 2001-2009 by the GRASS Development Team
 
-   (C) 2001-2008 by the GRASS Development Team
-
-   This program is free software under the 
-   GNU General Public License (>=v2). 
-   Read the file COPYING that comes with GRASS
-   for details.
+  This program is free software under the GNU General Public License
+  (>=v2).  Read the file COPYING that comes with GRASS for details.
 
    \author CERL
  */
@@ -94,13 +95,12 @@ int G_get_ellipsoid_parameters(double *a, double *e2)
 }
 
 /*!
- * \brief get ellipsoid parameters by name
+ * \brief Get ellipsoid parameters by name
  *
- * This routine returns the semi-major axis <b>a</b> (in meters) and
- * eccentricity squared <b>e2</b> for the named ellipsoid.  Returns 1
- * if <b>name</b> is a known ellipsoid, 0 otherwise.
+ * This routine returns the semi-major axis <i>a</i> (in meters) and
+ * eccentricity squared <i>e2</i> for the named ellipsoid.
  *
- * \param[in]  name ellipsoid name
+ * \param  name ellipsoid name
  * \param[out] a    semi-major axis
  * \param[out] e2   eccentricity squared
  *
@@ -124,16 +124,16 @@ int G_get_ellipsoid_by_name(const char *name, double *a, double *e2)
 }
 
 /*!
- * \brief get ellipsoid name
+ * \brief Get ellipsoid name
  *
  * This function returns a pointer to the short name for the
- * <b>n</b><i>th</i> ellipsoid.  If <b>n</b> is less than 0 or greater
+ * <i>n</i><i>th</i> ellipsoid.  If <i>n</i> is less than 0 or greater
  * than the number of known ellipsoids, it returns a NULL pointer.
  *
- * \param[in] n ellipsoid identificator
+ * \param n ellipsoid identificator
  *
- *  \return char * ellipsoid name
- *  \return NULL if no ellipsoid found
+ * \return ellipsoid name
+ * \return NULL if no ellipsoid found
  */
 const char *G_ellipsoid_name(int n)
 {
@@ -141,26 +141,14 @@ const char *G_ellipsoid_name(int n)
     return n >= 0 && n < table.count ? table.ellipses[n].name : NULL;
 }
 
-/*
- * new 05/2000 by al: for datum shift the f parameter is needed too.
- * this all is not a clean design, but it keeps backward-
- * compatibility. 
- * looks up ellipsoid in ellipsoid table and returns the
- * a, e2 and f parameters for the ellipsoid
- * 
- * returns 1 if ok,
- *         0 if not found in table 
- */
-
 /*!
- * \brief get spheroid parameters by name
+ * \brief Get spheroid parameters by name
  *
- * This function returns the semi-major axis <b>a</b> (in meters), the
- * eccentricity squared <b>e2</b> and the inverse flattening <b>f</b>
- * for the named ellipsoid. Returns 1 if <b>name</b> is a known
- * ellipsoid, 0 otherwise.
+ * This function returns the semi-major axis <i>a</i> (in meters), the
+ * eccentricity squared <i>e2</i> and the inverse flattening <i>f</i>
+ * for the named ellipsoid.
  *
- * \param[in] name spheroid name
+ * \param name spheroid name
  * \param[out] a   semi-major axis
  * \param[out] e2  eccentricity squared
  * \param[out] f   inverse flattening
@@ -187,18 +175,17 @@ int G_get_spheroid_by_name(const char *name, double *a, double *e2, double *f)
 
 
 /*!
- * \brief get description for <b>n</b><i>th</i> ellipsoid
+ * \brief Get description for nth ellipsoid
  *
  * This function returns a pointer to the description text for the
- * <b>n</b><i>th</i> ellipsoid. If <b>n</b> is less than 0 or greater
+ * <i>n</i>th ellipsoid. If <i>n</i> is less than 0 or greater
  * than the number of known ellipsoids, it returns a NULL pointer.
  *
- * \param[in] n ellipsoid identificator
+ * \param n ellipsoid identificator
  *
  * \return pointer to ellipsoid description
  * \return NULL if no ellipsoid found
  */
-
 const char *G_ellipsoid_description(int n)
 {
     G_read_ellipsoid_table(0);
@@ -253,6 +240,15 @@ static int compare_ellipse_names(const void *pa, const void *pb)
     return G_strcasecmp(a->name, b->name);
 }
 
+/*!
+  \brief Read ellipsoid table
+
+  \param fatal non-zero value for G_fatal_error(), otherwise
+  G_warning() is used
+
+  \return 1 on sucess
+  \return 0 on error
+*/
 int G_read_ellipsoid_table(int fatal)
 {
     FILE *fd;

lib/gis/get_window.c

@@ -1,24 +1,15 @@
-/*
- *************************************************************************
- * G_get_window (window)
- *     struct Cell_head *window
- *
- *      read the current mapset window
- *      dies if error
- *
- *************************************************************************
- * G_get_default_window (window)
- *     struct Cell_head *window
- *
- *      read the default window for the location
- *      dies if error
- *
- *************************************************************************
- * char *
- * G__get_window (window, element, name, mapset)
- *      read the window 'name' in 'element' in 'mapset'
- *      returns NULL if ok, error message if not
- ************************************************************************/
+/*!
+  \file gis/get_window.c
+
+  \brief GIS Library - Get window (i.e. GRASS region)
+
+  (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
+*/
 
 #include <stdlib.h>
 #include "G.h"
@@ -33,21 +24,22 @@ static struct state {
 static struct state *st = &state;
 
 /*!
- * \brief read the database region
+ * \brief Read the database region
  *
  * Reads the database region as stored in the WIND file in the user's
- * current mapset <b>into region.</b>
+ * current mapset into region.
+ *
  * 3D values are set to defaults if not available in WIND file.
- * An error message is printed and exit( ) is called if there is a problem reading
+ * An error message is printed and exit() is called if there is a problem reading
  * the region.
- * <b>Note.</b> GRASS applications that read or write raster maps should not
- * use this routine since its use implies that the active module region will not
- * be used. Programs that read or write raster map data (or vector data) can
- * query the active module region <i>using G_window_rows and
- * G_window_cols..</i>
  *
- *  \param region
- *  \return int
+ * <b>Note:</b> GRASS applications that read or write raster maps
+ * should not use this routine since its use implies that the active
+ * module region will not be used. Programs that read or write raster
+ * map data (or vector data) can query the active module region using
+ * G_window_rows() and G_window_cols().
+ *
+ * \param window pointer to Cell_head
  */
 
 void G_get_window(struct Cell_head *window)
@@ -76,7 +68,8 @@ void G_get_window(struct Cell_head *window)
     }
 
     if (err)
-	G_fatal_error(_("region for current mapset %s\nrun \"g.region\""), err);
+	G_fatal_error(_("Region for current mapset %s. "
+			"Run \"g.region\" to fix the current region."), err);
 
     *window = st->dbwindow;
 
@@ -88,17 +81,16 @@ void G_get_window(struct Cell_head *window)
     G_initialize_done(&st->initialized);
 }
 
-
 /*!
- * \brief read the default region
+ * \brief Read the default region
  *
- * Reads the default region for the location into <b>region.</b>
- * 3D values are set to defaults if not available in WIND file.
- * An error message is printed and exit( ) is called if there is a problem
- * reading the default region.
+ * Reads the default region for the location into <i>region.</i> 3D
+ * values are set to defaults if not available in WIND file.
+ *
+ * An error message is printed and exit() is called if there is a
+ * problem reading the default region.
  *
- *  \param region
- *  \return int
+ * \param[out] window pointer to Cell_head
  */
 
 void G_get_default_window(struct Cell_head *window)
@@ -106,9 +98,20 @@ void G_get_default_window(struct Cell_head *window)
     const char *err = G__get_window(window, "", "DEFAULT_WIND", "PERMANENT");
 
     if (err)
-	G_fatal_error(_("default region %s"), err);
+	G_fatal_error(_("Default region %s"), err);
 }
 
+/*!
+  \brief Get cwindow (region) of selected map layer
+  
+  \param window pointer to Cell_head
+  \param element element name
+  \param name map name
+  \param mapset mapset name
+
+  \return string on error
+  \return NULL on success
+*/
 char *G__get_window(struct Cell_head *window,
 		    const char *element, const char *name, const char *mapset)
 {

lib/gis/getl.c

@@ -1,19 +1,33 @@
+/*!
+ * \file gis/getl.c
+ *
+ * \brief GIS Library - Get line of text from file
+ *
+ * (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
+ */
+
 #include <stdio.h>
 #include <grass/gis.h>
 
 /*!
- * \brief gets a line of text from a file
+ * \brief Gets a line of text from a file
  *
- * This routine runs fgets() to fetch a line of text from a file (advancing
- * file pointer) and removes trailing newline. fgets() does not recognize
- * '<code>\\r</code>' as an EOL and will read past it.<br>
+ * This routine runs fgets() to fetch a line of text from a file
+ * (advancing file pointer) and removes trailing newline. fgets() does
+ * not recognize '<code>\\r</code>' as an EOL and will read past * it.
  *
- * \param buf: string buffer to receive read data
- * \param n: maximum number of bytes to read
- * \param fd: file descriptor structure
- * \return 1 if ok, 0 if EOF
+ * \param buf string buffer to receive read data
+ * \param n maximum number of bytes to read
+ * \param fd file descriptor structure
+ *
+ * \return 1 on success
+ * \return 0 EOF
  */
-
 int G_getl(char *buf, int n, FILE * fd)
 {
     if (!fgets(buf, n, fd))
@@ -25,30 +39,28 @@ int G_getl(char *buf, int n, FILE * fd)
     return 1;
 }
 
-
-
 /*!
- * \brief gets a line of text from a file of any pedigree
+ * \brief Gets a line of text from a file of any pedigree
  *
- * This routine is like G_getl() but is more portable. 
- * It supports text files created on various platforms (UNIX, MacOS9, DOS),
- * i.e. <code>\\n (\\012)</code>, <code>\\r (\\015)</code>, and 
+ * This routine is like G_getl() but is more portable.  It supports
+ * text files created on various platforms (UNIX, MacOS9, DOS),
+ * i.e. <code>\\n (\\012)</code>, <code>\\r (\\015)</code>, and
  * <code>\\r\\n (\\015\\012)</code> style newlines.
- * <br>
- * <br>
- * Reads in at most <b>n-1</b> characters from stream (the last spot is
- * reserved for the end-of-string NUL) and stores them into the buffer
- * pointed to by <b>buf</b>. Reading stops after an EOF or a newline.
- * New line is not stored in the buffer. At least <b>n</b> must be allocated
- * for the string buffer.<br>
+ * 
+ * 
+ * Reads in at most <i>n-1</i> characters from stream (the last spot
+ * is reserved for the end-of-string NUL) and stores them into the
+ * buffer pointed to by <i>buf</i>. Reading stops after an EOF or a
+ * newline.  New line is not stored in the buffer. At least <i>n</i>
+ * must be allocated for the string buffer.
  *
- * \param buf: string buffer to receive read data, at least <b>n</b> must
- *   be allocated
+ * \param buf: string buffer to receive read data, at least <i>n</i> must be allocated
  * \param n: maximum number of bytes to read
  * \param fd: file descriptor structure
- * \return 1 if ok, 0 if EOF
+ *
+ * \return 1 on success
+ * \return 0 EOF
  */
-
 int G_getl2(char *buf, int n, FILE * fd)
 {
     int i = 0;

lib/gis/gisbase.c

@@ -12,33 +12,32 @@
 
 
 /*!
- * \brief top level module directory
+ * \brief Get full path name of the top level module directory
  *
- * Returns the full
- * path name of the top level directory for GRASS programs.  This directory will
- * have subdirectories which will contain modules and files required for the
- * running of the system. Some of these directories are:
- \code
+ * Returns the full path name of the top level directory for GRASS
+ * programs. This directory will have subdirectories which will
+ * contain modules and files required for the running of the
+ * system. Some of these directories are:
+ 
+ \verbatim
  bin    commands run by the user
  etc    modules and data files used by GRASS commands
- txt    help files
- menu   files used by the <i>grass3</i> menu interface
- \endcode
- * The use of G_gisbase( ) to find these subdirectories enables GRASS modules 
- * to be written independently of where the GRASS system is actually installed 
- * on the machine. For example, to run the module <i>sroff</i> in the GRASS 
- * <i>etc</i> directory:
+ \endverbatim
+
+ * The use of G_gisbase() to find these subdirectories enables GRASS
+ * modules to be written independently of where the GRASS system is
+ * actually installed on the machine. For example, to run the module
+ * <i>sroff</i> in the GRASS <i>etc</i> directory:
+
  \code
  char command[200];
 
- sprintf (command, "%s/etc/sroff", G_gisbase( ) );
- G_spawn (command, "sroff", NULL);
+ sprintf(command, "%s/etc/sroff", G_gisbase());
+ G_spawn(command, "sroff", NULL);
  \endcode
  *
- *  \param void
- *  \return char * 
+ * \return pointer to a string
  */
-
 const char *G_gisbase(void)
 {
     return G_getenv("GISBASE");

lib/gis/gisdbase.c

@@ -1,9 +1,9 @@
 /*!
-   \file gisdbase.c
+   \file gis/gisdbase.c
 
    \brief GIS library - environment routines (gisdbase)
 
-   (C) 2001-2008 by the GRASS Development Team
+   (C) 2001-2009 by the GRASS Development Team
 
    This program is free software under the 
    GNU General Public License (>=v2). 
@@ -19,13 +19,10 @@
  * \brief Get name of top level database directory
  *
  * Returns the full UNIX path name of the directory which holds the
- * database locations. See GISDBASE for a full explanation of this
- * directory.
+ * database locations. 
  *
- *  \param
  *  \return pointer to string containing the base directory
  */
-
 const char *G_gisdbase(void)
 {
     return G_getenv("GISDBASE");

lib/gis/home.c

@@ -1,34 +1,30 @@
-/*
- ****************************************************************
- * char *
- * G_home ()
+/*!
+ * \file gis/home.c
  *
- *   returns char pointer to home directory for user
- *   dies if can't determine
+ * \brief GIS Library - Get user's home directory.
  *
- * char *
- * G__home()
+ * (C) 2001-2009 by the GRASS Development Team
  *
- *   returns char pointer to home directory for user
- *   NULL if can't determine
+ * 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
+ */
+
 #include <stdlib.h>
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
-
 /*!
- * \brief user's home directory
+ * \brief Get user's home directory
  *
- * Returns a pointer to a string
- * which is the full path name of the user's home directory.
+ * Returns a pointer to a string which is the full path name of the
+ * user's home directory.
  *
- *  \param ~
- *  \return char * 
+ * \return pointer to string
+ * \return NULL on error
  */
-
 const char *G_home(void)
 {
     const char *home = G__home();
@@ -36,10 +32,20 @@ const char *G_home(void)
     if (home)
 	return home;
 
-    G_fatal_error(_("unable to determine user's home directory"));
+    G_fatal_error(_("Unable to determine user's home directory"));
+    
     return NULL;
 }
 
+/*!
+ * \brief Get user's home directory
+ *
+ * Returns a pointer to a string which is the full path name of the
+ * user's home directory.
+ *
+ * \return pointer to string
+ * \return NULL on error
+ */
 const char *G__home(void)
 {
     static int initialized;

lib/gis/location.c

@@ -1,17 +1,17 @@
 /*!
-   \file location.c
-
-   \brief GIS library - environment routines (location)
-
-   (C) 2001-2008 by the GRASS Development Team
-
-   This program is free software under the 
-   GNU General Public License (>=v2). 
-   Read the file COPYING that comes with GRASS
-   for details.
-
-   \author Original author CERL
- */
+  \file gis/location.c
+  
+  \brief GIS library - environment routines (location)
+  
+  (C) 2001-2008 by the GRASS Development Team
+  
+  This program is free software under the 
+  GNU General Public License (>=v2). 
+  Read the file COPYING that comes with GRASS
+  for details.
+  
+  \author Original author CERL
+*/
 
 #include <stdio.h>
 #include <string.h>

lib/gis/mapset.c

@@ -1,33 +1,34 @@
-
-/**********************************************************************
- *
- *   char *
- *   G_mapset()
- *
- *   returns:    pointer to string containing the one word mapset
- *               name.
- *               NULL if user does not have access to mapset.
- *
- **********************************************************************/
+/*!
+  \file gis/mapset.c
+  
+  \brief GIS library - environment routines (mapset)
+  
+  (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
+ */
 
 #include <string.h>
 #include <stdlib.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
-
 /*!
- * \brief current mapset name
+ * \brief Get current mapset name
+ *
+ * Returns the name of the current mapset in the current
+ * location. This routine is often used when accessing files in the
+ * current mapset. See Mapsets for an explanation of mapsets.
  *
- * Returns the name of the
- * current mapset in the current location. This routine is often used when
- * accessing files in the current mapset. See Mapsets for an
- * explanation of mapsets.
+ * G_fatal_error() is called on error.
  *
- *  \param void
- *  \return char * 
+ * \return pointer mapset name
  */
-
 const char *G_mapset(void)
 {
     const char *m = G__mapset();
@@ -38,6 +39,12 @@ const char *G_mapset(void)
     return m;
 }
 
+/*!
+ * \brief Get current mapset name
+ *
+ * \return pointer mapset name
+ * \return NULL on error
+ */
 const char *G__mapset(void)
 {
     return G__getenv("MAPSET");

lib/gis/myname.c

@@ -1,35 +1,31 @@
-
-/**
- * \file myname.c
+/*!
+ * \file gis/myname.c
  *
  * \brief GIS Library - Database name functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
-
-/**
+/*!
  * \brief Returns location title.
  *
- * Returns a one line title for the database location. This title is 
- * read from the file MYNAME in the PERMANENT mapset. See also 
- * Permanent_Mapset for a discussion of the PERMANENT mapset.<br>
+ * Returns a one line title for the database location. This title is
+ * read from the file MYNAME in the PERMANENT mapset. See also \ref
+ * Permanent_Mapset for a discussion of the PERMANENT mapset.
  *
  * <b>Note:</b> This name is the first line in the file 
  * $GISDBASE/$LOCATION_NAME/PERMANENT/MYNAME
  *
- * \return Pointer to a string
+ * \return pointer to a string
  */
 
 char *G_myname(void)

lib/gis/nme_in_mps.c

@@ -1,34 +1,37 @@
 /*!
-   \file nme_in_mps.c
+  \file gis/nme_in_mps.c
 
-   \brief GIS Library - check map name
+  \brief GIS Library - check map name
 
-   (C) 2001-2008 by the GRASS Development Team
+  (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.
+  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
- */
+  \author Original author CERL
+*/
 
 #include <string.h>
 #include <grass/gis.h>
 
 /*!
-   \brief Check if map name is fully qualified (map @ mapset)
-
-   Note:
-   - <b>name</b> is char array of size GNAME_MAX
-   - <b>mapset</b> is char array of size GMAPSET_MAX
-
-   \param fullname full map name
-   \param[out] name map name
-   \param[out] mapset mapset name
-
-   \return 1 if input map name is fully qualified
-   \return 0 if input map name is not fully qualified
+  \brief Check if map name is fully qualified (map @ mapset)
+  
+  Returns a fully qualified name for the file <i>name</i> in
+  <i>mapset</i>. Currently this string is in the form
+  <i>name@mapset</i>, but the programmer should pretend not to know this
+  and always call this routine to get the fully qualified name.
+
+  Note:
+   - <i>name</i> is char array of size GNAME_MAX
+   - <i>mapset</i> is char array of size GMAPSET_MAX
+
+  \param fullname full map name
+  \param[out] name map name
+  \param[out] mapset mapset name
+  
+  \return 1 if input map name is fully qualified
+  \return 0 if input map name is not fully qualified
  */
 int G__name_is_fully_qualified(const char *fullname, char *name, char *mapset)
 {

lib/gis/open.c

@@ -1,9 +1,9 @@
 /*!
  * \file gis/open.c
  * 
- * \brief GIS Library - open file functions
+ * \brief GIS Library - Open file functions
  *
- * (C) 1999-2008 by the GRASS Development Team
+ * (C) 1999-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

lib/gis/parser.c

@@ -1,12 +1,12 @@
-
-/**
- * \file parser.c
+/*!
+ * \file gis/parser.c
  *
  * \brief GIS Library - Argument parsing functions.
  *
  * Parses the command line provided through argc and argv.  Example:
  * Assume the previous calls:
  *
+ * \code
  *  opt1 = G_define_option() ;
  *  opt1->key        = "map",
  *  opt1->type       = TYPE_STRING,
@@ -29,28 +29,37 @@
  *  opt3->answer     = "12345.67",
  *  opt3->options    = "0-99999",
  *  opt3->description= "Number to test parser" ;
+ * \endcode
  *
  * G_parser() will respond to the following command lines as described:
  *
+ * \verbatim
  * command      (No command line arguments)
+ * \endverbatim
  *    Parser enters interactive mode.
  *
+ * \verbatim
  * command map=map.name
+ * \endverbatim
  *    Parser will accept this line.  Map will be set to "map.name", the
  *    'a' and 'b' flags will remain off and the num option will be set
  *    to the default of 5.
  *
+ * \verbatim
  * command -ab map=map.name num=9
  * command -a -b map=map.name num=9
  * command -ab map.name num=9
  * command map.name num=9 -ab
  * command num=9 -a map=map.name -b
+ * \endverbatim
  *    These are all treated as acceptable and identical. Both flags are
  *    set to on, the map option is "map.name" and the num option is "9".
  *    Note that the "map=" may be omitted from the command line if it
  *    is part of the first option (flags do not count).
  *
+ * \verbatim
  * command num=12
+ * \endverbatim
  *    This command line is in error in two ways.  The user will be told 
  *    that the "map" option is required and also that the number 12 is
  *    out of range.  The acceptable range (or list) will be printed.
@@ -60,10 +69,7 @@
  * This program is free software under the GNU General Public License
  * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- * \author Radim Blazek
- *
- * \date 2003-2009
- *
+ * \author Original author CERL
  */
 
 #include <grass/config.h>
@@ -145,17 +151,15 @@ static void G_usage_xml(void);
 static void G_usage_html(void);
 static void G_script(void);
 
-
-/**
+/*!
  * \brief Disables the ability of the parser to operate interactively.
  *
- * When a user calls a command with no arguments on the command line, 
- * the parser will enter its own standardized interactive session in 
- * which all flags and options  are presented to the user for input. A 
- * call to <i>G_disable_interactive()</i> disables the parser's 
- * interactive prompting.
+ * When a user calls a command with no arguments on the command line,
+ * the parser will enter its own standardized interactive session in
+ * which all flags and options are presented to the user for input. A
+ * call to G_disable_interactive() disables the parser's interactive
+ * prompting.
  *
- * \return always returns 0
  */
 
 void G_disable_interactive(void)
@@ -163,20 +167,18 @@ void G_disable_interactive(void)
     st->no_interactive = 1;
 }
 
-
-/**
+/*!
  * \brief Initializes a Flag struct.
  *
- * Allocates memory for the Flag structure and returns a pointer to this 
- * memory (of <i>type struct Flag *</i>).<br>
+ * Allocates memory for the Flag structure and returns a pointer to
+ * this memory.
  *
- * Flags are always represented by single letters.  A user "turns them on"
- * at the command line using a minus sign followed by the character
- * representing the flag.
+ * Flags are always represented by single letters.  A user "turns them
+ * on" at the command line using a minus sign followed by the
+ * character representing the flag.
  *
- * \return Flag * Pointer to a Flag struct
+ * \return Pointer to a Flag struct
  */
-
 struct Flag *G_define_flag(void)
 {
     struct Flag *flag;
@@ -216,23 +218,21 @@ struct Flag *G_define_flag(void)
     return (flag);
 }
 
-
-/**
+/*!
  * \brief Initializes an Option struct.
  *
  * Allocates memory for the Option structure and returns a pointer to
- * this memory (of <i>type struct Option *</i>).<br>
+ * this memory.
  *
  * Options are provided by user on command line using the standard
- * format: <i>key=value</i>. Options identified as REQUIRED must be 
- * specified by user on command line. The option string can either 
- * specify a range of values (e.g. "10-100") or a list of acceptable 
- * values (e.g. "red,orange,yellow").  Unless the option string is NULL, 
- * user provided input will be evaluated agaist this string.
+ * format: <i>key=value</i>. Options identified as REQUIRED must be
+ * specified by user on command line. The option string can either
+ * specify a range of values (e.g. "10-100") or a list of acceptable
+ * values (e.g. "red,orange,yellow").  Unless the option string is
+ * NULL, user provided input will be evaluated agaist this string.
  *
- * \return Option * Pointer to an Option struct
+ * \return pointer to an Option struct
  */
-
 struct Option *G_define_option(void)
 {
     struct Option *opt;
@@ -286,14 +286,13 @@ struct Option *G_define_option(void)
     return (opt);
 }
 
-
-/**
+/*!
  * \brief Create standardised Option structure.
  *
- * This function will create a standardised Option structure
- * defined by parameter opt. A list of valid parameters can be found in gis.h.
- * It allocates memory for the Option structure and returns a pointer to
- * this memory (of <i>type struct Option *</i>).<br>
+ * This function will create a standardised Option structure defined
+ * by parameter opt. A list of valid parameters can be found in gis.h.
+ * It allocates memory for the Option structure and returns a pointer
+ * to this memory.
  *
  * If an invalid parameter was specified a empty Option structure will 
  * be returned (not NULL).
@@ -339,9 +338,9 @@ struct Option *G_define_option(void)
  *   - G_OPT_V_CAT
  *   - G_OPT_V_CATS
  *
- * \param[in] opt Type of Option struct to create
+ * \param opt type of Option struct to create
  *
- * \return Option * Pointer to an Option struct
+ * \return pointer to an Option struct
  */
 
 struct Option *G_define_standard_option(int opt)
@@ -690,12 +689,11 @@ struct Option *G_define_standard_option(int opt)
 }
 
 
-/**
+/*!
  * \brief Initializes a new module.
  *
- * \return GModule * Pointer to a GModule struct
+ * \return pointer to a GModule struct
  */
-
 struct GModule *G_define_module(void)
 {
     struct GModule *module;
@@ -711,43 +709,40 @@ struct GModule *G_define_module(void)
     return (module);
 }
 
-/* The main parsing routine */
-
-/**
+/*!
  * \brief Parse command line.
  *
- * The command line parameters <b>argv</b> and the number of parameters 
- * <b>argc</b> from the main() routine are passed directly to 
- * <i>G_parser()</i>. <i>G_parser()</i> accepts the command line input 
- * entered by the user, and parses this input according to the input 
- * options and/or flags that were defined by the programmer.<br>
+ * The command line parameters <i>argv</i> and the number of
+ * parameters <i>argc</i> from the main() routine are passed directly
+ * to G_parser(). G_parser() accepts the command line input entered by
+ * the user, and parses this input according to the input options
+ * and/or flags that were defined by the programmer.
  *
  * <b>Note:</b> The only functions which can legitimately be called 
- * before G_parser() are:<br>
- * <ul>
- *  <li>G_gisinit()</li>
- *  <li>G_no_gisinit()</li>
- *  <li>G_define_module()</li>
- *  <li>G_define_flag()</li>
- *  <li>G_define_option()</li>
- *  <li>G_define_standard_option()</li>
- *  <li>G_disable_interactive()</li>
- * </ul>
+ * before G_parser() are:
+ * 
+ *  - G_gisinit()
+ *  - G_no_gisinit()
+ *  - G_define_module()
+ *  - G_define_flag()
+ *  - G_define_option()
+ *  - G_define_standard_option()
+ *  - G_disable_interactive()
+ *
+ * The usual order a module calls functions is:
  *
- * The usual order a module calls functions is:<br>
- * <ul>
- *  <li>G_gisinit()</li>
- *  <li>G_define_module()</li>
- *  <li>G_define_{flag,option}()</li>
- *  <li>G_parser()</li>
- * </ul>
+ *  # G_gisinit()
+ *  # G_define_module()
+ *  # G_define_flag()
+ *  # G_define_option()
+ *  # G_parser()
+ *
+ * \param argc number of arguments
+ * \param argv argument list
  *
- * \param[in] argc number of arguments
- * \param[in] argv argument list
  * \return 0 on success
- * \return -1 on error and calls <b>G_usage()</b>
+ * \return -1 on error and calls G_usage()
  */
-
 int G_parser(int argc, char **argv)
 {
     int need_first_opt;
@@ -1025,29 +1020,26 @@ static int uses_new_gisprompt(void)
     return 0;
 }
 
-
-/**
+/*!
  * \brief Command line help/usage message.
  *
- * Calls to <i>G_usage()</i> allow the programmer to print the usage 
+ * Calls to G_usage() allow the programmer to print the usage 
  * message at any time. This will explain the allowed and required 
  * command line input to the user. This description is given according 
  * to the programmer's definitions for options and flags. This function 
  * becomes useful when the user enters options and/or flags on the 
  * command line that are syntactically valid to the parser, but 
- * functionally invalid for the command (e.g. an invalid file name.)<br>
- * For example, the parser logic doesn't directly support grouping 
- * options. If two options be specified together or not at all, the 
- * parser must be told that these options are not required and the 
- * programmer must check that if one is specified the other must be as 
- * well. If this additional check fails, then <i>G_parser()</i> will 
- * succeed, but the programmer can then call <i>G_usage()</i>  to print 
- * the standard usage message and print additional information about how 
- * the two options work together.
+ * functionally invalid for the command (e.g. an invalid file name.)
  *
- * \return
+ * For example, the parser logic doesn't directly support grouping
+ * options. If two options be specified together or not at all, the
+ * parser must be told that these options are not required and the
+ * programmer must check that if one is specified the other must be as
+ * well. If this additional check fails, then G_parser() will succeed,
+ * but the programmer can then call G_usage() to print the standard
+ * usage message and print additional information about how the two
+ * options work together.
  */
-
 void G_usage(void)
 {
     struct Option *opt;
@@ -1219,14 +1211,12 @@ void G_usage(void)
     }
 }
 
-
-/**
+/*!
  * \brief Formats text for XML.
  *
  * \param[in,out] fp file to write to
- * \param[in] str string to write
+ * \param str string to write
  */
-
 static void print_escaped_for_xml(FILE * fp, const char *str)
 {
     for (; *str; str++) {
@@ -1247,7 +1237,7 @@ static void print_escaped_for_xml(FILE * fp, const char *str)
 }
 
 
-/**
+/*!
  * \brief Format text for HTML output
  */
 #define do_escape(c,escaped) case c: fputs(escaped,f);break
@@ -1269,9 +1259,9 @@ static void print_escaped_for_html(FILE * f, const char *str)
 
 #undef do_escape
 
-/**
-   \brief Print module usage description in XML format.
-**/
+/*!
+  \brief Print module usage description in XML format.
+*/
 static void G_usage_xml(void)
 {
     struct Option *opt;
@@ -1507,9 +1497,9 @@ static void G_usage_xml(void)
     fprintf(stdout, "</task>\n");
 }
 
-/**
-   \brief Print module usage description in HTML format.
-**/
+/*!
+  \brief Print module usage description in HTML format.
+*/
 static void G_usage_html(void)
 {
     struct Option *opt;
@@ -1735,9 +1725,9 @@ static void G_usage_html(void)
     fprintf(stdout, "</body>\n</html>\n");
 }
 
-/**
-   \brief Print a module parameter template to assist with creating shell script wrappers.
-**/
+/*!
+  \brief Print a module parameter template to assist with creating shell script wrappers.
+*/
 static void G_script(void)
 {
     FILE *fp = stdout;
@@ -1852,9 +1842,9 @@ static void G_script(void)
 	    "fi\n" "\n" "# CODE GOES HERE\n" "\n");
 }
 
-/**
-   \brief Build wxPython GUI dialog
-**/
+/*!
+  \brief Build wxPython GUI dialog.
+*/
 static void G_gui_wx(void)
 {
     char script[GPATH_MAX];
@@ -1869,13 +1859,13 @@ static void G_gui_wx(void)
     G_spawn(getenv("GRASS_PYTHON"), "menuform.py", script, st->pgm_name, NULL);
 }
 
-/**
-   \brief Invoke GUI dialog 
+/*!
+  \brief Invoke GUI dialog 
 
-   Use G_gui_wx() to generate GUI dialog.
+  Use G_gui_wx() to generate GUI dialog.
 
-   G_gui_wx() is called by default (if GRASS_GUI is not defined)
-**/
+  G_gui_wx() is called by default (if GRASS_GUI is not defined)
+*/
 static void G_gui(void)
 {
     G_gui_wx();
@@ -2442,13 +2432,13 @@ static void split_gisprompt(const char *gisprompt, char *age, char *element,
     *ptr2 = '\0';
 }
 
-/**
+/*!
  * \brief Creates command to run non-interactive.
  *
  * Creates a command-line that runs the current command completely
  * non-interactive.
  *
- * \return char * Pointer to a char string
+ * \return pointer to a char string
  */
 char *G_recreate_command(void)
 {

lib/gis/plot.c

@@ -1,5 +1,8 @@
-
-/*****************************************************************
+/*
+ * \file gis/plot.c
+ *
+ * \brief GIS Library - Plotting functions.
+ *
  * Plot lines and filled polygons. Input space is database window.
  * Output space and output functions are user defined.
  * Converts input east,north lines and polygons to output x,y
@@ -12,7 +15,15 @@
  *
  * Note:
  *  Hopefully, cartographic style projection plotting will be added later.
- *******************************************************************/
+ *
+ * (C) 2001-2008 by the GRASS Development Team
+ *
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
+ *
+ * \author Original author CERL
+ */
+
 #include <stdlib.h>
 #include <math.h>
 #include <grass/gis.h>
@@ -54,57 +65,32 @@ static struct state {
 
 static struct state *st = &state;
 
-/*!
- * \brief returns east larger than west
- *
- * If the region projection is
- * PROJECTION_LL, then this routine returns an equivalent <b>east</b> that is
- * larger, but no more than 360 degrees larger, than the coordinate for the
- * western edge of the region. Otherwise no adjustment is made and the original
- * <b>east</b> is returned.
- *
- *  \param east
- *  \param region
- *  \return double
- */
-
-/*
- * G_setup_plot (t, b, l, r, Move, Cont)
- *     double t, b, l, r;
- *     int (*Move)(), (*Cont)();
- *
- * initialize the plotting capability.
- *    t,b,l,r:   top, bottom, left, right of the output x,y coordinate space.
- *    Move,Cont: subroutines that will draw lines in x,y space.
- *       Move(x,y)   move to x,y (no draw)
- *       Cont(x,y)   draw from previous position to x,y
- * Notes:
- *   Cont() is responsible for clipping.
- *   The t,b,l,r are only used to compute coordinate transformations.
- *   The input space is assumed to be the current GRASS window.
- */
+#define OK            0
+#define TOO_FEW_EDGES 2
+#define NO_MEMORY     1
+#define OUT_OF_SYNC  -1
 
 /*!
- * \brief initialize plotting routines
+ * \brief Initialize plotting routines
  *
- * Initializes the plotting
- * capability. This routine must be called once before calling the
- * <b>G_plot_*(~)</b> routines described below.
- * The parameters <b>t, b, l, r</b> are the top, bottom, left, and right of the
- * output x,y coordinate space. They are not integers, but doubles to allow for
- * subpixel registration of the input and output coordinate spaces. The input
- * coordinate space is assumed to be the current GRASS region, and the routines
- * supports both planimetric and latitude- longitude coordinate systems.
+ * Initializes the plotting capability. This routine must be called
+ * once before calling the G_plot_*() routines described below.  The
+ * parameters <i>t, b, l, r</i> are the top, bottom, left, and right
+ * of the output x,y coordinate space. They are not integers, but
+ * doubles to allow for subpixel registration of the input and output
+ * coordinate spaces. The input coordinate space is assumed to be the
+ * current GRASS region, and the routines supports both planimetric
+ * and latitude-longitude coordinate systems.
+
  * <b>Move</b> and <b>Cont</b> are subroutines that will draw lines in x,y
  * space. They will be called as follows:
- * Move(x, y) move to x,y (no draw)
- * Cont(x, y) draw from previous position
- * to x,y. Cont(~) is responsible for clipping
+ * - Move(x, y) move to x,y (no draw)
+ * - Cont(x, y) draw from previous position to x,y. Cont(~) is responsible for clipping
  *
- *  \param ~
- *  \return
+ * \param t,b,l,r top, bottom, left, right
+ * \param move Move function
+ * \param Cont Cont function
  */
-
 void G_setup_plot(double t, double b, double l, double r,
 		  int (*Move) (int, int), int (*Cont) (int, int))
 {
@@ -132,15 +118,14 @@ void G_setup_plot(double t, double b, double l, double r,
 }
 
 /*!
- * \brief set row_fill routine to row_solid_fill or row_dotted_fill
+ * \brief Set row_fill routine to row_solid_fill or row_dotted_fill
  *
- * After calling this function, <b>G_plot_polygon()</b> and
- * <b>G_plot_area()</b> fill shapes with solid or dotted lines.  If gap is
- * greater than zero, this value will be used for row_dotted_fill.  Otherwise,
+ * After calling this function, G_plot_polygon() and G_plot_area()
+ * fill shapes with solid or dotted lines. If gap is greater than
+ * zero, this value will be used for row_dotted_fill.  Otherwise,
  * row_solid_fill is used.
  *
- *  \param int
- *  \return
+ * \param gap
  */
 void G_setup_fill(int gap)
 {
@@ -160,36 +145,32 @@ void G_setup_fill(int gap)
 
 
 /*!
- * \brief east,north to x,y
+ * \brief Converts east,north to x,y
  *
- * The map coordinates <b>east,north</b> are converted
- * to pixel coordinates <b>x,y.</b>
+ * The map coordinates <i>east,north</i> are converted
+ * to pixel coordinates <i>x,y</i>.
  *
- *  \param east
- *  \param north
- *  \param x
- *  \param y
- *  \return
+ * \param east easting
+ * \param north nothing
+ * \param x x coordinate
+ * \param y y coordinate
  */
-
 void G_plot_where_xy(double east, double north, int *x, int *y)
 {
     *x = ifloor(X(G_adjust_easting(east, &st->window)) + 0.5);
     *y = ifloor(Y(north) + 0.5);
 }
 
-
 /*!
- * \brief x,y to east,north
+ * \brief Converts x,y to east,north
  *
- * The pixel coordinates <b>x,y</b> are converted to map
- * coordinates <b>east,north.</b>
+ * The pixel coordinates <i>x,y</i> are converted to map
+ * coordinates <i>east,north</i>.
  *
- *  \param x
- *  \param y
- *  \param east
- *  \param north
- *  \return
+ * \param x x coordinate
+ * \param y y coordinate
+ * \param east easting
+ * \param north northing
  */
 
 void G_plot_where_en(int x, int y, double *east, double *north)
@@ -198,6 +179,12 @@ void G_plot_where_en(int x, int y, double *east, double *north)
     *north = NORTH(y);
 }
 
+/*!
+  \brief Plot point
+
+  \param east easting
+  \param north northing
+*/
 void G_plot_point(double east, double north)
 {
     int x, y;
@@ -207,32 +194,31 @@ void G_plot_point(double east, double north)
     st->cont(x, y);
 }
 
-/*
- * Line in map coordinates is plotted in output x,y coordinates
- * This routine handles global wrap-around for lat-long databses.
- *
- */
-
 /*!
- * \brief plot line between latlon coordinates
+ * \brief Plot line between latlon coordinates (fastline)
  *
- * A line from <b>east1,north1</b>
- * to <b>east2,north2</b> is plotted in output x,y coordinates (e.g. pixels for
- * graphics.) This routine handles global wrap-around for latitude-longitude
- * databases.
+ * A line from <i>east1,north1</i> to <i>east2,north2</i> is plotted
+ * in output x,y coordinates (e.g. pixels for graphics.) This routine
+ * handles global wrap-around for latitude-longitude databases.
  *
- *  \param east1
- *  \param north1
- *  \param east2
- *  \param north2
- *  \return
+ * \param east1, north1 first point (start line node)
+ * \param east2, north2 second point (end line node)
  */
-
 void G_plot_line(double east1, double north1, double east2, double north2)
 {
     plot_line(east1, north1, east2, north2, fastline);
 }
 
+/*!
+ * \brief Plot line between latlon coordinates (slowline)
+ *
+ * A line from <i>east1,north1</i> to <i>east2,north2</i> is plotted
+ * in output x,y coordinates (e.g. pixels for graphics.) This routine
+ * handles global wrap-around for latitude-longitude databases.
+ *
+ * \param east1, north1 first point (start line node)
+ * \param east2, north2 second point (end line node)
+ */
 void G_plot_line2(double east1, double north1, double east2, double north2)
 {
     plot_line(east1, north1, east2, north2, slowline);
@@ -241,7 +227,6 @@ void G_plot_line2(double east1, double north1, double east2, double north2)
 /* fastline converts double rows/cols to ints then plots
  * this is ok for graphics, but not the best for vector to raster
  */
-
 static void fastline(double x1, double y1, double x2, double y2)
 {
     st->move(ifloor(x1 + 0.5), ifloor(y1 + 0.5));
@@ -359,24 +344,6 @@ static void plot_line(double east1, double north1, double east2, double north2,
     }
 }
 
-/*
- * G_plot_polygon (x, y, n)
- * 
- *    double *x       x coordinates of vertices
- *    double *y       y coordinates of vertices
- *    int n           number of verticies
- *
- * polygon fill from map coordinate space to plot x,y space.
- * for lat-lon, handles global wrap-around as well as polar polygons.
- *
- * returns 0 ok, 2 n<3, -1 weird internal error, 1 no memory
- */
-
-#define OK 0
-#define TOO_FEW_EDGES 2
-#define NO_MEMORY 1
-#define OUT_OF_SYNC -1
-
 static double nearest(double e0, double e1)
 {
     while (e0 - e1 > 180)
@@ -389,17 +356,20 @@ static double nearest(double e0, double e1)
 
 
 /*!
- * \brief plot filled polygon with n vertices
+ * \brief Plot filled polygon with n vertices
+ *
+ * The polygon, described by the <i>n</i> vertices
+ * <i>east,north</i>, is plotted in the output x,y space as a filled polygon.
  *
- * The polygon, described by the <b>n</b> vertices
- * <b>east,north</b>, is plotted in the output x,y space as a filled polygon.
+ * \param x coordinates of vertices
+ * \param y coordinates of vertices
+ * \param n number of verticies
  *
- *  \param east
- *  \param north
- *  \param n
- *  \return int
+ * \return 0 on success
+ * \return 2 n < 3
+ * \return -1 weird internal error
+ * \return 1 no memory
  */
-
 int G_plot_polygon(const double *x, const double *y, int n)
 {
     int i;
@@ -507,32 +477,24 @@ int G_plot_polygon(const double *x, const double *y, int n)
     return OK;
 }
 
-/*
- * G_plot_area (xs, ys, rpnts, rings)
- *      double **xs;  -- pointer to pointer for X's
- *      double **ys;  -- pointer to pointer for Y's
- *      int *rpnts;   -- array of ints w/ num points per ring
- *      int rings;    -- number of rings
- *
- * Essentially a copy of G_plot_polygon, with minor mods to
- * handle a set of polygons.  return values are the same.
- */
-
 /*!
- * \brief plot multiple polygons
+ * \brief Plot multiple polygons
  *
- * Like G_plot_polygon, except it takes a set of polygons,
- * each with \textbf{npts[<i>i</i>]} vertices, where the number of polygons 
- * is specified with the <b>rings</b> argument.  It is especially useful for 
+ * Like G_plot_polygon(), except it takes a set of polygons, each with
+ * npts[<i>i</i>] vertices, where the number of polygons is specified
+ * with the <i>rings</i> argument. It is especially useful for
  * plotting vector areas with interior islands.
  *
- *  \param xs
- *  \param ys
- *  \param npts
- *  \param rings
- *  \return int
+ * \param xs pointer to pointer for X's
+ * \param ys pointer to pointer for Y's
+ * \param rpnts array of ints w/ num points per ring
+ * \param rings number of rings
+ *
+ * \return 0 on success
+ * \return 2 n < 3
+ * \return -1 weird internal error
+ * \return 1 no memory
  */
-
 int G_plot_area(double *const *xs, double *const *ys, int *rpnts, int rings)
 {
     int i, j, n;
@@ -783,24 +745,17 @@ static int iceil(double x)
     return i;
 }
 
-/*
- * G_plot_fx(e1,e2)
- *
- * plot f(x) from x=e1 to x=e2
- */
-
-
 /*!
- * \brief plot f(east1) to f(east2)
+ * \brief Plot f(east1) to f(east2)
  *
- * The function <b>f(east)</b> is plotted from
- * <b>east1</b> to <b>east2.</b> The function <b>f(east)</b> must return
- * the map northing coordinate associated with east.
+ * The function <i>f(east)</i> is plotted from <i>east1</i> to
+ * <i>east2</i>. The function <i>f(east)</i> must return the map
+ * northing coordinate associated with east.
  *
- *  \param ~
- *  \return int
+ * \param f plotting function
+ * \param east1 easting (first point)
+ * \param east2 easting (second point)
  */
-
 void G_plot_fx(double (*f) (double), double east1, double east2)
 {
     double east, north, north1;

lib/gis/pole_in_poly.c

@@ -1,40 +1,37 @@
-#include <grass/gis.h>
+/*!
+  \file gis/pole_in_poly.c
 
-/**********************************************************
- * G_pole_in_polygon(x, y, n)
- *     double *x, *y, n;
- *
- * For lat-lon coordinates, this routine determines if the polygon
- * defined by the n verticies x,y contain one of the poles
- *
- * returns
- *  -1 if it contains the south pole,
- *   1 if it contains the north pole,
- *   0 no pole
- *
- * Note: don't use this routine if the projection isn't PROJECTION_LL
- *       no check is made by this routine for valid projection
- ***********************************************************/
+  \brief GIS Library - Pole in polygon
+  
+  (C) 2001-2009 by the GRASS Development Team
 
-static void mystats(double, double, double, double, double *, double *);
+  This program is free software under the GNU General Public License
+  (>=v2).  Read the file COPYING that comes with GRASS for details.
 
+  \author CERL
+ */
+
+#include <grass/gis.h>
+
+static void mystats(double, double, double, double, double *, double *);
 
 /*!
- * \brief pole in polygon
+ * \brief Check if pole is in polygon
  *
  * For latitude-longitude coordinates, this routine determines if the polygon
- * defined by the <b>n</b> coordinate vertices <b>x,y</b> contains one of the
+ * defined by the <i>n</i> coordinate vertices <i>x,y</i> contains one of the
  * poles.
- * Returns -1 if it contains the south pole; 1 if it contains the north pole; 0
- * if it contains neither pole.
- * <b>Note.</b> Use this routine only if the projection is PROJECTION_LL.
  *
- *  \param x
- *  \param y
- *  \param n
- *  \return int
+ * <b>Note:</b> Use this routine only if the projection is PROJECTION_LL.
+ *
+ *  \param x array of x coordinates
+ *  \param y array of y coordinates
+ *  \param n number of coordinates
+ * 
+ * \return -1 if it contains the south pole
+ * \return 1 if it contains the north pole
+ * \return 0 if it contains neither pole.
  */
-
 int G_pole_in_polygon(const double *x, const double *y, int n)
 {
     int i;

lib/gis/proj1.c

@@ -1,15 +1,15 @@
 /*!
-  \file proj1.c
-
-  \brief GIS Library - Get projection info
-  
-  (C) 1999-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
-*/
+  \file gis/proj1.c
+ *
+ * \brief GIS Library - Projection support
+ *
+ * (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
+ */
 
 #include <grass/gis.h>
 
@@ -18,7 +18,6 @@
   
   This routine returns a code indicating the projection for the active region.  The current
   values are:
-
    - PROJECTION_XY  0 - x,y (Raw imagery)
    - PROJECTION_UTM 1 - UTM   Universal Transverse Mercator
    - PROJECTION_SP  2 - State Plane (in feet)

lib/gis/proj2.c

@@ -1,6 +1,26 @@
+/*!
+  \file gis/proj2.c
+
+  \brief GIS Library - Projection support
+  
+  (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
+ */
+
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
+/*!
+  \brief Get units code
+
+  \param n project code
+
+  \retun units code
+*/
 int G__projection_units(int n)
 {
     switch (n) {
@@ -17,6 +37,14 @@ int G__projection_units(int n)
     }
 }
 
+/*!
+  \brief Get units name
+
+  \param unit units code
+  \param plural plural form
+
+  \return units name
+*/
 const char *G__unit_name(int unit, int plural)
 {
     switch (unit) {
@@ -33,6 +61,13 @@ const char *G__unit_name(int unit, int plural)
     }
 }
 
+/*!
+  \brief Get projection name
+  
+  \param n projection code
+
+  \return projection name
+*/
 const char *G__projection_name(int n)
 {
     switch (n) {

lib/gis/proj3.c

@@ -1,3 +1,16 @@
+/*!
+  \file gis/proj3.c
+
+  \brief GIS Library - Projection support
+  
+  (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
+ */
+
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
@@ -22,16 +35,16 @@ static void init(void)
 }
 
 /*!
- * \brief database units
+ * \brief Get database units
  *
- * Returns a
- * string describing the database grid units. It returns a plural form (eg. feet)
- * if <b>plural</b> is true. Otherwise it returns a singular form (eg. foot).
+ * Returns a string describing the database grid units. It returns a
+ * plural form (eg. feet) if <i>plural</i> is true. Otherwise it
+ * returns a singular form (eg. foot).
  *
- *  \param plural
- *  \return char * 
+ * \param plural plural form if true
+ *
+ * \return units name
  */
-
 const char *G_database_unit_name(int plural)
 {
     int n;
@@ -54,16 +67,14 @@ const char *G_database_unit_name(int plural)
 
 
 /*!
- * \brief query cartographic projection
+ * \brief Query cartographic projection
  *
  * Returns a pointer to a string which is a printable name for
- * projection code <b>proj</b> (as returned by <i>G_projection</i>). Returns
- * NULL if <b>proj</b> is not a valid projection.
+ * projection code <i>proj</i> (as returned by G_projection). Returns
+ * NULL if <i>proj</i> is not a valid projection.
  *
- *  \param proj
- *  \return char * 
+ * \return projection name
  */
-
 const char *G_database_projection_name(void)
 {
     int n;
@@ -84,18 +95,15 @@ const char *G_database_projection_name(void)
     return name;
 }
 
-
 /*!
- * \brief conversion to meters
+ * \brief Conversion to meters
  *
  * Returns a factor which converts the grid unit to meters (by
- * multiplication).  If the database is not metric (eg. imagery) then 0.0 is
- * returned.
+ * multiplication). If the database is not metric (eg. imagery) then
+ * 0.0 is returned.
  *
- *  \param void
- *  \return double
+ * \return value
  */
-
 double G_database_units_to_meters_factor(void)
 {
     const char *unit;
@@ -130,26 +138,16 @@ double G_database_units_to_meters_factor(void)
     return factor;
 }
 
-/***********************************************************************
- * G_database_datum_name(void)
- *
- * return name of datum of current database
- *
- * returns pointer to valid name if ok
- * NULL otherwise
- ***********************************************************************/
-
-
 /*!
- * \brief get datum name for database
+ * \brief Get datum name for database
  *
- * Returns a pointer to the name of the map datum of the current database. If 
- * there is no map datum explicitely associated with the acutal database, the 
- * standard map datum WGS84 is returned, on error a NULL pointer is returned. 
+ * Returns a pointer to the name of the map datum of the current
+ * database. If there is no map datum explicitely associated with the
+ * acutal database, the standard map datum WGS84 is returned, on error
+ * a NULL pointer is returned.
  *
- *  \return char * 
+ * \return datum name
  */
-
 const char *G_database_datum_name(void)
 {
     const char *name;
@@ -170,15 +168,12 @@ const char *G_database_datum_name(void)
 	return NULL;
 }
 
-/***********************************************************************
- * G_database_ellipse_name(void)
- *
- * return name of ellipsoid of current database
- *
- * returns pointer to valid name if ok
- * NULL otherwise
- ***********************************************************************/
-
+/*!
+  \brief Get ellipsoid name of current database
+  
+  \return pointer to valid name if ok
+  \return NULL on error
+*/
 const char *G_database_ellipse_name(void)
 {
     const char *name;

lib/gis/put_window.c

@@ -1,34 +1,35 @@
-/*
- **********************************************************************
- *
- * G_put_window (window)
- *      write the current mapset window
- **********************************************************************
- *
- * G__put_window (window, dir, name)
- *      write the window 'name' in 'mapset'
- *      returns -1  error
- *               1  ok
- *********************************************************************/
+/*!
+  \file gis/put_window.c
+
+  \brief GIS Library - Modify window (i.e. GRASS region)
+
+  (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
+*/
 
 #include <stdlib.h>
 #include <grass/gis.h>
 
 /*!
- * \brief write the database region
+ * \brief Write the database region
  *
  * Writes the database region file (WIND) in the user's current mapset
- * from <b>region.</b> Returns 1 if the region is written ok. Returns -1 if not
- * (no diagnostic message is printed).
- * <b>Warning.</b> Since this routine actually changes the database region, it
- * should only be called by modules which the user knows will change the region.
- * It is probably fair to say that under GRASS 3.0 only the <i>g.region</i>,
- * and <i>d.zoom</i> modules should call this routine.
+ * from region. 
+
+ * <b>Warning:</b> Since this routine actually changes the database
+ * region, it should only be called by modules which the user knows
+ * will change the region. It is probably fair to say that only the
+ * <tt>g.region</tt>.
+ *
+ * \param[in,out] window pointer to Cell_head
  *
- *  \param region
- *  \return int
+ * \return 1 on success
+ * \return -1 on error (no diagnostic message is printed)
  */
-
 int G_put_window(const struct Cell_head *window)
 {
     char *wind = getenv("WIND_OVERRIDE");
@@ -37,6 +38,24 @@ int G_put_window(const struct Cell_head *window)
 	: G__put_window(window, "", "WIND");
 }
 
+/*!
+ * \brief Write the database region
+ *
+ * Writes the database region file (WIND) in the user's current mapset
+ * from region. 
+
+ * <b>Warning:</b> Since this routine actually changes the database
+ * region, it should only be called by modules which the user knows
+ * will change the region. It is probably fair to say that only the
+ * <tt>g.region</tt>.
+ *
+ * \param[in,out] window pointer to Cell_head
+ * \param dir directory name
+ * \param name file name
+ *
+ * \return 1 on success
+ * \return -1 on error (no diagnostic message is printed)
+ */
 int G__put_window(const struct Cell_head *window, const char *dir, const char *name)
 {
     FILE *fd;

lib/gis/radii.c

@@ -1,75 +1,82 @@
-/* TODO: 
-
-   Suggestion: all "lon"s in the file "radii.c" should read as "lat"
-
-   Comments:
-   on page http://www.mentorsoftwareinc.com/cc/gistips/TIPS0899.HTM
-   down where it says "Meridional Radius of Curvature" is the exact formula
-   out of "radii.c".
-   Quote: "essentially, the radius of curvature, at a specific latitude ...".
-
-   See also http://williams.best.vwh.net/ellipsoid/node1.html which has a nice
-   picture showning the parametric latitude and phi, the geodetic latitude.
-   On the next page,
-   http://williams.best.vwh.net/ellipsoid/node2.html, in equation 3, the
-   Meridional Radius of Curvature shows up.
-
-   So, it looks like you are calculating the Meridional Radius of Curvature
-   as a function of GEODETIC LATITUDE.
- */
-
-#include <math.h>
-#include <grass/gis.h>
-#include "pi.h"
-
+/*!
+  \file gis/radii.c
+
+  \brief GIS Library - Calculating the Meridional Radius of Curvature
+  
+  \todo Suggestion: all "lon"s in the file "radii.c" should read as "lat"
+  
+  Comments:
+  on page http://www.mentorsoftwareinc.com/cc/gistips/TIPS0899.HTM
+  down where it says "Meridional Radius of Curvature" is the exact formula
+  out of "radii.c".
+  Quote: "essentially, the radius of curvature, at a specific latitude ...".
+  
+  See also http://williams.best.vwh.net/ellipsoid/node1.html which has a nice
+  picture showning the parametric latitude and phi, the geodetic latitude.
+  On the next page,
+  http://williams.best.vwh.net/ellipsoid/node2.html, in equation 3, the
+  Meridional Radius of Curvature shows up.
+  
+  So, it looks like you are calculating the Meridional Radius of Curvature
+  as a function of GEODETIC LATITUDE.
 
-/****************************************************************
  Various formulas for the ellipsoid.
  Reference: Map Projections by Peter Richardus and Ron K. Alder
 	    University of Illinois Library Call Number: 526.8 R39m
  Parameters are:
-    lon = longitude of the meridian
-    a   = ellipsoid semi-major axis
-    e2  = ellipsoid eccentricity squared
+  - lon = longitude of the meridian
+  - a   = ellipsoid semi-major axis
+  - e2  = ellipsoid eccentricity squared
 
 
   meridional radius of curvature (p. 16)
+  \verbatim
                         2
                a ( 1 - e )
        M = ------------------
                  2   2    3/2
            (1 - e sin lon)
-
+  \endverbatim
   transverse radius of curvature (p. 16)
-
+  \verbatim
                     a
        N = ------------------
                  2   2    1/2
            (1 - e sin lon)
-
+  \endverbatim
   radius of the tangent sphere onto which angles are mapped
   conformally (p. 24)
-
+  \verbatim
        R = sqrt ( N * M )
+  \endverbatim
+  
+  (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 CERL
+ */
+
+#include <math.h>
+#include <grass/gis.h>
+#include "pi.h"
 
 /*!
- * \brief meridional radius of curvature
+ * \brief Meridional radius of curvature
+ *
+ * Returns the meridional radius of curvature at a given longitude:
  *
- * Returns the meridional radius of
- * curvature at a given longitude:
  \f$
  \rho = \frac{a (1-e^2)}{(1-e^2\sin^2 lon)^{3/2}}
  \f$
- * 
  *
- *  \param lon
- *  \param a
- *  \param e2
- *  \return double
+ *  \param lon longitude
+ *  \param a ellipsoid semi-major axis
+ *  \param e2 ellipsoid eccentricity squared
+ *
+ *  \return radius value
  */
-
 double G_meridional_radius_of_curvature(double lon, double a, double e2)
 {
     double x;
@@ -81,24 +88,21 @@ double G_meridional_radius_of_curvature(double lon, double a, double e2)
     return a * (1 - e2) / (x * sqrt(x));
 }
 
-
-
 /*!
- * \brief transverse radius of curvature
+ * \brief Transverse radius of curvature
+ *
+ * Returns the transverse radius of curvature at a given longitude:
  *
- * Returns the transverse radius of
- * curvature at a given longitude:
  \f$
  \nu = \frac{a}{(1-e^2\sin^2 lon)^{1/2}}
  \f$
  * 
+ *  \param lon longitude
+ *  \param a ellipsoid semi-major axis
+ *  \param e2 ellipsoid eccentricity squared
  *
- *  \param lon
- *  \param a
- *  \param e2
- *  \return double
+ *  \return radius value
  */
-
 double G_transverse_radius_of_curvature(double lon, double a, double e2)
 {
     double x;
@@ -110,23 +114,22 @@ double G_transverse_radius_of_curvature(double lon, double a, double e2)
     return a / sqrt(x);
 }
 
-
 /*!
- * \brief radius of conformal tangent sphere
+ * \brief Radius of conformal tangent sphere
+ *
+ * Returns the radius of the conformal sphere tangent to ellipsoid at
+ * a given longitude:
  *
- * Returns the radius of the
- * conformal sphere tangent to ellipsoid at a given longitude:
  \f$
  r = \frac{a (1-e^2)^{1/2}}{(1-e^2\sin^2 lon)}
  \f$
  * 
+ *  \param lon longitude
+ *  \param a ellipsoid semi-major axis
+ *  \param e2 ellipsoid eccentricity squared
  *
- *  \param lon
- *  \param a
- *  \param e2
- *  \return double
+ *  \return radius value
  */
-
 double G_radius_of_conformal_tangent_sphere(double lon, double a, double e2)
 {
     double x;

lib/gis/remove.c

@@ -1,17 +1,14 @@
-
-/**
- * \file remove.c
+/*!
+ * \file gis/remove.c
  *
  * \brief GIS Library - File remove functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <grass/config.h>
@@ -28,18 +25,19 @@ static int recursive_remove(const char *path);
 static int G__remove(int misc, const char *dir, const char *element,
 		     const char *name);
 
-/**
+/*!
  * \brief Remove a database file.
  *
- * The file or directory <b>name</b> under the database <b>element</b> directory
- * in the current mapset is removed.<br>
+ * The file or directory <i>name</i> under the database <i>element</i>
+ * directory in the current mapset is removed.
  * 
- * <b>Note:</b> If <b>name</b> is a directory, everything within the
- * directory is removed as well.
+ * If <i>name</i> is a directory, everything within the directory is
+ * removed as well.
  *
- * \param[in] element element name
- * \param[in] name file nane
- * \return 0 if <b>name</b> does not exist
+ * \param element element name
+ * \param name file name
+ *
+ * \return 0 if <i>name</i> does not exist
  * \return 1 if successful
  * \return -1 on error
  */
@@ -49,18 +47,19 @@ int G_remove(const char *element, const char *name)
     return G__remove(0, NULL, element, name);
 }
 
-/**
+/*!
  * \brief Remove a database misc file.
  *
- * The file or directory <b>name</b> under the database <b>element</b> directory
- * in the current mapset is removed.<br>
+ * The file or directory <i>name</i> under the database <i>element</i>
+ * directory in the current mapset is removed.
  * 
- * <b>Note:</b> If <b>name</b> is a directory, everything within the
- * directory is removed as well.
+ * If <i>name</i> is a directory, everything within the directory is
+ * removed as well.
+ *
+ * \param element element name
+ * \param name file name
  *
- * \param[in] element element name
- * \param[in] name file name
- * \return 0 if <b>name</b> does not exist
+ * \return 0 if <i>name</i> does not exist
  * \return 1 if successful
  * \return -1 on error
  */

lib/gis/rename.c

@@ -1,17 +1,14 @@
-
-/**
- * \file rename.c
+/*!
+ * \file gis/rename.c
  *
  * \brief GIS Library - Rename file functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2006
+ * \author Original author CERL
  */
 
 #include <stdio.h>
@@ -21,17 +18,17 @@
 #include <grass/gis.h>
 
 
-/**
- **\brief Rename a file in the filesystem.
- **
- **The file or directory <b>oldname</b> is renamed to <b>newname</b>.<br>
- **
- ** \param[in] oldname
- ** \param[in] newname
- ** \return 0 if successful
- ** \return -1 on error
- **/
+/*!
+  \brief Rename a file in the filesystem.
+  
+  The file or directory <i>oldname</i> is renamed to <i>newname</i>.
 
+  \param oldname current name
+  \param newname new name
+  
+  \return 0 if successful
+  \return -1 on error
+*/
 int G_rename_file(const char *oldname, const char *newname)
 {
 
@@ -42,28 +39,28 @@ int G_rename_file(const char *oldname, const char *newname)
     return rename(oldname, newname);
 }
 
-/**
- * \brief Rename a database file.
- *
- * The file or directory <b>oldname</b> under the database <b>element</b>
- * directory in the current mapset is renamed to <b>newname</b>.<br>
- *
- * <b>Bug:</b> This routine does not check to see if the <b>newname</b> 
- * name is a valid database file name.
- *
- * \param[in] element
- * \param[in] oldname
- * \param[in] newname
- * \return 0 if <b>oldname</b> does not exist
- * \return 1 if successful
- * \return -1 on error
- */
+/*!
+  \brief Rename a database file.
+
+  The file or directory <i>oldname</i> under the database <i>element</i>
+  directory in the current mapset is renamed to <i>newname</i>.
+
+  \bug This routine does not check to see if the <i>newname</i> 
+  name is a valid database file name.
+
+  \param element element name
+  \param oldname current name
+  \param newname new name
 
+  \return 0 if <i>oldname</i> does not exist
+  \return 1 if successful
+  \return -1 on error
+*/
 int G_rename(const char *element, const char *oldname, const char *newname)
 {
     const char *mapset;
     char xname[GNAME_MAX], xmapset[GMAPSET_MAX];
-    char from[512], to[512];
+    char from[GPATH_MAX], to[GPATH_MAX];
 
     /* name in mapset legal only if mapset is current mapset */
     mapset = G_mapset();

lib/gis/set_window.c

@@ -1,31 +1,27 @@
-
-/**
- * \file set_window.c
+/*!
+ * \file gis/set_window.c
  *
- * \brief Set window
+ * \brief GIS Library - Set window (map region)
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2007
+ * \author Original author CERL
  */
 
 #include <grass/gis.h>
 #include <grass/glocale.h>
 #include "G.h"
 
-/**
- * \brief Get the current working window.
+/*!
+ * \brief Get the current working window (region)
  *
  * The current working window values are returned in the structure
- * 'window'.
+ * <i>window</i>.
  *
- * \param[out] window window structure to be set
- * \return
+ * \param[in,out] window window structure to be set
  */
 void G_get_set_window(struct Cell_head *window)
 {
@@ -34,12 +30,12 @@ void G_get_set_window(struct Cell_head *window)
 }
 
 
-/**
+/*!
  * \brief Establishes 'window' as the current working window.
  * 
  * Any opened cell files has its file-to-window mapping reworked.
  *
- * \param[in] window window to become operative window
+ * \param window window to become operative window
  * 
  * \return -1 on error
  * \return  1 on success
@@ -129,9 +125,8 @@ int G_set_window(struct Cell_head *window)
 	fcb->min_null_row = (-1) * NULL_ROWS_INMEM;
 	if(fcb->null_cur_row > 0)
 	{
-	    G_warning(
-		"Calling G_set_window() in the middle of writing map %s", 
-		fcb->name);
+	  G_warning(_("Calling G_set_window() in the middle of writing map %s"), 
+		    fcb->name);
 	    fcb->null_cur_row = 0;
 	}
 #endif

lib/gis/short_way.c

@@ -1,33 +1,28 @@
-
-/**
- * \file short_way.c
+/*!
+ * \file gis/short_way.c
  *
  * \brief GIS Library - Shortest path functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <grass/gis.h>
 
-
-/**
+/*!
  * \brief Shortest way between two eastings.
  *
- * For lat-lon projection (<i>PROJECTION_LL</i>), <b>east1</b>, 
- * <b>east2</b> are changed so that they are no more than 180 degrees 
+ * For lat-lon projection (<tt>PROJECTION_LL</tt>), <i>east1</i>, 
+ * <i>east2</i> are changed so that they are no more than 180 degrees 
  * apart. Their true locations are not changed. For all other 
  * projections, this function does nothing.
  *
- * \param[in] east1 east (x) coordinate of first point
- * \param[in] east2 east (x) coordinate of second point
- * \return
+ * \param[in,out] east1 east (x) coordinate of first point
+ * \param[in,out] east2 east (x) coordinate of second point
  */
 
 void G_shortest_way(double *east1, double *east2)

lib/gis/strings.c

@@ -65,7 +65,7 @@ int G_strcasecmp(const char *x, const char *y)
     return 0;
 }
 
-/**
+/*!
  * \brief Copy string to allocated memory.
  *
  * This routine allocates enough memory to hold the string <b>s</b>,
@@ -323,7 +323,7 @@ int G_str_to_sql(char *str)
     return count;
 }
 
-/**
+/*!
  * \brief Remove superfluous white space.
  *
  * Leading and trailing white space is removed from the string 

lib/gis/system.c

@@ -1,17 +1,14 @@
-
-/**
- * \file system.c
+/*!
+ * \file gis/system.c
  *
  * \brief GIS Library - Command execution functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <grass/config.h>
@@ -27,7 +24,7 @@
 #include <grass/glocale.h>
 
 
-/**
+/*!
  * \brief Run a shell level command.
  *
  * This is essentially the UNIX <i>system()</i> call, except for the 
@@ -43,11 +40,11 @@
  * parent and the command being run, set them yourself and use
  * the UNIX <i>system()</i> call instead.
  *
- * \param[in] command
+ * \param command
+ *
  * \return -1 on error
  * \return status on success
  */
-
 int G_system(const char *command)
 {
     int status;
@@ -82,7 +79,7 @@ int G_system(const char *command)
     }
 
     if (pid < 0) {
-	G_warning(_("Can not create a new process!"));
+	G_warning(_("Unable to create a new process!"));
 	status = -1;
     }
     else {

lib/gis/tempfile.c

@@ -1,17 +1,14 @@
-
-/**
- * \file tempfile.c
+/*!
+ * \file gis/tempfile.c
  *
  * \brief GIS Library - Temporary file functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <string.h>
@@ -22,6 +19,9 @@
 static struct Counter unique;
 static int initialized;
 
+/*!
+  \brief Initialize environment for creating tempfiles.
+*/
 void G_init_tempfile(void)
 {
     if (G_is_initialized(&initialized))
@@ -32,44 +32,42 @@ void G_init_tempfile(void)
     G_initialize_done(&initialized);
 }
 
-/**
+/*!
  * \brief Returns a temporary file name.
  *
  * This routine returns a pointer to a string containing a unique 
  * temporary file name that can be used as a temporary file within the 
- * module. Successive calls to <i>G_tempfile()</i> will generate new 
+ * module. Successive calls to G_tempfile() will generate new 
  * names. Only the file name is generated. The file itself is not 
  * created. To create the file, the module must use standard UNIX 
  * functions which create and open files, e.g., <i>creat()</i> or 
- * <i>fopen()</i>.<br>
+ * <i>fopen()</i>.
  *
  * Successive calls will generate different names the names are of the 
  * form pid.n where pid is the programs process id number and n is a 
- * unique identifier.<br>
+ * unique identifier.
  *
  * <b>Note:</b> It is recommended to <i>unlink()</i> (remove) the 
  * temp file on exit/error. Only if GRASS is left with 'exit', the GIS 
- * mapset manangement will clean up the temp directory (ETC/clean_temp).
+ * mapset management will clean up the temp directory (ETC/clean_temp).
  *
  * \return pointer to a character string containing the name. The name 
  * is copied to allocated memory and may be released by the unix free() 
  * routine.
  */
-
 char *G_tempfile(void)
 {
     return G__tempfile(getpid());
 }
 
-/**
+/*!
  * \brief Create tempfile from process id.
  *
- * See <i>G_tempfile()</i>.
+ * See G_tempfile().
  *
- * \param[in] pid
- * \return Pointer to string path
+ * \param pid
+ * \return pointer to string path
  */
-
 char *G__tempfile(int pid)
 {
     char path[GPATH_MAX];
@@ -91,14 +89,11 @@ char *G__tempfile(int pid)
     return G_store(path);
 }
 
-
-/**
- * \brief Populates <b>element</b> with a path string.
+/*!
+ * \brief Populates element with a path string.
  *
- * \param[in,out] element
- * \return
+ * \param[out] element element name
  */
-
 void G__temp_element(char *element)
 {
     const char *machine;

lib/gis/trim_dec.c

@@ -1,31 +1,25 @@
-
-/**
+/*!
  * \file trim_dec.c
  *
  * \brief GIS Library - Trim string decimal functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <grass/gis.h>
 
-
-/**
+/*!
  * \brief Removes trailing zeros from decimal number.
  *
  * Example: 23.45000 would come back as 23.45
  *
  * \param[in,out] buf
- * \return
  */
-
 void G_trim_decimal(char *buf)
 {
     char *mark;

lib/gis/wind_format.c

@@ -1,38 +1,31 @@
-
-/**
- * \file wind_format.c
+/*!
+ * \file gis/wind_format.c
  *
  * \brief GIS Library - Window formatting functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <stdio.h>
 #include <grass/gis.h>
 
-
 static void format_double(double, char *);
 
-
-/**
+/*!
  * \brief Northing to ASCII.
  *
- * Converts the double representation of the <b>north</b> coordinate to 
- * its ASCII representation (into <b>buf</b>).
+ * Converts the double representation of the <i>north</i> coordinate to 
+ * its ASCII representation (into <i>buf</i>).
  *
- * \param[in] north northing
- * \param[in,out] buf buffer to hold formatted string
- * \param[in] projection
- * \return
+ * \param north northing
+ * \param[out] buf buffer to hold formatted string
+ * \param projection projection code
  */
-
 void G_format_northing(double north, char *buf, int projection)
 {
     if (projection == PROJECTION_LL)
@@ -41,19 +34,16 @@ void G_format_northing(double north, char *buf, int projection)
 	format_double(north, buf);
 }
 
-
-/**
+/*!
  * \brief Easting to ASCII.
  *
- * Converts the double representation of the <b>east</b> coordinate to
- * its ASCII representation (into <b>buf</b>).
+ * Converts the double representation of the <i>east</i> coordinate to
+ * its ASCII representation (into <i>buf</i>).
  *
- * \param[in] east easting
- * \param[in,out] buf buffer to hold formatted string
- * \param[in] projection
- * \return
+ * \param east easting
+ * \param[out] buf buffer to hold formatted string
+ * \param projection projection code
  */
-
 void G_format_easting(double east, char *buf, int projection)
 {
     if (projection == PROJECTION_LL)
@@ -62,19 +52,16 @@ void G_format_easting(double east, char *buf, int projection)
 	format_double(east, buf);
 }
 
-
-/**
+/*!
  * \brief Resolution to ASCII.
  *
- * Converts the double representation of the <b>resolution</b> to its 
- * ASCII representation (into <b>buf</b>).
+ * Converts the double representation of the <i>resolution</i> to its 
+ * ASCII representation (into <i>buf</i>).
  *
- *  \param[in] resolution
- *  \param[in,out] buf buffer to hold formatted string
- *  \param[in] projection
- *  \return
+ * \param resolution resolution value
+ * \param[out] buf buffer to hold formatted string
+ * \param projection projection code
  */
-
 void G_format_resolution(double res, char *buf, int projection)
 {
     if (projection == PROJECTION_LL)

lib/gis/wind_scan.c

@@ -1,39 +1,34 @@
-
-/**
- * \file wind_scan.c
+/*!
+ * \file gis/wind_scan.c
  *
  * \brief GIS Library - Window scanning functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <stdio.h>
 #include <grass/gis.h>
 
-
 static int scan_double(const char *, double *);
 
-
-/**
+/*!
  * \brief ASCII northing to double.
  *
- * Converts the ASCII "northing" coordinate string in <b>buf</b> to its 
- * double representation (into <b>northing</b>).
+ * Converts the ASCII "northing" coordinate string in <i>buf</i> to its 
+ * double representation (into <i>northing</i>).
+ *
+ * \param buf buffer hold string northing
+ * \param[out] northing northing
+ * \param projection projection code
  *
- * \param[in] buf buffer hold string northing
- * \param[in,out] northing
- * \param[in] projection
  * \return 0 on error
  * \return 1 on success
  */
-
 int G_scan_northing(const char *buf, double *northing, int projection)
 {
     if (projection == PROJECTION_LL) {
@@ -48,20 +43,19 @@ int G_scan_northing(const char *buf, double *northing, int projection)
     return scan_double(buf, northing);
 }
 
-
-/**
+/*!
  * \brief ASCII easting to double.
  *
- * Converts the ASCII "easting" coordinate string in <b>buf</b> to its 
- * double representation (into <b>easting</b>).
+ * Converts the ASCII "easting" coordinate string in <i>buf</i> to its 
+ * double representation (into <i>easting</i>).
+ *
+ * \param buf buffer containing string easting
+ * \param[out] easting easting
+ * \param projection projection code
  *
- * \param[in] buf buffer containing string easting
- * \param[in,out] easting
- * \param[in] projection
  * \return 0 on error
  * \return 1 on success
  */
-
 int G_scan_easting(const char *buf, double *easting, int projection)
 {
     if (projection == PROJECTION_LL) {
@@ -80,20 +74,19 @@ int G_scan_easting(const char *buf, double *easting, int projection)
     return scan_double(buf, easting);
 }
 
-
-/**
+/*!
  * \brief ASCII resolution to double.
  *
- * Converts the ASCII "resolution" string in <b>buf</b> to its double 
+ * Converts the ASCII "resolution" string in <i>buf</i> to its double 
  * representation (into resolution).
  *
- * \param[in] buf buffer containing string resolution
- * \param[in,out] resolution
- * \param[in] projection
+ * \param buf buffer containing string resolution
+ * \param[out] resolution resolution value
+ * \param projection projection code
+ *
  * \return 0 on error
  * \return 1 on success
  */
-
 int G_scan_resolution(const char *buf, double *res, int projection)
 {
     if (projection == PROJECTION_LL) {
@@ -104,7 +97,6 @@ int G_scan_resolution(const char *buf, double *res, int projection)
     return (scan_double(buf, res) && *res > 0.0);
 }
 
-
 static int scan_double(const char *buf, double *value)
 {
     char junk[2];

lib/gis/window_map.c

@@ -1,17 +1,14 @@
-
-/**
+/*!
  * \file window_map.c
  *
  * \brief GIS Library - Window mapping functions.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (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 GRASS GIS Development Team
- *
- * \date 1999-2008
+ * \author Original author CERL
  */
 
 #include <stdlib.h>
@@ -22,17 +19,15 @@
 #define alloc_index(n) (COLUMN_MAPPING *) G_malloc((n)*sizeof(COLUMN_MAPPING))
 
 
-/**
+/*!
  * \brief Create window mapping.
  *
  * Creates mapping from cell header into window. The boundaries and 
  * resolution of the two spaces do not have to be the same or aligned in 
  * any way.
  *
- * \param[in] fd file descriptor
- * \return
+ * \param fd file descriptor
  */
-
 void G__create_window_mapping(int fd)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -112,16 +107,18 @@ void G__create_window_mapping(int fd)
 }
 
 
-/**
+/*!
  * \brief Northing to row.
  *
- * Converts a <b>north</b>ing relative to a <b>window</b> to a row.<br>
+ * Converts a <i>north</i>ing relative to a <i>window</i> to a row.
+
  * <b>Note:</b> The result is a double. Casting it to an integer will 
  * give the row number.
  *
- * \param[in] north
- * \param[in] window
- * \return row id
+ * \param north northing value
+ * \param window pointer to Cell_head
+ *
+ * \return row number
  */
 
 double G_northing_to_row(double north, const struct Cell_head *window)
@@ -130,20 +127,21 @@ double G_northing_to_row(double north, const struct Cell_head *window)
 }
 
 
-/**
+/*!
  * \brief Adjust east longitude.
  *
- * This routine returns an equivalent <b>east</b> that is
- * larger, but no more than 360 larger than the <b>west</b> 
- * coordinate.<br>
- * <b>Note:</b> This routine should be used only with latitude-longitude 
- * coordinates.
+ * This routine returns an equivalent <i>east</i> that is
+ * larger, but no more than 360 larger than the <i>west</i> 
+ * coordinate.
+
+ * <b>Note:</b> This routine should be used only with
+ * latitude-longitude coordinates.
+ *
+ * \param east east coordinate
+ * \param west west coordinate
  *
- * \param[in,out] east
- * \param[in] west
  * \return east coordinate
  */
-
 double G_adjust_east_longitude(double east, double west)
 {
     while (east > west + 360.0)
@@ -155,17 +153,18 @@ double G_adjust_east_longitude(double east, double west)
 }
 
 
-/**
+/*!
  * \brief Returns east larger than west.
  *
- * If the region projection is <i>PROJECTION_LL</i>, then this routine 
- * returns an equivalent <b>east</b> that is larger, but no more than 
+ * If the region projection is <tt>PROJECTION_LL</tt>, then this routine 
+ * returns an equivalent <i>east</i> that is larger, but no more than 
  * 360 degrees larger, than the coordinate for the western edge of the 
  * region. Otherwise no adjustment is made and the original
- * <b>east</b> is returned.
+ * <i>east</i> is returned.
+ *
+ * \param east east coordinate
+ * \param window pointer to Cell_head
  *
- * \param[in,out] east
- * \param[in] window
  * \return east coordinate
  */
 
@@ -180,17 +179,18 @@ double G_adjust_easting(double east, const struct Cell_head *window)
     return east;
 }
 
-
-/**
+/*!
  * \brief Easting to column.
  *
- * Converts <b>east</b> relative to a <b>window</b> to a column.<br>
+ * Converts <i>east</i> relative to a <i>window</i> to a column.
+
  * <b>Note:</b> The result is a <i>double</i>. Casting it to an 
  * <i>int</i> will give the column number.
  *
- * \param[in] east
- * \param[in] window
- * \return column id
+ * \param east east coordinate
+ * \param window pointer to Cell_head
+ *
+ * \return column number
  */
 
 double G_easting_to_col(double east, const struct Cell_head *window)
@@ -200,74 +200,72 @@ double G_easting_to_col(double east, const struct Cell_head *window)
     return (east - window->west) / window->ew_res;
 }
 
-
-/**
+/*!
  * \brief Row to northing.
  *
- * Converts a <b>row</b> relative to a <b>window</b> to a
- * northing.<br>
+ * Converts a <i>row</i> relative to a <i>window</i> to a
+ * northing.
+
  * <b>Note:</b> row is a double:
- *  - row+0.0 will return the northing for the northern edge of the row.<br>
- *  - row+0.5 will return the northing for the center of the row.<br>
- *  - row+1.0 will return the northing for the southern edge of the row.<br>
- * <b>Note:</b> The result is a <i>double</i>. Casting it to an 
+ *  - row+0.0 will return the northing for the northern edge of the row.
+ *  - row+0.5 will return the northing for the center of the row.
+ *  - row+1.0 will return the northing for the southern edge of the row.
+ *
+ * <b>Note:</b> The result is a <i>double</i>. Casting it to an
  * <i>int</i> will give the column number.
  *
- * \param[in] row
- * \param[in] window
+ * \param row row number
+ * \param[in] window pointer to Cell_head
+ *
  * \return north coordinate
  */
-
 double G_row_to_northing(double row, const struct Cell_head *window)
 {
     return window->north - row * window->ns_res;
 }
 
-
-/**
+/*!
  * \brief Column to easting.
  *
- * Converts a <b>col</b> relative to a <b>window</b> to an easting.<br>
- * <b>Note:</b> <b>col</b> is a <i>double</i>:<br>
- *  - col+0.0 will return the easting for the western edge of the column.<br>
- *  - col+0.5 will return the easting for the center of the column.<br>
- *  - col+1.0 will return the easting for the eastern edge of the column.<br>
+ * Converts a <i>col</i> relative to a <i>window</i> to an easting.
+ *
+ * <b>Note:</b> <i>col</i> is a <i>double</i>:
+ *  - col+0.0 will return the easting for the western edge of the column.
+ *  - col+0.5 will return the easting for the center of the column.
+ *  - col+1.0 will return the easting for the eastern edge of the column.
+ *
+ * \param col column number
+ * \param[in] window pointer to Cell_head
  *
- * \param[in] col
- * \param[in] window
  * \return east coordinate
  */
-
 double G_col_to_easting(double col, const struct Cell_head *window)
 {
     return window->west + col * window->ew_res;
 }
 
-
-/**
+/*!
  * \brief Number of rows in active window.
  *
  * This routine returns the number of rows in the active module window. 
  * Before raster files can be read or written, it is necessary to
- * known how many rows are in the active window. For example:<br>
+ * known how many rows are in the active window. For example:
  \code  
-  int nrows, cols;
-  int row, col; 
-  nrows = G_window_rows( ); 
-  ncols = G_window_cols( ); 
-  for (row = 0; row < nrows; row++)
-  {
-  <i>read</i> row ...
-  for (col = 0; col < ncols; col++)
-  {
-  process col ...
-  }
-  }
+int nrows, cols;
+int row, col;
+
+nrows = G_window_rows();
+ncols = G_window_cols();
+for (row = 0; row < nrows; row++) {
+    // read row ...
+    for (col = 0; col < ncols; col++) {
+        // process col ...
+    }
+}
  \endcode 
  *
- *  \return number of rows
+ * \return number of rows
  */
-
 int G_window_rows(void)
 {
     G__init_window();
@@ -275,32 +273,30 @@ int G_window_rows(void)
     return G__.window.rows;
 }
 
-
-/**
+/*!
  * \brief Number of columns in active window.
  *
- * These
- * routines return the number of rows and columns (respectively) in the active
- * module region. Before raster maps can be read or written, it is necessary to
- * known how many rows and columns are in the active region. For example:<br>
+ * These routines return the number of rows and columns (respectively)
+ * in the active module region. Before raster maps can be read or
+ * written, it is necessary to known how many rows and columns are in
+ * the active region. For example:
+ *
  \code  
-  int nrows, cols;
-  int row, col; 
-  nrows = G_window_rows( ); 
-  ncols = G_window_cols( ); 
-  for (row = 0; row < nrows; row++)
-  {
-  <i>read</i> row ...
-  for (col = 0; col < ncols; col++)
-  {
-  process col ...
-  }
-  }
+int nrows, cols;
+int row, col;
+
+nrows = G_window_rows();
+ncols = G_window_cols();
+for (row = 0; row < nrows; row++) {
+    // read row ...
+    for (col = 0; col < ncols; col++) {
+        // process col ...
+    }
+}
  \endcode 
  *
  * \return number of columns
  */
-
 int G_window_cols(void)
 {
     G__init_window();
@@ -308,13 +304,10 @@ int G_window_cols(void)
     return G__.window.cols;
 }
 
-
-/**
+/*!
  * \brief Initialize window.
  *
- * \return
  */
-
 void G__init_window(void)
 {
     if (G_is_initialized(&G__.window_set))
@@ -325,20 +318,19 @@ void G__init_window(void)
     G_initialize_done(&G__.window_set);
 }
 
-
-/**
+/*!
  * \brief Loops rows until mismatch?.
  *
- * This routine works fine if the mask is not set. It may give incorrect 
- * results with a mask, since the mask row may have a different repeat 
- * value. The issue can be fixed by doing it for the mask as well and 
- * using the smaller value.
+ * This routine works fine if the mask is not set. It may give
+ * incorrect results with a mask, since the mask row may have a
+ * different repeat value. The issue can be fixed by doing it for the
+ * mask as well and using the smaller value.
+ *
+ * \param fd file descriptor
+ * \param row starting row
  *
- * \param[in] fd file descriptor
- * \param[in] row starting row
  * \return number of rows completed
  */
-
 int G_row_repeat_nomask(int fd, int row)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];

lib/gis/zone.c

@@ -1,25 +1,22 @@
-
-/**
- * \file zone.c
+/*!
+ * \file gis/zone.c
  *
- * \brief Cartographic zone functions.
+ * \brief GIS Library - Cartographic zone functions.
  *
  * This program is free software under the GNU General Public License
  * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- * \author GRASS GIS Development Team
- *
- * \date 1999-2006
+ * \author Original author CERL
  */
 
 #include <grass/gis.h>
 
 
-/**
+/*!
  * \brief Query cartographic zone.
  *
- * This routine returns the zone for the active region. The meaning for 
- * the zone depends on the projection. For example, zone 18 for 
+ * This routine returns the zone for the active region. The meaning
+ * for the zone depends on the projection. For example, zone 18 for
  * projection type 1 would be UTM zone 18.
  *
  * \return int cartographic zone