[glib] gvariant: Document the need to cast varargs when constructing GVariants

[Philip Withnall <pwithnall src gnome org>]

commit 2b8edf234c9f1926ca2b24bf431fc1c8dc7c4ecf
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Thu Nov 21 17:39:16 2013 +0000

    gvariant: Document the need to cast varargs when constructing GVariants
    
    Slightly expand on the documentation about casting varargs when
    constructing GVariants, and link to it from all the functions where it’s
    a necessary consideration.
    
    Add an example of passing flags to a ‘t’ type variable (guint64).
    Assuming the flags enum does not have many members, the flag variable
    will be 32 bits wide, and needs an explicit cast to be passed into
    g_variant_new() as a 64-bit value.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=712837

 docs/reference/glib/gvariant-varargs.xml |    1 +
 glib/gvariant-parser.c                   |   12 ++++++++++++
 glib/gvariant.c                          |   23 +++++++++++++++++++++++
 3 files changed, 36 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/glib/gvariant-varargs.xml b/docs/reference/glib/gvariant-varargs.xml
index 3f34d53..550cea0 100644
--- a/docs/reference/glib/gvariant-varargs.xml
+++ b/docs/reference/glib/gvariant-varargs.xml
@@ -466,6 +466,7 @@
     </tgroup>
    </informaltable>
 
+   <anchor id='gvariant-varargs'/>
    <para>
     Note that in C, small integer types in variable argument lists are promoted up to <link
     linkend='gint'><type>int</type></link> or <link linkend='guint'><type>unsigned int</type></link> as 
appropriate, and
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index 128523c..7617f34 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -2428,6 +2428,10 @@ g_variant_parse (const GVariantType  *type,
  * #GVariant pointer will be returned unmodified, without adding any
  * additional references.
  *
+ * Note that the arguments in @app must be of the correct width for their types
+ * specified in @format when collected into the #va_list. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * In order to behave correctly in all cases it is necessary for the
  * calling function to g_variant_ref_sink() the return result before
  * returning control to the user that originally provided the pointer.
@@ -2481,6 +2485,10 @@ g_variant_new_parsed_va (const gchar *format,
  * that case, the same arguments are collected from the argument list as
  * g_variant_new() would have collected.
  *
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * Consider this simple example:
  * |[<!-- language="C" --> 
  *  g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
@@ -2530,6 +2538,10 @@ g_variant_new_parsed (const gchar *format,
  * calling g_variant_new_parsed() followed by
  * g_variant_builder_add_value().
  *
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format_string. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * This function might be used as follows:
  *
  * |[<!-- language="C" --> 
diff --git a/glib/gvariant.c b/glib/gvariant.c
index e5f23c4..93d2278 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -5168,6 +5168,21 @@ g_variant_valist_get (const gchar **str,
  * 'r'; in essence, a new #GVariant must always be constructed by this
  * function (and not merely passed through it unmodified).
  *
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format_string. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
+ * <programlisting>
+ * MyFlags some_flags = FLAG_ONE | FLAG_TWO;
+ * const gchar *some_strings[] = { "a", "b", "c", NULL };
+ * GVariant *new_variant;
+ *
+ * new_variant = g_variant_new ("(t^as)",
+ *                              /<!-- -->* This cast is required. *<!-- -->/
+ *                              (guint64) some_flags,
+ *                              some_strings);
+ * </programlisting>
+ *
  * Returns: a new floating #GVariant instance
  *
  * Since: 2.24
@@ -5214,6 +5229,10 @@ g_variant_new (const gchar *format_string,
  * @format_string, are collected from this #va_list and the list is left
  * pointing to the argument following the last.
  *
+ * Note that the arguments in @app must be of the correct width for their types
+ * specified in @format_string when collected into the #va_list. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * These two generalisations allow mixing of multiple calls to
  * g_variant_new_va() and g_variant_get_va() within a single actual
  * varargs call by the user.
@@ -5365,6 +5384,10 @@ g_variant_get_va (GVariant     *value,
  * This call is a convenience wrapper that is exactly equivalent to
  * calling g_variant_new() followed by g_variant_builder_add_value().
  *
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format_string. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * This function might be used as follows:
  *
  * |[<!-- language="C" -->