[glib] gvariant: Clarify that nullable strings should use maybe types

[Philip Withnall <pwithnall src gnome org>]

commit 8c858a018d752e06e4a9720735ffc495c3159e20
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Fri Dec 19 17:23:54 2014 +0000

    gvariant: Clarify that nullable strings should use maybe types
    
    Otherwise people might try to encode a NULL string as "NULL". I’m not
    even kidding.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=741779

 docs/reference/glib/gvariant-varargs.xml |    3 ++-
 glib/gvariant.c                          |    9 ++++++---
 2 files changed, 8 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/glib/gvariant-varargs.xml b/docs/reference/glib/gvariant-varargs.xml
index 2e1eed6..a253865 100644
--- a/docs/reference/glib/gvariant-varargs.xml
+++ b/docs/reference/glib/gvariant-varargs.xml
@@ -530,7 +530,8 @@ value4 = g_variant_new ("x", G_GINT64_CONSTANT (998877665544332211));
     '<literal>s</literal>', '<literal>o</literal>' or '<literal>g</literal>' in a format string,
     <link linkend='g-variant-new'><function>g_variant_new()</function></link> takes a <code>(const
     <link linkend='gchar'>gchar</link> *)</code> and makes a copy of it.
-    <link linkend='NULL:CAPS'><literal>NULL</literal></link> is not a valid string.  If the 
'<literal>o</literal>' or
+    <link linkend='NULL:CAPS'><literal>NULL</literal></link> is not a valid string; use
+    <link linkend='gvariant-format-strings-maybe-types'>maybe types</link> to encode that.  If the 
'<literal>o</literal>' or
     '<literal>g</literal>' characters are used, care must be taken to ensure that the passed string is a 
valid DBus
     object path or DBus type signature, respectively.
    </para>
diff --git a/glib/gvariant.c b/glib/gvariant.c
index d5aee7d..a9c34d4 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -1217,7 +1217,9 @@ g_variant_new_fixed_array (const GVariantType  *element_type,
  *
  * Creates a string #GVariant with the contents of @string.
  *
- * @string must be valid UTF-8.
+ * @string must be valid UTF-8, and must not be %NULL. To encode
+ * potentially-%NULL strings, use g_variant_new() with `ms` as the
+ * [format string][gvariant-format-strings-maybe-types].
  *
  * Returns: (transfer none): a floating reference to a new string #GVariant instance
  *
@@ -1239,7 +1241,8 @@ g_variant_new_string (const gchar *string)
  *
  * Creates a string #GVariant with the contents of @string.
  *
- * @string must be valid UTF-8.
+ * @string must be valid UTF-8, and must not be %NULL. To encode
+ * potentially-%NULL strings, use this with g_variant_new_maybe().
  *
  * This function consumes @string.  g_free() will be called on @string
  * when it is no longer required.
@@ -1407,7 +1410,7 @@ g_variant_is_signature (const gchar *string)
  * type.  This includes the types %G_VARIANT_TYPE_STRING,
  * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
  *
- * The string will always be UTF-8 encoded.
+ * The string will always be UTF-8 encoded, and will never be %NULL.
  *
  * If @length is non-%NULL then the length of the string (in bytes) is
  * returned there.  For trusted values, this information is already