dox: updating the color section of raster 3D main page and adding comments into color.c file

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

lib/raster3d/color.c

@@ -17,6 +17,13 @@ static int read_old_colors(FILE *, struct Colors *);
 
 /*---------------------------------------------------------------------------*/
 
+/*!
+   \brief Removes the primary and/or secondary color file.
+
+   \todo Is <em>primary and/or secondary color file</em> still valid for 7?
+
+   \see G_remove_colr
+*/
 int Rast3d_remove_color(const char *name)
  /* adapted from G_remove_colr */
 {
@@ -25,8 +32,16 @@ int Rast3d_remove_color(const char *name)
 
 /*---------------------------------------------------------------------------*/
 
-int
-Rast3d_read_colors(const char *name, const char *mapset, struct Colors *colors)
+/*!
+   \brief Reads color file for map \p name in \p mapset into the Colors structure.
+
+   \param name 3D raster map name
+   \param mapset mapset name
+   \param colors colors to be associated with a map
+
+   \see Rast3d_write_colors, Rast_read_colors
+*/
+int Rast3d_read_colors(const char *name, const char *mapset, struct Colors *colors)
  /* adapted from Rast_read_colors */
 {
     const char *err;
@@ -321,8 +336,16 @@ static int read_old_colors(FILE * fd, struct Colors *colors)
 
 /*---------------------------------------------------------------------------*/
 
-int
-Rast3d_write_colors(const char *name, const char *mapset, struct Colors *colors)
+/*!
+   \brief Writes the \p colors for map \p name in \p mapset into a color file.
+
+   \param name 3D raster map name
+   \param mapset mapset name
+   \param colors colors to be associated with a map
+
+   \see Rast3d_read_colors, Rast3d_remove_color, Rast_write_colors
+*/
+int Rast3d_write_colors(const char *name, const char *mapset, struct Colors *colors)
  /* adapted from Rast_write_colors */
 {
     FILE *fd;

lib/raster3d/raster3dlib.dox

@@ -1343,32 +1343,13 @@ not possible to use functions for reading and writing.
 
 \subsection RASTER3D_Color_Support RASTER3D Color Support
 
-<P>
-Applications can use the standard GRASS functions to work with colors, except
-for the file manipulations.
-
-<P>
-int Rast3d_removeColor(char *name)
-Removes the primary and/or secondary color file. See <EM>G_remove_colr</EM> for
-details.
-
-<P>
-Returns always 0.
+Applications can use the standard GRASS functions to work with colors,
+e.g. Rast_get_d_color_range(). However, the file manipulations must be handled
+using specialized raster 3D functions.
 
-<P>
-int Rast3d_readColors(char *name, char *mapset, struct Colors
-   *colors) Reads color file for map <EM>name</EM> in <EM>mapset</EM> into the
-   <EM>colors</EM> structure.  See <EM>G_read_colors</EM>
-   (Raster_Color_Table) for details and return values.
-
-<P>
-int Rast3d_writeColors(char *name, char *mapset, struct Colors
-   *colors)Writes colors stored in <EM>colors</EM> structure into the color
-   file for map <EM>name</EM> in <EM>mapset</EM>.  See <EM>G_write_colors</EM>
-   (Raster_Color_Table) for
-   details and return values.
-
-<P>
+Rast3d_read_colors() function reads color file for a map into a Colors structure.
+Rast3d_write_colors() function stores colors in color files for a map and
+Rast3d_remove_color() function removes the color file.
 
 \subsection RASTER3D_Categories_Support RASTER3D Categories Support