[GRASS-SVN] r49283 - grass/trunk/lib/gis

[svn_grass at osgeo.org]

Author: martinl
Date: 2011-11-17 04:48:31 -0800 (Thu, 17 Nov 2011)
New Revision: 49283

Modified:
   grass/trunk/lib/gis/handler.c
Log:
gislib: document error handlers


Modified: grass/trunk/lib/gis/handler.c
===================================================================
--- grass/trunk/lib/gis/handler.c	2011-11-16 21:56:18 UTC (rev 49282)
+++ grass/trunk/lib/gis/handler.c	2011-11-17 12:48:31 UTC (rev 49283)
@@ -1,3 +1,16 @@
+/*!
+  \file lib/gis/handler.c
+ 
+  \brief GIS Library - Error handlers
+ 
+  (C) 2010-2011 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 Glynn Clements
+*/
 
 #include <stddef.h>
 #include <grass/gis.h>
@@ -2,4 +15,13 @@
 
+/*!
+  \brief Error handler (see G_add_error_handler() for usage)
+*/
 struct handler {
+    /*!
+      \brief Pointer to the handler routine
+    */
     void (*func)(void *);
+    /*!
+      \brief Pointer to closure data
+    */
     void *closure;
@@ -30,6 +52,21 @@
     return &handlers[num_handlers++];
 }
 
+/*!
+  \brief Add new error handler
+
+  Example
+  \code
+  static void error_handler(void *p) {
+      const char *map = (const char *) p;
+      Vect_delete(map);
+  }
+  G_add_error_handler(error_handler, new->answer);
+  \endcode
+  
+  \param func handler to add
+  \param closure pointer to closure data
+*/
 void G_add_error_handler(void (*func)(void *), void *closure)
 {
     struct handler *h = alloc_handler();
@@ -38,6 +75,12 @@
     h->closure = closure;
 }
 
+/*!
+  \brief Remove existing error hander
+
+  \param func handler to be remove
+  \param closure pointer to closure data
+*/
 void G_remove_error_handler(void (*func)(void *), void *closure)
 {
     int i;
@@ -52,6 +95,9 @@
     }
 }
 
+/*!
+  \brief Call available error handlers (internal use only)
+*/
 void G__call_error_handlers(void)
 {
     int i;