[glib/gvariant-utils] last of the GVariant docs for this iteration

[Ryan Lortie <ryanl src gnome org>]

commit 5a0bc762026eba65a71d2ebc53ee73933bdac3e3
Author: Ryan Lortie <desrt desrt ca>
Date:   Fri Feb 12 11:10:13 2010 -0500

    last of the GVariant docs for this iteration

 glib/gvariant.c |   88 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 88 insertions(+), 0 deletions(-)
---
diff --git a/glib/gvariant.c b/glib/gvariant.c
index 1284281..eb49c81 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -614,6 +614,19 @@ g_variant_is_container (GVariant *value)
   return g_variant_type_is_container (g_variant_get_type (value));
 }
 
+/**
+ * g_variant_new_maybe:
+ * @type: the #GVariantType of the child
+ * @value: the child value, or %NULL
+ * @returns: a new #GVariant maybe instance
+ *
+ * Depending on if @value is %NULL, either wraps @value inside of a
+ * maybe container or creates a Nothing instance for the given @type.
+ *
+ * At least one of @type and @value must be non-%NULL.  If @type is
+ * non-%NULL then it must be a definite type.  If they are both
+ * non-%NULL then @type must be the type of @value.
+ **/
 GVariant *
 g_variant_new_maybe (const GVariantType *type,
                      GVariant           *value)
@@ -650,6 +663,14 @@ g_variant_new_maybe (const GVariantType *type,
   return value;
 }
 
+/**
+ * g_variant_get_maybe:
+ * @value: a maybe-typed value
+ * @returns: the contents of @value, or %NULL
+ *
+ * Given a maybe-typed #GVariant instance, extract its value.  If the
+ * value is Nothing, then this function returns %NULL.
+ **/
 GVariant *
 g_variant_get_maybe (GVariant *value)
 {
@@ -1003,6 +1024,26 @@ g_variant_dup_strv (GVariant *value,
   return strv;
 }
 
+/**
+ * g_variant_new_array:
+ * @child_type: the element type of the new array
+ * @children: an array of #GVariant pointers, the children
+ * @n_children: the length of @children
+ * @returns: a new #GVariant array
+ *
+ * Creates a new #GVariant array from @children.
+ *
+ * @child_type must be non-%NULL if @n_children is zero.  Otherwise, the
+ * child type is determined by inspecting the first element of the
+ * @children array.  If @child_type is non-%NULL then it must be a
+ * definite type.
+ *
+ * The items of the array are taken from the @children array.  No entry
+ * in the @children array may be %NULL.
+ *
+ * All items in the array must have the same type, which must be the
+ * same as @child_type, if given.
+ **/
 GVariant *
 g_variant_new_array (const GVariantType *child_type,
                      GVariant * const   *children,
@@ -1016,6 +1057,8 @@ g_variant_new_array (const GVariantType *child_type,
 
   g_return_val_if_fail (n_children > 0 || child_type != NULL, NULL);
   g_return_val_if_fail (n_children == 0 || children != NULL, NULL);
+  g_return_val_if_fail (child_type == NULL ||
+                        g_variant_type_is_definite (child_type), NULL);
 
   my_children = g_new (GVariant *, n_children);
   trusted = TRUE;
@@ -1038,6 +1081,18 @@ g_variant_new_array (const GVariantType *child_type,
   return value;
 }
 
+/**
+ * g_variant_new_tuple:
+ * @children: the items to make the tuple out of
+ * @n_children: the length of @children
+ * @returns: a new #GVariant tuple
+ *
+ * Creates a new tuple #GVariant out of the items in @children.  The
+ * type is determined from the types of @children.  No entry in the
+ * @children array may be %NULL.
+ *
+ * If @n_children is 0 then the unit tuple is constructed.
+ **/
 GVariant *
 g_variant_new_tuple (GVariant * const *children,
                      gsize             n_children)
@@ -1071,6 +1126,17 @@ g_variant_new_tuple (GVariant * const *children,
   return value;
 }
 
+/**
+ * g_variant_new_dict_entry:
+ * @key: a basic #GVariant, the key
+ * @value: a #GVariant, the value
+ * @returns: a new dictionary entry #GVariant
+ *
+ * Creates a new dictionary entry #GVariant.  @key and @value must be
+ * non-%NULL.
+ *
+ * @key must be a value of a basic type (ie: not a container).
+ **/
 GVariant *
 g_variant_new_dict_entry (GVariant *key,
                           GVariant *value)
@@ -1095,6 +1161,28 @@ g_variant_new_dict_entry (GVariant *key,
   return value;
 }
 
+/**
+ * g_variant_get_fixed_array:
+ * @value: a #GVariant array with fixed-sized elements
+ * @n_elements: a pointer to the location to store the number of items
+ * @element_size: the size of each element
+ * @returns: a pointer to the fixed array
+ *
+ * Provides access to the serialised data for an array of fixed-sized
+ * items.
+ *
+ * @value must be an array with fixed-sized elements.  Numeric types are
+ * fixed-size as are tuples containing only other fixed-sized types.
+ *
+ * @element_size must be the size of a single element in the array.  For
+ * example, if calling this function for an array of 32 bit integers,
+ * you might say <code>sizeof (gint32)<code>.  This value isn't used
+ * except for the purpose of a double-check that the form of the
+ * seralised data matches the caller's expectation.
+ *
+ * @n_elements, which must be non-%NULL is set equal to the number of
+ * items in the array.
+ **/
 gconstpointer
 g_variant_get_fixed_array (GVariant *value,
                            gsize    *n_elements,