gvariant.c: Elaborate on GVariant concept and its use

Inserts a paragraph in the start of the description
explaining briefly the concept of GVariant as a
variant datatypes using examples and explaining
a few use cases where GVariant can be useful.

https://bugzilla.gnome.org/show_bug.cgi?id=748806

1 files changed, 16 insertions, 4 deletions

diff --git a/glib/gvariant.c b/glib/gvariant.c
index 85bb1ca90..d28249139 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -40,10 +40,22 @@
  * @short_description: strongly typed value datatype
  * @see_also: GVariantType
  *
- * #GVariant is a variant datatype; it stores a value along with
- * information about the type of that value.  The range of possible
- * values is determined by the type.  The type system used by #GVariant
- * is #GVariantType.
+ * #GVariant is a variant datatype; it can contain one or more values
+ * along with information about the type of the values.
+ * A GVariant can for example contain an array of two strings, an integer or a dictionary.
+ * This is useful for example when sending data via D-Bus, or when
+ * interacting with GSettings or GActions.
+ * When declaring a new GVariant, you parse the data you want to store in it
+ * along with a string representing the type of data you wish to parse to it.
+ * If you, for example, want to make a GVariant holding a string:
+ * |[<!-- language="C" -->
+ * g_variant_new('u','40');
+ * ]|
+ * The string 'u' tells GVariant that the data parsed to it (40) is an integer.
+ * More advanced examples of #GVariant in use can be found in documentation for
+ * [GVariant format strings][gvariant-format-strings-pointers].
+ * The range of possible values is determined by the type.
+ * The type system used by #GVariant is #GVariantType. 
  *
  * #GVariant instances always have a type and a value (which are given
  * at construction time).  The type and value of a #GVariant instance