[GRASS-SVN] r34774 - grass/branches/develbranch_6/lib/gis

[svn_grass at osgeo.org]

Author: martinl
Date: 2008-12-07 05:22:25 -0500 (Sun, 07 Dec 2008)
New Revision: 34774

Modified:
   grass/branches/develbranch_6/lib/gis/percent.c
Log:
G_percent() doxygen string updated


Modified: grass/branches/develbranch_6/lib/gis/percent.c
===================================================================
--- grass/branches/develbranch_6/lib/gis/percent.c	2008-12-07 10:16:21 UTC (rev 34773)
+++ grass/branches/develbranch_6/lib/gis/percent.c	2008-12-07 10:22:25 UTC (rev 34774)
@@ -36,20 +36,29 @@
   int nrows;
   nrows = 1352; // 1352 is not a special value - example only
 
-  fprintf (stderr, "Percent complete: ");
+  G_message(_("Percent complete..."));
   for (row = 0; row < nrows; row++)
   {
-      G_percent (row, nrows, 10);
+      G_percent (row+1, nrows, 10);
+      ...
+      ...
+      ...
   }
-  G_percent (row, nrows, 10);
 \endcode
+ *
  * This will print completion messages at 10% increments; i.e., 10%, 20%, 30%,
  * etc., up to 100%. Each message does not appear on a new line, but rather erases
- * the previous message. After 100%, a new line is printed.
+ * the previous message.
+ * 
+ * G_percent() should stay at the start of the for loop. If the loop takes
+ * a long time to run, 0% should print before the first iteration has begun,
+ * and final 100% message in loop should not be printed before the last
+ * iteration is complete. Otherwise it seems to stall at 99% done, etc.
  *
- * \param[in] n current element
- * \param[in] d total number of elements
- * \param[in] s increment size
+ * \param n current element
+ * \param d total number of elements
+ * \param s increment size
+ *
  * \return always returns 0
  */
 
@@ -64,29 +73,15 @@
  *
  * This routine prints a percentage complete message to stderr. The
  * percentage complete is <i>(<b>n</b>/<b>d</b>)*100</i>, and these are 
- * printed only for each <b>s</b> percentage. This is perhaps best 
- * explained by example:
-\code
-  #include <stdio.h>
-  #include <grass/gis.h>
-  int row;
-  int nrows;
-  nrows = 1352; // 1352 is not a special value - example only
-  fprintf (stderr, "Percent complete: ");
-  for (row = 0; row < nrows; row++)
-  {
-      G_percent (row, nrows, 10);
-  }
-  G_percent (row, nrows, 10);
-\endcode
- * This will print completion messages at 10% increments; i.e., 10%, 20%, 30%,
- * etc., up to 100%. Each message does not appear on a new line, but rather erases
- * the previous message. After 100%, a new line is printed.
+ * printed only for each <b>s</b> percentage.
  *
- * \param[in] n current element
- * \param[in] d total number of elements
- * \param[in] s increment size
- * \param[in,out] out file to print to
+ * See G_percent() for details.
+ *
+ * \param n current element
+ * \param d total number of elements
+ * \param s increment size
+ * \param[out] out file to print to
+ *
  * \return always returns 0
  */