[GRASS-SVN] r52479 - in grass/trunk: include lib/gis lib/raster

[svn_grass at osgeo.org]

Author: martinl
Date: 2012-07-30 09:53:28 -0700 (Mon, 30 Jul 2012)
New Revision: 52479

Modified:
   grass/trunk/include/raster.h
   grass/trunk/lib/gis/gislib.dox
   grass/trunk/lib/raster/rasterlib.dox
Log:
rasterlib: better documentation of History structure


Modified: grass/trunk/include/raster.h
===================================================================
--- grass/trunk/include/raster.h	2012-07-30 16:20:49 UTC (rev 52478)
+++ grass/trunk/include/raster.h	2012-07-30 16:53:28 UTC (rev 52479)
@@ -147,24 +147,40 @@
     /* label, and quant rules are never reordered. Olga apr,95 */
 };
 
+/*! \brief Raster history info (metadata)
+
+  See History structure for implementation issues.
+*/
 enum History_field
 {
+    /*! \brief Raster name */
     HIST_MAPID,
+    /*! \brief Raster title */
     HIST_TITLE,
+    /*! \brief Raster mapset */
     HIST_MAPSET,
+    /*! \brief User who creater raster map */
     HIST_CREATOR,
+    /*! \brief Map type (always "raster") */
     HIST_MAPTYPE,
+    /*! \brief Description of original data source (two lines) */
     HIST_DATSRC_1,
     HIST_DATSRC_2,
+    /*! \brief One-line data description */
     HIST_KEYWRD,
 
+    /*! \brief Number of fields to be defined in History structure */
     HIST_NUM_FIELDS,
 };
 
+/*! \brief Raster history info (metadata) */
 struct History
 {
+    /*! \brief Array of fields (see \ref History_field for details) */
     char *fields[HIST_NUM_FIELDS];
+    /*! \brief Number of lines in lines array */
     int nlines;
+    /*! \brief Lines array */
     char **lines;
 };
 

Modified: grass/trunk/lib/gis/gislib.dox
===================================================================
--- grass/trunk/lib/gis/gislib.dox	2012-07-30 16:20:49 UTC (rev 52478)
+++ grass/trunk/lib/gis/gislib.dox	2012-07-30 16:53:28 UTC (rev 52479)
@@ -2203,29 +2203,12 @@
 
 \subsection struct_History struct History
 
-The <i>History</i> structure is used to document raster files. The 
-information contained here is for the user. It is not used in any 
-operational way by GRASS. The structure is:
+The History structure is used to document raster files. The
+information contained here is for the user. It is not used in any
+operational way by GRASS. 
 
-\code
-# define MAXEDLINES 50
-# define RECORD_LEN 80
+See documentation of History structure for details.
 
-struct History
-{
- char mapid[RECORD_LEN];
- char title[RECORD_LEN];
- char mapset[RECORD_LEN];
- char creator[RECORD_LEN];
- char maptype[RECORD_LEN];
- char datsrc_1[RECORD_LEN];
- char datsrc_2[RECORD_LEN];
- char keywrd[RECORD_LEN];
- int edlinecnt;
- char edhist[MAXEDLINES][RECORD_LEN];
-};
-\endcode
-
 The <i>mapid</i> and <i>mapset</i> are the raster file name and
 mapset, <i>title</i> is the raster file title, <i>creator</i> is the
 user who created the file, <i>maptype</i> is the map type (which

Modified: grass/trunk/lib/raster/rasterlib.dox
===================================================================
--- grass/trunk/lib/raster/rasterlib.dox	2012-07-30 16:20:49 UTC (rev 52478)
+++ grass/trunk/lib/raster/rasterlib.dox	2012-07-30 16:53:28 UTC (rev 52479)
@@ -294,13 +294,10 @@
  - Rast_get_cellhd()
 
 The raster header for the raster file in the specified mapset is read
-into the <em>cellhd</em> structure. If there is an error reading the
-raster header file, a diagnostic message is printed and -1 is
-returned. Otherwise, 0 is returned.
+into the Cell_head structure.
 
-<b>Note:</b> If the raster file is a reclass file, the raster header
-for the referenced raster file is read instead. See \ref Reclass_Format
-for information about reclass files, and Rast_is_reclass()
+<b>Note:</b> If the raster file is a reclassified, the raster header
+for the referenced raster file is read instead. See Rast_is_reclass()
 for distinguishing reclass files from regular raster files.
 
 <b>Note:</b> It is not necessary to get the raster header for a map
@@ -319,9 +316,7 @@
  - Rast_put_cellhd()
 
 This routine writes the information from the Cell_head structure to
-the raster header file for the map layer in the current mapset. If
-there was an error creating the raster header, -1 is returned. No
-diagnostic is printed. Otherwise, 1 is returned to indicate success.
+the raster header file for the map layer in the current mapset.
 
 <b>Note:</b> Programmers should have no reason to use this routine. It
 is used by Rast_close() to give new raster files correct header
@@ -640,10 +635,9 @@
 
 The history file contains documentary information about the raster
 file: who created it, when it was created, what was the original data
-source, what information is contained in the raster file, etc. This
-file is discussed in \ref Raster_History_File_Format.
+source, what information is contained in the raster file, etc.
 
-The following routines manage this file. They use the <em>History</em>
+The following routines manage this file. They use the History
 structure which is described in \ref GIS_Library_Data_Structures.
 
 <b>Note:</b> This structure has existed relatively unmodified since
@@ -653,31 +647,25 @@
 
  - Rast_read_history()
 
-Read raster history file. This routine reads the history file for the
-raster map into the <em>history</em> structure. A diagnostic message
-is printed and -1 is returned if there is an error reading the history
-file. Otherwise, 0 is returned.
+Reads raster history file. This routine reads the history file for the
+raster map into the History structure.
 
  - Rast_write_history()
 
-Write raster history file. This routine writes the history file for
-the raster map in the current mapset from the <em>history</em>
-structure. A diagnostic message is printed and -1 is returned if there
-is an error writing the history file. Otherwise, 0 is returned.
+Writes raster history file. This routine writes the history file for
+the raster map in the current mapset from the History structure.
 
-<b>Note:</b> The <em>history</em> structure should first be
+<b>Note:</b> The History structure should first be
 initialized using Rast_short_history().
 
  - Rast_short_history()
 
-Initialize history structureThis routine initializes the
-<em>history</em> structure, recording the date, user, module name and
-the raster map.
+This routine initializes History structure, recording the date, user,
+module name and the raster map.
 
 <b>Note:</b> This routine only initializes the data structure. It does
 not write the history file.
 
-
 \section Raster_Range_File Raster Range File
 
 The following routines manage the raster range file. This file