[glib] gvariant: Add example to docs for g_variant_builder_open()

[Philip Withnall <pwithnall src gnome org>]

commit b001f592066525ff3542337cc36e620ed66f031e
Author: Philip Withnall <philip tecnocode co uk>
Date:   Sat Jan 21 23:42:20 2017 +0000

    gvariant: Add example to docs for g_variant_builder_open()
    
    Try to clarify that the type is the type of the container, not of the
    items with in it; and give an example of how to use it for nested types.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=777592

 glib/gvariant.c |   34 ++++++++++++++++++++++++++++++++--
 1 files changed, 32 insertions(+), 2 deletions(-)
---
diff --git a/glib/gvariant.c b/glib/gvariant.c
index ea6e76a..a57b2fb 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -3513,15 +3513,45 @@ g_variant_builder_add_value (GVariantBuilder *builder,
 /**
  * g_variant_builder_open:
  * @builder: a #GVariantBuilder
- * @type: a #GVariantType
+ * @type: the #GVariantType of the container
  *
  * Opens a subcontainer inside the given @builder.  When done adding
- * items to the subcontainer, g_variant_builder_close() must be called.
+ * items to the subcontainer, g_variant_builder_close() must be called. @type
+ * is the type of the container: so to build a tuple of several values, @type
+ * must include the tuple itself.
  *
  * It is an error to call this function in any way that would cause an
  * inconsistent value to be constructed (ie: adding too many values or
  * a value of an incorrect type).
  *
+ * Example of building a nested variant:
+ * |[<!-- language="C" -->
+ * GVariantBuilder builder;
+ * guint32 some_number = get_number ();
+ * g_autoptr (GHashTable) some_dict = get_dict ();
+ * GHashTableIter iter;
+ * const gchar *key;
+ * const GVariant *value;
+ * g_autoptr (GVariant) output = NULL;
+ *
+ * g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
+ * g_variant_builder_add (&builder, "u", some_number);
+ * g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
+ *
+ * g_hash_table_iter_init (&iter, some_dict);
+ * while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
+ *   {
+ *     g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
+ *     g_variant_builder_add (&builder, "s", key);
+ *     g_variant_builder_add (&builder, "v", value);
+ *     g_variant_builder_close (&builder);
+ *   }
+ *
+ * g_variant_builder_close (&builder);
+ *
+ * output = g_variant_builder_end (&builder);
+ * ]|
+ *
  * Since: 2.24
  **/
 void