major gislib.dox update (still not complete, https://trac.osgeo.org/grass/changeset/37744)

various minor doxygen fixes


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

lib/gis/adj_cellhd.c

@@ -1,45 +1,43 @@
-
-/**
- * \file adj_cellhd.c
+/*!
+ * \file gis/adj_cellhd.c
  *
  * \brief GIS Library - CELL header adjustment.
  *
- * (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>
 #include <grass/glocale.h>
 
-
-/**
+/*!
  * \brief Adjust cell header.
  *
- * This function fills in missing parts of the input
- * cell header (or region).  It also makes projection-specific adjustments. The
- * <b>cellhd</b> structure must have its <i>north, south, east, west</i>,
- * and <i>proj</i> fields set. 
+ * This function fills in missing parts of the input cell header (or
+ * region). It also makes projection-specific adjustments. The
+ * <i>cellhd</i> structure must have its <i>north, south, east,
+ * west</i>, and <i>proj</i> fields set.
  * 
- * If <b>row_flag</b> is true, then the north-south resolution is computed 
- * from the number of <i>rows</i> in the <b>cellhd</b> structure. Otherwise the number of 
- * <i>rows</i> is computed from the north-south resolution in the structure, similarly for
- * <b>col_flag</b> and the number of columns and the east-west resolution. 
+ * If <i>row_flag</i> is true, then the north-south resolution is
+ * computed from the number of <i>rows</i> in the <i>cellhd</i>
+ * structure. Otherwise the number of <i>rows</i> is computed from the
+ * north-south resolution in the structure, similarly for
+ * <i>col_flag</i> and the number of columns and the east-west
+ * resolution.
  *
  * <b>Note:</b> 3D values are not adjusted.
  *
- * \param[in,out] cellhd
- * \param[in] row_flag
- * \param[in] col_flag
+ * \param[in,out] cellhd pointer to Cell_head structure
+ * \param row_flag compute n-s resolution
+ * \param col_flag compute e-w resolution
+
  * \return NULL on success
- * \return Localized text string on error
+ * \return localized text string on error
  */
-
 const char *G_adjust_Cell_head(struct Cell_head *cellhd, int row_flag, int col_flag)
 {
     if (!row_flag) {
@@ -163,34 +161,33 @@ const char *G_adjust_Cell_head(struct Cell_head *cellhd, int row_flag, int col_f
     return NULL;
 }
 
-
-/**
+/*!
  * \brief Adjust cell header for 3D values.
  *
- * This function fills in missing parts of the input
- * cell header (or region).  It also makes projection-specific adjustments. The
- * <b>cellhd</b> structure must have its <i>north, south, east, west</i>,
- * and <i>proj</i> fields set. 
+ * This function fills in missing parts of the input cell header (or
+ * region).  It also makes projection-specific adjustments. The
+ * <i>cellhd</i> structure must have its <i>north, south, east,
+ * west</i>, and <i>proj</i> fields set.
  * 
- * If <b>row_flag</b> is true, then the north-south resolution is computed 
- * from the number of <i>rows</i> in the <b>cellhd</b> structure. 
+ * If <i>row_flag</i> is true, then the north-south resolution is computed 
+ * from the number of <i>rows</i> in the <i>cellhd</i> structure. 
  * Otherwise the number of <i>rows</i> is computed from the north-south 
- * resolution in the structure, similarly for <b>col_flag</b> and the 
+ * resolution in the structure, similarly for <i>col_flag</i> and the 
  * number of columns and the east-west resolution. 
  *
- * If <b>depth_flag</b> is true, top-bottom resolution is calculated 
+ * If <i>depth_flag</i> is true, top-bottom resolution is calculated 
  * from depths.
- * If <b>depth_flag</b> are false, number of depths is calculated from 
+ * If <i>depth_flag</i> are false, number of depths is calculated from 
  * top-bottom resolution.
  *
- * \param[in,out] cellhd
- * \param[in] row_flag
- * \param[in] col_flag
- * \param[in] depth_flag
+ * \param[in,out] cellhd pointer to Cell_head structure
+ * \param row_flag compute n-s resolution
+ * \param col_flag compute e-w resolution
+ * \param depth_flag compute t-b resolution
+ *
  * \return NULL on success
- * \return Localized text string on error
+ * \return localized text string on error
  */
-
 const char *G_adjust_Cell_head3(struct Cell_head *cellhd, int row_flag,
 				int col_flag, int depth_flag)
 {

lib/gis/alloc_cell.c

@@ -1,17 +1,14 @@
-
-/**
- * \file alloc_cell.c
+/*!
+ * \file gis/alloc_cell.c
  *
  * \brief GIS Library - Raster 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 <math.h>
@@ -23,16 +20,16 @@
 
 static const int type_size[3] = { sizeof(CELL), sizeof(FCELL), sizeof(DCELL) };
 
-
-/**
+/*!
  * \brief Returns size of a raster CELL in bytes.
  *
- * If <b>data_type</b> is CELL_TYPE, returns sizeof(CELL)
- * If <b>data_type</b> is FCELL_TYPE, returns sizeof(FCELL)
- * If <b>data_type</b> is DCELL_TYPE, returns sizeof(DCELL)
+ *  - If <i>data_type</i> is CELL_TYPE, returns sizeof(CELL)
+ *  - If <i>data_type</i> is FCELL_TYPE, returns sizeof(FCELL)
+ *  - If <i>data_type</i> is DCELL_TYPE, returns sizeof(DCELL)
+ *
+ * \param data_type raster type (CELL, FCELL, DCELL)
  *
- * \param[in] data_type
- * \return int
+ * \return raster type size
  */
 
 size_t G_raster_size(RASTER_MAP_TYPE data_type)
@@ -40,134 +37,124 @@ size_t G_raster_size(RASTER_MAP_TYPE data_type)
     return (type_size[F2I(data_type)]);
 }
 
-
-/**
+/*!
  * \brief Allocate memory for a CELL type raster map.
  *
  * This routine allocates a buffer of type CELL just large enough to 
  * hold one row of raster data based on the number of columns in the 
- * active region.<br>
+ * active region.
+ *
  \code
  CELL *cell;
- cell = G_allocate_cell_buf ();
+ cell = G_allocate_cell_buf();
  \endcode
- * If larger buffers are required, the routine <i>G_malloc</i> can be used.
- * The routine is generally used with each open cell file.<br>
- * <b>Note:</b> <i>G_allocate_raster_buf()</i> or 
- * <i>G_alloc_c_raster_buf()</i> is preferred over 
- * <i>G_allocate_cell_buf()</i>.
- *
- * \return CELL * Pointer to allocated buffer
- * \return Prints error message and calls <i>exit()</i> on error
+ *
+ * If larger buffers are required, the routine G_malloc() can be used.
+ * The routine is generally used with each open cell file.
+ *
+ * <b>Note:</b> G_allocate_raster_buf() or G_alloc_c_raster_buf() is
+ * preferred over G_allocate_cell_buf().
+ *
+ * Prints error message and calls exit() on error.
+ *
+ * \return CELL * pointer to allocated buffer
  */
-
 CELL *G_allocate_cell_buf(void)
 {
     return (CELL *) G_calloc(G_window_cols() + 1, sizeof(CELL));
 }
 
-
-/**
- * \brief Allocate memory for a raster map of type <b>data_type</b>.
+/*!
+ * \brief Allocate memory for a raster map of given type
  *
- * Allocate an array of CELL, FCELL, or DCELL (depending on 
- * <b>data_type</b>) based on the number of columns in the current 
+ * Allocate an array of CELL, FCELL, or DCELL (depending on
+ * <i>data_type</i>) based on the number of columns in the current
  * region.
  *
- * \param[in] data_type
- * \return void * 
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return pointer to allocated buffer
  */
-
 void *G_allocate_raster_buf(RASTER_MAP_TYPE data_type)
 {
     return (void *)G_calloc(G_window_cols() + 1, G_raster_size(data_type));
 }
 
-
-/**
+/*!
  * \brief Allocates memory for a raster map of type CELL.
  *
- * Allocate an array of CELL based on the number of columns in the 
+ * Allocate an array of CELL based on the number of columns in the
  * current region.
  *
- * \return CELL * 
+ * \return pointer to allocated buffer
  */
-
 CELL *G_allocate_c_raster_buf(void)
 {
     return (CELL *) G_calloc(G_window_cols() + 1, sizeof(CELL));
 }
 
-
-/**
+/*!
  * \brief Allocates memory for a raster map of type FCELL.
  *
  * Allocate an array of FCELL based on the number of columns in the 
  * current region.
  *
- * \return FCELL * 
+ * \return pointer to allocated buffer
  */
-
 FCELL *G_allocate_f_raster_buf(void)
 {
     return (FCELL *) G_calloc(G_window_cols() + 1, sizeof(FCELL));
 }
 
-
-/**
+/*!
  * \brief Allocates memory for a raster map of type DCELL.
  *
- * Allocate an array of DCELL based on the number of columns in the 
+ * Allocate an array of DCELL based on the number of columns in the
  * current region.
  *
- * \return DCELL * 
+ * \return pointer to allocated buffer
  */
-
 DCELL *G_allocate_d_raster_buf(void)
 {
     return (DCELL *) G_calloc(G_window_cols() + 1, sizeof(DCELL));
 }
 
-
-/**
+/*!
  * \brief Allocates memory for a null buffer.
  *
  * Allocate an array of char based on the number of columns in the 
  * current region.
  *
- * \return char * 
+ * \return pointer to allocated buffer
  */
-
 char *G_allocate_null_buf(void)
 {
     return (char *)G_calloc(G_window_cols() + 1, sizeof(char));
 }
 
-
-/**
+/*!
  * \brief Allocates memory for null bits.
  *
- * Allocates an array of unsigned char based on <b>cols</b>.
+ * Allocates an array of unsigned char based on <i>cols</i>.
  *
- * \param[in] cols number of columns in region
- * \return unsigned char *
+ * \param cols number of columns in region
+ * 
+ * \return pointer to allocated buffer
  */
-
 unsigned char *G__allocate_null_bits(int cols)
 {
     return (unsigned char *)G_calloc(G__null_bitstream_size(cols) + 1,
 				     sizeof(unsigned char));
 }
 
-
-/**
+/*!
  * \brief Determines null bitstream size.
  *
- * \param[in] cols number of columns
- * \return -1 if <b>cols</b> is invalid (<= 0)
+ * \param cols number of columns
+ *
+ * \return -1 if <i>cols</i> is invalid (<= 0)
  * \return size of null bistream
  */
-
 int G__null_bitstream_size(int cols)
 {
     if (cols <= 0)

lib/gis/cell_stats.c

@@ -1,3 +1,16 @@
+/*!
+ * \file gis/cell_stats.c
+ *
+ * \brief GIS Library - Raster cell statistics
+ *
+ * (C) 2001-2009 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 <stdlib.h>
 
@@ -11,26 +24,16 @@ static const int NCATS = 1 << SHIFT;
 static int next_node(struct Cell_stats *);
 static void init_node(NODE *, int, int);
 
-
 /*!
- * \brief initialize cell stats
+ * \brief Initialize cell stats
  *
- * This routine, which must be called first, initializes the Cell_stats
- * structure <b>s.</b>
- *
- *  \param s
- *  \return int
- */
-
-
-/*!
- * \brief 
+ * This routine, which must be called first, initializes the
+ * Cell_stats structure.
  *
  * Set the count for NULL-values to zero.
  *
- *  \return
+ * \param s pointer to Cell_stats structure
  */
-
 void G_init_cell_stats(struct Cell_stats *s)
 {
     s->N = 0;
@@ -39,29 +42,21 @@ void G_init_cell_stats(struct Cell_stats *s)
     s->null_data_count = 0;
 }
 
-
 /*!
- * \brief add data to cell stats
+ * \brief Sdd data to cell stats
  *
- * The <b>n</b> CELL values in the <b>data</b>
- * array are inserted (and counted) in the Cell_stats structure <b>s.</b>
+ * The <i>n</i> CELL values in the <i>data</i> array are inserted (and
+ * counted) in the Cell_stats structure.
  *
- *  \param data
- *  \param n
- *  \param s
- *  \return int
- */
-
-
-/*!
- * \brief 
+ * Look for NULLs and update the NULL-value count.
  *
- * Look for NULLs and update the
- * NULL-value count.
+ * \param cell raster values
+ * \param n number of values
+ * \param s pointer to Cell_stats structure which holds cell stats info
  *
- *  \return int
+ * \return 1 on failure
+ * \return 0 on success
  */
-
 int G_update_cell_stats(const CELL * cell, int n, struct Cell_stats *s)
 {
     CELL cat;
@@ -174,29 +169,22 @@ static void init_node(NODE * node, int idx, int offset)
 
 
 /*!
- * \brief random query of cell stats
+ * \brief Random query of cell stats
  *
- * This routine allows a random query of the
- * Cell_stats structure <b>s.</b>  The <b>count</b> associated with the
- * raster value <b>cat</b> is set. The routine returns 1 if <b>cat</b> was
- * found in the structure, 0 otherwise.
+ * This routine allows a random query of the Cell_stats structure. The
+ * <i>count</i> associated with the raster value <i>cat</i> is
+ * set. The routine returns 1 if <i>cat<i> was found in the
+ * structure, 0 otherwise.
  *
- *  \param cat
- *  \param count
- *  \param s
- *  \return int
- */
-
-
-/*!
- * \brief 
+ * Allow finding the count for the NULL-value.
  *
- * Allow finding the count for the
- * NULL-value
+ * \param cat raster value
+ * \param[out] count count
+ * \param s pointer to Cell_stats structure which holds cell stats info
  *
- *  \return int
+ * \return 1 if found
+ * \return 0 if not found
  */
-
 int G_find_cell_stat(CELL cat, long *count, const struct Cell_stats *s)
 {
     int q;
@@ -247,17 +235,16 @@ int G_find_cell_stat(CELL cat, long *count, const struct Cell_stats *s)
     return 0;
 }
 
-
 /*!
- * \brief reset/rewind cell stats
+ * \brief Reset/rewind cell stats
  *
- * The structure <b>s</b> is rewound (i.e., positioned at the first
+ * The structure <i>s</i> is rewound (i.e., positioned at the first
  * raster category) so that sorted sequential retrieval can begin.
  *
- *  \param s
- *  \return int
+ * \param s pointer to Cell_stats structure which holds cell stats info
+ *
+ * \return 0
  */
-
 int G_rewind_cell_stats(struct Cell_stats *s)
 {
     int q;
@@ -294,14 +281,12 @@ static int next_node(struct Cell_stats *s)
     return 1;
 }
 
-
 /*!
- * \brief retrieve sorted cell stats
+ * \brief Retrieve sorted cell stats
  *
- * Retrieves the next <b>cat,count</b>
- * combination from the structure <b>s.</b> Returns 0 if there are no more
- * items, non-zero if there are more.
- * For example:
+ * Retrieves the next <i>cat, count</i> combination from the
+ * structure. Returns 0 if there are no more items, non-zero if there
+ * are more. For example:
  * 
  \code
  struct Cell_stats s;
@@ -315,22 +300,15 @@ static int next_node(struct Cell_stats *s)
  fprintf(stdout, "%ld %ld\n", (long) cat, count);
  \endcode
  *
- *  \param cat
- *  \param count
- *  \param s
- *  \return int
- */
-
-
-/*!
- * \brief 
+ * Do not return a record for the NULL-value
  *
- * Do not return a record for the
- * NULL-value
+ * \param cat raster value
+ * \param[out] count
+ * \param s pointer to Cell_stats structure which holds cell stats info
  *
- *  \return int
+ * \return 0 if there are no more items
+ * \return non-zero if there are more
  */
-
 int G_next_cell_stat(CELL * cat, long *count, struct Cell_stats *s)
 {
     int idx;
@@ -377,34 +355,31 @@ int G_next_cell_stat(CELL * cat, long *count, struct Cell_stats *s)
 
 
 /*!
- * \brief 
+ * \brief Get number of null values.
  *
- * Get a number of null values from stats structure. Note: when reporting
- * values which appear in a map using G_next_cell_stats(), to get stats for
- * null, call G_get_stats_for_null_value() first, since
- * G_next_cell_stats() does not report stats for null.
+ * Get a number of null values from stats structure.
  *
- *  \param count
- *  \param s
- *  \return
+ * Note: when reporting values which appear in a map using
+ * G_next_cell_stats(), to get stats for null, call
+ * G_get_stats_for_null_value() first, since G_next_cell_stats() does
+ * not report stats for null.
+ *
+ * \param count count
+ * \param s pointer to Cell_stats structure which holds cell stats info
  */
-
 void G_get_stats_for_null_value(long *count, const struct Cell_stats *s)
 {
     *count = s->null_data_count;
 }
 
-
 /*!
- * \brief free cell stats
+ * \brief Free cell stats structure
  *
- * The memory associated with structure <b>s</b> is freed. This routine may be
- * called any time after calling<i>G_init_cell_stats.</i>
+ * The memory associated with structure <i>s</i> is freed. This
+ * routine may be called any time after calling G_init_cell_stats().
  *
- *  \param s
- *  \return
+ * \param s pointer to Cell_stats structure
  */
-
 void G_free_cell_stats(struct Cell_stats *s)
 {
     int i;

lib/gis/closecell.c

@@ -1,25 +1,16 @@
-
-/***********************************************************************
- *
- *   G_close_cell(fd)
- *      Closes and does housekeeping on an opened cell file
- *
- *   G_unopen_cell(fd)
- *      Closes and does housekeeping on an opened cell file
- *      without creating the cell file
- *
- *   parms:
- *      int fd     open cell file
+/*!
+ * \file gis/closecell.c
+ * 
+ * \brief GIS Library - Close raster file
  *
- *   returns:
- *      -1   on fail
- *       0   on success
+ * (C) 1999-2009 by the GRASS Development Team
  *
- *   note:
- *      On closing of a cell file that was open for writing, dummy cats
- *      and history files are created. Histogram and range info are written.
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
  *
- **********************************************************************/
+ * \author USACERL and many others
+ */
 
 #ifdef __MINGW32__
 #  include <windows.h>
@@ -45,37 +36,34 @@ static int close_new(int, int);
 static int write_fp_format(int fd);
 
 /*!
- * \brief close a raster map
+ * \brief Close a raster map
  *
- * The raster map
- * opened on file descriptor <b>fd</b> is closed. Memory allocated for raster
- * processing is freed. If open for writing, skeletal support files for the new
- * raster map are created as well.
- * <b>Note.</b> If a module wants to explicitly write support files (e.g., a
- * specific color table) for a raster map it creates, it must do so after the
- * raster map is closed. Otherwise the close will overwrite the support files.
- * See Raster_Map_Layer_Support_Routines for routines which write
- * raster support files.
+ * The raster map opened on file descriptor <i>fd</i> is
+ * closed. Memory allocated for raster processing is freed. If open
+ * for writing, skeletal support files for the new raster map are
+ * created as well.
  *
- *  \param fd
- *  \return int
- */
-
-
-/*!
- * \brief 
+ * <b>Note:</b> If a module wants to explicitly write support files
+ * (e.g., a specific color table) for a raster map it creates, it must
+ * do so after the raster map is closed. Otherwise the close will
+ * overwrite the support files. See \ref
+ * Raster_Map_Layer_Support_Routines for routines which write raster
+ * support files.
  *
- * If the map is a new floating point, move the
- * <tt>.tmp</tt> file into the <tt>fcell</tt> element, create an empty file in the
- * <tt>cell</tt> directory; write the floating-point range file; write a default
- * quantization file quantization file is set here to round fp numbers (this is
- * a default for now). create an empty category file, with max cat = max value
- * (for backwards compatibility). Move the <tt>.tmp</tt> NULL-value bitmap file to
- * the <tt>cell_misc</tt> directory.
+ * If the map is a new floating point, move the <tt>.tmp</tt> file
+ * into the <tt>fcell</tt> element, create an empty file in the
+ * <tt>cell</tt> directory; write the floating-point range file; write
+ * a default quantization file quantization file is set here to round
+ * fp numbers (this is a default for now). create an empty category
+ * file, with max cat = max value (for backwards compatibility). Move
+ * the <tt>.tmp</tt> NULL-value bitmap file to the <tt>cell_misc</tt>
+ * directory.
  *
- *  \return int
+ * \param fd file descriptor
+ *
+ * \return -1 on error
+ * \return 1 on success
  */
-
 int G_close_cell(int fd)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -88,27 +76,27 @@ int G_close_cell(int fd)
     return close_new(fd, 1);
 }
 
-
 /*!
- * \brief unopen a raster map
+ * \brief Unopen a raster map
+ *
+ * The raster map opened on file descriptor <i>fd</i> is
+ * closed. Memory allocated for raster processing is freed. If open
+ * for writing, the raster map is not created and the temporary file
+ * created when the raster map was opened is removed (see \ref
+ * Creating_and_Opening_New_Raster_Files). This routine is useful when
+ * errors are detected and it is desired to not create the new raster
+ * map. While it is true that the raster map will not be created if
+ * the module exits without closing the file, the temporary file will
+ * not be removed at module exit. GRASS database management will
+ * eventually remove the temporary file, but the file can be quite
+ * large and will take up disk space until GRASS does remove it. Use
+ * this routine as a courtesy to the user.
  *
- * The raster map
- * opened on file descriptor <b>fd</b> is closed. Memory allocated for raster
- * processing is freed. If open for writing, the raster map is not created and
- * the temporary file created when the raster map was opened is removed (see
- * Creating_and_Opening_New_Raster_Files).
- * This routine is useful when errors are detected and it is desired to not
- * create the new raster map. While it is true that the raster map will not be
- * created if the module exits without closing the file, the temporary file will
- * not be removed at module exit. GRASS database management will eventually
- * remove the temporary file, but the file can be quite large and will take up
- * disk space until GRASS does remove it. Use this routine as a courtesy to the
- * user.  
+ * \param fd file descriptor
  *
- *  \param fd
- *  \return int
+ * \return -1 on error
+ * \return 1 on success
  */
-
 int G_unopen_cell(int fd)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -383,7 +371,7 @@ static int close_new(int fd, int ok)
 	    close(null_fd);
 
 	    if (rename(fcb->null_temp_name, path)) {
-		G_warning(_("closecell: can't move %s\nto null file %s"),
+		G_warning(_("Unable to renae null file '%s'"),
 			  fcb->null_temp_name, path);
 		stat = -1;
 	    }
@@ -405,7 +393,7 @@ static int close_new(int fd, int ok)
 	    int cell_fd;
 
 	    if (write_fp_format(fd) != 0) {
-		G_warning(_("Error writing floating point format file for map %s"),
+		G_warning(_("Error writing floating point format file for map <%s>"),
 			  fcb->name);
 		stat = -1;
 	    }
@@ -453,7 +441,7 @@ static int close_new(int fd, int ok)
 	G__file_name(path, CELL_DIR, fcb->name, fcb->mapset);
 	remove(path);
 	if (rename(fcb->temp_name, path)) {
-	    G_warning(_("closecell: can't move %s\nto cell file %s"),
+	    G_warning(_("Unable to rename cell file '%s'"),
 		      fcb->temp_name, path);
 	    stat = -1;
 	}

lib/gis/color_compat.c

@@ -1,188 +1,313 @@
-
-/****************************************************************************
- *
- * MODULE:       gis library
- * AUTHOR(S):    Glynn Clements <glynn@gclements.plus.com>
- * COPYRIGHT:    (C) 2007 Glynn Clements and the GRASS Development Team
+/*!
+ * \file gis/color_compat.c
  *
- * NOTE:         Compatibility wrappers for G_make_*[_fp]_colors()
+ * \brief GIS Library - Predefined color tables
  *
- *  This program is free software; you can redistribute it and/or modify
- *  it under the terms of the GNU General Public License as published by
- *  the Free Software Foundation; either version 2 of the License, or
- *  (at your option) any later version.
+ * (C) 2007-2009 Glynn Clements and the GRASS Development Team
  *
- *  This program is distributed in the hope that it will be useful,
- *  but WITHOUT ANY WARRANTY; without even the implied warranty of
- *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- *  GNU General Public License for more details.
+ * This program is free software under the GNU General Public License 
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- *****************************************************************************/
+ * \author Glynn Clements <glynn@gclements.plus.com>
+ */
 
 #include <grass/gis.h>
 
-
 /*!
- * \brief make color wave
+ * \brief Make color wave (integer)
  *
- * Generates a color table with 3 sections: red only,
- * green only, and blue only, each increasing from none to full intensity and
- * back down to none.  This table is good for continuous data like elevation.
+ * Generates a color table with 3 sections: red only, green only, and
+ * blue only, each increasing from none to full intensity and back
+ * down to none. This table is good for continuous data like
+ * elevation.
  *
- *  \param colors
- *  \param min
- *  \param max
- *  \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
  */
-
 void G_make_wave_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "wave", min, max);
 }
 
+/*!
+ * \brief Make color wave (floating-point)
+ *
+ * Generates a color table with 3 sections: red only, green only, and
+ * blue only, each increasing from none to full intensity and back
+ * down to none. This table is good for continuous data like
+ * elevation.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_wave_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "wave", min, max);
 }
 
-
+/*!
+ * \brief Create RYG color table (integer)
+ *
+ * Generates a color table red-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_ryg_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "ryg", min, max);
 }
 
+/*!
+ * \brief Create RYG color table (floating-point)
+ *
+ * Generates a color table red-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_ryg_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "ryg", min, max);
 }
 
 /*!
- * \brief make color ramp
+ * \brief Make color ramp (integer)
  *
- * Generates a color table with 3 sections: red only,
- * green only, and blue only, each increasing from none to full intensity. This
- * table is good for continuous data, such as elevation.
+ * Generates a color table with 3 sections: red only, green only, and
+ * blue only, each increasing from none to full intensity. This table
+ * is good for continuous data, such as elevation.
  *
- *  \param colors
- *  \param min
- *  \param max
- *  \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
  */
-
 void G_make_ramp_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "ramp", min, max);
 }
 
+/*!
+ * \brief Make color ramp (floating-point)
+ *
+ * Generates a color table with 3 sections: red only, green only, and
+ * blue only, each increasing from none to full intensity. This table
+ * is good for continuous data, such as elevation.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_ramp_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "ramp", min, max);
 }
 
 /*!
- * \brief make rainbow colors
+ * \brief Make rainbow colors (integer)
  *
- * Generates a "shifted" rainbow color table - yellow
- * to green to cyan to blue to magenta to red. The color table is based on
- * rainbow colors. (Normal rainbow colors are red, orange, yellow, green, blue,
- * indigo, and violet.)  This table is good for continuous data, such as
- * elevation.
+ * Generates a "shifted" rainbow color table - yellow to green to cyan
+ * to blue to magenta to red. The color table is based on rainbow
+ * colors. (Normal rainbow colors are red, orange, yellow, green,
+ * blue, indigo, and violet.) This table is good for continuous data,
+ * such as elevation.
  *
- *  \param colors
- *  \param min
- *  \param max
- *  \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
  */
-
 void G_make_rainbow_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "rainbow", min, max);
 }
 
+/*!
+ * \brief Make rainbow colors (floating-point)
+ *
+ * Generates a "shifted" rainbow color table - yellow to green to cyan
+ * to blue to magenta to red. The color table is based on rainbow
+ * colors. (Normal rainbow colors are red, orange, yellow, green,
+ * blue, indigo, and violet.) This table is good for continuous data,
+ * such as elevation.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_rainbow_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "rainbow", min, max);
 }
 
-
+/*!
+ * \brief Create GYR color table (integer)
+ *
+ * Generates a color table green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_gyr_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "gyr", min, max);
 }
 
+/*!
+ * \brief Create GYR color table (floating-point)
+ *
+ * Generates a color table green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_gyr_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "gyr", min, max);
 }
 
 /*!
- * \brief make linear grey scale
+ * \brief Make linear grey scale (integer)
  *
- * Generates a grey scale color table. Each color
- * is a level of grey, increasing from black to white.
+ * Generates a grey scale color table. Each color is a level of grey,
+ * increasing from black to white.
  *
- *  \param colors
- *  \param min
- *  \param max
- *  \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
  */
-
 void G_make_grey_scale_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "grey", min, max);
 }
 
+/*!
+ * \brief Make linear grey scale (floating-point)
+ *
+ * Generates a grey scale color table. Each color is a level of grey,
+ * increasing from black to white.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_grey_scale_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "grey", min, max);
 }
 
+/*!
+ * \brief Create BYR color table (integer)
+ *
+ * Generates a color table blue-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_byr_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "byr", min, max);
 }
 
+/*!
+ * \brief Create BYR color table (floating-point)
+ *
+ * Generates a color table blue-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_byr_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "byr", min, max);
 }
 
+/*!
+ * \brief Create BGYR color table (integer)
+ *
+ * Generates a color table blue-green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_bgyr_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "bgyr", min, max);
 }
 
+/*!
+ * \brief Create BGYR color table (floating-point)
+ *
+ * Generates a color table blue-green-yellow-red.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_bgyr_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "bgyr", min, max);
 }
 
+/*!
+ * \brief Create BYG color table (integer)
+ *
+ * Generates a color table blue-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_byg_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "byg", min, max);
 }
 
+/*!
+ * \brief Create BYG color table (floating-point)
+ *
+ * Generates a color table blue-yellow-green.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_byg_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "byg", min, max);
 }
 
 /*!
- * \brief make aspect colors
+ * \brief Make aspect colors (integer)
  *
  * Generates a color table for aspect data.
  *
- *  \param colors
- *  \param min
- *  \param max
- *  \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
  */
-
 void G_make_aspect_colors(struct Colors *colors, CELL min, CELL max)
 {
     G_make_colors(colors, "aspect", min, max);
 }
 
+/*!
+ * \brief Make aspect colors (floating-point)
+ *
+ * Generates a color table for aspect data.
+ *
+ * \param colors pointer to Colors structure which holds color info
+ * \param min minimum value
+ * \param max maximum value
+ */
 void G_make_aspect_fp_colors(struct Colors *colors, DCELL min, DCELL max)
 {
     G_make_fp_colors(colors, "aspect", min, max);

lib/gis/color_free.c

@@ -1,30 +1,43 @@
+/*!
+ * \file gis/color_free.c
+ *
+ * \brief GIS Library - Free Colors structure
+ *
+ * (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 free color structure memory
+ * \brief Free color structure memory
  *
- * The dynamically allocated memory associated with the <b>colors</b>
+ * The dynamically allocated memory associated with the <i>colors</i>
  * structure is freed.
- * <b>Note.</b> This routine may be used after <i>G_read_colors</i> as
- * well as after <i>G_init_colors.</i>
  *
- *  \param colors
- *  \return
+ * <b>Note:</b> This routine may be used after G_read_colors() as well
+ * as after G_init_colors().
+ *
+ * \param colors pointer to Colors structure
  */
-
 void G_free_colors(struct Colors *colors)
 {
     G__color_reset(colors);
     G_init_colors(colors);
 }
 
-/*******************************************
- * G__color* routines only to be used by other routines in this
- * library
- *******************************************/
+/*!
+  \brief Free color rules structure
+
+  Note: Only for internal use.
 
+  \param cp pointer to _Color_Info structure
+*/
 void G__color_free_rules(struct _Color_Info_ *cp)
 {
     struct _Color_Rule_ *rule, *next;
@@ -36,6 +49,13 @@ void G__color_free_rules(struct _Color_Info_ *cp)
     cp->rules = NULL;
 }
 
+/*!
+  \brief Free color rules structure
+
+  Note: Only for internal use.
+
+  \param cp pointer to _Color_Info structure
+*/
 void G__color_free_lookup(struct _Color_Info_ *cp)
 {
     if (cp->lookup.active) {
@@ -47,6 +67,13 @@ void G__color_free_lookup(struct _Color_Info_ *cp)
     }
 }
 
+/*!
+  \brief Free color rules structure
+
+  Note: Only for internal use.
+
+  \param cp pointer to _Color_Info structure
+*/
 void G__color_free_fp_lookup(struct _Color_Info_ *cp)
 {
     if (cp->fp_lookup.active) {
@@ -57,6 +84,15 @@ void G__color_free_fp_lookup(struct _Color_Info_ *cp)
     }
 }
 
+/*!
+  \brief Reset colors structure
+
+  Note: Only for internal use.
+
+  This routine should NOT init the colors.
+
+  \param colors pointer to Colors structure
+*/
 void G__color_reset(struct Colors *colors)
 {
     G__color_free_lookup(&colors->fixed);
@@ -64,5 +100,4 @@ void G__color_reset(struct Colors *colors)
     G__color_free_rules(&colors->fixed);
     G__color_free_rules(&colors->modular);
     colors->version = 0;
-    /* this routine should NOT init the colors */
 }

lib/gis/color_get.c

@@ -1,38 +1,37 @@
-
-/**
- * \file color_get.c
+/*!
+ * \file gis/color_get.c
  *
- * \brief GIS Library - Functions to get colors from a raster map.
+ * \brief GIS Library - Get colors from a raster map.
  *
- * (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 Get a category color.
  *
- * The <b>red, green</b>, and
- * <b>blue</b> intensities for the color associated with category <b>n</b>
- * are extracted from the <b>colors</b> structure. The intensities will be in
- * the range 0 ­- 255.  Also works for null cells.
- *
- *  \param[in] n CELL to get color from
- *  \param[out] red red value
- *  \param[out] grn green value
- *  \param[out] blu blue value
- *  \param[in] colors Colors struct
- *  \return int
+ * \todo To be removed, replaced by G_get_raster_color().
+ *
+ * The <i>red, green</i>, and <i>blue</i> intensities for the color
+ * associated with category <i>n</i> are extracted from the
+ * <i>colors</i> structure. The intensities will be in the range 0 ­-
+ * 255. Also works for null cells.
+ *
+ * \param n cell to get color from
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
  */
-
 int G_get_color(CELL n, int *red, int *grn, int *blu, struct Colors *colors)
 {
     CELL cat;
@@ -48,22 +47,22 @@ int G_get_color(CELL n, int *red, int *grn, int *blu, struct Colors *colors)
     return (int)set;
 }
 
-
-/**
- * \brief Gets color from raster.
- *
- * Looks up the rgb colors for
- * <em>rast</em> in the color table <em>colors</em>
- *
- *  \param[in] rast input raster map
- *  \param[out] red red value
- *  \param[out] grn green value
- *  \param[out] blu blue value
- *  \param[in] colors Colors struct
- *  \param[in] map_type type of map (CELL_TYPE,FCELL_TYPE,DCELL_TYPE)
- *  \return int
+/*!
+ * \brief Gets color from raster map
+ *
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
+ *
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ * \param map_type map type (CELL, FCELL, DCELL)
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
  */
-
 int G_get_raster_color(const void *rast,
 		       int *red, int *grn, int *blu,
 		       struct Colors *colors, RASTER_MAP_TYPE map_type)
@@ -79,83 +78,80 @@ int G_get_raster_color(const void *rast,
     return (int)set;
 }
 
-
-/**
- * \brief Gets color for a CELL raster.
- *
- * Looks up the rgb colors for CELL
- * <em>rast</em> in the color table <em>colors</em>
- *
- *  \param[in] rast input CELL raster
- *  \param[out] red red value
- *  \param[out] grn green value
- *  \param[out] blu blue value
- *  \param[in] colors Colors struct
- *  \return int
+/*!
+ * \brief Gets color from raster map (CELL)
+ *
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
+ *
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
  */
-
 int G_get_c_raster_color(const CELL * rast,
 			 int *red, int *grn, int *blu, struct Colors *colors)
 {
     return G_get_raster_color(rast, red, grn, blu, colors, CELL_TYPE);
 }
 
-
-/**
- * \brief Gets color for a FCELL raster.
- *
- *  Looks up the rgb colors for FCELL <em>rast</em> in the color table
- * <em>colors</em>
- *
- *  \param[in] rast input FCELL raster
- *  \param[out] red red value
- *  \param[out] grn green value
- *  \param[out] blu blue value
- *  \param[in] colors Colors struct
- *  \return int
+/*!
+ * \brief Gets color from raster map (FCELL)
+ *
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
+ *
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
  */
-
 int G_get_f_raster_color(const FCELL * rast,
 			 int *red, int *grn, int *blu, struct Colors *colors)
 {
     return G_get_raster_color(rast, red, grn, blu, colors, FCELL_TYPE);
 }
 
-
-/**
- * \brief Gets color for a DCELL raster.
- *
- *  Looks up the rgb colors for DCELL <em>rast</em> in the color table
- * <em>colors</em>
- *
- *  \param[in] rast input DCELL raster
- *  \param[out] red red value
- *  \param[out] grn green value
- *  \param[out] blu blue value
- *  \param[in] colors Colors struct
- *  \return int
+/*!
+ * \brief Gets color from raster map (DCELL)
+ *
+ * Looks up the rgb colors for <i>rast</i> in the color table
+ * <i>colors</i>.
+ *
+ * \param rast raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
+ *
+ * \return 1 if color is set
+ * \return 0 if color is not set
  */
-
 int G_get_d_raster_color(const DCELL * rast,
 			 int *red, int *grn, int *blu, struct Colors *colors)
 {
     return G_get_raster_color(rast, red, grn, blu, colors, DCELL_TYPE);
 }
 
-
-/**
- * \brief  Gets color for null value.
+/*!
+ * \brief Gets color for null value.
  *
- * Puts the red, green, and blue components of <b>colors</b> for the
- * NULL-value into <b>red, grn, and blu</b>.
+ * Puts the red, green, and blue components of <i>colors</i> for the
+ * NULL-value into <i>red, grn, and blu</i>.
  *
- *  \param[out] red red value
- *  \param[out] grn green value
- *  \param[out] blu blue value
- *  \param[in] colors Colors struct
- *  \return
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_get_null_value_color(int *red, int *grn, int *blu,
 			   const struct Colors *colors)
 {
@@ -173,20 +169,17 @@ void G_get_null_value_color(int *red, int *grn, int *blu,
 	*red = *blu = *grn = 255;	/* white */
 }
 
-
-/**
+/*!
  * \brief Gets default color.
  *
- *  Puts the red, green, and blue components of the
- * <tt>"default"</tt> color into <b>red, grn, and blu</b>.
+ * Puts the red, green, and blue components of the <tt>"default"</tt>
+ * color into <i>red, grn, and blu</i>.
  *
- *  \param[out] red red value
- *  \param[out] grn green value
- *  \param[out] blu blue value
- *  \param[in] colors Colors struct
- *  \return
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_get_default_color(int *red, int *grn, int *blu,
 			 const struct Colors *colors)
 {

lib/gis/color_hist.c

@@ -1,44 +1,31 @@
-
-/**********************************************************************
- *
- *  G_make_histogram_eq_colors (colors, statf)
- *
- *   struct Colors *colors      struct to hold colors
- *   struct Cell_stats *statf   cell stats info
- *
- *  Generates histogram equalized grey scale from
- *  cell stats structure info.
- *  Color range is 0-255.
- *
- **********************************************************************
+/*!
+ * \file gis/color_hist.c
  *
- *  G_make_histogram_log_colors (colors, statf, min, max)
+ * \brief GIS Library - histogram grey scale colors
  *
- *   struct Colors *colors      struct to hold colors
- *   struct Cell_stats *statf   cell stats info
+ * (C) 2007-2009 Glynn Clements and the GRASS Development Team
  *
- *  Generates histogram with normalized log transformed grey scale from
- *  cell stats structure info.
- *  Color range is 0-255.
+ * This program is free software under the GNU General Public License 
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- **********************************************************************/
-#include <grass/gis.h>
-#include <math.h>
+ * \author Glynn Clements <glynn@gclements.plus.com>
+ */
 
+#include <math.h>
+#include <grass/gis.h>
 
 /*!
- * \brief make histogram-stretched grey colors
+ * \brief Make histogram-stretched grey colors
+ *
+ * Generates a histogram contrast-stretched grey scale color table
+ * that goes from the, histogram information in the Cell_stats
+ * structure (see \ref Raster_Histograms).
  *
- * Generates a histogram
- * contrast-stretched grey scale color table that goes from the ,histogram
- * information in the Cell_stats structure <b>s.</b>  (See
- * Raster_Histograms).
+ * Color range is 0-255.
  *
- *  \param colors
- *  \param s
- *  \return
+ * \param colors pointer to Colors structure which holds color info
+ * \param stalf pointer to Cell_stats structure which holds cell stats info
  */
-
 void G_make_histogram_eq_colors(struct Colors *colors,
 				struct Cell_stats *statf)
 {
@@ -96,6 +83,17 @@ void G_make_histogram_eq_colors(struct Colors *colors,
     }
 }
 
+/*!
+  \brief Generates histogram with normalized log transformed grey scale.
+
+  Generates histogram with normalized log transformed grey scale from
+  cell stats structure info. Color range is 0-255.
+
+  \param colors pointer to Colors structure which holds color info
+  \param stalf pointer to Cell_stats structure which holds cell stats info
+  \param min minimum value
+  \param max maximum value
+*/
 void G_make_histogram_log_colors(struct Colors *colors,
 				 struct Cell_stats *statf, int min, int max)
 {

lib/gis/color_init.c

@@ -1,25 +1,26 @@
-
-/**********************************************************************
+/*!
+ * \file gis/color_init.c
+ *
+ * \brief GIS Library - Initialize Colors structure
+ *
+ * (C) 2001-2009 by the GRASS Development Team
  *
- * G_init_colors (colors)
- *      struct Colors *colors         structure to hold color info
+ * This program is free software under the GNU General Public License
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- * Initializes the color structure for subsequent calls to G_add_color_rule()
- *********************************************************************/
+ * \author Original author CERL
+ */
 
 #include <grass/gis.h>
 
-
 /*!
- * \brief initialize color structure
+ * \brief Initialize color structure
  *
- * The <b>colors</b> structure is initialized for subsequent calls
- * to <i>G_add_color_rule</i> and<i>G_set_color.</i>
+ * The <i>colors</i> structure is initialized for subsequent calls
+ * to G_add_color_rule() and G_set_color().
  *
- *  \param colors
- *  \return
+ * \param colors pointer to Colors structure
  */
-
 void G_init_colors(struct Colors *colors)
 {
     colors->version = 0;

lib/gis/color_look.c

@@ -1,40 +1,47 @@
-#include <math.h>
-#include <grass/gis.h>
-
-/* old 4.1 routine */
-
 /*!
- * \brief lookup an array of colors
+ * \file gis/color_lookup.c
+ * 
+ * \brief GIS Library - Lookup array of colors 
  *
- * Extracts colors for an array of <b>raster</b> values. The
- * colors for the <b>n</b> values in the <b>raster</b> array are stored in
- * the <b>red, green</b>, and <b>blue</b> arrays. The values in the
- * <b>set</b> array will indicate if the corresponding <b>raster</b> value
- * has a color or not (1 means it does, 0 means it does not). The programmer
- * must allocate the <b>red, green, blue</b>, and <b>set</b> arrays to be at
- * least dimension <b>n.</b>
- * <b>Note.</b> The <b>red, green</b>, and <b>blue</b> intensities will be
- * in the range 0 -­ 255.
+ * (C) 1999-2009 by the GRASS Development Team
  *
- *  \param raster
- *  \param red
- *  \param green
- *  \param blue
- *  \param set
- *  \param n
- *  \param colors
- *  \return int
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
+ *
+ * \author USACERL and many others
  */
 
+#include <math.h>
+#include <grass/gis.h>
 
 /*!
- * \brief 
+ * \brief Lookup an array of colors
+ *
+ * \todo To be removed, replaced by G_lookup_c_raster_colors().
+ *
+ * Extracts colors for an array of <i>cell</i> values. The colors
+ * for the <i>n</i> values in the <i>cell</i> array are stored in
+ * the <i>red, green</i>, and <i>blue</i> arrays. The values in the
+ * <i>set</i> array will indicate if the corresponding <i>cell</i>
+ * value has a color or not (1 means it does, 0 means it does not).
+ *
+ * The programmer must allocate the <i>red, green, blue</i>, and
+ * <b>set</b> arrays to be at least dimension <i>n</i>.
+ *
+ * <b>Note:</b> The <i>red, green</i>, and <i>blue</i> intensities
+ * will be in the range 0 -­ 255.
  *
  * Modified to return a color for NULL-values.
  *
- * \return
+ * \param cell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_lookup_colors(const CELL * cell,
 		     unsigned char *red, unsigned char *grn,
 		     unsigned char *blu, unsigned char *set, int n,
@@ -43,34 +50,31 @@ void G_lookup_colors(const CELL * cell,
     G_lookup_c_raster_colors(cell, red, grn, blu, set, n, colors);
 }
 
-/* I don't think it should exist, because it requires openning
-   of raster map every time Olga 
-   int G_lookup_rgb_colors(map, mapset, r, g, b)
-   char *name, *mapset;
-   unsigned char *r, *g, *b;
-   {
-   RASTER_MAP_TYPE map_type;
-   void *rast;
-   ....
-   }
- */
-
-
 /*!
- * \brief 
+ * \brief Lookup an array of colors
+ *
+ * Extracts colors for an array of <i>cell</i> values. The colors
+ * for the <i>n</i> values in the <i>cell</i> array are stored in
+ * the <i>red, green</i>, and <i>blue</i> arrays. The values in the
+ * <i>set</i> array will indicate if the corresponding <i>cell</i>
+ * value has a color or not (1 means it does, 0 means it does not).
  *
- *  The same as G_lookup_colors(cell, r, g, b, set, n, colors).
+ * The programmer must allocate the <i>red, green, blue</i>, and
+ * <b>set</b> arrays to be at least dimension <i>n</i>.
  *
- *  \param cell
- *  \param r
- *  \param g
- *  \param b
- *  \param set
- *  \param n
- *  \param colors
- *  \return
+ * <b>Note:</b> The <i>red, green</i>, and <i>blue</i> intensities
+ * will be in the range 0 -­ 255.
+ *
+ * Modified to return a color for NULL-values.
+ *
+ * \param cell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_lookup_c_raster_colors(const CELL * cell,
 			      unsigned char *red, unsigned char *grn,
 			      unsigned char *blu, unsigned char *set, int n,
@@ -89,28 +93,22 @@ void G_lookup_c_raster_colors(const CELL * cell,
 		     CELL_TYPE);
 }
 
-
 /*!
- * \brief 
+ * \brief Lookup an array of colors
  *
- * If the <em>cell_type</em> is CELL_TYPE, calls G_lookup_colors((CELL *)cell, r,
- * g, b, set, n, colors);
- * If the <em>cell_type</em> is FCELL_TYPE, calls
- * G_lookup_f_raster_colors(FCELL *)cell, r, g, b, set, n, colors);
- * If the <em>cell_type</em> is DCELL_TYPE, calls
- * G_lookup_d_raster_colors(DCELL *)cell, r, g, b, set, n, colors);
+ * - If the <em>map_type</em> is CELL_TYPE, calls G_lookup_colors()
+ * - If the <em>map_type</em> is FCELL_TYPE, calls G_lookup_f_raster_colors()
+ * - If the <em>map_type</em> is DCELL_TYPE, calls G_lookup_d_raster_colors()
  *
- *  \param rast
- *  \param r
- *  \param g
- *  \param b
- *  \param set
- *  \param n
- *  \param colors
- *  \param cell_type
- *  \return 
+ * \param raster raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
+ * \param map_type raster type (CELL, FCELL, DCELL)
  */
-
 void G_lookup_raster_colors(const void *raster,
 			    unsigned char *red, unsigned char *grn,
 			    unsigned char *blu, unsigned char *set, int n,
@@ -128,24 +126,21 @@ void G_lookup_raster_colors(const void *raster,
     G__lookup_colors(raster, red, grn, blu, set, n, colors, 1, 0, map_type);
 }
 
-
 /*!
- * \brief 
+ * \brief Lookup an array of colors (FCELL)
  *
- * Converts the <em>n</em>
- * floating-point values in the <em>fcell</em> array to their <em>r,g,b</em> color
- * components. Embedded NULL-values are handled properly as well.
+ * Converts the <em>n</em> floating-point values in the <em>fcell</em>
+ * array to their <em>r,g,b</em> color components. Embedded
+ * NULL-values are handled properly as well.
  *
- *  \param fcell
- *  \param r
- *  \param g
- *  \param b
- *  \param set
- *  \param n
- *  \param colors
- *  \return
+ * \param fcell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_lookup_f_raster_colors(const FCELL * fcell, unsigned char *red,
 			      unsigned char *grn, unsigned char *blu,
 			      unsigned char *set, int n, struct Colors *colors)
@@ -164,24 +159,21 @@ void G_lookup_f_raster_colors(const FCELL * fcell, unsigned char *red,
 		     FCELL_TYPE);
 }
 
-
 /*!
- * \brief 
+ * \brief Lookup an array of colors (DCELL)
  *
- * Converts the <em>n</em>
- * floating-point values in the <em>dcell</em> array to their <em>r,g,b</em> color
+ * Converts the <em>n</em> double-precision values in the
+ * <em>dcell</em> array to their <em>r,g,b</em> color
  * components. Embedded NULL-values are handled properly as well.
  *
- *  \param dcell
- *  \param r
- *  \param g
- *  \param b
- *  \param set
- *  \param n
- *  \param colors
- *  \return
+ * \param dcell raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_lookup_d_raster_colors(const DCELL * dcell, unsigned char *red,
 			      unsigned char *grn, unsigned char *blu,
 			      unsigned char *set, int n, struct Colors *colors)
@@ -217,7 +209,20 @@ static int less(double x, double y)
 	return 0;
 }
 
-
+/*!
+ * \brief Lookup an array of colors
+ *
+ * \param raster raster cell value
+ * \param[out] red red value
+ * \param[out] grn green value
+ * \param[out] blu blue value
+ * \param set array which indicates if color is set or not
+ * \param n number of values
+ * \param colors pointer to Colors structure which holds color info
+ * \param mod
+ * \param rules_only
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ */
 void G__lookup_colors(const void *raster, unsigned char *red,
 		      unsigned char *grn, unsigned char *blu,
 		      unsigned char *set, int n, struct Colors *colors,
@@ -431,6 +436,15 @@ void G__lookup_colors(const void *raster, unsigned char *red,
     }
 }
 
+/*!
+  \brief Interpolate color rules
+
+  \param val raster cell value
+  \param[out] red red value
+  \param[out] grn green value
+  \param[out] blu blue value
+  \param rule pointer to _Color_Rule which holds color rules info
+*/
 void G__interpolate_color_rule(DCELL val, unsigned char *red,
 			       unsigned char *grn, unsigned char *blu,
 			       const struct _Color_Rule_ *rule)

lib/gis/color_range.c

@@ -1,6 +1,27 @@
+/*!
+ * \file gis/color_range.c
+ *
+ * \brief GIS Library - Color range functions.
+ *
+ * (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 <math.h>
 #include <grass/gis.h>
 
+/*!
+  \brief Set color range (CELL version)
+
+  \todo Rename to G_set_c_color_range() ?
+
+  \param min,max minimum and maximum value
+  \param colors pointer to Colors structure which holds color info
+*/
 void G_set_color_range(CELL min, CELL max, struct Colors *colors)
 {
     if (min < max) {
@@ -13,6 +34,12 @@ void G_set_color_range(CELL min, CELL max, struct Colors *colors)
     }
 }
 
+/*!
+  \brief Set color range (DCELL version)
+
+  \param min,max minimum and maximum value
+  \param colors pointer to Colors structure which holds color info
+*/
 void G_set_d_color_range(DCELL min, DCELL max, struct Colors *colors)
 {
     if (min < max) {
@@ -25,18 +52,18 @@ void G_set_d_color_range(DCELL min, DCELL max, struct Colors *colors)
     }
 }
 
-/* returns min and max category in the range or huge numbers
-   if the co,lor table is defined on floating cell values and
-   not on categories */
+/*!
+  \brief Get color range values (CELL)
 
+  \todo Rename to G_get_c_color_range() ?
+  
+  Returns min and max category in the range or huge numbers if the
+  color table is defined on floating cell values and not on
+  categories.
 
-/*!
- * \brief
- *
- *  \param G_get_color_range
- *  \return int
+  \param[out] min,max minimum and maximum value
+  \param colors pointer to Colors structure which holds color info
  */
-
 void G_get_color_range(CELL * min, CELL * max, const struct Colors *colors)
 {
     if (!colors->is_float) {
@@ -49,7 +76,16 @@ void G_get_color_range(CELL * min, CELL * max, const struct Colors *colors)
     }
 }
 
-/* returns min and max values in the range */
+/*!
+  \brief Get color range values (DELL)
+  
+  Returns min and max category in the range or huge numbers if the
+  color table is defined on floating cell values and not on
+  categories.
+
+  \param[out] min,max minimum and maximum value
+  \param colors pointer to Colors structure which holds color info
+ */
 void G_get_d_color_range(DCELL * min, DCELL * max, const struct Colors *colors)
 {
     *min = colors->cmin;

lib/gis/color_read.c

@@ -1,26 +1,16 @@
-
-/**********************************************************************
- *
- *  G_read_colors (name, mapset, colors)
- *      char *name                   name of map
- *      char *mapset                 mapset that map belongs to
- *      struct Colors *colors        structure to hold color info
- *
- *  Reads the color information associated with map layer "map"
- *  in mapset "mapset" into the structure "colors".
+/*!
+ * \file gis/color_read.c
+ * 
+ * \brief GIS Library - Read color table of raster map
  *
- *  returns:    1  if successful
- *              0  if missing, but default colors generated
- *             -1  on fail
+ * (C) 1999-2009 by the GRASS Development Team
  *
- *  note:   If a secondary color file for map name "name" exists
- *          in the current project, that color file is read.  This
- *          allows the user to define their own color lookup tables
- *          for cell maps found in other mapsets.
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
  *
- *          Warning message is printed if the color file is
- *          missing or invalid.
- *********************************************************************/
+ * \author USACERL and many others
+ */
 
 #include <grass/gis.h>
 #include <grass/glocale.h>
@@ -33,32 +23,35 @@ static int read_old_colors(FILE *, struct Colors *);
 
 
 /*!
- * \brief read map layer color table
+ * \brief Read raster map layer color table
  *
- * The color table for the raster map
- * <b>name</b> in the specified <b>mapset</b> is read into the
- * <b>colors</b> structure.
- * If the data layer has no color table, a default color table is generated and
- * 0 is returned. If there is an error reading the color table, a diagnostic
- * message is printed and -1 is returned. If the color table is read ok, 1 is
- * returned.
+ * The color table for the raster map <i>name</i> in the specified
+ * <i>mapset</i> is read into the <i>colors</i> structure. If the data
+ * layer has no color table, a default color table is generated and 0
+ * is returned. If there is an error reading the color table, a
+ * diagnostic message is printed and -1 is returned. If the color
+ * table is read ok, 1 is returned.
  *
- *  \param name
- *  \param mapset
- *  \param colors
- *  \return int
- */
-
-
-/*!
- * \brief 
+ * This routine reads the rules from the color file. If the input
+ * raster map is is a floating-point map it calls
+ * G_mark_colors_as_fp().
+ *
+ *  Note: If a secondary color file for map name <i>name</i> exists in
+ *  the current project, that color file is read.  This allows the
+ *  user to define their own color lookup tables for cell maps found
+ *  in other mapsets.
+ *
+ *  Warning message is printed if the color file is
+ *  missing or invalid.
  *
- * This routine reads the rules from the color
- * file. If the input raster map is is a floating-point map it calls <tt>G_mark_colors_as_fp()</tt>.
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] colors pointer to Colors structure
  *
- *  \return int
+ * \return -1 on error
+ * \return 0 if missing, but default colors generated
+ * \return 1 on success
  */
-
 int G_read_colors(const char *name, const char *mapset, struct Colors *colors)
 {
     int fp;
@@ -104,16 +97,16 @@ int G_read_colors(const char *name, const char *mapset, struct Colors *colors)
 		return 0;
 	    }
 	}
-	err = "missing";
+	err = _("missing");
 	break;
     case -1:
-	err = "invalid";
+	err = _("invalid");
 	break;
     default:
 	return 1;
     }
 
-    G_warning(_("color support for [%s] in mapset [%s] %s"), name, mapset,
+    G_warning(_("Color support for <%s@%s> %s"), name, mapset,
 	      err);
     return -1;
 }
@@ -303,9 +296,8 @@ static int read_new_colors(FILE * fd, struct Colors *colors)
 		G_add_color_rule((CELL) cat1, r1, g1, b1,
 				 (CELL) cat2, r2, g2, b2, colors);
 	}
-	/*
-	   fprintf (stderr, "adding rule %d=%.2lf %d %d %d  %d=%.2lf %d %d %d\n", cat1,val1,  r1, g1, b1, cat2, val2, r2, g2, b2);
-	 */
+	G_debug(3, "adding rule %d=%.2lf %d %d %d  %d=%.2lf %d %d %d",
+		cat1, val1,  r1, g1, b1, cat2, val2, r2, g2, b2);
     }
     return 1;
 }
@@ -380,19 +372,17 @@ static int read_old_colors(FILE * fd, struct Colors *colors)
     return 0;
 }
 
-
 /*!
- * \brief 
+ * \brief Mark colors as floating-point.
  *
- * Sets a flag in
- * the <em>colors</em> structure that indicates that these colors should only be
- * looked up using floating-point raster data (not integer data).
- * In particular if this flag is set, the routine <tt>G_get_colors_min_max()</tt> should return min=-255$^3$ and max=255$^3$.
+ * Sets a flag in the <i>colors</i> structure that indicates that
+ * these colors should only be looked up using floating-point raster
+ * data (not integer data). In particular if this flag is set, the
+ * routine G_get_colors_min_max() should return min=-255$^3$ and
+ * max=255$^3$.
  *
- *  \param colors
- *  \return int
+ * \param colors pointer to Colors structure
  */
-
 void G_mark_colors_as_fp(struct Colors *colors)
 {
     colors->is_float = 1;

lib/gis/color_rule.c

@@ -1,17 +1,14 @@
-
-/**
- * \file color_rule.c
+/*!
+ * \file gis/color_rule.c
  *
  * \brief GIS Library - Color rules.
  *
- * (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>
@@ -36,11 +33,9 @@ static void add_color_rule(const void *, int, int, int,
  *  \param[in,out] colors pointer to color table structure
  *  \return
  */
-
-void G_add_d_raster_color_rule(
-    const DCELL * val1, int r1, int g1, int b1,
-    const DCELL * val2, int r2, int g2, int b2,
-    struct Colors *colors)
+void G_add_d_raster_color_rule(const DCELL * val1, int r1, int g1, int b1,
+			       const DCELL * val2, int r2, int g2, int b2,
+			       struct Colors *colors)
 {
     add_color_rule(val1, r1, g1, b1, val2, r2, g2, b2, &colors->fixed,
 		   colors->version, &colors->cmin, &colors->cmax, DCELL_TYPE);
@@ -59,11 +54,9 @@ void G_add_d_raster_color_rule(
  *  \param[in,out] colors pointer to color table structure
  *  \return
  */
-
-void G_add_f_raster_color_rule(
-    const FCELL * cat1, int r1, int g1, int b1,
-    const FCELL * cat2, int r2, int g2, int b2,
-    struct Colors *colors)
+void G_add_f_raster_color_rule(const FCELL * cat1, int r1, int g1, int b1,
+			       const FCELL * cat2, int r2, int g2, int b2,
+			       struct Colors *colors)
 {
     add_color_rule(cat1, r1, g1, b1, cat2, r2, g2, b2, &colors->fixed,
 		   colors->version, &colors->cmin, &colors->cmax, FCELL_TYPE);
@@ -82,11 +75,9 @@ void G_add_f_raster_color_rule(
  *  \param[in,out] colors pointer to color table structure
  *  \return
  */
-
-void G_add_c_raster_color_rule(
-    const CELL * cat1, int r1, int g1, int b1,
-    const CELL * cat2, int r2, int g2, int b2,
-    struct Colors *colors)
+void G_add_c_raster_color_rule(const CELL * cat1, int r1, int g1, int b1,
+			       const CELL * cat2, int r2, int g2, int b2,
+			       struct Colors *colors)
 {
     add_color_rule(cat1, r1, g1, b1, cat2, r2, g2, b2, &colors->fixed,
 		   colors->version, &colors->cmin, &colors->cmax, CELL_TYPE);
@@ -115,10 +106,9 @@ void G_add_c_raster_color_rule(
  *  \return
  */
 
-void G_add_raster_color_rule(
-    const void *val1, int r1, int g1, int b1,
-    const void *val2, int r2, int g2, int b2,
-    struct Colors *colors, RASTER_MAP_TYPE data_type)
+void G_add_raster_color_rule(const void *val1, int r1, int g1, int b1,
+			     const void *val2, int r2, int g2, int b2,
+			     struct Colors *colors, RASTER_MAP_TYPE data_type)
 {
     add_color_rule(val1, r1, g1, b1, val2, r2, g2, b2, &colors->fixed,
 		   colors->version, &colors->cmin, &colors->cmax, data_type);
@@ -138,16 +128,20 @@ void G_add_raster_color_rule(
  * components <b>r1,g1,b1</b> and <b>r2,g2,b2</b> must be in the range
  * 0 -- 255.
  * For example, to create a linear grey scale for the range 200 -- 1000:
+ *
  \code
  struct Colors colr;
  G_init_colors (&colr);
- G_add_color_rule ((CELL)200, 0,0,0, (CELL)1000, 255,255,255);
+ G_add_color_rule ((CELL)200, 0,0,0, (CELL) 1000, 255,255,255);
  \endcode
- * The programmer is encouraged to review Raster_Color_Table_Format how
- * this routine fits into the 5.x raster color logic.
- * <b>Note.</b> The <b>colors</b> structure must have been initialized by
- * <i>G_init_colors.</i> See Predefined_Color_Tables for routines to
- * build some predefined color tables. 
+ *
+ * The programmer is encouraged to review \ref
+ * Raster_Color_Table_Format how this routine fits into the 5.x raster
+ * color logic.
+ *
+ * <b>Note:</b> The <i>colors</i> structure must have been initialized
+ * by G_init_colors(). See \ref Predefined_Color_Tables for routines
+ * to build some predefined color tables.
  *
  *  \param cat1 cell value
  *  \param r1,g1,b1 color value
@@ -156,18 +150,16 @@ void G_add_raster_color_rule(
  *  \param[in,out] colors pointer to color table structure
  *  \return
  */
-
-void G_add_color_rule(
-    CELL cat1, int r1, int g1, int b1,
-    CELL cat2, int r2, int g2,
-    int b2, struct Colors *colors)
+void G_add_color_rule(CELL cat1, int r1, int g1, int b1,
+		      CELL cat2, int r2, int g2,
+		      int b2, struct Colors *colors)
 {
     add_color_rule((void *)&cat1, r1, g1, b1, (void *)&cat2, r2, g2, b2,
 		   &colors->fixed, colors->version, &colors->cmin,
 		   &colors->cmax, CELL_TYPE);
 }
 
-/**
+/*!
  * \brief Add modular color rule (DCELL version)
  *
  * \param val1 cell value
@@ -179,10 +171,9 @@ void G_add_color_rule(
  * \return -1 on failure
  * \return 1 on success
  */
-int G_add_modular_d_raster_color_rule(
-    const DCELL * val1, int r1, int g1, int b1,
-    const DCELL * val2, int r2, int g2, int b2,
-    struct Colors *colors)
+int G_add_modular_d_raster_color_rule(const DCELL * val1, int r1, int g1, int b1,
+				      const DCELL * val2, int r2, int g2, int b2,
+				      struct Colors *colors)
 {
     DCELL min, max;
 
@@ -198,7 +189,7 @@ int G_add_modular_d_raster_color_rule(
     return 1;
 }
 
-/**
+/*!
  * \brief Add modular color rule (FCELL version)
  *
  * \param val1 cell value
@@ -210,10 +201,9 @@ int G_add_modular_d_raster_color_rule(
  * \return -1 on failure
  * \return 1 on success
  */
-int G_add_modular_f_raster_color_rule(
-    const FCELL * val1, int r1, int g1, int b1,
-    const FCELL * val2, int r2, int g2, int b2,
-    struct Colors *colors)
+int G_add_modular_f_raster_color_rule(const FCELL * val1, int r1, int g1, int b1,
+				      const FCELL * val2, int r2, int g2, int b2,
+				      struct Colors *colors)
 {
     DCELL min, max;
 
@@ -229,7 +219,7 @@ int G_add_modular_f_raster_color_rule(
     return 1;
 }
 
-/**
+/*!
  * \brief Add modular color rule (CCELL version)
  *
  * \param val1 cell value
@@ -241,20 +231,19 @@ int G_add_modular_f_raster_color_rule(
  * \return -1 on failure
  * \return 1 on success
  */
-int G_add_modular_c_raster_color_rule(
-    const CELL * val1, int r1, int g1, int b1,
-    const CELL * val2, int r2, int g2, int b2,
-    struct Colors *colors)
+int G_add_modular_c_raster_color_rule(const CELL * val1, int r1, int g1, int b1,
+				      const CELL * val2, int r2, int g2, int b2,
+				      struct Colors *colors)
 {
     return G_add_modular_color_rule(*val1, r1, g1, b1, *val2, r2, g2, b2,
 				    colors);
 }
 
-/**
+/*!
  * \brief Add modular color rule
  *
- * Question: shouldn't this function call
- * G_add_modular_<data_type>_raster_color_rule() instead???
+ * \todo Question: shouldn't this function call
+ * G_add_modular_<data_type>_raster_color_rule() instead?
  *
  * \param val1 cell value
  * \param r1,g1,b1 color value
@@ -285,10 +274,10 @@ int G_add_modular_raster_color_rule(
     return 1;
 }
 
-/**
+/*!
  * \brief Add modular color rule
  *
- * This function seems to be same as
+ * \todo This function seems to be same as
  * G_add_modular_raster_color_rule(). Can be removed?
  *
  * \param val1 cell value
@@ -301,10 +290,9 @@ int G_add_modular_raster_color_rule(
  * \return -1 on failure
  * \return 1 on success
  */
-int G_add_modular_color_rule(
-    CELL cat1, int r1, int g1,
-    int b1, CELL cat2, int r2,
-    int g2, int b2, struct Colors *colors)
+int G_add_modular_color_rule(CELL cat1, int r1, int g1,
+			     int b1, CELL cat2, int r2,
+			     int g2, int b2, struct Colors *colors)
 {
     CELL min, max;
 

lib/gis/color_set.c

@@ -1,30 +1,42 @@
-#include <grass/gis.h>
+/*!
+ * \file gis/color_set.c
+ *
+ * \brief GIS Library - Set colors for raster maps.
+ *
+ * (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
+ */
 
-/* for convenience, but to be avoided if possible */
+#include <grass/gis.h>
 
 /*!
- * \brief set a category color
+ * \brief Set a category color (CELL)
+ *
+ * The <i>red, green</i>, and <i>blue</i> intensities for the color
+ * associated with category <i>cat</i> are set in the <i>colors</i>
+ * structure.  The intensities must be in the range 0 -­ 255. Values
+ * below zero are set as zero, values above 255 are set as 255.
+ *
+ * <b>Warning: Use of this routine is discouraged because it defeats the new
+ * color logic.</b>
  *
- * The <b>red, green</b>, and
- * <b>blue</b> intensities for the color associated with category <b>cat</b>
- * are set in the <b>colors</b> structure.  The intensities must be in the
- * range 0 -­ 255. Values below zero are set as zero, values above 255 are set as
- * 255.
- * <b>Use of this routine is discouraged because it defeats the new color
- * logic.</b> It is provided only for backward compatibility. Overuse can create
- * large color tables. <i>G_add_color_rule</i> should be used whenever
+ * It is provided only for backward compatibility. Overuse can create
+ * large color tables. G_add_color_rule() should be used whenever
  * possible.
- * <b>Note.</b> The <b>colors</b> structure must have been initialized by
- * <i>G_init_color.</i>
  *
- *  \param cat
- *  \param red
- *  \param green
- *  \param blue
- *  \param colors
- *  \return
+ * <b>Note:</b> The <i>colors</i> structure must have been
+ * initialized by G_init_color().
+ *
+ * \param cat raster cell value
+ * \param r red value
+ * \param g green value
+ * \param b blue value
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_set_color(CELL cat, int r, int g, int b, struct Colors *colors)
 {
     if (G_is_c_null_value(&cat))
@@ -33,6 +45,17 @@ void G_set_color(CELL cat, int r, int g, int b, struct Colors *colors)
 	G_add_color_rule(cat, r, g, b, cat, r, g, b, colors);
 }
 
+/*!
+ * \brief Set a category color (DCELL)
+ * 
+ * See G_set_color() for detailed information.
+ *
+ * \param cat raster cell value
+ * \param r red value
+ * \param g green value
+ * \param b blue value
+ * \param colors pointer to Colors structure which holds color info
+ */
 void G_set_d_color(DCELL val, int r, int g, int b, struct Colors *colors)
 {
     if (G_is_d_null_value(&val))
@@ -41,19 +64,17 @@ void G_set_d_color(DCELL val, int r, int g, int b, struct Colors *colors)
 	G_add_d_raster_color_rule(&val, r, g, b, &val, r, g, b, colors);
 }
 
-
 /*!
- * \brief 
+ * \brief Set color for NULL-value
  *
- * Sets the color (in <em>colors</em>) for the NULL-value to <em>r,g,b</em>.
+ * Sets the color (in <i>colors</i>) for the NULL-value to
+ * <i>red, green, blue</i>.
  *
- *  \param r
- *  \param g
- *  \param b
- *  \param colors
- *  \return
+ * \param red red value
+ * \param grn green value
+ * \param blu blue value
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_set_null_value_color(int red, int grn, int blu, struct Colors *colors)
 {
     colors->null_red = red;
@@ -62,20 +83,18 @@ void G_set_null_value_color(int red, int grn, int blu, struct Colors *colors)
     colors->null_set = 1;
 }
 
-
 /*!
- * \brief 
+ * \brief Set default color value 
  *
- * Sets the default color (in <em>colors</em>) to <em>r,g,b</em>. This is
- * the color for values which do not have an explicit rule.
+ * Sets the default color (in <i>colors</i>) to <i>red, green,
+ * blue</i>. This is the color for values which do not have an
+ * explicit rule.
  *
- *  \param r
- *  \param g
- *  \param b
- *  \param colors
- *  \return
+ * \param red red value
+ * \param grn green value
+ * \param blu blue value
+ * \param colors pointer to Colors structure which holds color info
  */
-
 void G_set_default_color(int red, int grn, int blu, struct Colors *colors)
 {
     colors->undef_red = red;

lib/gis/color_write.c

@@ -1,28 +1,24 @@
-
-/**********************************************************************
- *  G_write_colors (name, mapset, colors)
- *      char *name                   name of map
- *      char *mapset                 mapset that map belongs to
- *      struct Colors *colors        structure holding color info
+/*!
+ * \file gis/color_write.c
+ * 
+ * \brief GIS Library - Write color table of raster map
  *
- *  Writes the color information associated with map layer "map"
- *  in mapset "mapset" from the structure "colors".
+ * (C) 1999-2009 by the GRASS Development Team
  *
- *  returns:    1  if successful
- *             -1  on fail
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
  *
- * If the environment variable FORCE_GRASS3_COLORS is set (to anything at all)
- * then the output format is 3.0, even if the structure contains 4.0 rules.
- * This allows users to create 3.0 color files for export to sites which
- * don't yet have 4.0
- ***********************************************************************/
+ * \author USACERL and many others
+ */
+
 #include <string.h>
 #include <stdlib.h>
 #include <stdio.h>
 #include <grass/gis.h>
+
 #define PRECISION 30
-#define THRESHOLD .0000000000000000000000000000005
-/* .5 * 10 ^(-30) */
+#define THRESHOLD .0000000000000000000000000000005 /* .5 * 10 ^(-30) */
 
 static void write_rules(FILE *, struct _Color_Rule_ *, DCELL, DCELL);
 static void write_new_colors(FILE *, struct Colors *);
@@ -31,49 +27,50 @@ static void forced_write_old_colors(FILE *, struct Colors *);
 static void format_min(char *, double);
 static void format_max(char *, double);
 
-
 /*!
- * \brief write map layer color table
+ * \brief Write map layer color table
  *
- * The color table is written for the
- * raster map <b>name</b> in the specified <b>mapset</b> from the
- * <b>colors</b> structure.
- * If there is an error, -1 is returned. No diagnostic is printed. Otherwise, 1
- * is returned.
- * The <b>colors</b> structure must be created properly, i.e.,
- * <i>G_init_colors</i> to initialize the structure and
- * <i>G_add_color_rule</i> to set the category colors.\remarks{These
- * routines are called by higher level routines which read or create entire
- * color tables, such as<i>G_read_colors</i> or
- * <i>G_make_ramp_colors.</i>}
- * <b>Note.</b> The calling sequence for this function deserves special
- * attention. The <b>mapset</b> parameter seems to imply that it is possible
- * to overwrite the color table for a raster map which is in another mapset.
- * However, this is not what actually happens. It is very useful for users to
- * create their own color tables for raster maps in other mapsets, but without
- * overwriting other users' color tables for the same raster map. If
- * <b>mapset</b> is the current mapset, then the color file for <b>name</b>
- * will be overwritten by the new color table. But if <b>mapset</b> is not the
- * current mapset, then the color table is actually written in the current
- * mapset under the <b>colr2</b> element as: colr2/mapset/name.
+ * The color table is written for the raster map <i>name</i> in the
+ * specified <i>mapset</i> from the <i>colors</i> structure.
  *
- *  \param name
- *  \param mapset
- *  \param colors
- *  \return int
- */
-
-
-/*!
- * \brief 
+ * If there is an error, -1 is returned. No diagnostic is
+ * printed. Otherwise, 1 is returned.
+ *
+ * The <i>colors</i> structure must be created properly, i.e.,
+ * G_init_colors() to initialize the structure and G_add_color_rule()
+ * to set the category colors. These routines are called by
+ * higher level routines which read or create entire color tables,
+ * such as G_read_colors() or G_make_ramp_colors().
  *
- * The rules are written out using
- * floating-point format, removing trailing zeros (possibly producing integers).
- * The flag marking the colors as floating-point is <b>not</b> written.
+ * <b>Note:</b> The calling sequence for this function deserves
+ * special attention. The <i>mapset</i> parameter seems to imply that
+ * it is possible to overwrite the color table for a raster map which
+ * is in another mapset. However, this is not what actually
+ * happens. It is very useful for users to create their own color
+ * tables for raster maps in other mapsets, but without overwriting
+ * other users' color tables for the same raster map. If <i>mapset</i>
+ * is the current mapset, then the color file for <i>name</i> will be
+ * overwritten by the new color table. But if <i>mapset</i> is not the
+ * current mapset, then the color table is actually written in the
+ * current mapset under the <tt>colr2</tt> element as:
+ * <tt>colr2/mapset/name</tt>.
  *
- *  \return int
+ * The rules are written out using floating-point format, removing
+ * trailing zeros (possibly producing integers).  The flag marking the
+ * colors as floating-point is <b>not</b> written.
+ *
+ * If the environment variable FORCE_GRASS3_COLORS is set (to anything at all)
+ * then the output format is 3.0, even if the structure contains 4.0 rules.
+ * This allows users to create 3.0 color files for export to sites which
+ * don't yet have 4.0
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param colors pointer to structure Colors which holds color info
+ *
+ * \return 1 on success
+ * \return -1 on failure
  */
-
 int G_write_colors(const char *name, const char *mapset,
 		   struct Colors *colors)
 {
@@ -104,6 +101,12 @@ int G_write_colors(const char *name, const char *mapset,
     return 1;
 }
 
+/*!
+ * \brief Write map layer color table
+ *
+ * \param fd file descriptor
+ * \param colors pointer to Colors structure which holds color info
+ */
 void G__write_colors(FILE * fd, struct Colors *colors)
 {
     if (getenv("FORCE_GRASS3_COLORS"))

lib/gis/find_cell.c

@@ -1,43 +1,34 @@
-/*
- **********************************************************************
- *  char *
- *  G_find_cell (name, mapset)
- *        char *name       file name to look for
- *        char *mapset     mapset to search. if mapset is ""
- *                         will search in mapset search list
+/*!
+ * \file strings.c
+ * 
+ * \brief GIS Library - Find raster map
  *
- *      searches for a cell file from the mapset search list
- *      or in a specified mapset.
- *      returns the mapset name where the cell file was found.
+ * (C) 1999-2009 by the GRASS Development Team
  *
- *  returns:
- *      char *  pointer to a string with name of mapset
- *              where cell file was found, or NULL if not found
- *  note:
- *      rejects all names that begin with .
+ * This program is free software under the GNU General Public
+ * License (>=v2). Read the file COPYING that comes with GRASS
+ * for details.
  *
- *      if name is of the form nnn in ppp then 
- *      name = nnn and mapset = ppp
- **********************************************************************/
+ * \author Original author CERL
+ */
 
 #include <grass/gis.h>
 
-
 /*!
- * \brief find a raster map
+ * \brief Find a raster map
  *
- * Looks for the raster map <b>name</b> in the database. The
- * <b>mapset</b> parameter can either be the empty string "", which means
- * search all the mapsets in the user's current mapset search path,
- * \remarks{See Mapset_Search_Path for more details about the search path.}
- * or it can be a specific mapset name, which means look for the raster map
- * only in this one mapset (for example, in the current mapset). If found,
- * the mapset where the raster map lives is returned. If not found, the NULL
- * pointer is returned.
+ * Looks for the raster map <i>name</i> in the database. The
+ * <i>mapset</i> parameter can either be the empty string "", which
+ * means search all the mapsets in the user's current mapset search
+ * path (see \ref Mapset_Search_Path for more details about the search
+ * path) or it can be a specific mapset name, which means look for the
+ * raster map only in this one mapset (for example, in the current
+ * mapset). If found, the mapset where the raster map lives is
+ * returned. If not found, the NULL pointer is returned.
  *
- * NOTE: If the user specifies a fully qualified raster map which exists,
- * then <i>G_find_cell(~)</i> modifies <b>name</b> by removing the
- * "@<i>mapset</i>".
+ * Note: If the user specifies a fully qualified raster map which
+ * exists, then G_find_cell() modifies <i>name</i> by removing
+ * the "@<i>mapset</i>".
  *
  * For example, to find a raster map anywhere in the database:
  \code
@@ -51,35 +42,36 @@
  *
  \code
  char name[GNAME_MAX];
- if (G_find_cell(name,G_mapset( )) == NULL)
+ if (G_find_cell(name, G_mapset()) == NULL)
  // not found
  \endcode
  *
- *  \param name
- *  \param mapset
- *  \return char * 
+ * \param[in,out] name map name
+ * \param mapset mapset name or ""
+ * 
+ * \return mapset where raster map was found
+ * \return NULL if not found
  */
-
 const char *G_find_cell(char *name, const char *mapset)
 {
     return G_find_file("cell", name, mapset);
 }
 
-
 /*!
- * \brief find a raster map (look but don't touch)
+ * \brief Find a raster map (look but don't touch)
  *
  * The same as G_find_cell() but doesn't remove the "@<i>mapset</i>"
- * qualification from <b>name</b>, if present.
+ * qualification from <i>name</i>, if present.
  *
  * Returns NULL if the map wasn't found, or the mapset the raster was
  * found in if it was.
  *
- *  \param name
- *  \param mapset
- *  \return char *
+ * \param name map name
+ * \param mapset mapset name or ""
+ * 
+ * \return mapset where raster map was found
+ * \return NULL if not found
  */
-
 const char *G_find_cell2(const char *name, const char *mapset)
 {
     return G_find_file2("cell", name, mapset);

lib/gis/get_cellhd.c

@@ -3,7 +3,7 @@
   
   \brief GIS library - Read raster map header
   
-  (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.
@@ -20,28 +20,26 @@
   \brief Read the raster header
   
   The raster header for the raster map <i>name</i> in the specified
-  <i>mapset</i> is read into the <i>cellhd</i> structure.  If there is
+  <i>mapset</i> is read into the <i>cellhd</i> structure. If there is
   an error reading the raster header file, a diagnostic message is
   printed and -1 is returned. Otherwise, 0 is returned.
   
   <b>Note</b>:a warning message for errors encountered.
   
-  Cell header files may contain either grid cell header 
-  information or reclass information.   If it is a reclass
-  file, it will specify the map and mapset names of the actual
-  grid cell file being reclassed.  G_get_cellhd(), upon 
-  reading reclass information will go read the cell header
-  information for the referenced file.  Only one reference is 
-  allowed.
+  Cell header files may contain either grid cell header information or
+  reclass information. If it is a reclass file, it will specify the
+  map and mapset names of the actual grid cell file being
+  reclassed. G_get_cellhd(), upon reading reclass information will go
+  read the cell header information for the referenced file. Only one
+  reference is allowed.
   
   \param name name of map
   \param mapset mapset that map belongs to
-  \param cellhd structure to hold cell header info
+  \param[out] cellhd structure to hold cell header info
   
   \return 0 on success
   \return -1 on error
  */
-
 int G_get_cellhd(const char *name, const char *mapset,
 		 struct Cell_head *cellhd)
 {

lib/gis/get_row.c

@@ -1,16 +1,14 @@
 /*!
-   \file get_row.c
+  \file gis/get_row.c
 
-   \brief GIS library - get raster row
+  \brief GIS library - Get raster row
 
-   (C) 2003-2008 by the GRASS Development Team
+  (C) 2003-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>
@@ -25,16 +23,10 @@
 
 #include "G.h"
 
-/*--------------------------------------------------------------------------*/
-
 #define NULL_FILE   "null"
 
-/*--------------------------------------------------------------------------*/
-
 static int embed_nulls(int, void *, int, RASTER_MAP_TYPE, int, int);
 
-/*--------------------------------------------------------------------------*/
-
 static int compute_window_row(int fd, int row, int *cellRow)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -63,8 +55,6 @@ static int compute_window_row(int fd, int row, int *cellRow)
     return 1;
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void do_reclass_int(int fd, void *cell, int null_is_zero)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -96,8 +86,6 @@ static void do_reclass_int(int fd, void *cell, int null_is_zero)
     }
 }
 
-/*--------------------------------------------------------------------------*/
-
 static int read_data_fp_compressed(int fd, int row, unsigned char *data_buf,
 				   int *nbytes)
 {
@@ -118,8 +106,6 @@ static int read_data_fp_compressed(int fd, int row, unsigned char *data_buf,
     return 0;
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void rle_decompress(unsigned char *dst, const unsigned char *src,
 			   int nbytes, int size)
 {
@@ -183,8 +169,6 @@ static int read_data_compressed(int fd, int row, unsigned char *data_buf,
     return 0;
 }
 
-/*--------------------------------------------------------------------------*/
-
 static int read_data_uncompressed(int fd, int row, unsigned char *data_buf,
 				  int *nbytes)
 {
@@ -202,8 +186,6 @@ static int read_data_uncompressed(int fd, int row, unsigned char *data_buf,
     return 0;
 }
 
-/*--------------------------------------------------------------------------*/
-
 #ifdef HAVE_GDAL
 static int read_data_gdal(int fd, int row, unsigned char *data_buf, int *nbytes)
 {
@@ -238,10 +220,6 @@ static int read_data_gdal(int fd, int row, unsigned char *data_buf, int *nbytes)
 }
 #endif
 
-/*--------------------------------------------------------------------------*/
-
-/* Actually read a row of data in */
-
 static int read_data(int fd, int row, unsigned char *data_buf, int *nbytes)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -262,10 +240,7 @@ static int read_data(int fd, int row, unsigned char *data_buf, int *nbytes)
 	return read_data_fp_compressed(fd, row, data_buf, nbytes);
 }
 
-/*--------------------------------------------------------------------------*/
-
 /* copy cell file data to user buffer translated by window column mapping */
-
 static void cell_values_int(int fd, const unsigned char *data,
 			    const COLUMN_MAPPING * cmap, int nbytes,
 			    void *cell, int n)
@@ -311,8 +286,6 @@ static void cell_values_int(int fd, const unsigned char *data,
     }
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void cell_values_float(int fd, const unsigned char *data,
 			      const COLUMN_MAPPING * cmap, int nbytes,
 			      void *cell, int n)
@@ -352,8 +325,6 @@ static void cell_values_float(int fd, const unsigned char *data,
     }
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void cell_values_double(int fd, const unsigned char *data,
 			       const COLUMN_MAPPING * cmap, int nbytes,
 			       void *cell, int n)
@@ -393,14 +364,7 @@ static void cell_values_double(int fd, const unsigned char *data,
     }
 }
 
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
 #ifdef HAVE_GDAL
-
-/*--------------------------------------------------------------------------*/
-
 static void gdal_values_int(int fd, const unsigned char *data,
 			    const COLUMN_MAPPING *cmap, int nbytes,
 			    CELL *cell, int n)
@@ -439,8 +403,6 @@ static void gdal_values_int(int fd, const unsigned char *data,
     }
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void gdal_values_float(int fd, const float *data,
 			      const COLUMN_MAPPING *cmap, int nbytes,
 			      FCELL *cell, int n)
@@ -465,8 +427,6 @@ static void gdal_values_float(int fd, const float *data,
     }
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void gdal_values_double(int fd, const double *data,
 			       const COLUMN_MAPPING *cmap, int nbytes,
 			       DCELL *cell, int n)
@@ -490,13 +450,8 @@ static void gdal_values_double(int fd, const double *data,
 	cmapold = cmap[i];
     }
 }
-
-/*--------------------------------------------------------------------------*/
-
 #endif
 
-/*--------------------------------------------------------------------------*/
-
 /* transfer_to_cell_XY takes bytes from fcb->data, converts these bytes with
    the appropriate procedure (e.g. XDR or byte reordering) into type X 
    values which are put into array work_buf.  
@@ -506,9 +461,6 @@ static void gdal_values_double(int fd, const double *data,
    work_buf might be ommited. check the appropriate function for XY to
    determine the procedure of conversion. 
  */
-
-/*--------------------------------------------------------------------------*/
-
 static void transfer_to_cell_XX(int fd, void *cell)
 {
     static void (*cell_values_type[3]) () = {
@@ -531,8 +483,6 @@ static void transfer_to_cell_XX(int fd, void *cell)
 				       G__.window.cols);
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void transfer_to_cell_fi(int fd, void *cell)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];
@@ -565,8 +515,6 @@ static void transfer_to_cell_di(int fd, void *cell)
     G__freea(work_buf);
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void transfer_to_cell_if(int fd, void *cell)
 {
     CELL *work_buf = G__alloca(G__.window.cols * sizeof(CELL));
@@ -593,8 +541,6 @@ static void transfer_to_cell_df(int fd, void *cell)
     G__freea(work_buf);
 }
 
-/*--------------------------------------------------------------------------*/
-
 static void transfer_to_cell_id(int fd, void *cell)
 {
     CELL *work_buf = G__alloca(G__.window.cols * sizeof(CELL));
@@ -621,11 +567,6 @@ static void transfer_to_cell_fd(int fd, void *cell)
     G__freea(work_buf);
 }
 
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
 /*
  *   works for all map types and doesn't consider
  *   null row corresponding to the requested row 
@@ -676,8 +617,6 @@ static int get_map_row_nomask(int fd, void *rast, int row,
     return 1;
 }
 
-/*--------------------------------------------------------------------------*/
-
 static int get_map_row_no_reclass(int fd, void *rast, int row,
 				  RASTER_MAP_TYPE data_type, int null_is_zero,
 				  int with_mask)
@@ -695,8 +634,6 @@ static int get_map_row_no_reclass(int fd, void *rast, int row,
     return 1;
 }
 
-/*--------------------------------------------------------------------------*/
-
 static int get_map_row(int fd, void *rast, int row, RASTER_MAP_TYPE data_type,
 		       int null_is_zero, int with_mask)
 {
@@ -746,12 +683,6 @@ static int get_map_row(int fd, void *rast, int row, RASTER_MAP_TYPE data_type,
     return 1;
 }
 
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
 /*!
  * \brief Read raster row without masking (this routine is deprecated)
  *
@@ -783,7 +714,6 @@ static int get_map_row(int fd, void *rast, int row, RASTER_MAP_TYPE data_type,
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_map_row_nomask(int fd, CELL * buf, int row)
 {
     return get_map_row(fd, buf, row, CELL_TYPE, 1, 0);
@@ -803,7 +733,6 @@ int G_get_map_row_nomask(int fd, CELL * buf, int row)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_raster_row_nomask(int fd, void *buf, int row,
 			    RASTER_MAP_TYPE data_type)
 {
@@ -824,7 +753,6 @@ int G_get_raster_row_nomask(int fd, void *buf, int row,
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_c_raster_row_nomask(int fd, CELL * buf, int row)
 {
     return G_get_raster_row_nomask(fd, buf, row, CELL_TYPE);
@@ -844,7 +772,6 @@ int G_get_c_raster_row_nomask(int fd, CELL * buf, int row)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_f_raster_row_nomask(int fd, FCELL * buf, int row)
 {
     return G_get_raster_row_nomask(fd, buf, row, FCELL_TYPE);
@@ -864,14 +791,11 @@ int G_get_f_raster_row_nomask(int fd, FCELL * buf, int row)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_d_raster_row_nomask(int fd, DCELL * buf, int row)
 {
     return G_get_raster_row_nomask(fd, buf, row, DCELL_TYPE);
 }
 
-/*--------------------------------------------------------------------------*/
-
 /*!
  * \brief Get raster row (this routine is deprecated!)
  *
@@ -891,7 +815,6 @@ int G_get_d_raster_row_nomask(int fd, DCELL * buf, int row)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_map_row(int fd, CELL * buf, int row)
 {
     return get_map_row(fd, buf, row, CELL_TYPE, 1, 1);
@@ -939,7 +862,6 @@ int G_get_map_row(int fd, CELL * buf, int row)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_raster_row(int fd, void *buf, int row, RASTER_MAP_TYPE data_type)
 {
     return get_map_row(fd, buf, row, data_type, 0, 1);
@@ -966,7 +888,6 @@ int G_get_raster_row(int fd, void *buf, int row, RASTER_MAP_TYPE data_type)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_c_raster_row(int fd, CELL * buf, int row)
 {
     return G_get_raster_row(fd, buf, row, CELL_TYPE);
@@ -989,7 +910,6 @@ int G_get_c_raster_row(int fd, CELL * buf, int row)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_f_raster_row(int fd, FCELL * buf, int row)
 {
     return G_get_raster_row(fd, buf, row, FCELL_TYPE);
@@ -1009,18 +929,11 @@ int G_get_f_raster_row(int fd, FCELL * buf, int row)
  * \return 0 row requested not within window
  * \return -1 on error
  */
-
 int G_get_d_raster_row(int fd, DCELL * buf, int row)
 {
     return G_get_raster_row(fd, buf, row, DCELL_TYPE);
 }
 
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
-/*--------------------------------------------------------------------------*/
-
 static int open_null_read(int fd)
 {
     struct fileinfo *fcb = &G__.fileinfo[fd];

lib/gis/history.c

@@ -1,117 +1,95 @@
-
-/**********************************************************************
- *
- *  G_read_history (name, mapset, phist)
- *      char *name                   name of map
- *      char *mapset                 mapset that map belongs to
- *      struct History *phist        structure to hold history info
- *
- *  Reads the history information associated with map layer "map"
- *  in mapset "mapset" into the structure "phist".
- *
- *   returns:    0  if successful
- *              -1  on fail
- *
- *  note:   a warning message is printed if the file is incorrect
- *
- **********************************************************************
- *
- *  G_write_history (name, phist)
- *      char *name                   name of map
- *      struct History *phist        structure holding history info
- *
- *  Writes the history information associated with map layer "map"
- *  into current from the structure "phist".
- *
- *   returns:    0  if successful
- *              -1  on fail
- ***********************************************************************
- *
- *  G_short_history (name, type, hist)
- *     char *name             name of cell file
- *     char *type             type of cell file
- *     struct History *hist   History structure to be filled in
- *
- *  Puts local information like time and date, user's name, map name,
- *  and current mapset name into the hist structure
- *
- *  NOTE: use G_write_history() to write the structure.
- **********************************************************************
+/*!
+ * \file gis/history.c
  *
- *  G_command_history (hist)
- *     struct History *hist   History structure to be filled in
+ * \brief GIS Library - History management
  *
- *  Appends (parsed) command line to history structure's comments
+ * (C) 2001-2009 GRASS Development Team
  *
- * Returns:
- *     0 success
- *     1 failure (history file full, no change)
- *     2 failure (history file full, added as much as we could)
+ * This program is free software under the GNU General Public License 
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- *  NOTE: initialize structure with G_short_history() first.
- *  NOTE: use G_write_history() to write the structure.
- **********************************************************************/
+ * \author Original author CERL
+ */
 
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
+static void print_history_error(const char *, const char *, FILE *);
 
 /*!
- * \brief read raster history file
+ * \brief Read raster history file
+ *
+ * This routine reads the history file for the raster map <i>name</i>
+ * in <i>mapset</i> into the <i>hist</i> structure.
+ *
+ * A diagnostic message is printed and -1 is returned if there is an
+ * error reading the history file. Otherwise, 0 is returned.
  *
- * This routine reads the history file for
- * the raster map <b>name</b> in <b>mapset</b> into the <b>history</b>
- * structure.
- * A diagnostic message is printed and -1 is returned if there is an error
- * reading the history file. Otherwise, 0 is returned.
+ * \param name map name
+ * \param mapset mapset name
+ * \param hist pointer to History structure which holds history info
  *
- *  \param name
- *  \param mapset
- *  \param history
- *  \return int
+ * \return -1 on error
+ * \return 0 on success
  */
-
 int G_read_history(const char *name, const char *mapset, struct History *hist)
 {
     FILE *fd;
 
     G_zero(hist, sizeof(struct History));
     fd = G_fopen_old("hist", name, mapset);
-    if (!fd)
-	goto error;
-
+    if (!fd) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
 
-    if (!G_getl(hist->mapid, sizeof(hist->mapid), fd))
-	goto error;
+    if (!G_getl(hist->mapid, sizeof(hist->mapid), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->mapid);
 
-    if (!G_getl(hist->title, sizeof(hist->title), fd))
-	goto error;
+    if (!G_getl(hist->title, sizeof(hist->title), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->title);
 
-    if (!G_getl(hist->mapset, sizeof(hist->mapset), fd))
-	goto error;
+    if (!G_getl(hist->mapset, sizeof(hist->mapset), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->mapset);
 
-    if (!G_getl(hist->creator, sizeof(hist->creator), fd))
-	goto error;
+    if (!G_getl(hist->creator, sizeof(hist->creator), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->creator);
 
-    if (!G_getl(hist->maptype, sizeof(hist->maptype), fd))
-	goto error;
+    if (!G_getl(hist->maptype, sizeof(hist->maptype), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->maptype);
 
-    if (!G_getl(hist->datsrc_1, sizeof(hist->datsrc_1), fd))
-	goto error;
+    if (!G_getl(hist->datsrc_1, sizeof(hist->datsrc_1), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->datsrc_1);
 
-    if (!G_getl(hist->datsrc_2, sizeof(hist->datsrc_2), fd))
-	goto error;
+    if (!G_getl(hist->datsrc_2, sizeof(hist->datsrc_2), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->datsrc_2);
 
-    if (!G_getl(hist->keywrd, sizeof(hist->keywrd), fd))
-	goto error;
+    if (!G_getl(hist->keywrd, sizeof(hist->keywrd), fd)) {
+	print_history_error(name, mapset, fd);
+	return -1;
+    }
     G_ascii_check(hist->keywrd);
 
     hist->edlinecnt = 0;
@@ -122,43 +100,54 @@ int G_read_history(const char *name, const char *mapset, struct History *hist)
 	hist->edlinecnt++;
     }
 
-
     fclose(fd);
+
     return 0;
+}
 
-  error:
+void print_history_error(const char *name, const char *mapset, FILE *fd)
+{
     if (fd != NULL)
 	fclose(fd);
-    G_warning(_("can't get history information for [%s] in mapset [%s]"),
-	      name, mapset);
-    return -1;
+    
+    if (mapset) {
+	G_warning(_("Unable to get history information for <%s@%s>"),
+		  name, mapset);
+    }
+    else { /* write */
+	G_warning(_("Unable to write history information for <%s>"), name);
+    }
 }
 
-
 /*!
- * \brief write raster history file
+ * \brief Write raster history file
  *
  * This routine writes the history file for the raster map
- * <b>name</b> in the current mapset from the <b>history</b> structure.
- * A diagnostic message is printed and -1 is returned if there is an error
- * writing the history file. Otherwise, 0 is returned.
- * <b>Note.</b> The <b>history</b> structure should first be initialized
- * using <i>G_short_history.</i>
+ * <i>name</i> in the current mapset from the <i>hist</i> structure.
+ *
+ * A diagnostic message is printed and -1 is returned if there is an
+ * error writing the history file. Otherwise, 0 is returned.
+ *
+ * <b>Note:</b> The <i>hist</i> structure should first be initialized
+ * using G_short_history().
+ *
+ * \param name map name
+ * \param[out] hist pointer to History structure which holds history info
  *
- *  \param name
- *  \param history
- *  \return int
+ * \return -1 on error
+ * \return 0 on success
  */
-
 int G_write_history(const char *name, struct History *hist)
 {
     FILE *fd;
     int i;
 
     fd = G_fopen_new("hist", name);
-    if (!fd)
-	goto error;
-
+    if (!fd) {
+	print_history_error(name, NULL, fd);
+	return -1;
+    }
+    
     fprintf(fd, "%s\n", hist->mapid);
     fprintf(fd, "%s\n", hist->title);
     fprintf(fd, "%s\n", hist->mapset);
@@ -172,33 +161,25 @@ int G_write_history(const char *name, struct History *hist)
 	fprintf(fd, "%s\n", hist->edhist[i]);
 
     fclose(fd);
+    
     return 0;
-
-  error:
-    if (fd)
-	fclose(fd);
-    G_warning(_("can't write history information for [%s]"), name);
-    return -1;
 }
 
-
-
 /*!
- * \brief initialize history structure
+ * \brief Initialize history structure
+ *
+ * This routine initializes the <i>hist</i> structure, recording the
+ * date, user, module name and the raster map <i>name</i>
+ * structure. The <i>type</i> is an anachronism from earlier versions
+ * of GRASS and should be specified as "raster".
  *
- * This routine initializes the
- * <b>history</b> structure, recording the date, user, module name and the
- * raster map <b>name</b> structure. The <b>type</b> is an anachronism from
- * earlier versions of GRASS and should be specified as "raster".
- * <b>Note.</b> This routine only initializes the data structure. It does not
- * write the history file.
+ * <b>Note:</b> This routine only initializes the data structure. It
+ * does not write the history file.
  *
- *  \param name
- *  \param type
- *  \param history
- *  \return
+ * \param name map name
+ * \param type map type
+ * \param hist pointer to History structure which holds history info
  */
-
 void G_short_history(const char *name, const char *type, struct History *hist)
 {
     strncpy(hist->mapid, G_date(), RECORD_LEN);
@@ -207,7 +188,7 @@ void G_short_history(const char *name, const char *type, struct History *hist)
     strncpy(hist->creator, G_whoami(), RECORD_LEN);
     strncpy(hist->maptype, type, RECORD_LEN);
 
-    sprintf(hist->keywrd, "generated by %s", G_program_name());
+    sprintf(hist->keywrd, _("generated by %s"), G_program_name());
     strcpy(hist->datsrc_1, "");
     strcpy(hist->datsrc_2, "");
     hist->edlinecnt = 0;
@@ -216,39 +197,36 @@ void G_short_history(const char *name, const char *type, struct History *hist)
 /*!
  * \brief Save command line to raster history structure
  *
- * This routine takes an existing (run <i>G_short_history first</i>) history
- *  structure and adds the command line to the end of the comments array, as
- *  cleaned & expanded by the parser.
+ * This routine takes an existing (run G_short_history first() history
+ * structure and adds the command line to the end of the comments
+ * array, as cleaned & expanded by the parser.
  *
  * History file is limited to [80]x[50], as defined in include/gis.h
  *
- * * First version had for loops of [i][j] character assignments and ending
- *   nulls, but using the string libraries is cleaner and less bug prone.
- * * Second version had white space detection, intelligent wrapping, and
- *   indentation of continued lines, but this proved a pain in the neck for 
- *   things like r.patch which can have long strings without any
- *   parser-acceptable breaks.
- * * This is MK-III, simplified, but that's good: it's cut & paste-able.
+ *  - First version had for loops of [i][j] character assignments and ending
+ *    nulls, but using the string libraries is cleaner and less bug prone.
+ *  - Second version had white space detection, intelligent wrapping, and
+ *    indentation of continued lines, but this proved a pain in the neck for 
+ *    things like r.patch which can have long strings without any
+ *    parser-acceptable breaks.
+ *  - This is MK-III, simplified, but that's good: it's cut & paste-able.
  *
- *  NOTE: use G_write_history() to write the structure.
+ * Note: use G_write_history() to write the structure.
  *
  * Sample Usage:
- *
+ * \code
  *   struct History history;
  *   G_short_history(rasterfile, "raster", &history);
  *   G_command_history(&history);
  *   G_write_history(rasterfile, &history);
+ * \endcode
  *
- * Returns:
- *     0 success
- *     1 failure (history file full, no change)
- *     2 failure (history file full, added as much as we could)
- *
- * \param history
- * \return int
+ * \param hist pointer to History structure which holds history info
  *
+ * \return 0 on success
+ * \return 1 on failure (history file full, no change)
+ * \return 2 on failure (history file full, added as much as we could)
  */
-
 int G_command_history(struct History *hist)
 {
     int j, cmdlen;
@@ -258,7 +236,7 @@ int G_command_history(struct History *hist)
     cmdlen = strlen(cmdlin);
 
     if (hist->edlinecnt > MAXEDLINES - 2) {
-	G_warning(_("Not enough room in history file to record command line."));
+	G_warning(_("Not enough room in history file to record command line"));
 	return 1;
     }
 
@@ -280,7 +258,7 @@ int G_command_history(struct History *hist)
 	    j += 68;
 	    hist->edlinecnt++;
 	    if (hist->edlinecnt > MAXEDLINES - 2) {
-		G_warning(_("Not enough room in history file for command line (truncated)."));
+		G_warning(_("Not enough room in history file for command line (truncated)"));
 		return 2;
 	    }
 	}

lib/gis/maskfd.c

@@ -1,24 +1,20 @@
-
-/**
- * \file maskfd.c
+/*!
+ * \file gis/maskfd.c
  *
  * \brief GIS Library - Mask 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>
 #include "G.h"
 
-
-/**
+/*!
  * \brief Test for MASK.
  *
  * \return -1 if no MASK

lib/gis/null_val.c

@@ -1,21 +1,19 @@
-/*
+/*!
+ * \file gis/null_value.c
  *
- *****************************************************************************
+ * \brief GIS Library - NULL value management
  *
- * MODULE:      GRASS gis library
- * AUTHOR(S):   Original author unknown - probably CERL
- *              Justin Hickey - Thailand - jhickey@hpcc.nectec.or.th
- * PURPOSE:     To provide functionality to handle NULL values for data types
- *              CELL, FCELL, and DCELL. May need more...
- * COPYRIGHT:    (C) 2000 by the GRASS Development Team
+ * To provide functionality to handle NULL values for data types CELL,
+ * FCELL, and DCELL. May need more...
  *
- *               This program is free software under the GNU General Public
- *              License (>=v2). Read the file COPYING that comes with GRASS
- *              for details.
+ * (C) 2001-2009 GRASS Development Team
  *
- *****************************************************************************/
-
-/*============================= Include Files ==============================*/
+ * 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 unknown - probably CERL
+ * \author Justin Hickey - Thailand - jhickey@hpcc.nectec.or.th
+ */
 
 /* System include files */
 #include <string.h>
@@ -26,19 +24,16 @@
 
 static void EmbedGivenNulls(void *, char *, RASTER_MAP_TYPE, int);
 
-/****************************************************************************
-* int EmbedGivenNulls (void *cell, char *nulls, RASTER_MAP_TYPE map_type,
-*   int ncols)
-*
-* PURPOSE: 	To insert null values into a map. Needs more.....
-* INPUT VARS:	cell	    =>	??
-*   	    	nulls	    =>	??
-*   	    	map_type    =>	type of raster - CELL, FCELL, DCELL
-*   	    	ncols	    =>	??
-* RETURN VAL:	??
-*****************************************************************************/
-static void EmbedGivenNulls(void *cell, char *nulls, RASTER_MAP_TYPE map_type,
-			   int ncols)
+/*!
+  \brief To insert null values into a map. Needs more.....
+
+  \param cell raster values
+  \param nulls raster null values
+  \param map_type type of raster - CELL, FCELL, DCELL
+  \param ncols number of columns
+*/
+void EmbedGivenNulls(void *cell, char *nulls, RASTER_MAP_TYPE map_type,
+		     int ncols)
 {
     CELL *c;
     FCELL *f;
@@ -65,26 +60,22 @@ static void EmbedGivenNulls(void *cell, char *nulls, RASTER_MAP_TYPE map_type,
 		break;
 
 	    default:
-		G_warning(_("EmbedGivenNulls: wrong data type!"));
+		G_warning(_("EmbedGivenNulls: wrong data type"));
 	    }
 	}
     }
 }
 
-/*========================== Library Functions =============================*/
-
-/****************************************************************************
-* void G__set_null_value (void *rast, int numVals, int null_is_zero,
-*   RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: 	To set one or more raster values to null. It also sets null
-*   	    	to zero if null_is_zero is TRUE.
-* INPUT VARS:	rast	    	=>  pointer to values to set to null
-*   	    	numVals     	=>  number of values to set to null
-*   	    	null_is_zero	=>  flag to indicate if NULL = 0
-*   	    	data_type   	=>  type of raster - CELL, FCELL, DCELL
-* RETURN VAL:	none
-*****************************************************************************/
+/*!
+  \brief To set one or more raster values to null.
+
+  It also sets null to zero if null_is_zero is TRUE.
+
+  \param rast pointer to values to set to null
+  \param numVals number of values to set to null
+  \param null_is_zero flag to indicate if NULL = 0
+  \param data_type type of raster - CELL, FCELL, DCELL
+*/
 void G__set_null_value(void *rast, int numVals, int null_is_zero,
 		       RASTER_MAP_TYPE data_type)
 {
@@ -96,15 +87,13 @@ void G__set_null_value(void *rast, int numVals, int null_is_zero,
     G_set_null_value(rast, numVals, data_type);
 }
 
-/****************************************************************************
-* void G_set_null_value (void *buf, int numVals, RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: 	To set one or more raster values to null.
-* INPUT VARS:	buf	    =>	pointer to values to set to null
-*   	    	numVals     =>	number of values to set to null
-*   	    	data_type   =>	type of raster - CELL, FCELL, DCELL
-* RETURN VAL:	none
-*****************************************************************************/
+/*!
+ \brief To set one or more raster values to null.
+
+ \param buf pointer to values to set to null
+ \param numVals number of values to set to null
+ \param data_type type of raster - CELL, FCELL, DCELL
+*/
 void G_set_null_value(void *buf, int numVals, RASTER_MAP_TYPE data_type)
 {
     switch (data_type) {
@@ -125,14 +114,12 @@ void G_set_null_value(void *buf, int numVals, RASTER_MAP_TYPE data_type)
     }
 }
 
-/****************************************************************************
-* void G_set_c_null_value (CELL *cellVals, int numVals)
-*
-* PURPOSE: 	To set a number of CELL raster values to NULL.
-* INPUT VARS:	cellVals    =>	pointer to CELL values to set to null
-*   	    	numVals     =>	number of values to set to null
-* RETURN VAL:	none
-*****************************************************************************/
+/*!
+  \brief To set a number of CELL raster values to NULL.
+  
+  \param cellVals pointer to CELL values to set to null
+  \param numVals  number of values to set to null
+*/
 void G_set_c_null_value(CELL *cellVals, int numVals)
 {
     int i;			/* counter */
@@ -141,14 +128,12 @@ void G_set_c_null_value(CELL *cellVals, int numVals)
 	cellVals[i] = (int) 0x80000000;
 }
 
-/****************************************************************************
-* void G_set_f_null_value (FCELL *fcellVals, int numVals)
-*
-* PURPOSE: 	To set a number of FCELL raster values to NULL.
-* INPUT VARS:	fcellVals   =>	pointer to FCELL values to set to null
-*   	    	numVals     =>	number of values to set to null
-* RETURN VAL:	none
-*****************************************************************************/
+/*!
+ \brief To set a number of FCELL raster values to NULL.
+
+ \param fcellVals pointer to FCELL values to set to null
+ \param numVals number of values to set to null
+*/
 void G_set_f_null_value(FCELL *fcellVals, int numVals)
 {
     static const unsigned char null_bits[4] = {
@@ -159,14 +144,12 @@ void G_set_f_null_value(FCELL *fcellVals, int numVals)
 	memcpy(&fcellVals[i], null_bits, sizeof(null_bits));
 }
 
-/****************************************************************************
-* void G_set_d_null_value (DCELL *dcellVals, int numVals)
-*
-* PURPOSE: 	To set a number of DCELL raster values to NULL.
-* INPUT VARS:	dcellVals   =>	pointer to DCELL values to set to null
-*   	    	numVals     =>	number of values to set to null
-* RETURN VAL:	none
-*****************************************************************************/
+/*!
+  \brief To set a number of DCELL raster values to NULL.
+  
+  \param dcellVals pointer to DCELL values to set to null
+  \param numVals number of values to set to null
+*/
 void G_set_d_null_value(DCELL *dcellVals, int numVals)
 {
     static const unsigned char null_bits[8] = {
@@ -177,27 +160,19 @@ void G_set_d_null_value(DCELL *dcellVals, int numVals)
 	memcpy(&dcellVals[i], null_bits, sizeof(null_bits));
 }
 
-/****************************************************************************
-* int G_is_null_value (void *rast, RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: 	To check if a raster value is set to NULL
-* INPUT VARS:	rast	    =>	raster value to check 
-*   	    	data_type   =>	type of raster - CELL, FCELL, DCELL
-* RETURN VAL:	TRUE if raster value is NULL FALSE otherwise
-*****************************************************************************/
-
 /*!
- * \brief 
- *
- * If the <em>data_type</em> is CELL_TYPE, calls G_is_c_null_value ((CELL *) rast);
- * If the <em>data_type</em> is FCELL_TYPE, calls G_is_f_null_value ((FCELL *) rast);
- * If the <em>data_type</em> is DCELL_TYPE, calls G_is_d_null_value ((DCELL *) rast);
- *
- *  \param rast
- *  \param data_type
- *  \return int
- */
+  \brief To check if a raster value is set to NULL
 
+    - If the <em>data_type</em> is CELL_TYPE, calls G_is_c_null_value()
+    - If the <em>data_type</em> is FCELL_TYPE, calls G_is_f_null_value()
+    - If the <em>data_type</em> is DCELL_TYPE, calls G_is_d_null_value()
+  
+  \param rast raster value to check 
+  \param data_type type of raster - CELL, FCELL, DCELL
+
+  \return TRUE if raster value is NULL
+  \return FALSE otherwise
+ */
 int G_is_null_value(const void *rast, RASTER_MAP_TYPE data_type)
 {
     switch (data_type) {
@@ -216,221 +191,141 @@ int G_is_null_value(const void *rast, RASTER_MAP_TYPE data_type)
     }
 }
 
-/****************************************************************************
-* 
-* int G_is_c_null_value (CELL *cellVal)
-*
-* PURPOSE: 	To check if a CELL raster value is set to NULL
-* INPUT VARS:	cellVal    =>	CELL raster value to check
-* RETURN VAL:	TRUE if CELL raster value is NULL FALSE otherwise
-*****************************************************************************/
-
 /*!
- * \brief 
- *
- * Returns 1 if <em>cell</em> is NULL, 0 otherwise. This will test if the
- * value <em>cell</em> is the largest <tt>int</tt>.
- *
- *  \param cell
- *  \return int
- */
+  \brief To check if a CELL raster value is set to NULL
+
+  Returns 1 if <em>cell</em> is NULL, 0 otherwise. This will test if the
+  value <em>cell</em> is the largest <tt>int</tt>.
 
+  \param cellVal CELL raster value to check
+
+  \return TRUE if CELL raster value is NULL
+  \return FALSE otherwise
+*/
 int G_is_c_null_value(const CELL * cellVal)
 {
     /* Check if the CELL value matches the null pattern */
     return *cellVal == (CELL) 0x80000000;
 }
 
-/****************************************************************************
-* 
-* int G_is_f_null_value (FCELL *fcellVal)
-*
-* PURPOSE: 	To check if a FCELL raster value is set to NULL
-* INPUT VARS:	fcellVal    =>	FCELL raster value to check
-* RETURN VAL:	TRUE if FCELL raster value is NULL FALSE otherwise
-*****************************************************************************/
-
 /*!
- * \brief 
- *
- * Returns 1 if <em>fcell</em>
- * is NULL, 0 otherwise. This will test if the value <em>fcell</em> is a NaN. It
- * isn't good enough to test for a particular NaN bit pattern since the machine
- * code may change this bit pattern to a different NaN. The test will be
- \code
- if(fcell==0.0) return 0;
- if(fcell>0.0) return 0;
- if(fcell<0.0) return 0;
- return 1;
- \endcode
- * or (as suggested by Mark Line)
- \code
- return (fcell != fcell);
- \endcode
- *
- *  \param fcell
- *  \return int
- */
-
+  \brief To check if a FCELL raster value is set to NULL
+
+  Returns 1 if <em>fcell</em> is NULL, 0 otherwise. This will test if
+  the value <em>fcell</em> is a NaN. It isn't good enough to test for
+  a particular NaN bit pattern since the machine code may change this
+  bit pattern to a different NaN. The test will be
+
+  \code
+  if(fcell==0.0) return 0;
+  if(fcell>0.0) return 0;
+  if(fcell<0.0) return 0;
+  return 1;
+  \endcode
+ 
+  or (as suggested by Mark Line)
+  \code
+  return (fcell != fcell);
+  \endcode
+
+  \param fcellVal FCELL raster value to check
+
+  \return TRUE if FCELL raster value is NULL
+  \return FALSE otherwise
+*/
 int G_is_f_null_value(const FCELL * fcellVal)
 {
     return *fcellVal != *fcellVal;
 }
 
-/****************************************************************************
-* 
-* int G_is_d_null_value (DCELL *dcellVal)
-*
-* PURPOSE: 	To check if a DCELL raster value is set to NULL
-* INPUT VARS:	dcellVal    =>	DCELL raster value to check
-* RETURN VAL:	TRUE if DCELL raster value is NULL FALSE otherwise
-*****************************************************************************/
-
 /*!
- * \brief 
- *
- * Returns 1 if <em>dcell</em> is
- * NULL, 0 otherwise. This will test if the value <em>dcell</em> is a NaN. Same
- * test as in <tt>G_is_f_null_value()</tt>.
- *
- *  \param dcell
- *  \return int
- */
+  \brief To check if a DCELL raster value is set to NULL
 
+  Returns 1 if <em>dcell</em> is NULL, 0 otherwise. This will test if
+  the value <em>dcell</em> is a NaN. Same test as in
+  G_is_f_null_value().
+
+  \param dcellVal DCELL raster value to check
+
+  \return TRUE if DCELL raster value is NULL
+  \return FALSE otherwise
+*/
 int G_is_d_null_value(const DCELL * dcellVal)
 {
     return *dcellVal != *dcellVal;
 }
 
-/****************************************************************************
-* 
-* int G_insert_null_values (void *rast, char *null_row, int ncols,
-*   RASTER_MAP_TYPE data_type)
-*
-* PURPOSE: 	To insert null values into a map. Needs more.....
-* INPUT VARS:	rast	    =>	??
-*   	    	null_row    =>	??
-*   	    	ncols	    =>	??
-*   	    	data_type   =>	type of raster - CELL, FCELL, DCELL
-* RETURN VAL:	??
-*****************************************************************************/
-
 /*!
- * \brief Insert NULL value
- *
- * If the <em>data_type</em> is
- * CELL_TYPE, calls G_insert_c_null_values ((CELL *) rast, flags, count);
- * If the <em>data_type</em> is FCELL_TYPE, calls G_insert_f_null_values
- * ((FCELL *) rast, flags, count);
- * If the <em>data_type</em> is DCELL_TYPE, calls G_insert_d_null_values
- * ((DCELL *) rast, flags, count);
- *
- *  \param rast
- *  \param flags
- *  \param count
- *  \param data_type
- *  \return
+  \brief To insert null values into a map.
+
+  - If the <em>data_type</em> is CELL_TYPE, calls G_insert_c_null_values()
+  - If the <em>data_type</em> is FCELL_TYPE, calls G_insert_f_null_values()
+  - If the <em>data_type</em> is DCELL_TYPE, calls G_insert_d_null_values()
+  
+  \param rast pointer raster values
+  \param null_row null row
+  \param ncols number of columns
+  \param data_type type of raster - CELL, FCELL, DCELL
  */
-
 void G_insert_null_values(void *rast, char *null_row, int ncols,
 			  RASTER_MAP_TYPE data_type)
 {
     EmbedGivenNulls(rast, null_row, data_type, ncols);
 }
 
-/****************************************************************************
-* 
-* int G_insert_c_null_values (CELL *cellVal, char *null_row, int ncols)
-*
-* PURPOSE: 	To insert null values into a CELL map. Needs more.....
-* INPUT VARS:	cellVal	    =>	??
-*   	    	null_row    =>	??
-*   	    	ncols	    =>	??
-* RETURN VAL:	??
-*****************************************************************************/
-
 /*!
- * \brief Insert CELL NULL value
- *
- * For each of the <em>count</em> <em>flags</em>
- * which is true(!=0), set the corresponding <em>cell</em> to the NULL value.
- *
- *  \param cell
- *  \param flags
- *  \param count
- *  \return
- */
+  \brief To insert null values into an integer raster map (CELL)
+
+  For each of the <em>count</em> <em>flags</em> which is true(!=0),
+  set the corresponding <em>cell</em> to the NULL value.
 
+  \param rast pointer raster values
+  \param null_row null row
+  \param ncols number of columns
+*/
 void G_insert_c_null_values(CELL * cellVal, char *null_row, int ncols)
 {
     EmbedGivenNulls((void *)cellVal, null_row, CELL_TYPE, ncols);
 }
 
-/****************************************************************************
-* 
-* int G_insert_f_null_values (FCELL *fcellVal, char *null_row, int ncols)
-*
-* PURPOSE: 	To insert null values into a FCELL map. Needs more.....
-* INPUT VARS:	fcellVal    =>	??
-*   	    	null_row    =>	??
-*   	    	ncols	    =>	??
-* RETURN VAL:	??
-*****************************************************************************/
-
 /*!
- * \brief Insert FCELL NULL value
- *
- * For each of the <em>count</em> <em>flags</em>
- * which is true(!=0), set the corresponding <em>fcell</em> to the NULL value.
- *
- *  \param fcell
- *  \param flags
- *  \param count
- *  \return
- */
+  \brief To insert null values into an floating-point raster map (FCELL)
 
+  \param fcellVal pointer raster values
+  \param null_row null row
+  \param ncols number of columns
+*/
 void G_insert_f_null_values(FCELL * fcellVal, char *null_row, int ncols)
 {
     EmbedGivenNulls((void *)fcellVal, null_row, FCELL_TYPE, ncols);
 }
 
-/****************************************************************************
-* 
-* int G_insert_d_null_values (DCELL *dcellVal, char *null_row, int ncols)
-*
-* PURPOSE: 	To insert null values into a DCELL map. Needs more.....
-* INPUT VARS:	dcellVal    =>	??
-*   	    	null_row    =>	??
-*   	    	ncols	    =>	??
-* RETURN VAL:	??
-*****************************************************************************/
-
 /*!
- * \brief Insert DCELL NULL value
- *
- * For each for the <em>count</em> <em>flag</em>
- * which is true(!=0), set the corresponding <em>dcell</em> to the NULL value.
- *
- *  \param dcell
- *  \param flags
- *  \param count
- *  \return
- */
+  \brief To insert null values into an floating-point raster map (FCELL)
+
+  For each for the <em>count</em> <em>flag</em> which is true(!=0), set
+  the corresponding <em>dcell</em> to the NULL value.
 
+  \param dcellVal pointer raster values
+  \param null_row null row
+  \param ncols number of columns
+*/
 void G_insert_d_null_values(DCELL * dcellVal, char *null_row, int ncols)
 {
     EmbedGivenNulls((void *)dcellVal, null_row, DCELL_TYPE, ncols);
 }
 
-/****************************************************************************
-* int G__check_null_bit (unsigned char *flags, int bit_num, int n)
-*
-* PURPOSE: 	To...
-* INPUT VARS:	flags	=>  ??
-*   	    	bit_num =>  ??
-*   	    	n   	=>  ??
-* RETURN VAL:	??
-*****************************************************************************/
+/*!
+  \brief Check NULL
+
+  Note: Only for internal use.
+
+  \param flags ?
+  \param bit_num ?
+  \param n ?
+
+  \return -1 on error
+*/
 int G__check_null_bit(const unsigned char *flags, int bit_num, int n)
 {
     int ind;
@@ -442,9 +337,9 @@ int G__check_null_bit(const unsigned char *flags, int bit_num, int n)
     /* find how many unsigned chars the buffer with bit_num+1 (counting from 0
        has and subtract 1 to get unsigned char index */
     if (ind > G__null_bitstream_size(n) - 1) {
-	G_warning("G__check_null_bit: can't access index %d. "
+	G_warning("G__check_null_bit: Unable to access index %d. "
 		  "Size of flags is %d (bit # is %d)",
-	     ind, G__null_bitstream_size(n) - 1, bit_num);
+		  ind, G__null_bitstream_size(n) - 1, bit_num);
 	return -1;
     }
 
@@ -453,20 +348,23 @@ int G__check_null_bit(const unsigned char *flags, int bit_num, int n)
     return ((flags[ind] & ((unsigned char)1 << offset)) != 0);
 }
 
-/****************************************************************************
-* int G__set_flags_from_01_random (char *zero_ones, unsigned char *flags, 
-*   int col, int n, int ncols)
-*
-* PURPOSE: 	given array of 0/1 of length n starting from column col
-*   	    	set the corresponding  bits of flags; total number of bits
-*   	    	in flags is ncols
-* INPUT VARS:	zero_ones   =>	??
-*   	    	flags	    =>	??
-*   	    	col 	    =>	??
-*   	    	n   	    =>	??
-*   	    	ncols	    =>	??
-* RETURN VAL:	??
-*****************************************************************************/
+/*!
+  \brief Given array of 0/1 of length n starting from column.
+
+  Note: Only for internal use.
+  
+  Given array of 0/1 of length n starting from column set the
+  corresponding bits of flags; total number of bits in flags is ncols.
+
+  \param zero_ones
+  \param flags
+  \param col
+  \param n
+  \param ncols
+
+  \return 0
+  \return 1
+*/
 int G__set_flags_from_01_random(const char *zero_ones, unsigned char *flags,
 				int col, int n, int ncols)
 {
@@ -506,15 +404,15 @@ int G__set_flags_from_01_random(const char *zero_ones, unsigned char *flags,
     return 1;
 }
 
-/****************************************************************************
-* int G__convert_01_flags (char *zero_ones, unsigned char *flags, int n)
-*
-* PURPOSE: 	To...
-* INPUT VARS:	zero_ones   =>	??
-*   	    	flags	    =>	??
-*   	    	n   	    =>	??
-* RETURN VAL:	??
-*****************************************************************************/
+/*!
+  \brief ?
+
+  Note: Only for internal use.
+  
+  \param zero_ones
+  \param flags
+  \param n
+*/
 void G__convert_01_flags(const char *zero_ones, unsigned char *flags, int n)
 {
     unsigned char *v;
@@ -543,15 +441,15 @@ void G__convert_01_flags(const char *zero_ones, unsigned char *flags, int n)
     }
 }
 
-/****************************************************************************
-* int G__convert_flags_01 (char *zero_ones, unsigned char *flags, int n)
-*
-* PURPOSE: 	To...
-* INPUT VARS:	zero_ones   =>	??
-*   	    	flags	    =>	??
-*   	    	n   	    =>	??
-* RETURN VAL:	??
-*****************************************************************************/
+/*!
+  \brief ?
+
+  Note: Only for internal use.
+
+  \param zero_ones
+  \param flags
+  \param n
+ */
 void G__convert_flags_01(char *zero_ones, const unsigned char *flags, int n)
 {
     const unsigned char *v;
@@ -577,14 +475,14 @@ void G__convert_flags_01(char *zero_ones, const unsigned char *flags, int n)
     }
 }
 
-/****************************************************************************
-* int G__init_null_bits (unsigned char *flags, int cols)
-*
-* PURPOSE: 	To...
-* INPUT VARS:	flags	=>  ??
-*   	    	cols	=>  ??
-* RETURN VAL:	??
-*****************************************************************************/
+/*!
+  \brief ?
+
+  Note: Only for internal use.
+
+  \param flags
+  \param cols
+ */
 void G__init_null_bits(unsigned char *flags, int cols)
 {
     unsigned char *v;

lib/gis/opencell.c

@@ -1,9 +1,9 @@
 /*!
  * \file gis/opencell.c
  * 
- * \brief GIS Library - open raster (cell) file functions
+ * \brief GIS Library - Open raster file
  *
- * (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
@@ -24,6 +24,8 @@
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
+#define FORMAT_FILE "f_format"
+
 static struct fileinfo *new_fileinfo(int fd)
 {
     int oldsize = G__.fileinfo_count;
@@ -52,19 +54,24 @@ static struct fileinfo *new_fileinfo(int fd)
 
 
 /*!
- * \brief 
+ * \brief Open raster file
  *
- * Arrange for the NULL-value bitmap to be
- * read as well as the raster map.  If no NULL-value bitmap exists, arrange for
- * the production of NULL-values based on zeros in the raster map.
- * If the map is floating-point, arrange for quantization to integer for 
- * <tt>G_get_c_raster_row()</tt>, et. al., by reading the quantization rules for
- * the map using <tt>G_read_quant()</tt>.
- * If the programmer wants to read the floating point map using uing quant rules
- * other than the ones stored in map's quant file, he/she should call
- * G_set_quant_rules() after the call to G_open_cell_old().
+ * Arrange for the NULL-value bitmap to be read as well as the raster
+ * map. If no NULL-value bitmap exists, arrange for the production of
+ * NULL-values based on zeros in the raster map. If the map is
+ * floating-point, arrange for quantization to integer for
+ * G_get_c_raster_row(), et. al., by reading the quantization rules
+ * for the map using G_read_quant(). If the programmer wants to read
+ * the floating point map using uing quant rules other than the ones
+ * stored in map's quant file, he/she should call G_set_quant_rules()
+ * after the call to G_open_cell_old().
  *
- *  \return int
+ * \param name map name
+ * \param open_mode mode
+ * \param map_type map type (CELL, FCELL, DCELL)
+ *
+ * \return open file descriptor ( >= 0) if successful
+ *  \return negative integer if error
  */
 
 static int G__open_raster_new(const char *name, int open_mode,
@@ -83,10 +90,10 @@ static int G__open_raster_new(const char *name, int open_mode,
   GRASS users expect that all raster maps will be resampled into the
   current region, the resampling index for the raster map is prepared
   by this routine after the file is opened. The resampling is based on
-  the active module region.\remarks{See also The_Region.} Preparation
-  required for reading the various raster file formats\remarks{See
+  the active module region (see also \ref The_Region}. Preparation
+  required for reading the various raster file formats (see \ref
   Raster_File_Format for an explanation of the various raster file
-  formats.} is also done.
+  formats) is also done.
  
   Diagnostics: warning message printed if open fails.
 
@@ -118,9 +125,8 @@ int G_open_cell_old(const char *name, const char *mapset)
     return fd;
 }
 
-/*!
-  \brief Lower level function, open cell files, supercell
-  files, and the MASK file. 
+/*!  \brief Lower level function, open cell files, supercell files,
+  and the MASK file.
 
   Actions:
    - opens the named cell file, following reclass reference if
@@ -128,15 +134,13 @@ int G_open_cell_old(const char *name, const char *mapset)
    - creates the required mapping between the data and the window
    for use by the get_map_row family of routines.
   
-  Diagnostics:
-  Errors other than actual open failure will cause a diagnostic to be
-  delivered thru G_warning() open failure messages are left to the
-  calling routine since the masking logic will want to issue a different
-  warning.
+  Diagnostics: Errors other than actual open failure will cause a
+  diagnostic to be delivered thru G_warning() open failure messages
+  are left to the calling routine since the masking logic will want to
+  issue a different warning.
   
-  Note:
-  This routine does NOT open the MASK layer. If it did we would get
-  infinite recursion.  This routine is called to open the mask by
+  Note: This routine does NOT open the MASK layer. If it did we would
+  get infinite recursion.  This routine is called to open the mask by
   G__check_for_auto_masking() which is called by G_open_cell_old().
  
   \param name map name
@@ -344,8 +348,6 @@ int G__open_cell_old(const char *name, const char *mapset)
     return fd;
 }
 
-/*****************************************************************/
-
 /*!
   \brief Opens a new cell file in a database (compressed)
 
@@ -400,8 +402,6 @@ int G_open_cell_new_uncompressed(const char *name)
   otherwise set flag=0. Applies to subsequent opens.
 
   \param flag flag indicator
-
-  \return 0
 */
 void G_want_histogram(int flag)
 {
@@ -412,15 +412,13 @@ void G_want_histogram(int flag)
   \brief Sets the format for subsequent opens on new integer cell files
   (uncompressed and random only).
 
-  Warning: subsequent put_row calls will only write n+1 bytes
-  per cell. If the data requires more, the cell file
-  will be written incorrectly (but with n+1 bytes per cell)
+  Warning: subsequent put_row calls will only write n+1 bytes per
+  cell. If the data requires more, the cell file will be written
+  incorrectly (but with n+1 bytes per cell)
 
   When writing float map: format is -1
 
   \param n format
-  
-  \return 0
 */
 void G_set_cell_format(int n)
 /* sets the format for integer raster map */
@@ -716,10 +714,10 @@ static int G__open_raster_new(const char *name, int open_mode,
   \brief Set raster map floating-point data format.
   
   This controls the storage type for floating-point maps. It affects
-  subsequent calls to G_open_fp_map_new(). The <em>type</em>
-  must be one of FCELL_TYPE (float) or DCELL_TYPE
-  (double). The use of this routine by applications is discouraged
-  since its use would override user preferences.
+  subsequent calls to G_open_fp_map_new(). The <i>type</i> must be
+  one of FCELL_TYPE (float) or DCELL_TYPE (double). The use of this
+  routine by applications is discouraged since its use would override
+  user preferences.
   
   \param type raster data type
 
@@ -739,10 +737,6 @@ int G_set_fp_type(RASTER_MAP_TYPE map_type)
     }
 }
 
-
-#define FORMAT_FILE "f_format"
-
-
 /*!
   \brief Check if raster map is floating-point
  
@@ -762,7 +756,7 @@ int G_raster_map_is_fp(const char *name, const char *mapset)
 
     xmapset = G_find_cell2(name, mapset);
     if (!xmapset) {
-	G_warning(_("Unable to find '%s' in '%s'"), name, mapset);
+	G_warning(_("Unable to find <%s@%s>"), name, mapset);
 	return -1;
     }
     G__file_name(path, "fcell", name, xmapset);
@@ -779,7 +773,7 @@ int G_raster_map_is_fp(const char *name, const char *mapset)
   \brief Determine raster data type
   
   Determines if the raster map is floating point or integer. Returns
-  DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for 
+  DCELL_TYPE for double maps, FCELL_TYPE for float maps, CELL_TYPE for
   integer maps, -1 if error has occured
 
   \param name map name 
@@ -850,7 +844,7 @@ RASTER_MAP_TYPE G__check_fp_type(const char *name, const char *mapset)
 
     xmapset = G_find_cell2(name, mapset);
     if (!xmapset) {
-	G_warning(_("Unable to find '%s' in '%s'"), name, mapset);
+	G_warning(_("Unable to find <%s@%s>"), name, mapset);
 	return -1;
     }
     G__file_name_misc(path, "cell_misc", FORMAT_FILE, name, xmapset);

lib/gis/progrm_nme.c

@@ -1,40 +1,42 @@
-
-/**********************************************************************
- *
- *   char *
- *   G_program_name()
- *
- *   returns the current program name
+/*!
+ * \file gis/progrm_nme.c
  *
- **********************************************************************
+ * \brief GIS Library - Program name
  *
- *   G_set_program_name(name)
- *        char *name 
+ * (C) 2001-2009 by the GRASS Development Team
  *
- *   program name set to name (name will be returned by G_program_name
+ * 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>
 
 static const char *name = "?";
 
-
 /*!
- * \brief return module name
+ * \brief Return module name
  *
- * Routine returns the name
- * of the module as set by the call to <i>G_gisinit.</i>
+ * Routine returns the name of the module as set by the call to
+ * G_gisinit().
  *
- *  \param ~
- *  \return char * 
+ * \return pointer to string with program name
  */
-
 const char *G_program_name(void)
 {
     return name;
 }
 
+/*!
+  \brief Set program name
+
+  Program name set to name (name will be returned by
+  G_program_name*())
+
+  \param s program name
+*/
 void G_set_program_name(const char *s)
 {
     int i;

lib/gis/put_cellhd.c

@@ -1,27 +1,37 @@
-
-/**********************************************************************
+/*!
+ * \file gis/put_cellhd.c
  *
- *  G_put_cellhd (name, cellhd)
- *      char *name                   name of map
- *      struct Cell_head *cellhd    structure holding cell header info
+ * \brief GIS Library - Write raster header.
  *
- *  Writes the cell file header information associated with map layer "map"
- *  into current mapset from the structure "cellhd".
+ * (C) 2001-2009 by the GRASS Development Team
  *
- *  returns:     0  if successful
- *              -1  on fail
+ * 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 Writes the raster file header.
+
+  Writes the cell file header information associated with map layer "map"
+  into current mapset from the structure "cellhd".
+
+  \param name name of map
+  \param cellhd structure holding cell header info
+
+  \return 0 on success
+  \return -1 on failure
+*/
 int G_put_cellhd(const char *name, struct Cell_head *cellhd)
 {
     FILE *fd;
 
     if (!(fd = G_fopen_new("cellhd", name))) {
-	G_warning(_("Unable to create header file for [%s]"), name);
+	G_warning(_("Unable to create header file for <%s>"), name);
 	return -1;
     }
 

lib/gis/range.c

@@ -1,137 +1,70 @@
-
-/**********************************************************************
- *
- *  G_read_range (name, mapset, range)
- *      const char *name             name of map
- *      const char *mapset           mapset that map belongs to
- *      struct Range *range          struct to hold range info
- *
- *  Reads the data range information associated with map layer "map"
- *  in mapset "mapset" 
- *
- *   returns:    1  if successful
- *               2  range is empty
- *               3  map is fp: get range from quant rules
- *              -1  on fail
- *
- *  note:   a warning message is printed if the file is missing or incorrect
- *
- **********************************************************************
- *
- *  G_read_fp_range (name, mapset, range)
- *      const char *name               name of map
- *      const char *mapset             mapset that map belongs to
- *      struct FPRange *range          struct to hold range info
- *
- *  Reads the fp data range information associated with map layer "map"
- *  in mapset "mapset" . If map is integer, the integer range is read
- *  and the max and min values are casted to doubles and copied to FPRange
- *
- *   returns:    1  if successful
- *               2  range is empty
- *              -1  on fail
- *
- *  note:   a warning message is printed if the file is missing or incorrect
- *
- **********************************************************************
- *
- *  G_write_[fp_]range (name, range)
- *      const char *name                name of map
- *      struct [FP]Range *range         struct holding range info
- *
- *  Writes the range information associated with map layer "map"
- *
- *   returns:    0  if successful
- *              -1  on fail (or if the map is fp )
- *
- **********************************************************************
- *
- * G_init_[fp_]range (range)
- *      struct [FP]Range *range         struct for range info
- *
- * initializes range structure for call to G_update_[fp_]range()
- *
- **********************************************************************
- *
- * G_construct_default_range (range)
- *      struct Range *range         struct for range info
- *
- *  returns 1 and range is set to DEFAULT_CELL_MIN
- *  and DEFAULT_SET_MAX, otherwise returns -1
+/*!
+ * \file gis/range.c
  *
- **********************************************************************
+ * \brief GIS Library - Raster range file management
  *
- * G_update_[fp_]range (cat, range)
- *    DCELL cat                    cat to be factored into range
- *    struct [FP]Range *range      struct for range info
- **********************************************************************
+ * (C) 2001-2009 GRASS Development Team
  *
- * G_row_update_[fp_]range (rast, range, data_type)
- *    void *rast                   raster row to be factored into range
- *    struct [FP]Range *range      struct for range info
- *    RASTER_MAP_TYPE data_type;
- **********************************************************************
+ * This program is free software under the GNU General Public License 
+ * (>=v2). Read the file COPYING that comes with GRASS for details.
  *
- * G_get_[fp_]range_min_max (range, min, max)
- *    struct [FP]Range *range;
- *    [D]CELL *min, *max;
- **********************************************************************/
+ * \author Original author CERL
+ */
 
 #include <unistd.h>
 #include <rpc/types.h>		/* need this for sgi */
 #include <rpc/xdr.h>
 #include "G.h"
 #include <grass/glocale.h>
+
 #define DEFAULT_CELL_MIN 1
 #define DEFAULT_CELL_MAX 255
 
-/*-------------------------------------------------------------------------*/
-
-/*-------------------------------------------------------------------------*/
+/*!
+  \brief Remove floating-point range
 
-/* range functions for type "Range" */
+  Note: For internal use only.
 
-/*-------------------------------------------------------------------------*/
+  \param name map name
+*/
 void G__remove_fp_range(const char *name)
 {
     G_remove_misc("cell_misc", "f_range", name);
 }
 
-
 /*!
- * \brief 
+ * \brief Construct default range
  *
- * Sets the integer range <em>r</em> to [1,255]
+ * Sets the integer range to [1,255]
  *
- *  \param r
- *  \return
+ * \param[out] r pointer to Range structure which holds range info
  */
-
 void G_construct_default_range(struct Range *range)
 {
     G_update_range(DEFAULT_CELL_MIN, range);
     G_update_range(DEFAULT_CELL_MAX, range);
 }
 
-
 /*!
- * \brief 
- *
- * Read the floating point range file <tt>f_range</tt>. This file is
- * written in binary using XDR format. If there is no defined min/max in <em>r</em>, 
- * an empty <tt>f_range</tt>file is created.
- * An empty range file indicates that the min, max are undefined. This is a
- * valid case, and the result should be an initialized range struct with no
- * defined min/max.
- * If the range file is missing and the map is a floating-point map, this
- * function will create a default range by calling <tt>G_construct_default_range()</tt>.
- *
- *  \param r
- *  \param name
- *  \param mapset
- *  \return int
+ * \brief Read floating-point range
+ *
+ * Read the floating point range file <i>drange</i>. This file is
+ * written in binary using XDR format.
+ *
+ * An empty range file indicates that the min, max are undefined. This
+ * is a valid case, and the result should be an initialized range
+ * struct with no defined min/max.  If the range file is missing and
+ * the map is a floating-point map, this function will create a
+ * default range by calling G_construct_default_range().
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param drange pointer to FPRange structure which holds fp range
+ *
+ * \return 1 on success
+ * \return 2 range is empty
+ * \return -1 on error
  */
-
 int G_read_fp_range(const char *name, const char *mapset,
 		    struct FPRange *drange)
 {
@@ -163,9 +96,12 @@ int G_read_fp_range(const char *name, const char *mapset,
 
     if (G_find_file2_misc("cell_misc", "f_range", name, mapset)) {
 	fd = G_open_old_misc("cell_misc", "f_range", name, mapset);
-	if (fd < 0)
-	    goto error;
-
+	if (fd < 0) {
+	  G_warning(_("Unable to read fp range file for <%s@%s>"),
+		    name, mapset);
+	  return -1;
+	}
+	
 	if (read(fd, xdr_buf, 2 * XDR_DOUBLE_NBYTES) != 2 * XDR_DOUBLE_NBYTES)
 	    return 2;
 
@@ -173,52 +109,49 @@ int G_read_fp_range(const char *name, const char *mapset,
 		      XDR_DECODE);
 
 	/* if the f_range file exists, but empty */
-	if (!xdr_double(&xdr_str, &dcell1) || !xdr_double(&xdr_str, &dcell2))
-	    goto error;
+	if (!xdr_double(&xdr_str, &dcell1) || !xdr_double(&xdr_str, &dcell2)) {
+	  if (fd) 
+	    close(fd);
+	  G_warning(_("Unable to read fp range file for <%s@%s>"),
+		    name, mapset);
+	  return -1;
+	}
 
 	G_update_fp_range(dcell1, drange);
 	G_update_fp_range(dcell2, drange);
 	close(fd);
-	return 1;
     }
-
-  error:
-    if (fd > 0)
-	close(fd);
-    G_warning(_("can't read f_range file for [%s in %s]"),
-	      name, mapset);
-    return -1;
+    
+    return 1;
 }
 
-/*-------------------------------------------------------------------------*/
-
-
 /*!
- * \brief read raster range
+ * \brief Read raster range (CELL)
+ *
+ * This routine reads the range information for the raster map
+ * <i>name</i> in <i>mapset</i> into the <i>range</i> structure.
  *
- * This routine reads the range information for the
- * raster map <b>name</b> in <b>mapset</b> into the <b>range</b>
- * structure.
  * A diagnostic message is printed and -1 is returned if there is an error
  * reading the range file. Otherwise, 0 is returned.
  *
- * Old range file (those with 4 numbers) should
- * treat zeros in this file as NULL-values. New range files (those with just 2
- * numbers) should treat these numbers as real data (zeros are real data in this
- * case).
- * An empty range file indicates that the min, max are undefined. This is a
- * valid case, and the result should be an initialized range struct with no
- * defined min/max.
- * If the range file is missing and the map is a floating-point map, this
- * function will create a default range by calling <tt>G_construct_default_range()</tt>.
- *
- *  \param name
- *  \param mapset
- *  \param range
- *
- *  \return int
+ * Old range file (those with 4 numbers) should treat zeros in this
+ * file as NULL-values. New range files (those with just 2 numbers)
+ * should treat these numbers as real data (zeros are real data in
+ * this case).  An empty range file indicates that the min, max are
+ * undefined. This is a valid case, and the result should be an
+ * initialized range struct with no defined min/max. If the range file
+ * is missing and the map is a floating-point map, this function will
+ * create a default range by calling G_construct_default_range().
+ *
+ * \param name map name
+ * \param mapset mapset name
+ * \param range pointer to Range structure which holds range info
+ *
+ * \return -1 on error
+ * \return 1 on success
+ * \return 2 if range is empty
+ * \return 3 if raster map is floating-point, get range from quant rules
  */
-
 int G_read_range(const char *name, const char *mapset, struct Range *range)
 {
     FILE *fd;
@@ -236,8 +169,7 @@ int G_read_range(const char *name, const char *mapset, struct Range *range)
 	DCELL dmin, dmax;
 
 	if (G_read_quant(name, mapset, &quant) < 0) {
-	    G_warning(_("G_read_range(): can't read quant rules"
-			" for fp map %s@%s"),
+	    G_warning(_("Unable to read quant rules for raster map <%s@%s>"),
 		       name, mapset);
 	    return -1;
 	}
@@ -273,9 +205,12 @@ int G_read_range(const char *name, const char *mapset, struct Range *range)
 
     if (G_find_file2_misc("cell_misc", "range", name, mapset)) {
 	fd = G_fopen_old_misc("cell_misc", "range", name, mapset);
-	if (!fd)
-	    goto error;
-
+	if (!fd) {
+	    G_warning(_("Unable to read range file for <%s@%s>"),
+		      name, mapset);
+	    return -1;
+	}
+	
 	/* if range file exists but empty */
 	if (!fgets(buf, sizeof buf, fd))
 	    return 2;
@@ -284,9 +219,15 @@ int G_read_range(const char *name, const char *mapset, struct Range *range)
 	count = sscanf(buf, "%d%d%d%d", &x[0], &x[1], &x[2], &x[3]);
 
 	/* if wrong format */
-	if (count <= 0)
-	    goto error;
-
+	if (count <= 0) {
+	    if (fd)
+		fclose(fd);
+	    
+	    G_warning(_("Unable to read range file for <%s@%s>"),
+		      name, mapset);
+	    return -1;
+	}
+	
 	for (n = 0; n < count; n++) {
 	    /* if count==4, the range file is old (4.1) and 0's in it
 	       have to be ignored */
@@ -294,81 +235,73 @@ int G_read_range(const char *name, const char *mapset, struct Range *range)
 		G_update_range((CELL) x[n], range);
 	}
 	fclose(fd);
-	return 1;
     }
 
-  error:
-    if (fd)
-	fclose(fd);
-    G_warning(_("can't read range file for [%s in %s]"),
-	      name, mapset);
-    return -1;
+    return 1;
 }
 
-/*-------------------------------------------------------------------------*/
-
-
 /*!
- * \brief write raster range file
+ * \brief Write raster range file
  *
  * This routine writes the range information for the raster map
- * <b>name</b> in the current mapset from the <b>range</b> structure.
- * A diagnostic message is printed and -1 is returned if there is an error
- * writing the range file. Otherwise, 0 is returned.
+ * <i>name</i> in the current mapset from the <i>range</i> structure.
+ * A diagnostic message is printed and -1 is returned if there is an
+ * error writing the range file. Otherwise, 0 is returned.
  *
  * This routine only writes 2 numbers (min,max) to the range
  * file, instead of the 4 (pmin,pmax,nmin,nmax) previously written.
  * If there is no defined min,max, an empty file is written.
  *
- *  \param name
- *  \param range
+ * \param name map name
+ * \param range pointer to Range structure which holds range info
  *
- *  \return int
+ * \return -1 on error (or raster map is floating-point)
+ * \return 0 on success
  */
-
 int G_write_range(const char *name, const struct Range *range)
 {
     FILE *fd;
 
-    if (G_raster_map_type(name, G_mapset()) != CELL_TYPE)
-	goto error;
+    if (G_raster_map_type(name, G_mapset()) != CELL_TYPE) {
+	G_remove_misc("cell_misc", "range", name);	/* remove the old file with this name */
+	G_warning(_("Unable to write range file for <%s>"),
+		  name);
+	return -1;
+    }
 
     fd = G_fopen_new_misc("cell_misc", "range", name);
-    if (!fd)
-	goto error;
+    if (!fd) {
+	G_remove_misc("cell_misc", "range", name);	/* remove the old file with this name */
+	G_warning(_("Unable to write range file for <%s>"),
+		  name);
+	return -1;
+    }
 
-    if (range->first_time)
-	/* if range hasn't been updated */
-    {
+    /* if range hasn't been updated */
+    if (range->first_time) {
 	fclose(fd);
 	return 0;
     }
+
     fprintf(fd, "%ld %ld\n", (long)range->min, (long)range->max);
     fclose(fd);
-    return 0;
 
-  error:
-    G_remove_misc("cell_misc", "range", name);	/* remove the old file with this name */
-    G_warning(_("can't write range file for [%s in %s]"),
-	      name, G_mapset());
-    return -1;
+    return 0;
 }
 
-/*-------------------------------------------------------------------------*/
-
-
 /*!
- * \brief 
+ * \brief Write raster range file (floating-point)
  *
- * Write the floating point range
- * file <tt>f_range</tt>. This file is written in binary using XDR format. If
- * there is no defined min/max in <em>r</em>, an empty <tt>f_range</tt>file is
- * created.
+ * Write the floating point range file <tt>f_range</tt>. This file is
+ * written in binary using XDR format. If there is no defined min/max
+ * in <em>range</em>, an empty <tt>f_range</tt> file is created.
  *
- *  \param r
- *  \return
+ * \param name map name
+ * \param range pointer to FPRange which holds fp range info
+ *
+ * \return 0 on success
+ * \return -1 on error
  */
-
 int G_write_fp_range(const char *name, const struct FPRange *range)
 {
     int fd;
@@ -376,12 +309,15 @@ int G_write_fp_range(const char *name, const struct FPRange *range)
     XDR xdr_str;
 
     fd = G_open_new_misc("cell_misc", "f_range", name);
-    if (fd < 0)
-	goto error;
-
-    if (range->first_time)
-	/* if range hasn't been updated, write empty file meaning Nulls */
-    {
+    if (fd < 0) {
+	G_remove_misc("cell_misc", "f_range", name);
+	G_warning(_("Unable to write range file for <%s>"),
+		  name);
+	return -1;
+    }
+    
+    /* if range hasn't been updated, write empty file meaning Nulls */
+    if (range->first_time) {
 	close(fd);
 	return 0;
     }
@@ -389,40 +325,38 @@ int G_write_fp_range(const char *name, const struct FPRange *range)
     xdrmem_create(&xdr_str, xdr_buf, (u_int) XDR_DOUBLE_NBYTES * 2,
 		  XDR_ENCODE);
 
-    if (!xdr_double(&xdr_str, (double *)&(range->min)))
-	goto error;
-    if (!xdr_double(&xdr_str, (double *)&(range->max)))
-	goto error;
-
+    if (!xdr_double(&xdr_str, (double *)&(range->min))) {
+	G_remove_misc("cell_misc", "f_range", name);
+	G_warning(_("Unable to write range file for <%s>"),
+		  name);
+	return -1;
+    }
+    
+    if (!xdr_double(&xdr_str, (double *)&(range->max))) {
+	G_remove_misc("cell_misc", "f_range", name);
+	G_warning(_("Unable to write range file for <%s>"),
+		  name);
+	return -1;
+    }
+    
     write(fd, xdr_buf, XDR_DOUBLE_NBYTES * 2);
     close(fd);
-    return 0;
 
-  error:
-    G_remove_misc("cell_misc", "f_range", name);	/* remove the old file with this name */
-    G_warning(_("can't write range file for [%s in %s]"),
-	      name, G_mapset());
-    return -1;
+    return 0;
 }
 
-/*-------------------------------------------------------------------------*/
-
-
 /*!
- * \brief update range structure
+ * \brief Update range structure (CELL)
  *
- * Compares the <b>cat</b> value with the minimum and maximum
- * values in the <b>range</b> structure, modifying the range if <b>cat</b>
+ * Compares the <i>cat</i> value with the minimum and maximum values
+ * in the <i>range</i> structure, modifying the range if <i>cat</i>
  * extends the range.
  *
  * NULL-values must be detected and ignored.
  *
- *  \param cat
- *  \param range
- *
- *  \return
+ * \param cat raster value
+ * \param range pointer to Range structure which holds range info
  */
-
 void G_update_range(CELL cat, struct Range *range)
 {
     if (!G_is_c_null_value(&cat)) {
@@ -439,8 +373,18 @@ void G_update_range(CELL cat, struct Range *range)
     }
 }
 
-/*-------------------------------------------------------------------------*/
-
+/*!
+ * \brief Update range structure (floating-point)
+ *
+ * Compares the <i>cat</i> value with the minimum and maximum values
+ * in the <i>range</i> structure, modifying the range if <i>cat</i>
+ * extends the range.
+ *
+ * NULL-values must be detected and ignored.
+ *
+ * \param val raster value
+ * \param range pointer to Range structure which holds range info
+ */
 void G_update_fp_range(DCELL val, struct FPRange *range)
 {
     if (!G_is_d_null_value(&val)) {
@@ -457,29 +401,32 @@ void G_update_fp_range(DCELL val, struct FPRange *range)
     }
 }
 
-/*-------------------------------------------------------------------------*/
-
-
 /*!
- * \brief update range structure
+ * \brief Update range structure based on raster row (CELL)
  *
- * This routine updates the <b>range</b> data
- * just like <i>G_update_range</i>, but for <b>n</b> values from the
- * <b>cell</b> array.
+ * This routine updates the <i>range</i> data just like
+ * G_update_range(), but for <i>n</i> values from the <i>cell</i>
+ * array.
  *
- *  \param cell
- *  \param n
- *  \param range
- *  \return
+ * \param cell raster values
+ * \param n number of values
+ * \param range pointer to Range structure which holds range info
  */
-
 void G_row_update_range(const CELL *cell, int n, struct Range *range)
 {
     G__row_update_range(cell, n, range, 0);
 }
 
-/*-------------------------------------------------------------------------*/
-
+/*!
+ * \brief Update range structure based on raster row
+ *
+ * Note: for internal use only.
+ *
+ * \param cell raster values
+ * \param n number of values
+ * \param range pointer to Range structure which holds range info
+ * \param ignore_zeros ignore zeros
+ */
 void G__row_update_range(const CELL *cell, int n,
 			 struct Range *range, int ignore_zeros)
 {
@@ -502,8 +449,18 @@ void G__row_update_range(const CELL *cell, int n,
     }
 }
 
-/*-------------------------------------------------------------------------*/
-
+/*!
+ * \brief Update range structure based on raster row (floating-point)
+ *
+ * This routine updates the <i>range</i> data just like
+ * G_update_range(), but for <i>n</i> values from the <i>cell</i>
+ * array.
+ *
+ * \param cell raster values
+ * \param n number of values
+ * \param range pointer to Range structure which holds range info
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ */
 void G_row_update_fp_range(const void *rast, int n,
 			   struct FPRange *range, RASTER_MAP_TYPE data_type)
 {
@@ -542,21 +499,18 @@ void G_row_update_fp_range(const void *rast, int n,
     }
 }
 
-/*-------------------------------------------------------------------------*/
-
 /*!
- * \brief initialize range structure
+ * \brief Initialize range structure
  *
- * Initializes the <b>range</b> structure for updates by
- * <i>G_update_range</i> and <i>G_row_update_range.</i>
+ * Initializes the <i>range</i> structure for updates by
+ * G_update_range() and G_row_update_range().
  *
- * Must set a flag in the range structure that indicates that
- * no min/max have been defined - probably a <tt>"first"</tt> boolean flag.
+ * Must set a flag in the range structure that indicates that no
+ * min/max have been defined - probably a <tt>"first"</tt> boolean
+ * flag.
  *
- *  \param range
- *  \return
+ * \param range pointer to Range structure which holds range info
  */
-
 void G_init_range(struct Range *range)
 {
     G_set_c_null_value(&(range->min), 1);
@@ -564,26 +518,20 @@ void G_init_range(struct Range *range)
     range->first_time = 1;
 }
 
-/*-------------------------------------------------------------------------*/
-
-
 /*!
- * \brief get range min and max
+ * \brief Get range min and max
  *
- * The <b>min</b>inum and <b>max</b>imum CELL
- * values are extracted from the <b>range</b> structure.
+ * The mininum and maximum CELL values are extracted from the
+ * <i>range</i> structure.
  *
- * If the range structure has no defined min/max
- * (first!=0) there will not be a valid range. In this case the min and
- * max returned must be the NULL-value.
+ * If the range structure has no defined min/max (first!=0) there will
+ * not be a valid range. In this case the min and max returned must be
+ * the NULL-value.
  *
- *  \param range
- *  \param min
- *  \param max
- *  \return
+ * \param range pointer to Range structure which holds range info
+ * \param[out] min minimum value
+ * \param[out] max maximum value
  */
-
-
 void G_get_range_min_max(const struct Range *range, CELL * min, CELL * max)
 {
     if (range->first_time) {
@@ -603,19 +551,15 @@ void G_get_range_min_max(const struct Range *range, CELL * min, CELL * max)
     }
 }
 
-/*-------------------------------------------------------------------------*/
-
 /*!
- * \brief 
+ * \brief Initialize fp range
  *
- * Must set a flag in the range
- * structure that indicates that no min/max have been defined - probably a
- * <tt>"first"</tt> boolean flag.
+ * Must set a flag in the range structure that indicates that no
+ * min/max have been defined - probably a <tt>"first"</tt> boolean
+ * flag.
  *
- *  \param r
- *  \return
+ * \param range pointer to FPRange which holds fp range info
  */
-
 void G_init_fp_range(struct FPRange *range)
 {
     G_set_d_null_value(&(range->min), 1);
@@ -623,22 +567,18 @@ void G_init_fp_range(struct FPRange *range)
     range->first_time = 1;
 }
 
-/*-------------------------------------------------------------------------*/
-
-
 /*!
- * \brief 
+ * \brief Get minumum and maximum value from fp range
  *
- * Extract the min/max from the range structure <em>r</em>.
- * If the range structure has no defined min/max (first!=0) there will not be a
- * valid range. In this case the min and max returned must be the NULL-value.
+ * Extract the min/max from the range structure <i>range</i>.  If the
+ * range structure has no defined min/max (first!=0) there will not be
+ * a valid range. In this case the min and max returned must be the
+ * NULL-value.
  *
- *  \param r
- *  \param min
- *  \param max
- *  \return
+ * \param range pointer to FPRange which holds fp range info
+ * \param[out] min minimum value
+ * \param[out] max maximum value
  */
-
 void G_get_fp_range_min_max(const struct FPRange *range,
 			    DCELL *min, DCELL *max)
 {

lib/gis/raster.c

@@ -1,14 +1,27 @@
+/*!
+ * \file gis/raster.c
+ *
+ * \brief GIS Library - Raster cell value 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
+ */
+
 #include <stdlib.h>
 #include <grass/gis.h>
 
-
 /*!
- * \brief  Advance void pointer
+ * \brief Advance void pointer
  *
- * Advances void pointer by <em>size</em> bytes
- * Returns new pointer value.
+ * Advances void pointer by <i>size</i> bytes. Returns new pointer
+ * value.
  *
  * Useful in raster row processing loops, substitutes
+ *
  \code
  CELL *cell; 
  cell += n;
@@ -19,38 +32,35 @@
  rast = G_incr_void_ptr(rast, G_raster_size(data_type))
  \endcode
  *
- * (where rast is void* and data_type is RASTER_MAP_TYPE can be used instead
- * of rast++.)
+ * (where rast is void* and <i>data_type</i> is RASTER_MAP_TYPE can be
+ * used instead of rast++.)
  *
- * very useful to generalize the row processing - loop i.e.
+ * Very useful to generalize the row processing - loop i.e.
+ * \code
  *   void * buf_ptr += G_raster_size(data_type)
+ * \endcode
  *
- *  \param ptr
- *  \param size
- *  \return void * 
+ * \param ptr pointer
+ * \param size buffer size
+ *
+ * \return pointer to the data
  */
-
 void *G_incr_void_ptr(const void *ptr, const size_t size)
 {
     /* assuming that the size of unsigned char is 1 */
     return (void *)((const unsigned char *)ptr + size);
 }
 
-
 /*!
- * \brief  Compares raster values p and q
+ * \brief Compares raster values.
  *
- * Returns:
- *   1 if p > q or only q is null value
- *  -1 if p < q or only p is null value
- *   0 if p == q or p==q==null value
+ * \param v1,v2 values to be compared
+ * \param data_type raster type (CELL, FCELL, DCELL)
  *
- *  \param p
- *  \param q
- *  \param data_type
- *  \return int
+ * \return  1 if p > q or only q is null value
+ * \return -1 if p < q or only p is null value
+ * \return  0 if p == q or p==q==null value
  */
-
 int G_raster_cmp(const void *v1, const void *v2, RASTER_MAP_TYPE data_type)
 {
     if (G_is_null_value(v1, data_type)) {
@@ -89,38 +99,31 @@ int G_raster_cmp(const void *v1, const void *v2, RASTER_MAP_TYPE data_type)
     return 0;
 }
 
-
 /*!
- * \brief  Copies raster values q into p
+ * \brief Copies raster values.
  *
- * If q is null value, sets q to null value.
+ * If v2 is null value, sets v2 to null value.
  *
- *  \param p
- *  \param q
- *  \param n
- *  \param data_type
- *  \return
+ * \param v1, v2 raster values
+ * \param n ?
+ * \param data_type raster type (CELL, FCELL, DCELL)
  */
-
 void G_raster_cpy(void *v1, const void *v2, int n, RASTER_MAP_TYPE data_type)
 {
     G_copy(v1, v2, n * G_raster_size(data_type));
 }
 
-
 /*!
- * \brief  Places a CELL raster value
+ * \brief Places a CELL raster value
  *
- * If G_is_c_null_value(val) is true, sets p to null value.
- * Converts CELL val to data_type (type of p) and stores result in p.
- * Used for assigning CELL values to raster cells of any type.
+ * If G_is_c_null_value() is true, sets p to null value. Converts CELL
+ * val to data_type (type of p) and stores result in p. Used for
+ * assigning CELL values to raster cells of any type.
  *
- *  \param p
- *  \param val
- *  \param data_type
- *  \return
+ * \param rast pointer to raster cell value
+ * \param cval value to set
+ * \param data_type raster type (CELL, FCELL, DCELL)
  */
-
 void G_set_raster_value_c(void *rast, CELL cval, RASTER_MAP_TYPE data_type)
 {
     CELL c;
@@ -143,20 +146,17 @@ void G_set_raster_value_c(void *rast, CELL cval, RASTER_MAP_TYPE data_type)
     }
 }
 
-
 /*!
- * \brief  Places a FCELL raster value
+ * \brief Places a FCELL raster value
  *
- * If G_is_f_null_value(val) is true, sets p to null value.
- * Converts FCELL val to data_type (type of p) and stores result in p.
- * Used for assigning FCELL values to raster cells of any type.
+ * If G_is_f_null_value() is true, sets p to null value. Converts
+ * FCELL val to data_type (type of p) and stores result in p. Used for
+ * assigning FCELL values to raster cells of any type.
  *
- *  \param p
- *  \param val
- *  \param data_type
- *  \return
+ * \param rast pointer to raster cell value
+ * \param fval value to set
+ * \param data_type raster type (CELL, FCELL, DCELL)
  */
-
 void G_set_raster_value_f(void *rast, FCELL fval, RASTER_MAP_TYPE data_type)
 {
     FCELL f;
@@ -183,16 +183,14 @@ void G_set_raster_value_f(void *rast, FCELL fval, RASTER_MAP_TYPE data_type)
 /*!
  * \brief  Places a DCELL raster value
  *
- * If G_is_d_null_value(val) is true, sets p to null value.
- * Converts DCELL val to data_type (type of p) and stores result in p.
- * Used for assigning DCELL values to raster cells of any type.
+ * If G_is_d_null_value() is true, sets p to null value. Converts
+ * DCELL val to data_type (type of p) and stores result in p. Used for
+ * assigning DCELL values to raster cells of any type.
  *
- *  \param p
- *  \param val
- *  \param data_type
- *  \return
+ * \param rast pointer to raster cell value
+ * \param fval value to set
+ * \param data_type raster type (CELL, FCELL, DCELL)
  */
-
 void G_set_raster_value_d(void *rast, DCELL dval, RASTER_MAP_TYPE data_type)
 {
     DCELL d;
@@ -215,24 +213,23 @@ void G_set_raster_value_d(void *rast, DCELL dval, RASTER_MAP_TYPE data_type)
     }
 }
 
-
 /*!
- * \brief  Retrieves the value of type data_type from pointer p
+ * \brief Retrieves the value of give type from pointer p
  *
- * Retrieves the value of type data_type from pointer p,
- * converts it to CELL type and returns the result.
- * If null value is stored in p, returns CELL null value.
+ * Retrieves the value of type data_type from pointer p, converts it
+ * to CELL type and returns the result. If null value is stored in p,
+ * returns CELL null value.
  *
  * Used for retrieving CELL values from raster cells of any type.
  *
- * NOTE: when data_type != CELL_TYPE, no quantization is used, only
+ * Note: when data_type != CELL_TYPE, no quantization is used, only
  * type conversion.
  *
- *  \param p
- *  \param data_type
- *  \return CELL
+ * \param rast pointer to raster cell value
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return raster value
  */
-
 CELL G_get_raster_value_c(const void *rast, RASTER_MAP_TYPE data_type)
 {
     CELL c;
@@ -245,29 +242,28 @@ CELL G_get_raster_value_c(const void *rast, RASTER_MAP_TYPE data_type)
     case CELL_TYPE:
 	return *((const CELL *)rast);
     case FCELL_TYPE:
-	return (CELL) * ((const FCELL *)rast);
+	return (CELL) *((const FCELL *)rast);
     case DCELL_TYPE:
-	return (CELL) * ((const DCELL *)rast);
+	return (CELL) *((const DCELL *)rast);
     }
 
     return 0;
 }
 
-
 /*!
- * \brief  Retrieves the value of type data_type from pointer p
+ * \brief Retrieves the value of given raster type from pointer p (FCELL)
  *
- * Retrieves the value of type data_type from pointer p,
- * converts it to FCELL type and returns the result.
- * If null value is stored in p, returns FCELL null value.
+ * Retrieves the value of type data_type from pointer p, converts it
+ * to FCELL type and returns the result. If null value is stored in p,
+ * returns FCELL null value.
  *
  * Used for retrieving FCELL values from raster cells of any type.
  *
- *  \param p
- *  \param data_type
- *  \return FCELL
+ * \param rast pointer to raster cell value
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return raster value
  */
-
 FCELL G_get_raster_value_f(const void *rast, RASTER_MAP_TYPE data_type)
 {
     FCELL f;
@@ -290,19 +286,19 @@ FCELL G_get_raster_value_f(const void *rast, RASTER_MAP_TYPE data_type)
 
 
 /*!
- * \brief  Retrieves the value of type data_type from pointer p,
+ * \brief Retrieves the value of given type from pointer p (DCELL)
  *
- * Retrieves the value of type data_type from pointer p,
- * converts it to DCELL type and returns the result.
- * If null value is stored in p, returns DCELL null value.
+ * Retrieves the value of type data_type from pointer p, converts it
+ * to DCELL type and returns the result. If null value is stored in p,
+ * returns DCELL null value.
 
  * Used for retrieving DCELL values from raster cells of any type.
  *
- *  \param p
- *  \param data_type
- *  \return DCELL
+ * \param rast pointer to raster cell value
+ * \param data_type raster type (CELL, FCELL, DCELL)
+ *
+ * \return raster value
  */
-
 DCELL G_get_raster_value_d(const void *rast, RASTER_MAP_TYPE data_type)
 {
     DCELL d;

lib/gis/reclass.c

@@ -1,3 +1,16 @@
+/*!
+ * \file gis/reclass.c
+ *
+ * \brief GIS Library - Check if raster map is reclassified
+ *
+ * (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>
@@ -8,25 +21,23 @@ static FILE *fopen_cellhd_old(const char *, const char *);
 static FILE *fopen_cellhd_new(const char *);
 static int get_reclass_table(FILE *, struct Reclass *);
 
-
 /*!
- * \brief reclass file?
+ * \brief Check if raster map is reclassified
  *
- * This function determines if the raster map
- * <b>name</b> in <b>mapset</b> is a reclass file.
- * If it is, then the name and mapset of the referenced 
- * raster map are copied into the <b>r_name</b> and <b>r_mapset</b> 
- * buffers.
- * Returns 1 if <b>name</b> is a reclass file, 0 if it is not, and -1 if 
- * there was a problem reading the raster header for <b>name.</b>
+ * This function determines if the raster map <i>name</i> in
+ * <i>mapset</i> is a reclass file. If it is, then the name and mapset
+ * of the referenced raster map are copied into the <i>r_name</i> and
+ * <i>r_mapset</i> buffers.  
  *
- *  \param name
- *  \param mapset
- *  \param r_name
- *  \param r_mapset
- *  \return int
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] r_name name of reference map
+ * \param[out] r_mapset mapset where reference map lives
+ *
+ * \returns 1 if it is a reclass file
+ * \return 0 if it is not
+ * \return -1 if there was a problem reading the raster header
  */
-
 int G_is_reclass(const char *name, const char *mapset, char *rname,
 		 char *rmapset)
 {
@@ -45,24 +56,24 @@ int G_is_reclass(const char *name, const char *mapset, char *rname,
 	return type != 0;
 }
 
-
 /*!
- * \brief get child reclass maps list
+ * \brief Get child reclass maps list
+ *
+ * This function generates a child reclass maps list from the
+ * cell_misc/reclassed_to file which stores this list. The
+ * cell_misc/reclassed_to file is written by G_put_reclass().
+ * G_is_reclassed_to() is used by <tt>g.rename</tt>, <tt>g.remove</tt>
+ * and <tt>r.reclass</tt> to prevent accidentally deleting the parent
+ * map of a reclassed raster map.
  *
- * This function generates a
- * child reclass maps list from the cell_misc/reclassed_to file which stores 
- * this list. The cell_misc/reclassed_to file is written by 
- * G_put_reclass().
- * G_is_reclassed_to() is used by g.rename, g.remove and r.reclass to
- * prevent accidentally deleting the parent map of a reclassed raster map.
+ * \param name map name
+ * \param mapset mapset name
+ * \param[out] nrmaps number of reference maps
+ * \param[out] rmaps array of names of reference maps
  *
- *  \param name
- *  \param mapset
- *  \param nrmaps
- *  \param rmaps
- *  \return int
+ * \return number of reference maps
+ * \return -1 on error
  */
-
 int G_is_reclassed_to(const char *name, const char *mapset, int *nrmaps,
 		      char ***rmaps)
 {
@@ -112,6 +123,16 @@ int G_is_reclassed_to(const char *name, const char *mapset, int *nrmaps,
     return i;
 }
 
+/*!
+  \brief Get reclass
+
+  \param name map name
+  \param mapset mapset name
+  \param[out] reclass pointer to Reclass structure
+
+  \return -1 on error
+  \return type code
+*/
 int G_get_reclass(const char *name, const char *mapset,
 		  struct Reclass *reclass)
 {
@@ -140,16 +161,21 @@ int G_get_reclass(const char *name, const char *mapset,
     fclose(fd);
     if (stat < 0) {
 	if (stat == -2)
-	    G_warning(_("Too many reclass categories for [%s in %s]"),
+	    G_warning(_("Too many reclass categories for <%s@%s>"),
 		      name, mapset);
 	else
-	    G_warning(_("Illegal reclass format in header file for [%s in %s]"),
+	    G_warning(_("Illegal reclass format in header file for <%s@%s>"),
 		      name, mapset);
 	stat = -1;
     }
     return stat;
 }
 
+/*!
+  \brief Free Reclass structure
+
+  \param reclass pointer to Reclass structure
+*/
 void G_free_reclass(struct Reclass *reclass)
 {
     switch (reclass->type) {
@@ -220,6 +246,15 @@ static FILE *fopen_cellhd_old(const char *name, const char *mapset)
     return G_fopen_old("cellhd", name, mapset);
 }
 
+/*!
+  \brief Put reclass
+
+  \param name map name
+  \param reclass pointer to Reclass structure
+  
+  \return -1 on error
+  \return 1 on success
+*/
 int G_put_reclass(const char *name, const struct Reclass *reclass)
 {
     FILE *fd;
@@ -241,7 +276,7 @@ int G_put_reclass(const char *name, const struct Reclass *reclass)
 
     fd = fopen_cellhd_new(name);
     if (fd == NULL) {
-	G_warning(_("Unable to create header file for [%s in %s]"),
+	G_warning(_("Unable to create header file for <%s@%s>"),
 		  name, G_mapset());
 	return -1;
     }
@@ -289,7 +324,7 @@ int G_put_reclass(const char *name, const struct Reclass *reclass)
     fd = fopen(buf1, "a+");
     if (fd == NULL) {
 #if 0
-	G_warning(_("Unable to create dependency file in [%s in %s]"),
+	G_warning(_("Unable to create dependency file in <%s@%s>"),
 		  buf2, reclass->mapset);
 #endif
 	return 1;

lib/gis/timestamp.c

@@ -1,32 +1,9 @@
-/*
- *
- * provides DateTime functions for timestamp management:
- *
- * Authors: Michael Shapiro & Bill Brown, CERL
- *          grid3 functions by Michael Pelizzari, LMCO
- *
- * G_init_timestamp()
- * G_set_timestamp()
- * G_set_timestamp_range()
- * G_format_timestamp()
- * G_scan_timestamp()
- * G_get_timestamps()
- * G_read_raster_timestamp()
- * G_remove_raster_timestamp()
- * G_read_vector_timestamp()
- * G_remove_vector_timestamp()
- * G_read_grid3_timestamp()
- * G_remove_grid3_timestamp()
- * G_write_raster_timestamp()
- * G_write_vector_timestamp()
- * G_write_grid3_timestamp()
- *
- * COPYRIGHT:    (C) 2000 by the GRASS Development Team
+/*!
+ * \file gis/timestamp.c
  *
- *               This program is free software under the GNU General Public
- *               License (>=v2). Read the file COPYING that comes with GRASS
- *               for details.
+ * \brief GIS Library - Timestamp management
  *
+ * Provides DateTime functions for timestamp management.
  *
  * The timestamp values must use the format as described in the GRASS
  * datetime library. The source tree for this library should have a
@@ -89,24 +66,51 @@
  * 3 months 15 days
  * 3 years 10 days
  *
+ * (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 Michael Shapiro & Bill Brown, CERL
+ * \author grid3 functions by Michael Pelizzari, LMCO
  */
 
 #include <string.h>
 #include <grass/gis.h>
 #include <grass/glocale.h>
 
+#define RAST_MISC "cell_misc"
+#define VECT_MISC "dig_misc"
+#define GRID3	  "grid3"
+
+/*!
+  \brief Initialize timestamp structure
+
+  \param ts pointer to TimeStamp structure
+*/
 void G_init_timestamp(struct TimeStamp *ts)
 {
     ts->count = 0;
 }
 
+/*!
+  \brief Set timestamp (single)
+
+  \param ts pointer to TimeStamp structure
+  \param dt pointer to DateTime structure (date/time to be set)
+*/
 void G_set_timestamp(struct TimeStamp *ts, const DateTime * dt)
 {
     datetime_copy(&ts->dt[0], dt);
     ts->count = 1;
 }
 
+/*!
+  \brief Set timestamp (range)
+
+  \param ts pointer to TimeStamp structure
+  \param dt1,dt2 pointer to DateTime structures
+*/
 void G_set_timestamp_range(struct TimeStamp *ts,
 			   const DateTime * dt1, const DateTime * dt2)
 {
@@ -115,6 +119,16 @@ void G_set_timestamp_range(struct TimeStamp *ts,
     ts->count = 2;
 }
 
+/*!
+  \brief Read timestamp
+
+  \param fd file descriptor
+  \param[out] ts pointer to TimeStamp structure
+
+  \return -2 EOF
+  \return -1 on error
+  \return 0 on success
+*/
 int G__read_timestamp(FILE * fd, struct TimeStamp *ts)
 {
     char buf[1024];
@@ -128,20 +142,17 @@ int G__read_timestamp(FILE * fd, struct TimeStamp *ts)
     return -2;			/* nothing in the file */
 }
 
-
 /*!
- * \brief output TimeStamp structure to a file as a formatted string
- *
- * A handy fd might be "stdout".
- *
- * Returns:
- *  0 on success
- * -1 error
- *
- *  \param fd    file descriptor
- *  \param ts    TimeStamp struct
- *  \return int  exit value
- */
+  \brief Output TimeStamp structure to a file as a formatted string
+ 
+  A handy fd might be "stdout".
+  
+  \param[in,out] fd file descriptor
+  \param ts pointer to TimeStamp structure
+
+  \return 0 on success
+  \return -1 on error
+*/
 int G__write_timestamp(FILE * fd, const struct TimeStamp *ts)
 {
     char buf[1024];
@@ -152,22 +163,19 @@ int G__write_timestamp(FILE * fd, const struct TimeStamp *ts)
     return 0;
 }
 
-
 /*!
- * \brief Create text string from TimeStamp structure
- *
- * Fills string *buf with info from TimeStamp structure *ts in a pretty
- * way. The TimeStamp struct is defined in gis.h and populated with e.g.
- * G_read_raster_timestamp().
- *
- * Returns:
- *  1 on success
- * -1 error
- *
- *  \param ts    TimeStamp structure containing time info
- *  \param buf   string to receive formatted timestamp
- *  \return int  exit value
- */
+  \brief Create text string from TimeStamp structure
+  
+  Fills string *buf with info from TimeStamp structure *ts in a
+  pretty way. The TimeStamp struct is defined in gis.h and populated
+  with e.g. G_read_raster_timestamp().
+  
+  \param ts    TimeStamp structure containing time info
+  \param buf   string to receive formatted timestamp
+
+  \return 1 on success
+  \return -1 error
+*/
 int G_format_timestamp(const struct TimeStamp *ts, char *buf)
 {
     char temp1[128], temp2[128];
@@ -189,21 +197,19 @@ int G_format_timestamp(const struct TimeStamp *ts, char *buf)
     return 1;
 }
 
-
 /*!
- * \brief Fill a TimeStamp structure from a datetime string
- *
- * Populate a TimeStamp structure (defined in gis.h) from a text string.
- * Checks to make sure text string is in valid GRASS datetime format.
- *
- * Returns:
- * 1 on success
- * -1 error
- *
- *  \param ts   TimeStamp structure to be populated
- *  \param buf  String containing formatted time info
- *  \return int exit code
- */
+  \brief Fill a TimeStamp structure from a datetime string
+  
+  Populate a TimeStamp structure (defined in gis.h) from a text
+  string. Checks to make sure text string is in valid GRASS datetime
+  format.
+  
+  \param ts   TimeStamp structure to be populated
+  \param buf  string containing formatted time info
+  
+  \return 1 on success
+  \return -1 error
+*/
 int G_scan_timestamp(struct TimeStamp *ts, const char *buf)
 {
     char temp[1024], *t;
@@ -232,23 +238,21 @@ int G_scan_timestamp(struct TimeStamp *ts, const char *buf)
     return 1;
 }
 
-
 /*!
- * \brief copy TimeStamp into [two] Datetimes structs
- *
- * Use to copy the TimeStamp information into Datetimes, as the members of
- * struct TimeStamp shouldn't be accessed directly.
- *
- * count=0  means no datetimes were copied
- * count=1  means 1 datetime was copied into dt1
- * count=2  means 2 datetimes were copied
- *
- *  \param ts     source TimeStamp structure
- *  \param dt1    first DateTime struct to be filled
- *  \param dt2    second DateTime struct to be filled
- *  \param count  return code
- *  \return
- */
+  \brief Copy TimeStamp into [two] Datetimes structs
+  
+  Use to copy the TimeStamp information into Datetimes, as the members
+  of struct TimeStamp shouldn't be accessed directly.
+ 
+   - count=0  means no datetimes were copied
+   - count=1  means 1 datetime was copied into dt1
+   - count=2  means 2 datetimes were copied
+   
+   \param ts     source TimeStamp structure
+   \param[out] dt1    first DateTime struct to be filled
+   \param[out] dt2    second DateTime struct to be filled
+   \param[out] count  return code
+*/
 void G_get_timestamps(const struct TimeStamp *ts,
 		      DateTime * dt1, DateTime * dt2, int *count)
 {
@@ -264,11 +268,18 @@ void G_get_timestamps(const struct TimeStamp *ts,
 }
 
 
-/* write timestamp file
- * 1 ok
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- */
+/*!
+  \brief Write timestamp file
+
+  \param maptype map type
+  \param dir directory
+  \param name map name
+  \param ts pointer to TimeStamp
+
+  \return 1 on success
+  \return -1 error - can't create timestamp file
+  \return -2 error - invalid datetime in ts
+*/
 static int write_timestamp(const char *maptype, const char *dir,
 			   const char *name, const struct TimeStamp *ts)
 {
@@ -277,7 +288,7 @@ static int write_timestamp(const char *maptype, const char *dir,
 
     fd = G_fopen_new_misc(dir, "timestamp", name);
     if (fd == NULL) {
-	G_warning(_("Can't create timestamp file for %s map %s in mapset %s"),
+	G_warning(_("Unable to create timestamp file for %s map <%s@%s>"),
 		  maptype, name, G_mapset());
 	return -1;
     }
@@ -286,17 +297,25 @@ static int write_timestamp(const char *maptype, const char *dir,
     fclose(fd);
     if (stat == 0)
 	return 1;
-    G_warning(_("Invalid timestamp specified for %s map %s in mapset %s"),
+    G_warning(_("Invalid timestamp specified for %s map <%s@%s>"),
 	      maptype, name, G_mapset());
     return -2;
 }
 
-/* read timestamp file
- * 0 no timestamp file
- * 1 ok
- * -1 error - can't open timestamp file
- * -2 error - invalid datetime values in timestamp file
- */
+/*!
+  \brief Read timestamp file
+
+  \param maptype map type
+  \param dir directory
+  \param name map name
+  \param mapset mapset name
+  \param ts pointer to TimeStamp
+  
+  \return 0 no timestamp file
+  \return 1 on success
+  \return -1 error - can't open timestamp file
+  \return -2 error - invalid datetime values in timestamp file
+*/
 static int read_timestamp(const char *maptype, const char *dir,
 			  const char *name, const char *mapset,
 			  struct TimeStamp *ts)
@@ -308,7 +327,7 @@ static int read_timestamp(const char *maptype, const char *dir,
 	return 0;
     fd = G_fopen_old_misc(dir, "timestamp", name, mapset);
     if (fd == NULL) {
-	G_warning(_("Can't open timestamp file for %s map %s in mapset %s"),
+	G_warning(_("Unable to open timestamp file for %s map <%s@%s>"),
 		  maptype, name, mapset);
 	return -1;
     }
@@ -317,179 +336,153 @@ static int read_timestamp(const char *maptype, const char *dir,
     fclose(fd);
     if (stat == 0)
 	return 1;
-    G_warning(_("Invalid timestamp file for %s map %s in mapset %s"),
+    G_warning(_("Invalid timestamp file for %s map <%s@%s>"),
 	      maptype, name, mapset);
     return -2;
 }
 
-#define RAST_MISC "cell_misc"
-#define VECT_MISC "dig_misc"
-#define GRID3	  "grid3"
-
-
 /*!
- * \brief Read timestamp from raster map
- *
- * Returns:
- * 1 on success
- * 0 or negative on error.
- *
- *  \param name map name
- *  \param mapset mapset the map lives in
- *  \param ts TimeStamp struct to populate
- *  \return int
- */
+  \brief Read timestamp from raster map
+  
+  \param name map name
+  \param mapset mapset the map lives in
+  \param[out] ts TimeStamp struct to populate
+
+  \return 1 on success
+  \return 0 or negative on error
+*/
 int G_read_raster_timestamp(const char *name, const char *mapset,
 			    struct TimeStamp *ts)
 {
     return read_timestamp("raster", RAST_MISC, name, mapset, ts);
 }
 
-
 /*!
- * \brief 
- *
- * Only timestamp files in current mapset can be removed
- * Returns:
- * 0  if no file
- * 1  if successful
- * -1  on fail
- *
- *  \param name
- *  \return int
- */
+  \brief Remove timestamp from raster map
+  
+  Only timestamp files in current mapset can be removed.
+
+  \param name map name
+
+  \return 0 if no file
+  \return 1 on success
+  \return -1 on error
+*/
 int G_remove_raster_timestamp(const char *name)
 {
     return G_remove_misc(RAST_MISC, "timestamp", name);
 }
 
-
-
 /*!
- * \brief Read vector timestamp
- *
- * Is this used anymore with the new GRASS 6 vector engine???
- *
- * Returns 1 on success.  0 or negative on error.
- *
- *  \param name
- *  \param mapset
- *  \param ts
- *  \return int
- */
+  \brief Read timestamp from vector map
+  
+  Is this used anymore with the new GRASS 6 vector engine???
+  
+  \param name map name
+  \param mapset mapset name
+  \param[out] ts TimeStamp struct to populate
+
+  \return 1 on success
+  \return 0 or negative on error
+*/
 int G_read_vector_timestamp(const char *name, const char *mapset,
 			    struct TimeStamp *ts)
 {
     return read_timestamp("vector", VECT_MISC, name, mapset, ts);
 }
 
-
-
 /*!
- * \brief 
- *
- * Is this used anymore with the new GRASS 6 vector engine???
- *
- * Only timestamp files in current mapset can be removed
- * Returns:
- * 0  if no file
- * 1  if successful
- * -1  on fail
- *
- *  \param name
- *  \return int
- */
+  \brief Remove timestamp from vector map
+  
+  Is this used anymore with the new GRASS 6 vector engine???
+  
+  Only timestamp files in current mapset can be removed.
+
+  \param name map name
+
+  \return 0 if no file
+  \return 1 on success
+  \return -1 on failure
+*/
 int G_remove_vector_timestamp(const char *name)
 {
     return G_remove_misc(VECT_MISC, "timestamp", name);
 }
 
-
 /*!
- * \brief read grid3 timestamp
- *
- * Returns 1 on success. 0 or
- * negative on error.
- *
- *  \param name
- *  \param mapset
- *  \param ts
- *  \return int
- */
+  \brief Read timestamp from 3D raster map
+  
+  \param name map name
+  \param mapset mapset name
+  \param[out] ts TimeStamp struct to populate
+
+  \return 1 on success
+  \return 0 or negative on error
+*/
 int G_read_grid3_timestamp(const char *name, const char *mapset,
 			   struct TimeStamp *ts)
 {
     return read_timestamp("grid3", GRID3, name, mapset, ts);
 }
 
-
 /*!
- * \brief remove grid3 timestamp
- *
- * Only timestamp files in current mapset can be removed
- * Returns:
- * 0  if no file
- * 1  if successful
- * -1  on fail
- *
- *  \param name
- *  \return int
- */
+  \brief Remove timestamp from 3D raster map
+  
+  Only timestamp files in current mapset can be removed.
+
+  \param name map name
+
+  \return 0 if no file
+  \return 1 on success
+  \return -1 on failure
+*/
 int G_remove_grid3_timestamp(const char *name)
 {
     return G_remove_misc(GRID3, "timestamp", name);
 }
 
+/*!
+  \brief Write timestamp of raster map
 
+  \param name map name
+  \param[out] ts TimeStamp struct to populate
+  
+  \return 1 on success
+  \return -1 error - can't create timestamp file
+  \return -2 error - invalid datetime in ts
 
-/*!
- * \brief 
- *
- * Returns:
- * 1 on success.
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- *
- *  \param name
- *  \param ts
- *  \return int
  */
 int G_write_raster_timestamp(const char *name, const struct TimeStamp *ts)
 {
     return write_timestamp("raster", RAST_MISC, name, ts);
 }
 
+/*!
+  \brief Write timestamp of vector map
 
+  \param name map name
+  \param[out] ts TimeStamp struct to populate
+  
+  \return 1 on success
+  \return -1 error - can't create timestamp file
+  \return -2 error - invalid datetime in ts
 
-/*!
- * \brief 
- *
- * Returns:
- * 1 on success.
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- *
- *  \param name
- *  \param ts
- *  \return int
  */
 int G_write_vector_timestamp(const char *name, const struct TimeStamp *ts)
 {
     return write_timestamp("vector", VECT_MISC, name, ts);
 }
 
-
 /*!
- * \brief write grid3 timestamp
- *
- * Returns:
- * 1 on success.
- * -1 error - can't create timestamp file
- * -2 error - invalid datetime in ts
- *
- *  \param name
- *  \param ts
- *  \return int
+  \brief Write timestamp of 3D raster map
+
+  \param name map name
+  \param[out] ts TimeStamp struct to populate
+  
+  \return 1 on success
+  \return -1 error - can't create timestamp file
+  \return -2 error - invalid datetime in ts
+
  */
 int G_write_grid3_timestamp(const char *name, const struct TimeStamp *ts)
 {

lib/gis/whoami.c

@@ -1,17 +1,14 @@
-
-/**
- * \file whoami.c
+/*!
+ * \file gis/whoami.c
  *
  * \brief GIS Library - Login 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 <unistd.h>
@@ -23,8 +20,7 @@
 
 #include <grass/gis.h>
 
-
-/**
+/*!
  * \brief Gets user's name.
  *
  * Returns a pointer to a string containing the user's login name.
@@ -34,9 +30,8 @@
  * because the ttyname(0) rotuine fails in ucb universe.
  * So we check for this, too.
  *
- *  \retval char * Pointer to string
+ * \return pointer to string ("anonymous" by default)
  */
-
 const char *G_whoami(void)
 {
     static int initialized;

lib/grasslib.dox

@@ -33,13 +33,17 @@ who provides the GRASS main infrastructure.
 
 Main web site: <a href="http://grass.osgeo.org">http://grass.osgeo.org</a>
 
-<h2>Table of contents</h2>
+<b>Table of contents</b>
 
 - \subpage corelibs
 - \subpage libs
 - \subpage interfaces
 - \subpage gui
 - \subpage location
+- \subpage Compiling_and_Installing_GRASS_Modules
+ - \subpage Makefile_Variables
+ - \subpage Constructing_a_Makefile
+ - \subpage Multiple_Architecture_Conventions
 
 <p>
 <i>Missing entries below are either not yet uploaded to SVN (need to be migrated
@@ -164,4 +168,142 @@ as follows:
 -->
 \image html "loc_struct.png" "Diagram of GRASS file structure"
 
+\section Compiling_and_Installing_GRASS_Modules Compiling and Installing GRASS Modules
+
+GRASS modules are compiled and installed using the UNIX <tt>make</tt>
+command, which reads a file named <tt>Makefile</tt> (see \ref
+Multiple_Architecture_Conventions for more information) and then runs
+the compiler. The GRASS compilation process allows for
+multiple-architecture compilation from a single copy of the source
+code (for instance, if the source code is NFS mounted to various
+machines with differing architectures). This chapter assumes that the
+programmer is familiar with <tt>make</tt> and its accompanying
+Makefile.
+
+\todo Explain ''auto-conf''
+
+\todo Include contents of SUBMITTING and INSTALL files from source code
+
+To compile enter following:
+
+\verbatim
+./configure
+make
+make install
+\endverbatim
+
+Then the code will be compiled into "/usr/local/grass-7.x.y" directory. The start
+script "grass7x" will be placed into "/usr/local/bin/".
+
+Optionally other target directories can be specified while "configuring":
+
+\verbatim
+./configure --prefix=/opt/grass-7.x.y --with-bindir=/usr/bin
+make
+make install
+\endverbatim
+
+This will store the GRASS binaries into the directory
+"/opt/grass-7.x.y" and the script mentioned above into "/usr/bin".
+
+The script "make" is required to compile single modules. The
+compilation process and requirements are discussed in more detail now.
+
+\subsection Makefile_Variables Makefile Variables
+
+\todo Update the list.
+
+<b>GRASS Libraries</b>. The following variables name the various GRASS 
+libraries:
+
+ - <i>GISLIB</i> - This names the <b>GIS Library</b>, which is the
+principal GRASS library. See \ref GIS_Library for details about this
+library, and \ref Loading_the_GIS_Library for a sample Makefile which
+loads this library.
+
+ - <i>SEGMENTLIB</i> - This names the <b>Segment Library</b>, which
+manages large matrix data. See \ref Segment_Library for details about
+this library, and \ref Loading_the_Vask_Library for a sample
+<i>Makefile</i> which loads this library.
+
+ - <i>RASTERLIB</i> - This names the <b>Raster Graphics Library</b>,
+which communicates with GRASS graphics drivers. See \ref
+Raster_Graphics_Library for details about this library, and \ref
+Loading_the_Raster_Graphics_Library for a sample <i>Makefile</i> which
+loads this library.
+
+ - <i>DISPLAYLIB</i> - This names the <b>Display Graphics Library</b>,
+which provides a higher level graphics interface to
+<i>RASTERLIB</i>. See Display_Graphics_Library for details about this
+library, and Loading_the_Display_Graphics_Library for a sample
+<i>Makefile</i> which loads this library.
+
+<b>UNIX Libraries:</b> The following variables name some useful UNIX 
+system libraries:
+
+ - <i>MATHLIB</i> This names the math library. It should be used
+instead of the -lm loader option.
+
+ - <i>CURSES</i> This names both the curses and termcap libraries. It
+should be used instead of the -lcurses/-lncurses and
+-ltermcap loader options. Do not use <tt>$CURSES</tt> if you use
+<tt>$VASK</tt>.
+
+ - <i>TERMLIB</i> This names the termcap library. It should be used
+-instead of the ltermcap or -ltermlib loader options. Do not use
+-<tt>$TERMLIB</tt> if you use <tt>$VASK</tt> or <tt>$CURSES</tt>.
+
+<b>Compiler and loader variables.</b> The following variables are
+related to compiling and loading C programs:
+
+ - <i>EXTRA\_CFLAGS</i> This variable can be used to add additional
+options to <tt>$CFLAGS</tt>. It has no predefined values. It is
+usually used to specify additional -I include directories, or -D
+preprocessor defines.
+
+\subsection Constructing_a_Makefile Constructing a Makefile
+
+
+The complete syntax for a <i>Makefile</i> is discussed in the UNIX
+documentation for <tt>make</tt> and will not be repeated here. The
+essential idea is that a target (e.g. a GRASS module) is to be built
+from a list of dependencies (e.g. object files, libraries, etc.). The
+relationship between the target, its dependencies, and the rules for
+constructing the target is expressed according to the following
+syntax:
+
+\code
+target: dependencies
+
+actions
+
+more actions
+\endcode
+
+If the target does not exist, or if any of the dependencies have a newer 
+date than the target (i.e., have changed), the actions will be executed to 
+build the target. The actions must be indented using a TAB. <tt>make</tt> is 
+picky about this. It does not like spaces in place of the TAB.
+
+\section Multiple_Architecture_Conventions Multiple-Architecture Conventions
+
+
+The following conventions allow for multiple architecture compilation on a 
+machine that uses a common or networked GRASS source code directory tree.
+
+Object files and library archives are compiled into subdirectories
+that represent the architecture that they were compiled on. These
+subdirectories are created in the $SRC directory as OBJ.<tt>arch</tt>
+and LIB.<tt>arch</tt>, where <tt>arch</tt> represents the architecture
+of the compiling machine. Thus, for example, $SRC/OBJ.sun4 would
+contain the object files for Sun/4 and SPARC architectures, and
+<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
+Linux architectures. Likewise, <tt>$SRC/OBJ.686-pc-linux-gnu</tt>
+would contain the object files for Linux architectures, and
+<tt>$SRC/LIB.686-pc-linux-gnu</tt> would contain library archives for
+Linux architectures.
+
+Note that 'arch' is defined for a specific architecture during setup and 
+compilation of GRASS, it is not limited to sun4 or any specific string.
+
 */