[libgsystem] Document more

[Colin Walters <walters src gnome org>]

commit a6f48a9720aa7b01b8abee1fc0eb78230b273485
Author: Colin Walters <walters verbum org>
Date:   Thu Oct 18 13:11:04 2012 -0400

    Document more
    
    Thanks to Pavel Simerda <psimerda redhat com> for bringing this up.

 gsystem-local-alloc.c |   48 ++++++++++++++++++++++++++++++++++++++++++++++++
 gsystem-local-alloc.h |   43 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 91 insertions(+), 0 deletions(-)
---
diff --git a/gsystem-local-alloc.c b/gsystem-local-alloc.c
index 1bbea90..b19a329 100644
--- a/gsystem-local-alloc.c
+++ b/gsystem-local-alloc.c
@@ -22,6 +22,54 @@
 
 #include "gsystem-local-alloc.h"
 
+/**
+ * SECTION:gslocalalloc
+ * @title: GSystem local allocation
+ * @short_description: Release local variables automatically when they go out of scope
+ *
+ * These macros leverage the GCC extension __attribute__ ((cleanup))
+ * to allow calling a cleanup function such as g_free() when a
+ * variable goes out of scope.  See <ulink
+ * url="http://gcc.gnu.org/onlinedocs/gcc/Variable-Attributes.html";>
+ * for more information on the attribute.
+ *
+ * The provided macros make it easy to use the cleanup attribute for types
+ * that come with GLib.  The primary two are #gs_lfree and #gs_lobj,
+ * which correspond to g_free() and g_object_unref(), respectively.
+ *
+ * The rationale behind this is that particularly when handling error
+ * paths, it can be very tricky to ensure the right variables are
+ * freed.  With this, one simply applies gs_lobj to a
+ * locally-allocated #GFile for example, and it will be automatically
+ * unreferenced when it goes out of scope.
+ *
+ * Note - you should only use these macros for <emphasis>stack
+ * allocated</emphasis> variables.  They don't provide garbage
+ * collection or let you avoid freeing things.  They're simply a
+ * compiler assisted deterministic mechanism for calling a cleanup
+ * function when a stack frame ends.
+ *
+ * <example id="gs-lfree"><title>Calling g_free automatically</title>
+ * <programlisting>
+ *
+ * GFile *
+ * create_file (GError **error)
+ * {
+ *   gs_lfree char *random_id = NULL;
+ *
+ *   if (!prepare_file (error))
+ *     return NULL;
+ *
+ *   random_id = alloc_random_id ();
+ *
+ *   return create_file_real (error);
+ *   // Note that random_id is freed here automatically
+ * }
+ * </programlisting>
+ * </example>
+ *   
+ */
+
 void
 gs_local_free (void *loc)
 {
diff --git a/gsystem-local-alloc.h b/gsystem-local-alloc.h
index 24e7ca2..28d857f 100644
--- a/gsystem-local-alloc.h
+++ b/gsystem-local-alloc.h
@@ -25,16 +25,59 @@
 
 G_BEGIN_DECLS
 
+/* These functions shouldn't be invoked directly;
+ * they are stubs that:
+ * 1) Take a pointer to the location (typically itself a pointer).
+ * 2) Provide %NULL-safety where it doesn't exist already (e.g. g_object_unref)
+ */
 void gs_local_free (void *loc);
 void gs_local_obj_unref (void *loc);
 void gs_local_variant_unref (void *loc);
 void gs_local_ptrarray_unref (void *loc);
 void gs_local_hashtable_unref (void *loc);
 
+/**
+ * gs_lfree:
+ *
+ * Call g_free() on a variable location when it goes out of scope.
+ */
 #define gs_lfree __attribute__ ((cleanup(gs_local_free)))
+
+/**
+ * gs_lobj:
+ *
+ * Call g_object_unref() on a variable location when it goes out of
+ * scope.  Note that unlike g_object_unref(), the variable may be
+ * %NULL.
+ */
 #define gs_lobj __attribute__ ((cleanup(gs_local_obj_unref)))
+
+/**
+ * gs_lvariant:
+ *
+ * Call g_variant_unref() on a variable location when it goes out of
+ * scope.  Note that unlike g_variant_unref(), the variable may be
+ * %NULL.
+ */
 #define gs_lvariant __attribute__ ((cleanup(gs_local_variant_unref)))
+
+/**
+ * gs_lptrarray:
+ *
+ * Call g_ptr_array_unref() on a variable location when it goes out of
+ * scope.  Note that unlike g_ptr_array_unref(), the variable may be
+ * %NULL.
+
+ */
 #define gs_lptrarray __attribute__ ((cleanup(gs_local_ptrarray_unref)))
+
+/**
+ * gs_lhash:
+ *
+ * Call g_hash_table_unref() on a variable location when it goes out
+ * of scope.  Note that unlike g_hash_table_unref(), the variable may
+ * be %NULL.
+ */
 #define gs_lhash __attribute__ ((cleanup(gs_local_hashtable_unref)))
 
 G_END_DECLS