[glib/gvariant-varargs: 5/5] varargs docs

[Ryan Lortie <ryanl src gnome org>]

commit bc4df07b4c3ba7d314cb956088cf250bebce45ac
Author: Ryan Lortie <desrt desrt ca>
Date:   Sun Mar 7 02:14:40 2010 -0500

    varargs docs

 docs/reference/glib/glib-sections.txt    |   13 +++++++++++++
 docs/reference/glib/gvariant-varargs.xml |   10 ++++++----
 glib/gvariant.c                          |   29 ++++++++++++++++++++---------
 3 files changed, 39 insertions(+), 13 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 015a649..57b6b65 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -2799,6 +2799,14 @@ g_variant_classify
 GVariantClass
 
 <SUBSECTION>
+g_variant_format_string_scan
+g_variant_format_string_scan_type
+g_variant_get
+g_variant_get_va
+g_variant_new
+g_variant_new_va
+
+<SUBSECTION>
 g_variant_new_boolean
 g_variant_new_byte
 g_variant_new_int16
@@ -2844,6 +2852,7 @@ g_variant_new_dict_entry
 g_variant_get_maybe
 g_variant_n_children
 g_variant_get_child_value
+g_variant_get_child
 g_variant_get_fixed_array
 
 <SUBSECTION>
@@ -2878,9 +2887,13 @@ g_variant_builder_new
 g_variant_builder_init
 g_variant_builder_clear
 g_variant_builder_add_value
+g_variant_builder_add
 g_variant_builder_end
 g_variant_builder_open
 g_variant_builder_close
+
+<SUBSECTION Private>
+g_variant_type_checked_
 </SECTION>
 
 
diff --git a/docs/reference/glib/gvariant-varargs.xml b/docs/reference/glib/gvariant-varargs.xml
index 6d58a5b..d57e887 100644
--- a/docs/reference/glib/gvariant-varargs.xml
+++ b/docs/reference/glib/gvariant-varargs.xml
@@ -1,7 +1,9 @@
 <?xml version='1.0' encoding='utf-8'?>
 
-<refentry id='gvariant-varargs'>
- <refentrytitle>GVariant Format Strings</refentrytitle>
+<refentry id='gvariant-format-strings'>
+ <refmeta>
+  <refentrytitle>GVariant Format Strings</refentrytitle>
+ </refmeta>
 
  <refsect1>
   <title>Variable Argument Conversions</title>
@@ -10,8 +12,8 @@
    This page attempts to document how to perform variable argument conversions with GVariant.
   </para>
   <para>
-   A conversion string is a two-way mapping between a single <link linkend='GVariant'>GVariant</link> value and one or
-   more C values.
+   Conversions occur according to format strings.  A format string is a two-way mapping between a single
+   <link linkend='GVariant'>GVariant</link> value and one or more C values.
   </para>
   <para>
    A conversion from C values into a <link linkend='GVariant'>GVariant</link> value is made using the
diff --git a/glib/gvariant.c b/glib/gvariant.c
index 78c8d2e..0f5e884 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -3478,15 +3478,16 @@ g_variant_valist_get (const gchar **str,
  * Think of this function as an analogue to g_strdup_printf().
  *
  * The type of the created instance and the arguments that are
- * expected by this function are determined by @format_string.  Format
- * strings are described in more detail XXX.
+ * expected by this function are determined by @format_string.  See the
+ * section on <link linkend='gvariant-format-strings'>GVariant Format
+ * Strings</link>.  Please note that the syntax of the format string is
+ * very likely to be extended in the future.
  *
  * The first character of the format string must not be '*' '?' '@' or
  * 'r'; in essence, a new #GVariant must always be constructed by this
  * function (and not merely passed through it unmodified).
  *
- * Please note that the syntax of the format string is very likely to
- * be extended in the future.
+ * Since: 2.24
  **/
 GVariant *
 g_variant_new (const gchar *format_string,
@@ -3522,9 +3523,9 @@ g_variant_new (const gchar *format_string,
  *
  * The API is more general than g_variant_new() to allow a wider range
  * of possible uses.
-
+ *
  * @format_string must still point to a valid format string, but it only
- * need to be nul-terminated if @endptr is %NULL.  If @endptr is
+ * needs to be nul-terminated if @endptr is %NULL.  If @endptr is
  * non-%NULL then it is updated to point to the first character past the
  * end of the format string.
  *
@@ -3548,6 +3549,8 @@ g_variant_new (const gchar *format_string,
  * 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.
+ *
+ * Since: 2.24
  **/
 GVariant *
 g_variant_new_va (gpointer      must_be_null,
@@ -3583,10 +3586,12 @@ g_variant_new_va (gpointer      must_be_null,
  * The arguments that are expected by this function are entirely
  * determined by @format_string.  @format_string also restricts the
  * permissible types of @value.  It is an error to give a value with
- * an incompatible type.
+ * an incompatible type.  See the section on <link
+ * linkend='gvariant-format-strings'>GVariant Format Strings</link>.
+ * Please note that the syntax of the format string is very likely to be
+ * extended in the future.
  *
- * Please note that the syntax of the format string is very likely to
- * be extended in the future.
+ * Since: 2.24
  **/
 void
 g_variant_get (GVariant    *value,
@@ -3633,6 +3638,8 @@ g_variant_get (GVariant    *value,
  * 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.
+ *
+ * Since: 2.24
  **/
 void
 g_variant_get_va (GVariant     *value,
@@ -3692,6 +3699,8 @@ g_variant_get_va (GVariant     *value,
  *   return g_variant_builder_end (builder);
  * }
  * </programlisting>
+ *
+ * Since: 2.24
  **/
 void
 g_variant_builder_add (GVariantBuilder *builder,
@@ -3719,6 +3728,8 @@ g_variant_builder_add (GVariantBuilder *builder,
  * deconstructs it according to @format_string.  This call is
  * essentially a combination of g_variant_get_child_value() and
  * g_variant_get().
+ *
+ * Since: 2.24
  **/
 void
 g_variant_get_child (GVariant    *value,