From 33c977917c1dbcfec56168083dc05837da8ea57c Mon Sep 17 00:00:00 2001 From: Ryan Lortie Date: Wed, 20 Jul 2011 16:34:55 +0200 Subject: [PATCH] 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 file changed, 10 insertions(+), 2 deletions(-) diff --git a/glib/gvariant.c b/glib/gvariant.c index d7e9dafd0..fe1cd9f0c 100644 --- a/glib/gvariant.c +++ b/glib/gvariant.c @@ -4719,8 +4719,16 @@ g_variant_iter_next (GVariantIter *iter, * * * - * 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 **/ -- 2.34.1