[glib/gvariant: 85/85] more docs for GVariantType

From: Ryan Lortie <ryanl src gnome org>
To: svn-commits-list gnome org
Cc:
Subject: [glib/gvariant: 85/85] more docs for GVariantType
Date: Fri, 22 Jan 2010 18:14:58 +0000 (UTC)
commit d2549adeb748938d74e0770a20e09f1a1cfb17a0
Author: Ryan Lortie <desrt desrt ca>
Date:   Fri Jan 22 13:13:40 2010 -0500

    more docs for GVariantType

 docs/reference/glib/glib-sections.txt     |   33 +--
 docs/reference/glib/tmpl/glib-unused.sgml |  154 ++++++++---
 docs/reference/glib/tmpl/macros_misc.sgml |    5 +-
 docs/reference/glib/tmpl/threads.sgml     |   18 ++
 docs/reference/glib/tmpl/version.sgml     |   68 +++++
 glib/gvarianttype.c                       |  404 ++++++++++++++++++++++++++++-
 6 files changed, 610 insertions(+), 72 deletions(-)
---
diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt
index 12c41f5..9c48038 100644
--- a/docs/reference/glib/glib-sections.txt
+++ b/docs/reference/glib/glib-sections.txt
@@ -2708,15 +2708,7 @@ g_test_log_msg_free
 <SECTION>
 <TITLE>GVariantType</TITLE>
 <FILE>gvarianttype</FILE>
-GVariantTypeClass
-g_variant_type_class_is_basic
-g_variant_type_class_is_container
-
-<SUBSECTION>
 GVariantType
-G_VARIANT_TYPE
-
-<SUBSECTION>
 G_VARIANT_TYPE_BOOLEAN
 G_VARIANT_TYPE_BYTE
 G_VARIANT_TYPE_INT16
@@ -2725,21 +2717,23 @@ G_VARIANT_TYPE_INT32
 G_VARIANT_TYPE_UINT32
 G_VARIANT_TYPE_INT64
 G_VARIANT_TYPE_UINT64
+G_VARIANT_TYPE_HANDLE
 G_VARIANT_TYPE_DOUBLE
 G_VARIANT_TYPE_STRING
 G_VARIANT_TYPE_OBJECT_PATH
 G_VARIANT_TYPE_SIGNATURE
 G_VARIANT_TYPE_VARIANT
 G_VARIANT_TYPE_ANY
-G_VARIANT_TYPE_ANY_BASIC
-G_VARIANT_TYPE_ANY_MAYBE
-G_VARIANT_TYPE_ANY_ARRAY
-G_VARIANT_TYPE_ANY_TUPLE
+G_VARIANT_TYPE_BASIC
+G_VARIANT_TYPE_MAYBE
+G_VARIANT_TYPE_ARRAY
+G_VARIANT_TYPE_TUPLE
 G_VARIANT_TYPE_UNIT
-G_VARIANT_TYPE_ANY_DICT_ENTRY
-G_VARIANT_TYPE_ANY_DICTIONARY
+G_VARIANT_TYPE_DICT_ENTRY
+G_VARIANT_TYPE_DICTIONARY
 
 <SUBSECTION>
+G_VARIANT_TYPE
 g_variant_type_free
 g_variant_type_copy
 g_variant_type_new
@@ -2752,11 +2746,13 @@ g_variant_type_peek_string
 g_variant_type_dup_string
 
 <SUBSECTION>
-g_variant_type_get_class
-g_variant_type_is_in_class
-g_variant_type_is_basic
+g_variant_type_is_definite
 g_variant_type_is_container
-g_variant_type_is_concrete
+g_variant_type_is_basic
+g_variant_type_is_maybe
+g_variant_type_is_array
+g_variant_type_is_tuple
+g_variant_type_is_dict_entry
 
 <SUBSECTION>
 g_variant_type_hash
@@ -2766,7 +2762,6 @@ g_variant_type_is_subtype_of
 <SUBSECTION>
 g_variant_type_new_maybe
 g_variant_type_new_array
-GVariantTypeGetter
 g_variant_type_new_tuple
 g_variant_type_new_dict_entry
 
diff --git a/docs/reference/glib/tmpl/glib-unused.sgml b/docs/reference/glib/tmpl/glib-unused.sgml
index 139c500..bc6008d 100644
--- a/docs/reference/glib/tmpl/glib-unused.sgml
+++ b/docs/reference/glib/tmpl/glib-unused.sgml
@@ -206,6 +206,40 @@ the end of the string.
 @G_MATCH_EXACT: a pattern matching exactly one string.
 @G_MATCH_LAST: 
 
+<!-- ##### ENUM GVariantTypeClass ##### -->
+<para>
+
+</para>
+
+ G_VARIANT_TYPE_CLASS_INVALID: 
+ G_VARIANT_TYPE_CLASS_BOOLEAN: 
+ G_VARIANT_TYPE_CLASS_BYTE: 
+ G_VARIANT_TYPE_CLASS_INT16: 
+ G_VARIANT_TYPE_CLASS_UINT16: 
+ G_VARIANT_TYPE_CLASS_INT32: 
+ G_VARIANT_TYPE_CLASS_UINT32: 
+ G_VARIANT_TYPE_CLASS_INT64: 
+ G_VARIANT_TYPE_CLASS_UINT64: 
+ G_VARIANT_TYPE_CLASS_DOUBLE: 
+ G_VARIANT_TYPE_CLASS_STRING: 
+ G_VARIANT_TYPE_CLASS_OBJECT_PATH: 
+ G_VARIANT_TYPE_CLASS_SIGNATURE: 
+ G_VARIANT_TYPE_CLASS_VARIANT: 
+ G_VARIANT_TYPE_CLASS_MAYBE: 
+ G_VARIANT_TYPE_CLASS_ARRAY: 
+ G_VARIANT_TYPE_CLASS_TUPLE: 
+ G_VARIANT_TYPE_CLASS_DICT_ENTRY: 
+ G_VARIANT_TYPE_CLASS_ALL: 
+ G_VARIANT_TYPE_CLASS_BASIC: 
+
+<!-- ##### USER_FUNCTION GVariantTypeGetter ##### -->
+<para>
+
+</para>
+
+ data: 
+ Returns: 
+
 <!-- ##### USER_FUNCTION GWarningFunc ##### -->
 <para>
 Specifies the type of function passed to g_set_warning_handler().
@@ -267,6 +301,42 @@ not work.
 </para>
 
 
+<!-- ##### MACRO G_VARIANT_TYPE_ANY_ARRAY ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO G_VARIANT_TYPE_ANY_BASIC ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO G_VARIANT_TYPE_ANY_DICTIONARY ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO G_VARIANT_TYPE_ANY_DICT_ENTRY ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO G_VARIANT_TYPE_ANY_MAYBE ##### -->
+<para>
+
+</para>
+
+
+<!-- ##### MACRO G_VARIANT_TYPE_ANY_TUPLE ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### MACRO NAME_MAX ##### -->
 <para>
 Provided for UNIX emulation on Windows; equivalent to UNIX macro 
@@ -877,93 +947,93 @@ Turns the argument into a string literal by using the '#' stringizing operator.
 
 @x: text to convert to a literal string.
 
-<!-- ##### FUNCTION g_warn_message ##### -->
+<!-- ##### FUNCTION g_variant_get_type_class ##### -->
 <para>
 
 </para>
 
- domain: 
- file: 
- line: 
- func: 
- warnexpr: 
+ value: 
+ Returns: 
 
-<!-- ##### MACRO getcwd ##### -->
+<!-- ##### FUNCTION g_variant_matches ##### -->
 <para>
 
 </para>
 
+ value: 
+ pattern: 
+ Returns: 
 
-<!-- ##### MACRO getpid ##### -->
+<!-- ##### FUNCTION g_variant_type_class_is_basic ##### -->
 <para>
 
 </para>
 
+ tclass: 
+ Returns: 
 
-<!-- ##### VARIABLE glib_binary_age ##### -->
+<!-- ##### FUNCTION g_variant_type_class_is_container ##### -->
 <para>
-This is the binary age passed to <application>libtool</application>. If 
-<application>libtool</application> means nothing to you, don't worry 
-about it. ;-)
+
 </para>
 
+ tclass: 
+ Returns: 
 
-<!-- ##### FUNCTION glib_check_version ##### -->
+<!-- ##### FUNCTION g_variant_type_get_class ##### -->
 <para>
 
 </para>
 
- required_major: 
- required_minor: 
- required_micro: 
+ type: 
 @Returns: 
 
-<!-- ##### VARIABLE glib_interface_age ##### -->
+<!-- ##### FUNCTION g_variant_type_is_concrete ##### -->
 <para>
-This is the interface age passed to <application>libtool</application>. If 
-<application>libtool</application> means nothing to you, don't worry 
-about it. ;-)
+
 </para>
 
+ type: 
+ Returns: 
 
-<!-- ##### VARIABLE glib_major_version ##### -->
+<!-- ##### FUNCTION g_variant_type_is_in_class ##### -->
 <para>
-The major version number of the GLib library. 
-(e.g. in GLib version 1.2.5 this is 1.)
-</para>
 
-<para>
-This variable is in the library, so represents the
-GLib library you have linked against. Contrast with the
-#GLIB_MAJOR_VERSION macro, which represents the major version of the
-GLib headers you have included.
 </para>
 
+ type: 
+ tclass: 
+ Returns: 
 
-<!-- ##### VARIABLE glib_micro_version ##### -->
+<!-- ##### FUNCTION g_variant_type_matches ##### -->
 <para>
-The micro version number of the GLib library.
-(e.g. in GLib version 1.2.5 this is 5.)
+
 </para>
 
+ type: 
+ pattern: 
+ Returns: 
+
+<!-- ##### FUNCTION g_warn_message ##### -->
 <para>
-This variable is in the library, so represents the GLib library you
-have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which
-represents the micro version of the GLib headers you have included.
+
 </para>
 
+ domain: 
+ file: 
+ line: 
+ func: 
+ warnexpr: 
 
-<!-- ##### VARIABLE glib_minor_version ##### -->
+<!-- ##### MACRO getcwd ##### -->
 <para>
-The minor version number of the GLib library.
-(e.g. in GLib version 1.2.5 this is 2.)
+
 </para>
 
+
+<!-- ##### MACRO getpid ##### -->
 <para>
-This variable is in the library, so represents the
-GLib library you have linked against. Contrast with the
-#GLIB_MINOR_VERSION macro, which represents the minor version of the
-GLib headers you have included.
+
 </para>
 
 
diff --git a/docs/reference/glib/tmpl/macros_misc.sgml b/docs/reference/glib/tmpl/macros_misc.sgml
index 29ad670..7ce3ff3 100644
--- a/docs/reference/glib/tmpl/macros_misc.sgml
+++ b/docs/reference/glib/tmpl/macros_misc.sgml
@@ -403,7 +403,7 @@ Since: 2.14
 
 
 
-<!-- ##### MACRO G_LIKELY ##### -->
+<!-- ##### FUNCTION G_LIKELY ##### -->
 <para>
 Hints the compiler that the expression is likely to evaluate to a true
 value. The compiler may use this information for optimizations.
@@ -413,9 +413,10 @@ if (G_LIKELY (random () != 1))
   g_print ("not one");
 </programlisting></informalexample>
 
- expr: the expression
 @Returns: the value of @expr
 @Since: 2.2
+<!-- # Unused Parameters # -->
+ expr: the expression
 
 
 <!-- ##### MACRO G_UNLIKELY ##### -->
diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml
index feb9399..b5226a5 100644
--- a/docs/reference/glib/tmpl/threads.sgml
+++ b/docs/reference/glib/tmpl/threads.sgml
@@ -1799,3 +1799,21 @@ variable.
 @Since: 2.14
 
 
+<!-- ##### FUNCTION g_bit_lock ##### -->
+<para>
+
+</para>
+
+ address: 
+ lock_bit: 
+
+
+<!-- ##### FUNCTION g_bit_unlock ##### -->
+<para>
+
+</para>
+
+ address: 
+ lock_bit: 
+
+
diff --git a/docs/reference/glib/tmpl/version.sgml b/docs/reference/glib/tmpl/version.sgml
index b1cf0bb..f46c1e1 100644
--- a/docs/reference/glib/tmpl/version.sgml
+++ b/docs/reference/glib/tmpl/version.sgml
@@ -19,6 +19,74 @@ typically use the features described here.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### VARIABLE glib_major_version ##### -->
+<para>
+The major version number of the GLib library. 
+(e.g. in GLib version 1.2.5 this is 1.)
+</para>
+
+<para>
+This variable is in the library, so represents the
+GLib library you have linked against. Contrast with the
+#GLIB_MAJOR_VERSION macro, which represents the major version of the
+GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_minor_version ##### -->
+<para>
+The minor version number of the GLib library.
+(e.g. in GLib version 1.2.5 this is 2.)
+</para>
+
+<para>
+This variable is in the library, so represents the
+GLib library you have linked against. Contrast with the
+#GLIB_MINOR_VERSION macro, which represents the minor version of the
+GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_micro_version ##### -->
+<para>
+The micro version number of the GLib library.
+(e.g. in GLib version 1.2.5 this is 5.)
+</para>
+
+<para>
+This variable is in the library, so represents the GLib library you
+have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which
+represents the micro version of the GLib headers you have included.
+</para>
+
+
+<!-- ##### VARIABLE glib_binary_age ##### -->
+<para>
+This is the binary age passed to <application>libtool</application>. If 
+<application>libtool</application> means nothing to you, don't worry 
+about it. ;-)
+</para>
+
+
+<!-- ##### VARIABLE glib_interface_age ##### -->
+<para>
+This is the interface age passed to <application>libtool</application>. If 
+<application>libtool</application> means nothing to you, don't worry 
+about it. ;-)
+</para>
+
+
+<!-- ##### FUNCTION glib_check_version ##### -->
+<para>
+
+</para>
+
+ required_major: 
+ required_minor: 
+ required_micro: 
+ Returns: 
+
+
 <!-- ##### MACRO GLIB_MAJOR_VERSION ##### -->
 <para>
 The major version number of the GLib library.
diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c
index 3c76e1d..eae42a0 100644
--- a/glib/gvarianttype.c
+++ b/glib/gvarianttype.c
@@ -27,20 +27,21 @@
 
 /**
  * SECTION: gvarianttype
- * @title: The GVariant type system
+ * @title: GVariantType
  * @short_description: introduction to the GVariant type system
  * @see_also: #GVariantType, #GVariant
  *
  * This section introduces the GVariant type system.  It is based, in
- * large part, on the DBus type system, with two major changes and some
- * minor lifting of restrictions.  The DBus specification, therefore,
- * provides a significant amount information that is useful when working
- * with GVariant.
+ * large part, on the DBus type system, with two major changes and some minor
+ * lifting of restrictions.  The <ulink
+ * url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus
+ * specification</ulink>, therefore, provides a significant amount of
+ * information that is useful when working with GVariant.
  *
  * The first major change with respect to the DBus type system is the
- * introduction of nullable types.  Any type in GVariant can be
- * converted to a nullable type, in which case, "null" becomes a valid
- * value.
+ * introduction of maybe (or "nullable") types.  Any type in GVariant can be
+ * converted to a maybe type, in which case, "nothing" (or "null") becomes a
+ * valid value.
  *
  * The second major change is that the GVariant type system supports the
  * concept of "indefinite types" -- types that are less specific than
@@ -65,7 +66,392 @@
  * string -- except in the case that it is the signature of a message
  * containing exactly one argument.
  *
- * A detailed description of GVariant type strings is given here XXX.
+ * A detailed description of GVariant type strings is given here:
+ *
+ * <refsect2 id='gvariant-typestrings'>
+ *  <title>GVariant Type Strings</title>
+ *  <para>
+ *   A GVariant type string can be any of the following:
+ *  </para>
+ *  <itemizedlist>
+ *   <listitem>
+ *    <para>
+ *     any basic type string (listed below)
+ *    </para>
+ *   </listitem>
+ *   <listitem>
+ *    <para>
+ *     "<literal>v</literal>", "<literal>r</literal>" or
+ *     "<literal>*</literal>"
+ *    </para>
+ *   </listitem>
+ *   <listitem>
+ *    <para>
+ *     one of the characters '<literal>a</literal>' or
+ *     '<literal>m</literal>', followed by another type string
+ *    </para>
+ *   </listitem>
+ *   <listitem>
+ *    <para>
+ *     the character '<literal>(</literal>', followed by a concatenation
+ *     of zero or more other type strings, followed by the character
+ *     '<literal>)</literal>'
+ *    </para>
+ *   </listitem>
+ *   <listitem>
+ *    <para>
+ *     the character '<literal>{</literal>', followed by a basic type
+ *     string (see below), followed by another type string, followed by
+ *     the character '<literal>}</literal>'
+ *    </para>
+ *   </listitem>
+ *  </itemizedlist>
+ *  <para>
+ *   A basic type string describes a basic type (as per
+ *   g_variant_type_is_basic()) and is always a single
+ *   character in length.  The valid basic type strings are
+ *   "<literal>b</literal>", "<literal>y</literal>",
+ *   "<literal>n</literal>", "<literal>q</literal>",
+ *   "<literal>i</literal>", "<literal>u</literal>",
+ *   "<literal>x</literal>", "<literal>t</literal>",
+ *   "<literal>h</literal>", "<literal>d</literal>",
+ *   "<literal>s</literal>", "<literal>o</literal>",
+ *   "<literal>g</literal>" and "<literal>?</literal>".
+ *  </para>
+ *  <para>
+ *   The above definition is recursive to arbitrary depth.
+ *   "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
+ *   are both valid type strings, as is
+ *   "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
+ *  </para>
+ *  <para>
+ *   The meaning of each of the characters is as follows:
+ *  </para>
+ *  <informaltable>
+ *   <tgroup cols='2'>
+ *    <tbody>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <emphasis role='strong'>Character</emphasis>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        <emphasis role='strong'>Meaning</emphasis>
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>b</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>y</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_BYTE; a byte.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>n</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
+ *        integer.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>q</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
+ *        integer.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>i</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
+ *        integer.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>u</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
+ *        integer.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>x</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
+ *        integer.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>t</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
+ *        integer.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>h</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit
+ *        value that, by convention, is used as an index into an array
+ *        of file descriptors that are sent alongside a DBus message.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>d</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
+ *        floating point value.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>s</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_STRING; a string.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>o</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in
+ *        the form of a DBus object path.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>g</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_STRING; a string in the
+ *        form of a DBus type signature.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>?</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_BASIC; an indefinite type
+ *        that is a supertype of any of the basic types.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>v</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_VARIANT; a container type
+ *        that contain any other type of value.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>a</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        used as a prefix on another type string to mean an array of
+ *        that type; the type string "<literal>ai</literal>", for
+ *        example, is the type of an array of 32 bit signed integers.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>m</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        used as a prefix on another type string to mean a "maybe", or
+ *        "nullable", version of that type; the type string
+ *        "<literal>ms</literal>", for example, is the type of a value
+ *        that maybe contains a string, or maybe contains nothing.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>()</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        used to enclose zero or more other concatenated type strings
+ *        to create a tuple type; the type string
+ *        "<literal>(is)</literal>", for example, is the type of a pair
+ *        of an integer and a string.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>r</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type
+ *        that is a supertype of any tuple type, regardless of the
+ *        number of items.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>{}</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        used to enclose a basic type string concatenated with another
+ *        type string to create a dictionary entry type, which usually
+ *        appears inside of an array to form a dictionary; the type
+ *        string "<literal>a{sd}</literal>", for example, is the type of
+ *        a dictionary that maps strings to double precision floating
+ *        point values.
+ *       </para>
+ *       <para>
+ *        The first type (the basic type) is the key type and the second
+ *        type is the value type.  The reason that the first type is
+ *        restricted to being a basic type is so that it can easily be
+ *        hashed.
+ *       </para>
+ *      </entry>
+ *     </row>
+ *     <row>
+ *      <entry>
+ *       <para>
+ *        <literal>*</literal>
+ *       </para>
+ *      </entry>
+ *      <entry>
+ *       <para>
+ *        the type string of %G_VARIANT_TYPE_ANY; the indefinite type
+ *        that is a supertype of all types.  Note that, as with all type
+ *        strings, this character represents exactly one type.  It
+ *        cannot be used inside of tuples to mean "any number of items".
+ *       </para>
+ *      </entry>
+ *     </row>
+ *    </tbody>
+ *   </tgroup>
+ *  </informaltable>
+ *  <para>
+ *   Any type string of a container that contains an indefinite type is,
+ *   itself, an indefinite type.  For example, the type string
+ *   "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
+ *   an indefinite type that is a supertype of every array type.
+ *   "<literal>(*s)</literal>" is a supertype of all tuples that
+ *   contain exactly two items where the second item is a string.
+ *  </para>
+ *  <para>
+ *   "<literal>a{?*}</literal>" is an indefinite type that is a
+ *   supertype of all arrays containing dictionary entries where the key
+ *   is any basic type and the value is any type at all.  This is, by
+ *   definition, a dictionary, so this type string corresponds to
+ *   %G_VARIANT_TYPE_DICTIONARY.  Note that, due to the restriction that
+ *   the key of a dictionary entry must be a basic type,
+ *   "<literal>{**}</literal>" is not a valid type string.
+ *  </para>
+ * </refsect2>
  */
 
 /**
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]