[gobject-introspection] [gtypelib.h] Document SimpleTypeBlob more

[Colin Walters <walters src gnome org>]

commit 3715b02198c9efc34d70f489d4e55a39456d8f99
Author: Colin Walters <walters verbum org>
Date:   Wed Nov 4 11:43:13 2009 -0500

    [gtypelib.h] Document SimpleTypeBlob more

 girepository/gtypelib.h |   14 ++++++++++++++
 1 files changed, 14 insertions(+), 0 deletions(-)
---
diff --git a/girepository/gtypelib.h b/girepository/gtypelib.h
index 488c1b3..015682e 100644
--- a/girepository/gtypelib.h
+++ b/girepository/gtypelib.h
@@ -303,6 +303,20 @@ typedef struct {
  * @offset:  Offset relative to header->types that points to a TypeBlob. 
  * Unlike other offsets, this is in words (ie 32bit units) rather
  * than bytes.
+ *
+ * The SimpleTypeBlob is the general purpose "reference to a type" construct, used
+ * in method parameters, returns, callback definitions, fields, constants, etc.
+ * It's actually just a 32 bit integer which you can see from the union definition.
+ * This is for efficiency reasons, since there are so many references to types.
+ *
+ * SimpleTypeBlob is divided into two cases; first, if "reserved" and "reserved2", the
+ * type tag for a basic type is embedded in the "tag" bits.  This allows e.g.
+ * GI_TYPE_TAG_UTF8, GI_TYPE_TAG_INT and the like to be embedded directly without
+ * taking up extra space.
+ *
+ * References to "interfaces" (objects, interfaces) are more complicated;  In this case,
+ * the integer is actually an offset into the directory (see above).  Because the header
+ * is larger than 2^8=256 bits, all offsets will have one of the upper 24 bits set.
  */
 typedef union
 {