ogsf: very initial lib cleaning and doxygenization finished (sync'ed with devbr6)

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

lib/ogsf/GK2.c

@@ -13,14 +13,17 @@
   for details.
   
   \author Bill Brown USACERL, GMSL/University of Illinois
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdlib.h>
-#include <stdio.h>
+
+#include <grass/gis.h>
+#include <grass/glocale.h>
 #include <grass/gstypes.h>
 #include <grass/keyframe.h>
 #include <grass/kftypes.h>
-#include <grass/glocale.h>
+
 
 static int _add_key(Keylist *, int, float);
 static void _remove_key(Keylist *);

lib/ogsf/GP2.c

@@ -13,14 +13,15 @@
   for details.
   
   \author Bill Brown USACERL (January 1994)
-  Doxygenized by Martin landa <landa.martin gmail.com> (May 2008)
+  \author Doxygenized by Martin landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdlib.h>
 #include <string.h>
-#include <grass/gis.h>
 
+#include <grass/gis.h>
 #include <grass/gstypes.h>
+
 #include "gsget.h"
 
 static int Site_ID[MAX_SITES];

lib/ogsf/GS2.c

@@ -24,8 +24,8 @@
   for details.
   
   \author Bill Brown USACERL (1993)
-  Pierre de Mouveaux <p_de_mouveaux hotmail.com> (updated October 1999)
-  Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
+  \author Pierre de Mouveaux <p_de_mouveaux hotmail.com> (updated October 1999)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdlib.h>

lib/ogsf/GSX.c

@@ -13,6 +13,7 @@
   for details.
   
   \author Bill Brown USACERL (December 1993)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <grass/gstypes.h>

lib/ogsf/GS_util.c

@@ -13,13 +13,14 @@
   for details.
   
   \author Bill Brown USACERL, GMSL/University of Illinois
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 #include <math.h>
 #include <string.h>
 
+#include <grass/gis.h>
 #include <grass/gstypes.h>
 
 /*!

lib/ogsf/GV2.c

@@ -13,14 +13,15 @@
   for details.
   
   \author Bill Brown USACERL, GMSL/University of Illinois
-  Doxygenized by Martin Landa <landa.martin gmail.com>
+  \author Doxygenized by Martin Landa <landa.martin gmail.com>
 */
 
-#include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include <grass/gis.h>
 #include <grass/gstypes.h>
+
 #include "gsget.h"
 
 static int Vect_ID[MAX_VECTS];

lib/ogsf/Gs3.c

@@ -17,7 +17,6 @@
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 #include <string.h>
 
 #include <grass/gis.h>

lib/ogsf/Gv3.c

@@ -17,6 +17,7 @@
 */
 
 #include <stdlib.h>
+
 #include <grass/gis.h>
 #include <grass/Vect.h>
 #include <grass/glocale.h>

lib/ogsf/gk.c

@@ -17,9 +17,9 @@
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 #include <math.h>
 
+#include <grass/gis.h>
 #include <grass/glocale.h>
 #include <grass/gstypes.h>
 #include <grass/keyframe.h>

lib/ogsf/gp.c

@@ -17,8 +17,8 @@
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 
+#include <grass/gis.h>
 #include <grass/gstypes.h>
 
 #define FIRST_SITE_ID 21720

lib/ogsf/gpd.c

@@ -16,10 +16,11 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
 #include <stdlib.h>
 #include <math.h>
+
 #include <grass/gstypes.h>
+
 #include "rowcol.h"
 
 #define CHK_FREQ 50

lib/ogsf/gs_bm.c

@@ -16,9 +16,10 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
-#include <grass/gstypes.h>
+#include <grass/gis.h>
 #include <grass/glocale.h>
+#include <grass/gstypes.h>
+
 #include "gsget.h"
 
 /*!

lib/ogsf/gs_norms.c

@@ -17,11 +17,11 @@
 */
 
 #include <math.h>
-#include <stdio.h>
 
+#include <grass/gis.h>
 #include <grass/gstypes.h>
-#include "gsget.h"
 
+#include "gsget.h"
 #include "rowcol.h"
 
 #define NTOP 0x00001000

lib/ogsf/gsd_cplane.c

@@ -16,9 +16,6 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-/* DEBUG */
-#include <stdio.h>
-
 #include <grass/gstypes.h>
 #include "rowcol.h"
 

lib/ogsf/gsd_fonts.c

@@ -20,6 +20,7 @@
 
 #include <string.h>
 #include <assert.h>
+
 #include <grass/gstypes.h>
 #include <grass/ogsf_proto.h>
 

lib/ogsf/gsd_fringe.c

@@ -18,9 +18,8 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
-
 #include <grass/gstypes.h>
+
 #include "gsget.h"
 #include "rowcol.h"
 

lib/ogsf/gsd_img_mpeg.c

@@ -17,7 +17,6 @@
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 #include <string.h>
 
 #include <grass/gis.h>

lib/ogsf/gsd_img_ppm.c

@@ -25,7 +25,6 @@
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 
 #include <grass/gis.h>
 #include <grass/glocale.h>

lib/ogsf/gsd_img_tif.c

@@ -28,7 +28,6 @@
 #ifdef HAVE_TIFFIO_H
 
 #include <stdlib.h>
-#include <stdio.h>
 #include <sys/types.h>
 
 #include <grass/gis.h>

lib/ogsf/gsd_label.c

@@ -16,6 +16,7 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
+#include <grass/gis.h>
 #include <grass/glocale.h>
 #include <grass/gstypes.h>
 

lib/ogsf/gsd_legend.c

@@ -20,7 +20,6 @@
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 
 #include <grass/config.h>
 

lib/ogsf/gsd_objs.c

@@ -16,12 +16,13 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+
 #include <grass/gis.h>
 #include <grass/ogsf_proto.h>
 #include <grass/gstypes.h>
+
 #include "gsget.h"
 #include "math.h"
 #include "rowcol.h"

lib/ogsf/gsd_surf.c

@@ -13,17 +13,19 @@
   for details.
   
   \author Bill Brown USACERL (October 1993)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 
+#include <grass/gis.h>
+#include <grass/glocale.h>
 #include <grass/gstypes.h>
+
 #include "gsget.h"
 #include "rowcol.h"
 
 /*
-#define TRACE_DFUNCS
 #define CALC_AREA
 */
 
@@ -38,8 +40,9 @@
 
 #define DEBUG_ARROW (0)
 
-/***********************************************************************/
-/* MACROS for use in gsd_ortho_wall ONLY !!! */
+/*!
+  \brief MACROS for use in gsd_ortho_wall ONLY !!!
+*/
 #define SET_SCOLOR(sf) \
 	    if(check_color[sf]) \
 	    { \
@@ -66,15 +69,19 @@ static int FCmode;
  * pixmap to draw into.
 */
 
+/*!
+  \brief ADD
+
+  \param surf surface (geosurf)
+
+  \return
+  \return -1 on error
+*/
 int gsd_surf(geosurf * surf)
 {
     int desc, ret;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_surf");
-    }
-#endif
+    G_debug (3, "gsd_surf");
 
     desc = ATT_TOPO;
 
@@ -120,8 +127,15 @@ int gsd_surf(geosurf * surf)
     return (ret);
 }
 
-/************************************************************************/
-/* Using tmesh - not confident with qstrips portability */
+/*!
+  \brief ADD
+
+  Using tmesh - not confident with qstrips portability
+
+  \param surf surface (geosurf)
+
+  \return
+*/
 int gsd_surf_map_old(geosurf * surf)
 {
     int check_mask, check_color, check_transp;
@@ -151,11 +165,7 @@ int gsd_surf_map_old(geosurf * surf)
     float kem, ksh, pkem, pksh;
     unsigned int ktrans;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_surf_map_old");
-    }
-#endif
+    G_debug(3, "gsd_surf_map_old");
 
     /* avoid scaling by zero */
     GS_get_scale(&tx, &ty, &tz, 1);
@@ -695,17 +705,26 @@ int gsd_surf_map_old(geosurf * surf)
     show_colormode();
 
 #ifdef CALC_AREA
-    fprintf(stderr, "Surface Area: %.12lf\n", asurf);
-    fprintf(stderr, "Exaggerated Surface Area: %.12lf\n", axsurf);
+    G_debug (4, "  Surface Area: %.12lf", asurf);
+    G_debug (4, "  Exaggerated Surface Area: %.12lf", axsurf);
 #endif
 
     return (0);
 }
 
-/************************************************************************/
-/* Using tmesh - not confident with qstrips portability */
-/* TODO: FIX: do_diff won't work right - needs normals - maybe 
-   calculate on the fly */
+/*!
+  \brief 
+  
+  Using tmesh - not confident with qstrips portability
+  
+  \todo FIX: do_diff won't work right - needs normals - maybe 
+  calculate on the fly
+
+  \param surf surface (geosurf)
+  \param k
+
+  \return
+*/
 int gsd_surf_const(geosurf * surf, float k)
 {
     int do_diff, check_mask, check_color;
@@ -727,11 +746,7 @@ int gsd_surf_const(geosurf * surf, float k)
 
     unsigned int ktrans = 255;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_surf_const");
-    }
-#endif
+    G_debug(3, "gsd_surf_const");
 
     if (GS_check_cancel()) {
 	return (-1);
@@ -1063,18 +1078,35 @@ int gsd_surf_const(geosurf * surf, float k)
     return (0);
 }
 
-/************************************************************************/
+/*!
+  \brief Define user function
+
+  Not yet supported
+
+  \param gs surface (geosurf)
+  \param user_func user function
+
+  \return 1
+*/
 int gsd_surf_func(geosurf * gs, int (*user_func) ())
 {
 
-    /*
-       Gs_status("Not yet supported");
-     */
-
     return (1);
 }
 
-/************************************************************************/
+/*!
+  \brief ADD
+
+  \param npts1
+  \param npts2
+  \param surf1 first surface (geosurf)
+  \param surf2 second surface (geosurf)
+  \param points1
+  \param points2
+  \param norm
+
+  \return 1
+*/
 int gsd_triangulated_wall(int npts1, int npts2, geosurf * surf1,
 			  geosurf * surf2, Point3 * points1, Point3 * points2,
 			  float *norm)
@@ -1167,8 +1199,11 @@ int gsd_triangulated_wall(int npts1, int npts2, geosurf * surf1,
     return (1);
 }
 
+/*!
+  \brief ADD
 
-/************************************************************************/
+  \param mode
+*/
 void gsd_setfc(int mode)
 {
     FCmode = mode;
@@ -1176,13 +1211,24 @@ void gsd_setfc(int mode)
     return;
 }
 
-/************************************************************************/
+/*!
+  \brief ADD
+
+  \return
+*/
 int gsd_getfc(void)
 {
     return (FCmode);
 }
 
-/******************************** NEW **********************************/
+/*!
+  \brief ADD
+
+  \param surf surface (geosurf)
+  \param point
+
+  \return
+*/
 static int transpoint_is_masked(geosurf * surf, Point3 point)
 {
     Point3 tp;
@@ -1193,12 +1239,20 @@ static int transpoint_is_masked(geosurf * surf, Point3 point)
     return (gs_point_is_masked(surf, tp));
 }
 
-/***********************************************************************/
-/* get_point_below returns: 
-     0 if there is no surface below the current,
-    -1 if the current surface is masked,
-     1 if the surface below the current surface is not masked 
-       (belowsurf is assigned)
+/*!
+  \brief ADD
+
+  \param points
+  \param gsurf
+  \param ptn
+  \param cursurf
+  \param numsurfs
+  \param belowsurf
+
+  \return 0 if there is no surface below the current,
+  \return -1 if the current surface is masked,
+  \return 1 if the surface below the current surface is not masked 
+  (belowsurf is assigned)
 */
 static int get_point_below(Point3 ** points, geosurf ** gsurfs, int ptn,
 			   int cursurf, int numsurfs, int *belowsurf)
@@ -1254,10 +1308,21 @@ static int get_point_below(Point3 ** points, geosurf ** gsurfs, int ptn,
 }
 
 
-/***********************************************************************/
 /*
 #define CPDEBUG
 */
+
+/*!
+  \brief ADD
+
+  \param np
+  \param ns
+  \param gsurfs
+  \param points
+  \param norm
+
+  \return
+*/
 int gsd_ortho_wall(int np, int ns, geosurf ** gsurfs, Point3 ** points,
 		   float *norm)
 {
@@ -1445,15 +1510,10 @@ int gsd_ortho_wall(int np, int ns, geosurf ** gsurfs, Point3 ** points,
 							1.0, points[bn][i][Z],
 							&tx, &ty)) {
 				    /* crossing going up */
-#ifdef CPDEBUG
-				    {
-					fprintf(stderr,
-						"crossing going up at surf %d no. %d\n",
-						n, i);
-					G_sleep(1);
-				    }
-#endif
 
+				    G_debug(4, "crossing going up at surf %d no. %d",
+					    n, i);
+				    
 				    upper = 1;
 				    xing[Z] = ty;
 				    xing[Y] = points[n][i - 1][Y] + tx *
@@ -1486,14 +1546,9 @@ int gsd_ortho_wall(int np, int ns, geosurf ** gsurfs, Point3 ** points,
 							     points[bnl][i]
 							     [Z], &tx, &ty)) {
 				    /* crossing going down */
-#ifdef CPDEBUG
-				    {
-					fprintf(stderr,
-						"crossing going down at surf %d no. %d\n",
-						n, i);
-					G_sleep(1);
-				    }
-#endif
+
+				    G_debug (4, "crossing going down at surf %d no. %d",
+					     n, i);
 
 				    upper = 1;
 				    xing[Z] = ty;
@@ -1538,12 +1593,10 @@ int gsd_ortho_wall(int np, int ns, geosurf ** gsurfs, Point3 ** points,
 #ifdef CPDEBUG
 				    {
 					lower = 1;
-					fprintf(stderr,
-						"lower crossing at surf %d no. %d between surfs %d & %d\n",
-						n, i, bn, bnl);
-					G_sleep(1);
 				    }
 #endif
+				    G_debug (4, "lower crossing at surf %d no. %d between surfs %d & %d",
+					     n, i, bn, bnl);
 
 				    xing[Z] = ty;
 				    xing[Y] = points[bn][i - 1][Y] + tx *
@@ -1571,31 +1624,27 @@ int gsd_ortho_wall(int np, int ns, geosurf ** gsurfs, Point3 ** points,
 #ifdef CPDEBUG
 			    {
 				if (!upper && !lower) {
-				    fprintf(stderr,
-					    "Crossing NOT found or masked: \n");
-				    fprintf(stderr,
-					    "\tcurrent surf: %d [ %.2f %.2f %.2f -> %.2f %.2f %f\n",
-					    n, points[n][i - 1][X],
-					    points[n][i - 1][Y],
-					    points[n][i - 1][Z],
-					    points[n][i][X], points[n][i][Y],
-					    points[n][i][Z]);
-				    fprintf(stderr,
-					    "\tbelow surf: %d [ %.2f %.2f %.2f -> %.2f %.2f %f\n",
-					    bn, points[bn][i - 1][X],
-					    points[bn][i - 1][Y],
-					    points[bn][i - 1][Z],
-					    points[bn][i][X],
-					    points[bn][i][Y],
-					    points[bn][i][Z]);
-				    fprintf(stderr,
-					    "\tlast below surf: %d [ %.2f %.2f %.2f -> %.2f %.2f %f\n",
-					    bnl, points[bnl][i - 1][X],
-					    points[bnl][i - 1][Y],
-					    points[bnl][i - 1][Z],
-					    points[bnl][i][X],
-					    points[bnl][i][Y],
-					    points[bnl][i][Z]);
+				    G_debug (4, "Crossing NOT found or masked:");
+				    G_debug (4, "  current surf: %d [ %.2f %.2f %.2f -> %.2f %.2f %f",
+					     n, points[n][i - 1][X],
+					     points[n][i - 1][Y],
+					     points[n][i - 1][Z],
+					     points[n][i][X], points[n][i][Y],
+					     points[n][i][Z]);
+				    G_debug (4, "  below surf: %d [ %.2f %.2f %.2f -> %.2f %.2f %f\n",
+					     bn, points[bn][i - 1][X],
+					     points[bn][i - 1][Y],
+					     points[bn][i - 1][Z],
+					     points[bn][i][X],
+					     points[bn][i][Y],
+					     points[bn][i][Z]);
+				    G_debug (4, "  last below surf: %d [ %.2f %.2f %.2f -> %.2f %.2f %f\n",
+					     bnl, points[bnl][i - 1][X],
+					     points[bnl][i - 1][Y],
+					     points[bnl][i - 1][Z],
+					     points[bnl][i][X],
+					     points[bnl][i][Y],
+					     points[bnl][i][Z]);
 				}
 			    }
 #endif
@@ -1643,11 +1692,17 @@ int gsd_ortho_wall(int np, int ns, geosurf ** gsurfs, Point3 ** points,
     return (1);
 }
 
-/************************************************************************/
-/* bgn & end should already be in world modeling coords, but have to */
-/* be reverse-translated to apply to each surface */
-/* float bgn[2], end[2]  2d line for cutting plane */
-/* float norm[3]         indicates which way wall faces */
+/*!
+  \brief ADD
+
+  bgn,end should already be in world modeling coords, but have to
+  be reverse-translated to apply to each surface
+
+  \param bgn,end  2d line for cutting plane
+  \param norm indicates which way wall faces
+  
+  \return
+*/
 int gsd_wall(float *bgn, float *end, float *norm)
 {
     geosurf *gsurfs[MAX_SURFS];
@@ -1675,8 +1730,8 @@ int gsd_wall(float *bgn, float *end, float *norm)
 
 	if (n) {
 	    if (npts != npts1) {
-		fprintf(stderr, "Error: cut-plane points mis-match between surfaces\n");
-		fprintf(stderr, "Check resolution(s)\n");
+		G_warning (_("Cut-plane points mis-match between surfaces. "
+			     "Check resolution(s)."));
 		err = 1;
 		nsurfs = n;
 
@@ -1701,12 +1756,7 @@ int gsd_wall(float *bgn, float *end, float *norm)
 	}
 
 	/* allocate space in points and copy tmp to points */
-	if (NULL == (points[n] = (Point3 *) calloc(npts1, sizeof(Point3)))) {
-	    fprintf(stderr, "out of memory\n");
-	    err = 1;
-
-	    break;
-	}
+	points[n] = (Point3 *) G_calloc(npts1, sizeof(Point3)); /* G_fatal_error */
 
 	for (i = 0; i < npts1; i++) {
 	    GS_v3eq(points[n][i], tmp[i]);
@@ -1721,7 +1771,7 @@ int gsd_wall(float *bgn, float *end, float *norm)
     if (err) {
 	for (n = 0; n < nsurfs; n++) {
 	    if (points[n]) {
-		free(points[n]);
+		G_free(points[n]);
 	    }
 	}
 	return (0);
@@ -1732,15 +1782,22 @@ int gsd_wall(float *bgn, float *end, float *norm)
 
     for (n = 0; n < nsurfs - 1; n++) {
 	/* don't free last - it's constant */
-	free(points[n]);
+	G_free(points[n]);
     }
 
     return (ret);
 }
 
-/************************************************************************/
-/* need to do Zexag scale of normal for arrow direction, drawing
-routine unexags z for arrow */
+/*!
+  \brief ADD
+
+  Need to do Zexag scale of normal for arrow direction, drawing
+  routine unexags z for arrow
+
+  \param surf surface (geosurf)
+
+  \return
+*/
 int gsd_norm_arrows(geosurf * surf)
 {
     typbuff *buff, *cobuff;
@@ -1755,11 +1812,7 @@ int gsd_norm_arrows(geosurf * surf)
     int zeros, dr1, dr2, dr3, dr4;
     int datarow1, datacol1, datarow2, datacol2;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_norm_arrows");
-    }
-#endif
+    G_debug(3, "gsd_norm_arrows");
 
     /* avoid scaling by zero */
     GS_get_scale(&tx, &ty, &tz, 1);
@@ -1984,13 +2037,21 @@ int gsd_norm_arrows(geosurf * surf)
 }
 
 
-/************************************************************************
- * New (TEST) surface drawing routine using triangle fan instead of strip
- * Optimized by getting rid of BM_get mask check - GET_MAPPATT does same
- * and returns zero if masked 
- * Only do in window check on Fan center(v0) to further optimize -- this runs 
- * the risk of trimming points in view !!
-*************************************************************************/
+/*!
+  \brief ADD
+
+  New (TEST) surface drawing routine using triangle fan instead of strip
+  
+  Optimized by getting rid of BM_get mask check - GET_MAPPATT does same
+  and returns zero if masked 
+  
+  Only do in window check on Fan center(v0) to further optimize -- this runs 
+  the risk of trimming points in view !!
+
+  \param surf surface (geosurf)
+
+  \return
+*/
 int gsd_surf_map(geosurf * surf)
 {
     int check_mask, check_color, check_transp;
@@ -2299,7 +2360,3 @@ int gsd_surf_map(geosurf * surf)
 
     return (0);
 }
-
-
-
-

lib/ogsf/gsd_views.c

@@ -16,9 +16,6 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-/* DEBUG */
-#include <stdio.h>
-
 #include <grass/config.h>
 
 #if defined(OPENGL_X11) || defined(OPENGL_WINDOWS)

lib/ogsf/gsd_wire.c

@@ -13,17 +13,15 @@
   for details.
   
   \author Bill Brown USACERL (January 1993)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
-
+#include <grass/gis.h>
 #include <grass/gstypes.h>
+
 #include "gsget.h"
 #include "rowcol.h"
 
-/*
-#define TRACE_DFUNCS
-*/
 
 #define DO_ARROWS
 
@@ -38,15 +36,19 @@
 /* may need to add more parameters to tell it which window or off_screen
  * pixmap to draw into. nah - just have one current (OpenGL limitation)
 */
+
+/*!
+  \brief ADD
+
+  \param surf surface (geosurf)
+
+  \return
+*/
 int gsd_wire_surf(geosurf * surf)
 {
     int desc, ret;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_wire_surf");
-    }
-#endif
+    G_debug(3, "gsd_wire_surf");
 
     desc = ATT_TOPO;
 
@@ -88,7 +90,13 @@ int gsd_wire_surf(geosurf * surf)
     return (ret);
 }
 
-/************************************************************************/
+/*!
+  \brief ADD
+
+  \param surf surface (geosurf)
+
+  \return
+*/
 int gsd_wire_surf_map(geosurf * surf)
 {
     int check_mask, check_color;
@@ -99,11 +107,7 @@ int gsd_wire_surf_map(geosurf * surf)
     int col_src, curcolor;
     gsurf_att *coloratt;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_wire_surf_map");
-    }
-#endif
+    G_debug(3, "gsd_wire_surf_map");
 
     buff = gs_get_att_typbuff(surf, ATT_TOPO, 0);
     cobuff = gs_get_att_typbuff(surf, ATT_COLOR, 0);
@@ -261,7 +265,14 @@ int gsd_wire_surf_map(geosurf * surf)
     return (1);
 }
 
-/************************************************************************/
+/*!
+  \brief ADD
+
+  \param surf surface (geosurf)
+  \param k
+
+  \return
+*/
 int gsd_wire_surf_const(geosurf * surf, float k)
 {
     int do_diff, check_mask, check_color;
@@ -272,11 +283,7 @@ int gsd_wire_surf_const(geosurf * surf, float k)
     gsurf_att *coloratt;
     typbuff *cobuff;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_wire_surf_const");
-    }
-#endif
+    G_debug(3, "gsd_wire_surf_const");
 
     cobuff = gs_get_att_typbuff(surf, ATT_COLOR, 0);
 
@@ -422,15 +429,31 @@ int gsd_wire_surf_const(geosurf * surf, float k)
     return (1);
 }
 
-/************************************************************************/
+/*!
+  \brief ADD
+
+  Not yet implemented.
+
+  \param gs surface (geosurf)
+  \param user_func user defined function
+
+  \return 1
+*/
 int gsd_wire_surf_func(geosurf * gs, int (*user_func) ())
 {
     return (1);
 }
 
-/************************************************************************/
-/* need to do Zexag scale of normal for arrow direction, drawing
-routine unexags z for arrow */
+/*!
+  \brief ADD
+
+  Need to do Zexag scale of normal for arrow direction, drawing
+  routine unexags z for arrow
+
+  \param surf surface (geosurf)
+
+  \return
+*/
 int gsd_wire_arrows(geosurf * surf)
 {
     typbuff *buff, *cobuff;
@@ -442,11 +465,7 @@ int gsd_wire_arrows(geosurf * surf)
     int col_src, curcolor;
     gsurf_att *coloratt;
 
-#ifdef TRACE_DFUNCS
-    {
-	Gs_status("gsd_norm_arrows");
-    }
-#endif
+    G_debug(3, "gsd_norm_arrows");
 
     /* avoid scaling by zero */
     GS_get_scale(&tx, &ty, &tz, 1);
@@ -532,15 +551,23 @@ int gsd_wire_arrows(geosurf * surf)
     return (1);
 }
 
-/***********************************************************
- * New (TEST) wire routine that draws low res surface 
- * Based on new Trinagle Fan routine
- * Resolution is a function of current surface resolution 
- * times wire resolution
- * TODO - normals have to be recalculated before proper low
- * res surface can be drawn
- * In window optimization has been removed 
-*************************************************************/
+/*!
+  \brief ADD
+
+  New (TEST) wire routine that draws low res surface 
+  Based on new Trinagle Fan routine
+  Resolution is a function of current surface resolution 
+  times wire resolution
+  
+  \todo normals have to be recalculated before proper low
+  res surface can be drawn
+  
+  In window optimization has been removed 
+
+  \param surf surface (geosurf)
+
+  \return
+*/
 int gsd_coarse_surf_map(geosurf * surf)
 {
     int check_mask, check_color, check_transp;
@@ -801,5 +828,3 @@ int gsd_coarse_surf_map(geosurf * surf)
 
     return (0);
 }
-
-

lib/ogsf/gsdiff.c

@@ -27,8 +27,6 @@
   \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
-
 #include <grass/gstypes.h>
 #include "gsget.h"
 

lib/ogsf/gsdrape.c

@@ -44,12 +44,13 @@
   for details.
   
   \author Bill Brown UI GMS Lab
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
 #include <stdlib.h>
 
 #include <grass/gstypes.h>
+
 #include "gsget.h"
 #include "rowcol.h"
 #include "math.h"

lib/ogsf/gsds.c

@@ -1,7 +1,7 @@
 /*!
   \file gsds.c
  
-  \brief OGSF library - 
+  \brief OGSF library - ? (lower level functions) 
  
   GRASS OpenGL gsurf OGSF Library 
 
@@ -50,12 +50,14 @@
   for details.
   
   \author Bill Brown UI GMS Lab
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdlib.h>
-#include <stdio.h>
 #include <string.h>
 
+#include <grass/gis.h>
+#include <grass/glocale.h>
 #include <grass/gstypes.h>
 
 #define LUCKY 33
@@ -76,7 +78,9 @@ static int Cur_id = LUCKY;
 static int Cur_max;
 static int Tot_mem = 0;
 
-/******************************************************************/
+/*!
+  \brief Initialize 
+*/
 static int init_gsds(void)
 {
     int i;
@@ -91,22 +95,31 @@ static int init_gsds(void)
     return (1);
 }
 
-/******************************************************************/
+/*!
+  \brief Check numsets
+
+  \return 0 numset < cur_max
+*/
 static int check_numsets(void)
 {
     if (Numsets < Cur_max) {
 	return (0);
     }
 
-    fprintf(stderr, "maximum number of datasets exceeded\n");
-
-    exit(0);
+    G_fatal_error (_("Maximum number of datasets exceeded"));
 
     /* This return statement keeps compilers happy, it is never executed */
     return (0);
 }
 
-/******************************************************************/
+/*!
+  \brief Get dataset
+
+  \param id data id
+
+  \return pointer to dataset struct
+  \return NULL dataset not found
+*/
 static dataset *get_dataset(int id)
 {
     int i;
@@ -120,7 +133,14 @@ static dataset *get_dataset(int id)
     return (NULL);
 }
 
-/******************************************************************/
+/*!
+  \brief Get type
+
+  \param ds pointer to dataset struct
+
+  \return type code
+  \return -1 unsupported type
+*/
 static int get_type(dataset * ds)
 {
     if (ds) {
@@ -148,17 +168,22 @@ static int get_type(dataset * ds)
     return (-1);
 }
 
-/******************************************************************/
-/* returns handle to gsds.   
-   successive calls will continue search until "begin" is set   
-   (problem here is, unique_name no longer uniquely identifies
-   dataset, since changes may be made; but unique_name should still
-   be useful for reloading dataset)
-   changes & types are set to actual for dataset if found.
-
-    changes, types  acceptable changes & types, flags may be or'd
-		    not changed is assumed to always be acceptable
-    begin           flag to indicate search from beginning
+/*!
+  \brief Get handle to gsds.   
+
+  Successive calls will continue search until "begin" is set   
+  (problem here is, unique_name no longer uniquely identifies
+  dataset, since changes may be made; but unique_name should still
+  be useful for reloading dataset)
+  changes & types are set to actual for dataset if found.
+  
+  \param name
+  \param changes,types  acceptable changes & types, flags may be or'd
+  not changed is assumed to always be acceptable
+  \param begin flag to indicate search from beginning
+
+  \return data id
+  \return -1 not found
 */
 int gsds_findh(char *name, IFLAG * changes, IFLAG * types, int begin)
 {
@@ -183,8 +208,14 @@ int gsds_findh(char *name, IFLAG * changes, IFLAG * types, int begin)
     return (-1);
 }
 
-/******************************************************************/
-/* returns handle to gsds */
+/*!
+  \brief Get handle to gsds
+
+  \param name
+
+  \return -1 on failure
+  \return data id
+*/
 int gsds_newh(char *name)
 {
     dataset *new;
@@ -234,10 +265,21 @@ int gsds_newh(char *name)
     return (-1);
 }
 
-/******************************************************************/
-/* change_flag just tells us to set changed flag - doesn't prevent
-writing a buff thats's been gotten with change_flag == 0 (could return a
-copy, but willing to trust calling func for now) */
+/*!
+  \brief Get typbuff
+
+  change_flag just tells us to set changed flag
+  
+  Doesn't prevent
+  writing a buff thats's been gotten with change_flag == 0 (could return a
+  copy, but willing to trust calling func for now)
+  
+  \param id
+  \param change_flag
+
+  \return pointer to typbuff struct
+  \return NULL on failure
+*/
 typbuff *gsds_get_typbuff(int id, IFLAG change_flag)
 {
     dataset *ds;
@@ -252,7 +294,14 @@ typbuff *gsds_get_typbuff(int id, IFLAG change_flag)
     return (NULL);
 }
 
-/******************************************************************/
+/*!
+  \brief Get name
+
+  \param id
+
+  \return name
+  \return NULL on failure
+*/
 char *gsds_get_name(int id)
 {
     int i;
@@ -271,17 +320,20 @@ char *gsds_get_name(int id)
     return (NULL);
 }
 
-/******************************************************************/
+/*!
+  \brief ADD
+
+  \param id
+
+  \return 0 not found
+  \return 1 found
+*/
 int gsds_free_datah(int id)
 {
     int i, j, found = 0;
     dataset *fds;
 
-#ifdef TRACE_FUNCS
-    {
-	fprintf(stderr, "gsds_free_datah\n");
-    }
-#endif
+    G_debug (3, "gsds_free_datah");
 
     for (i = 0; i < Numsets; i++) {
 	if (Data[i]->data_id == id) {
@@ -306,7 +358,15 @@ int gsds_free_datah(int id)
     return (found);
 }
 
-/******************************************************************/
+/*!
+  \brief ADD
+
+  \param id
+  \param typ
+
+  \return 0 not found
+  \return 1 found
+*/
 int gsds_free_data_buff(int id, int typ)
 {
     int i, found = 0;
@@ -323,7 +383,14 @@ int gsds_free_data_buff(int id, int typ)
     return (found);
 }
 
-/******************************************************************/
+/*!
+  \brief ADD
+
+  \param ds
+  \param typ
+
+  \return
+*/
 int free_data_buffs(dataset * ds, int typ)
 {
     int nsiz = 1, i, siz, freed = 0;
@@ -389,22 +456,27 @@ int free_data_buffs(dataset * ds, int typ)
     Tot_mem -= freed;
     ds->numbytes -= freed;
 
-#ifdef DEBUG_MSG
-    {
-	if (freed) {
-	    fprintf(stderr, "freed data from id no. %d\n", ds->data_id);
-	    fprintf(stderr, "%.3f Kbytes freed, current total = %.3f\n",
-		    freed / 1000., Tot_mem / 1000.);
-	}
+    if (freed) {
+	G_debug (3, "freed data from id no. %d", ds->data_id);
+	G_debug (3, "%.3f Kbytes freed, current total = %.3f",
+		 freed / 1000., Tot_mem / 1000.);
     }
-#endif
-
+    
     return (freed);
 }
 
-/******************************************************************/
-/* allocates correct buffer according to type, keeps track of total mem */
-/* TODO: add ATTY_CONST */
+/*!
+  \brief Allocates correct buffer according to type, keeps track of total mem
+
+  \todo add ATTY_CONST
+
+  \param id
+  \param dims
+  \param ndims
+  \param type
+
+  \return
+*/
 int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
 {
     dataset *ds;
@@ -456,7 +528,7 @@ int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
 	    siz *= sizeof(char);
 
 	    if (siz) {
-		if (NULL == (ds->databuff.cb = (unsigned char *) malloc(siz))) {
+		if (NULL == (ds->databuff.cb = (unsigned char *) G_malloc(siz))) {
 		    return (-1);
 		}
 	    }
@@ -470,7 +542,7 @@ int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
 	    siz *= sizeof(short);
 
 	    if (siz) {
-		if (NULL == (ds->databuff.sb = (short *) malloc(siz))) {
+		if (NULL == (ds->databuff.sb = (short *) G_malloc(siz))) {
 		    return (-1);
 		}
 	    }
@@ -484,7 +556,7 @@ int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
 	    siz *= sizeof(int);
 
 	    if (siz) {
-		if (NULL == (ds->databuff.ib = (int *) malloc(siz))) {
+		if (NULL == (ds->databuff.ib = (int *) G_malloc(siz))) {
 		    return (-1);
 		}
 	    }
@@ -498,7 +570,7 @@ int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
 	    siz *= sizeof(float);
 
 	    if (siz) {
-		if (NULL == (ds->databuff.fb = (float *) malloc(siz))) {
+		if (NULL == (ds->databuff.fb = (float *) G_malloc(siz))) {
 		    return (-1);
 		}
 	    }
@@ -518,12 +590,8 @@ int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
 	ds->ndims = ndims;
 	Tot_mem += siz;
 
-#ifdef DEBUG_MSG
-	{
-	    fprintf(stderr, "%f Kbytes allocated, current total = %f\n",
-		    siz / 1000., Tot_mem / 1000.);
-	}
-#endif
+	G_debug (3, "%f Kbytes allocated, current total = %f",
+		 siz / 1000., Tot_mem / 1000.);
 
 	return (siz);
     }
@@ -531,7 +599,14 @@ int gsds_alloc_typbuff(int id, int *dims, int ndims, int type)
     return (-1);
 }
 
-/******************************************************************/
+/*!
+  \brief ADD
+
+  \param id
+
+  \return -1 on error
+  \return 
+*/
 int gsds_get_changed(int id)
 {
     dataset *ds;
@@ -543,7 +618,15 @@ int gsds_get_changed(int id)
     return (-1);
 }
 
-/******************************************************************/
+/*!
+  \brief ADD
+
+  \param id
+  \param reason
+  
+  \return -1 on error
+  \return
+*/
 int gsds_set_changed(int id, IFLAG reason)
 {
     dataset *ds;
@@ -555,7 +638,13 @@ int gsds_set_changed(int id, IFLAG reason)
     return (-1);
 }
 
-/******************************************************************/
+/*!						
+  \brief ADD
+
+  \param id
+
+  \return
+*/
 int gsds_get_type(int id)
 {
     dataset *ds;

lib/ogsf/gv_quick.c

@@ -16,41 +16,53 @@
   for details.
 
   \author Bill Brown, USACERL (December 1993)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
 #include <stdio.h>
 #include <stdlib.h>
 
+#include <grass/gis.h>
 #include <grass/gstypes.h>
+
 #include "rowcol.h"
 
-/* target number of desired points to represent entire file */
+/*!
+  \brief target number of desired points to represent entire file
+*/
 #define TFAST_PTS 800
 
-/* max number of lines desired */
+/*!
+  \brief max number of lines desired
+*/
 #define MFAST_LNS  400
 
 static geoline *copy_line(geoline *);
 static geoline *thin_line(geoline *, float);
 
-/******************************************************************/
+/*!
+  \brief Copy line
+
+  \param gln source line (geoline)
+
+  \return pointer to geoline struct
+  \return on failure
+*/
 static geoline *copy_line(geoline * gln)
 {
     geoline *newln;
     int i, np;
 
-    if (NULL == (newln = (geoline *) malloc(sizeof(geoline)))) {
-	fprintf(stderr, "Can't malloc.\n");
-
+    newln = (geoline *) G_malloc(sizeof(geoline)); /* G_fatal_error */
+    if (!newln) {
 	return (NULL);
     }
 
     np = newln->npts = gln->npts;
 
     if (2 == (newln->dims = gln->dims)) {
-	if (NULL == (newln->p2 = (Point2 *) calloc(np, sizeof(Point2)))) {
-	    fprintf(stderr, "Can't calloc.\n");	/* CLEAN UP */
-
+	newln->p2 = (Point2 *) G_calloc(np, sizeof(Point2)); /* G_fatal_error */
+	if (!newln->p2) {
 	    return (NULL);
 	}
 
@@ -60,9 +72,8 @@ static geoline *copy_line(geoline * gln)
 	}
     }
     else {
-	if (NULL == (newln->p3 = (Point3 *) calloc(np, sizeof(Point3)))) {
-	    fprintf(stderr, "Can't calloc.\n");	/* CLEAN UP */
-
+	newln->p3 = (Point3 *) G_calloc(np, sizeof(Point3)); /* G_fatal_error */
+	if (!newln->p3) {
 	    return (NULL);
 	}
 
@@ -78,16 +89,25 @@ static geoline *copy_line(geoline * gln)
     return (newln);
 }
 
-/******************************************************************/
-/* for now, just eliminate points at regular interval */
+
+/*!
+  \brief Thin line
+
+  For now, just eliminate points at regular interval
+
+  \param gln line (geoline)
+  \param factor
+
+  \return pointer to geoline struct
+  \return NULL on failure
+*/
 static geoline *thin_line(geoline * gln, float factor)
 {
     geoline *newln;
     int i, nextp, targp;
 
-    if (NULL == (newln = (geoline *) malloc(sizeof(geoline)))) {
-	fprintf(stderr, "Can't malloc.\n");
-
+    newln = (geoline *) G_malloc(sizeof(geoline)); /* G_fatal_error */
+    if (!newln) {
 	return (NULL);
     }
 
@@ -100,9 +120,8 @@ static geoline *thin_line(geoline * gln, float factor)
     newln->npts = targp;
 
     if (2 == (newln->dims = gln->dims)) {
-	if (NULL == (newln->p2 = (Point2 *) calloc(targp, sizeof(Point2)))) {
-	    fprintf(stderr, "Can't calloc.\n");	/* CLEAN UP */
-
+	newln->p2 = (Point2 *) G_calloc(targp, sizeof(Point2)); /* G_fatal_error */
+	if (!newln->p2) {
 	    return (NULL);
 	}
 
@@ -119,9 +138,8 @@ static geoline *thin_line(geoline * gln, float factor)
 	}
     }
     else {
-	if (NULL == (newln->p3 = (Point3 *) calloc(targp, sizeof(Point3)))) {
-	    fprintf(stderr, "Can't calloc.\n");	/* CLEAN UP */
-
+	newln->p3 = (Point3 *) G_calloc(targp, sizeof(Point3)); /* G_fatal_error */
+	if (!newln->p3) {
 	    return (NULL);
 	}
 
@@ -144,7 +162,13 @@ static geoline *thin_line(geoline * gln, float factor)
     return (newln);
 }
 
-/******************************************************************/
+/*!
+  \brief Get line width
+
+  \param gln line (geoline)
+
+  \return line width
+*/
 float gv_line_length(geoline * gln)
 {
     int n;
@@ -162,8 +186,13 @@ float gv_line_length(geoline * gln)
     return (length);
 }
 
+/*!
+  \brief Get number of line vertices
+
+  \param gln line (geoline)
 
-/******************************************************************/
+  \return number of vertices
+*/
 int gln_num_points(geoline * gln)
 {
     int np = 0;
@@ -176,7 +205,13 @@ int gln_num_points(geoline * gln)
     return (np);
 }
 
-/******************************************************************/
+/*!
+  \brief Get number of points in vector
+
+  \param gv vector (geovect)
+
+  \return number of points
+*/
 int gv_num_points(geovect * gv)
 {
     return (gln_num_points(gv->lines));
@@ -184,9 +219,16 @@ int gv_num_points(geovect * gv)
 
 
 
-/******************************************************************/
-/* strategy here: if line has more than average number of points, decimate
-   by eliminating points, otherwise decimate by eliminating shorter lines */
+/*!
+  \brief Decimate line
+
+  strategy here: if line has more than average number of points, decimate
+  by eliminating points, otherwise decimate by eliminating shorter lines
+
+  \param gv vector (geovect)
+
+  \return
+*/
 int gv_decimate_lines(geovect * gv)
 {
     int T_pts, A_ppl, N_s;
@@ -241,7 +283,8 @@ int gv_decimate_lines(geovect * gv)
 	}
     }
 
-    fprintf(stderr, "Decimated lines have %d points.\n",
-	    gln_num_points(gv->fastlines));
+    G_debug (3, "Decimated lines have %d points.",
+	     gln_num_points(gv->fastlines));
+
     return (1);
 }

lib/ogsf/trans.c

@@ -1,25 +1,13 @@
 /*!
   \file trans.c
  
-  \brief OGSF library - 
+  \brief OGSF library - matrix transformation (higher level functions)
  
   GRASS OpenGL gsurf OGSF Library 
 
   NOTE: This file should be REMOVED and any calls to the functions in this
   file should be replaced with appropriate OpenGL calls.
 
-  Matrix Transformation library.
-  
-  P_pushmatrix ()
-  
-  P_popmatrix ()
-
-  P_scale ()		
-  
-  P_rot ()
-
-  P_transform ()      transform array of vectors using current T matrix
-
   This routine should be available in GL!
 
   Arguments are same as GL counterparts
@@ -36,12 +24,14 @@
   for details.
   
   \author Dave Gerdes Jan 1990 All rights reserved, US Army Construction Engineering Research Lab
-  Bill Brown USACERL (November 1993)
+  \author Bill Brown USACERL (November 1993)
+  \author Doxygenized by Martin Landa <landa.martin gmail.com> (May 2008)
 */
 
-#include <stdio.h>
 #include <math.h>
 
+#include <grass/gis.h>
+#include <grass/glocale.h>
 #include <grass/gstypes.h>
 
 #define MAX_STACK 20
@@ -77,7 +67,11 @@ static float ident[4][4] = {
     {0., 0., 0., 1.}
 };
 
-/************************************************************************/
+/*!
+  \brief ADD
+
+  \param x,y,z
+*/
 void P_scale(float x, float y, float z)
 {
     d[0][0] = x;
@@ -98,9 +92,9 @@ void P_scale(float x, float y, float z)
     d[3][3] = 1.;
 
     /*
-       **  will write into 1 down on matrix stack
-       **  and then the popmatrix() will place it as the current T matrix
-     */
+    **  will write into 1 down on matrix stack
+    **  and then the popmatrix() will place it as the current T matrix
+    */
     P_pushmatrix();
     P__transform(4, d, c_stack[stack_ptr], trans_mat);
     P_popmatrix();
@@ -108,13 +102,17 @@ void P_scale(float x, float y, float z)
     return;
 }
 
+/*!
+  \brief Transform array of vectors using current T matrix
+  
+  Multiply 'in' matrix (homogenous coordinate generally) by
+  the current transformation matrix, placing the result in 'out'
 
-/************************************************************************/
-/*
-**   multiply 'in' matrix (homogenous coordinate generally) by
-**   the current transformation matrix, placing the result in 'out'
-**
-**       [in][trans_mat] => [out]
+  [in][trans_mat] => [out]
+  
+  \param num_vert
+  \param in
+  \param out
 */
 void P_transform(int num_vert, float (*in)[4], float (*out)[4])
 {
@@ -123,7 +121,18 @@ void P_transform(int num_vert, float (*in)[4], float (*out)[4])
     return;
 }
 
-/************************************************************************/
+/*!
+  \brief Transform array of vectors using current T matrix
+  
+  Multiply 'in' matrix (homogenous coordinate generally) by
+  the current transformation matrix, placing the result in 'out'
+
+  [in][trans_mat] => [out]
+  
+  \param num_vert
+  \param in
+  \param out
+*/
 static void P__transform(int num_vert, float (*in)[4], float (*out)[4],
 		  float (*c)[4])
 {
@@ -142,7 +151,13 @@ static void P__transform(int num_vert, float (*in)[4], float (*out)[4],
     return;
 }
 
-/************************************************************************/
+/*!
+  \brief Copy matrix 
+  
+  \param from 'from' matrix
+  \param to 'to' matrix
+  \param size number of rows (ncols=4)
+*/
 static void P_matrix_copy(float (*from)[4], float (*to)[4], int size)
 {
     register int i, j;
@@ -156,14 +171,13 @@ static void P_matrix_copy(float (*from)[4], float (*to)[4], int size)
     return;
 }
 
-/************************************************************************/
-/*
-** push current transformation matrix onto matrix stack
+/*!
+  \brief Push current transformation matrix onto matrix stack
 */
 int P_pushmatrix(void)
 {
     if (stack_ptr >= MAX_STACK) {
-	fprintf(stderr, "Out of matrix stack space\n");
+	G_warning ("P_pushmatrix(): %s", _("Out of matrix stack space"));
 
 	return (-1);
     }
@@ -174,14 +188,16 @@ int P_pushmatrix(void)
     return (0);
 }
 
-/************************************************************************/
-/*
-** pop top of matrix stack, placing it into the current transformation matrix
+/*!
+  \brief Pop top of matrix stack, placing it into the current transformation matrix
+
+  \return -1 on failure
+  \return 0 on success
 */
 int P_popmatrix(void)
 {
     if (stack_ptr < 0) {
-	fprintf(stderr, "Tried to pop an empty stack\n");
+	G_warning ("P_popmatrix(): %s", _("Tried to pop an empty stack"));
 
 	return (-1);
     }
@@ -192,8 +208,12 @@ int P_popmatrix(void)
     return (0);
 }
 
+/*!
+  \brief Rotate matrix
 
-/************************************************************************/
+  \param angle angle value
+  \param axis ('x, 'y', 'z')
+*/
 void P_rot(float angle, char axis)
 {
     double theta;