[glib/gvariant] clarify some gvarianttypeinfo comments

[Ryan Lortie <ryanl src gnome org>]

commit cae2e44428fa9cc751e294a7c4f0f1ce21554bc7
Author: Ryan Lortie <desrt desrt ca>
Date:   Sat Jan 30 15:41:08 2010 -0500

    clarify some gvarianttypeinfo comments

 glib/gvarianttypeinfo.c |   18 +++++++++++-------
 glib/gvarianttypeinfo.h |   24 +++++++++++++-----------
 2 files changed, 24 insertions(+), 18 deletions(-)
---
diff --git a/glib/gvarianttypeinfo.c b/glib/gvarianttypeinfo.c
index 8137c52..08439c9 100644
--- a/glib/gvarianttypeinfo.c
+++ b/glib/gvarianttypeinfo.c
@@ -514,14 +514,18 @@ tuple_align (gsize offset,
  * we can flatten this iteration into one addition, one alignment, then
  * one more addition.
  *
- * The algorithm keeps track of the values 'a', 'b', and 'c' such that
- * in order to get to the current point, you add 'a', align to 'b' then
- * add 'c'.  'b' is kept in "one less than" form.  The algorithm then
- * plays through the process of "align to X", "add Y", adjusting the
- * values of 'a', 'b' and 'c' as necessary.
- *
- * The 3 rules have been proven correct, but are provided here without
- * proof:
+ * The loop below plays through each item in the tuple, querying its
+ * alignment and fixed_size into 'd' and 'e', respectively.  At all
+ * times the variables 'a', 'b', and 'c' are maintained such that in
+ * order to get to the current point, you add 'a', align to 'b' then add
+ * 'c'.  'b' is kept in "one less than" form.  For each item, the proper
+ * alignment is applied to find the values of 'a', 'b' and 'c' to get to
+ * the start of that item.  Those values are recorded into the table.
+ * The fixed size of the item (if applicable) is then added on.
+ *
+ * These 3 rules are how 'a', 'b' and 'c' are modified for alignment and
+ * addition of fixed size.  They have been proven correct but are
+ * presented here, without proof:
  *
  *  1) in order to "align to 'd'" where 'd' is less than or equal to the
  *     largest level of alignment seen so far ('b'), you align 'c' to
diff --git a/glib/gvarianttypeinfo.h b/glib/gvarianttypeinfo.h
index 29e5f66..c77cb20 100644
--- a/glib/gvarianttypeinfo.h
+++ b/glib/gvarianttypeinfo.h
@@ -38,11 +38,12 @@ typedef struct _GVariantTypeInfo GVariantTypeInfo;
 /* < private >
  * GVariantMemberInfo:
  *
- * This structure describes how to rapidly construct a GVariant instance
- * corresponding to a given child of a tuple or dictionary entry.  It
- * contains the type of the child, along with 4 constants that allow the
- * bounds of the child's serialised data within the container's
- * serialised data to be found very efficiently.
+ * This structure describes how to construct a GVariant instance
+ * corresponding to a given child of a tuple or dictionary entry in a
+ * very short constant time.  It contains the typeinfo of the child,
+ * along with 4 constants that allow the bounds of the child's
+ * serialised data within the container's serialised data to be found
+ * very efficiently.
  *
  * Since dictionary entries are serialised as if they were tuples of 2
  * items, the term "tuple" will be used here in the general sense to
@@ -64,12 +65,13 @@ typedef struct _GVariantTypeInfo GVariantTypeInfo;
  *   determined by the items that preceed it in the tuple.  Logically,
  *   the start point of a particular item in a given type of tuple can
  *   be determined entirely by the end point of the nearest
- *   variable-sized item that came before it.  In the case of "(isis)"
- *   for example, in order to find out the start point of the last
- *   string, one must start at the end point of the first string, align
- *   to 4 (for the integer's alignment) and then add 4 (for storing the
- *   integer).  That's the point where the string starts (since no
- *   special alignment is required for strings).
+ *   variable-sized item that came before it (or from the start of the
+ *   container itself in case there is no preceeding variable-sized
+ *   item).  In the case of "(isis)" for example, in order to find out
+ *   the start point of the last string, one must start at the end point
+ *   of the first string, align to 4 (for the integer's alignment) and
+ *   then add 4 (for storing the integer).  That's the point where the
+ *   string starts (since no special alignment is required for strings).
  *
  *   Of course, this process requires iterating over the types in the
  *   tuple up to the item of interest.  As it turns out, it is possible