[glib/gvariant: 1/11] improve documentation of indefinite types

[Ryan Lortie <ryanl src gnome org>]

commit a9669308ad6be1d95ad7c5966936736a489c279d
Author: Ryan Lortie <desrt desrt ca>
Date:   Fri Jan 22 13:52:04 2010 -0500

    improve documentation of indefinite types

 glib/gvarianttype.c |   33 ++++++++++++++++++++++++++++++---
 1 files changed, 30 insertions(+), 3 deletions(-)
---
diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c
index eae42a0..ee81f63 100644
--- a/glib/gvarianttype.c
+++ b/glib/gvarianttype.c
@@ -41,14 +41,17 @@
  * The first major change with respect to the DBus type system is the
  * 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.
+ * valid value.  Maybe types have been added by introducing the
+ * character "<literal>m</literal>" to type strings.
  *
  * The second major change is that the GVariant type system supports the
  * concept of "indefinite types" -- types that are less specific than
  * the normal types found in DBus.  For example, it is possible to speak
  * of "an array of any type" in GVariant, where the DBus type system
  * would require you to speak of "an array of integers" or "an array of
- * strings".
+ * strings".  Indefinite types have been added by introducing the
+ * characters "<literal>*</literal>", "<literal>?</literal>" and
+ * "<literal>r</literal>" to type strings.
  *
  * Finally, all arbitrary restrictions relating to the complexity of
  * types are lifted along with the restriction that dictionary entries
@@ -66,6 +69,25 @@
  * string -- except in the case that it is the signature of a message
  * containing exactly one argument.
  *
+ * An indefinite type is similar in spirit to what may be called an
+ * abstract type in other type systems.  No value can exist that has an
+ * indefinite type as its type, but values can exist that have types
+ * that are subtypes of indefinite types.  That is to say,
+ * g_variant_get_type() will never return an indefinite type, but
+ * calling g_variant_is_a() with an indefinite type may return %TRUE.
+ * For example, you can not have a value that represents "an array of no
+ * particular type", but you can have an "array of integers" which
+ * certainly matches the type of "an array of no particular type", since
+ * "array of integers" is a subtype of "array of no particular type".
+ *
+ * This is similar to how instances of abstract classes may not
+ * directly exist in other type systems, but instances of their
+ * non-abstract subtypes may.  For example, in GTK, no object that has
+ * the type of #GtkBin can exist (since #GtkBin is an abstract class),
+ * but a #GtkWindow can certainly be instantiated, and you would say
+ * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
+ * #GtkBin).
+ *
  * A detailed description of GVariant type strings is given here:
  *
  * <refsect2 id='gvariant-typestrings'>
@@ -685,10 +707,15 @@ g_variant_type_dup_string (const GVariantType *type)
  * @returns: %TRUE if @type is definite
  *
  * Determines if the given @type is definite (ie: not indefinite).
- * A #GVariant instance may only have a definite type.
  *
  * A type is definite if its type string does not contain any indefinite
  * type characters ('*', '?', or 'r').
+ *
+ * A #GVariant instance may not have an indefinite type, so calling
+ * this function on the result of g_variant_get_type() will always
+ * result in %TRUE being returned.  Calling this function on an
+ * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
+ * %FALSE being returned.
  **/
 gboolean
 g_variant_type_is_definite (const GVariantType *type)