[glib] GVariant docs fixes

[Ryan Lortie <ryanl src gnome org>]

commit c5a1c95b1f991db6700a204e5d41c8cc650c7d42
Author: Ryan Lortie <desrt desrt ca>
Date:   Sun Mar 21 13:46:09 2010 -0500

    GVariant docs fixes

 glib/gvariant-parser.c |   16 +++++++++++++++-
 glib/gvariant.h        |    6 +++---
 2 files changed, 18 insertions(+), 4 deletions(-)
---
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index 2e35d05..46f48a5 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -2097,12 +2097,25 @@ g_variant_parse (const GVariantType  *type,
  * g_variant_new_parsed_va:
  * @format: a text format #GVariant
  * @app: a pointer to a #va_list
- * @returns: a new floating #GVariant instance
+ * @returns: a new, usually floating, #GVariant
  *
  * Parses @format and returns the result.
  *
  * This is the version of g_variant_new_parsed() intended to be used
  * from libraries.
+ *
+ * The return value will be floating if it was a newly created GVariant
+ * instance.  In the case that @format simply specified the collection
+ * of a #GVariant pointer (eg: @format was "%*") then the collected
+ * #GVariant pointer will be returned unmodified, without adding any
+ * additional references.
+ *
+ * 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.
+ * At this point, the caller will have their own full reference to the
+ * result.  This can also be done by adding the result to a container,
+ * or by passing it to another g_variant_new() call.
  **/
 GVariant *
 g_variant_new_parsed_va (const gchar *format,
@@ -2139,6 +2152,7 @@ g_variant_new_parsed_va (const gchar *format,
  * g_variant_new_parsed:
  * @format: a text format #GVariant
  * @...: arguments as per @format
+ * @returns: a new floating #GVariant instance
  *
  * Parses @format and returns the result.
  *
diff --git a/glib/gvariant.h b/glib/gvariant.h
index f51f793..9a17157 100644
--- a/glib/gvariant.h
+++ b/glib/gvariant.h
@@ -139,9 +139,9 @@ guint                           g_variant_hash                          (gconstp
 gboolean                        g_variant_equal                         (gconstpointer         one,
                                                                          gconstpointer         two);
 
-GVariant *                      g_variant_get_normal_form               (GVariant             *variant);
-gboolean                        g_variant_is_normal_form                (GVariant             *variant);
-GVariant *                      g_variant_byteswap                      (GVariant             *variant);
+GVariant *                      g_variant_get_normal_form               (GVariant             *value);
+gboolean                        g_variant_is_normal_form                (GVariant             *value);
+GVariant *                      g_variant_byteswap                      (GVariant             *value);
 GVariant *                      g_variant_new_from_data                 (const GVariantType   *type,
                                                                          gconstpointer         data,
                                                                          gsize                 size,