[glib] GVariant: document avoiding g_variant_iter_loop

[Ryan Lortie <ryanl src gnome org>]

commit 33c977917c1dbcfec56168083dc05837da8ea57c
Author: Ryan Lortie <desrt desrt ca>
Date:   Wed Jul 20 16:34:55 2011 +0200

    GVariant: document avoiding g_variant_iter_loop
    
    The choice between g_variant_iter_next() and g_variant_iter_loop() is a
    bit confusing for some people.  Add a note to the documentation of
    g_variant_iter_loop() to clarify that it should be avoided except in a
    few specific cases.

 glib/gvariant.c |   12 ++++++++++--
 1 files changed, 10 insertions(+), 2 deletions(-)
---
diff --git a/glib/gvariant.c b/glib/gvariant.c
index d7e9daf..fe1cd9f 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -4719,8 +4719,16 @@ g_variant_iter_next (GVariantIter *iter,
  *  </programlisting>
  * </example>
  *
- * If you want a slightly less magical alternative that requires more
- * typing, see g_variant_iter_next().
+ * For most cases you should use g_variant_iter_next().
+ *
+ * This function is really only useful when unpacking into #GVariant or
+ * #GVariantIter in order to allow you to skip the call to
+ * g_variant_unref() or g_variant_iter_free().
+ *
+ * For example, if you are only looping over simple integer and string
+ * types, g_variant_iter_next() is definitely preferred.  For string
+ * types, use the '&' prefix to avoid allocating any memory at all (and
+ * thereby avoiding the need to free anything as well).
  *
  * Since: 2.24
  **/