gislib: document error handlers

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

lib/gis/handler.c

@@ -1,9 +1,31 @@
+/*!
+  \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>
 
+/*!
+  \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 @@ static struct handler *alloc_handler(void)
     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 @@ void G_add_error_handler(void (*func)(void *), void *closure)
     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 @@ void G_remove_error_handler(void (*func)(void *), void *closure)
     }
 }
 
+/*!
+  \brief Call available error handlers (internal use only)
+*/
 void G__call_error_handlers(void)
 {
     int i;