docs: fix up reference docs a bit

      - require GTK-Doc 1.19
      - remove sgml mode
      - automatically generate gi.types (needs GTK-Doc 1.19)
      - fix https://bugzilla.gnome.org/show_bug.cgi?id=700025
[WIP] - rearange sections a bit
[WIP] - add gi-building, gi-programming sections
[WIP] - mark missing docs with TODO, which is only marginaly
        better than nothing but at least can be grepped :)

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

43 files changed, 1018 insertions, 449 deletions

diff --git a/girepository/docs.c b/girepository/docs.c
new file mode 100644
index 00000000..a4798c41
--- /dev/null
+++ b/girepository/docs.c
@@ -0,0 +1,33 @@
+/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*-
+ * GObject introspection: Dump introspection data
+ *
+ * Copyright (C) 2013 Dieter Verfaillie <dieterv@optionexplicit.be>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ */
+
+/* This file collects documentation for macros, typedefs and
+ * the like, which have no good home in any of the 'real' source
+ * files.
+ */
+
+/**
+ * SECTION:gicommontypes
+ * @title: common types
+ * @short_description: TODO
+ *
+ * TODO
+ */
diff --git a/girepository/giarginfo.c b/girepository/giarginfo.c
index d61f4be2..572839c3 100644
--- a/girepository/giarginfo.c
+++ b/girepository/giarginfo.c
@@ -26,12 +26,12 @@
 #include "girepository-private.h"
 
 
-/* GIArgInfo function */
+/* GIArgInfo functions */
 
 /**
  * SECTION:giarginfo
- * @Short_description: Struct representing an argument
- * @Title: GIArgInfo
+ * @title: GIArgInfo
+ * @short_description: Struct representing an argument
  *
  * GIArgInfo represents an argument. An argument is always
  * part of a #GICallableInfo.
@@ -293,8 +293,9 @@ g_arg_info_get_destroy (GIArgInfo *info)
  *
  * Obtain the type information for @info.
  *
- * Returns: (transfer full): the #GIArgInfo, free it with
- * g_base_info_unref() when done.
+ * Returns: (transfer full): the #GITypeInfo holding the type
+ *   information for @info, free it with g_base_info_unref()
+ *   when done.
  */
 GITypeInfo *
 g_arg_info_get_type (GIArgInfo *info)
diff --git a/girepository/giarginfo.h b/girepository/giarginfo.h
index 3f4163e3..4045ab9c 100644
--- a/girepository/giarginfo.h
+++ b/girepository/giarginfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_ARG_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a GIArgInfo.
+ */
 #define GI_IS_ARG_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_ARG)
 
diff --git a/girepository/gibaseinfo.c b/girepository/gibaseinfo.c
index 37893e6c..4bbe850a 100644
--- a/girepository/gibaseinfo.c
+++ b/girepository/gibaseinfo.c
@@ -71,6 +71,17 @@ _g_info_new_full (GIInfoType     type,
   return (GIBaseInfo*)info;
 }
 
+/**
+ * g_info_new:
+ * @type: TODO
+ * @container: TODO
+ * @typelib: TODO
+ * @offset: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 GIBaseInfo *
 g_info_new (GIInfoType     type,
             GIBaseInfo    *container,
@@ -169,8 +180,8 @@ _g_type_info_init (GIBaseInfo *info,
 
 /**
  * SECTION:gibaseinfo
- * @Short_description: Base struct for all GITypelib structs
- * @Title: GIBaseInfo
+ * @title: GIBaseInfo
+ * @short_description: Base struct for all GITypelib structs
  *
  * GIBaseInfo is the common base struct of all other *Info structs
  * accessible through the #GIRepository API.
@@ -209,7 +220,6 @@ _g_type_info_init (GIBaseInfo *info,
  *    +----<link linkend="gi-GITypeInfo">GITypeInfo</link>
  * </synopsis>
  * </refsect1>
- *
  */
 
 /**
diff --git a/girepository/gibaseinfo.h b/girepository/gibaseinfo.h
index 54c8ee4f..a49dd506 100644
--- a/girepository/gibaseinfo.h
+++ b/girepository/gibaseinfo.h
@@ -33,6 +33,11 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GIBaseInfoStub:
+ *
+ * TODO
+ */
 struct _GIBaseInfoStub {
   /* <private> */
   gint32 dummy1;
diff --git a/girepository/gicallableinfo.c b/girepository/gicallableinfo.c
index 28c5950e..e69e3e9d 100644
--- a/girepository/gicallableinfo.c
+++ b/girepository/gicallableinfo.c
@@ -33,8 +33,8 @@
 
 /**
  * SECTION:gicallableinfo
- * @Short_description: Struct representing a callable
- * @Title: GICallableInfo
+ * @title: GICallableInfo
+ * @short_description: Struct representing a callable
  *
  * GICallableInfo represents an entity which is callable.
  * Currently a function (#GIFunctionInfo), virtual function,
@@ -85,9 +85,10 @@ signature_offset (GICallableInfo *info)
  * g_callable_info_can_throw_gerror:
  * @info: a #GICallableInfo
  *
- * Returns: %TRUE if this #GICallableInfo can throw a #GError
+ * TODO
  *
  * Since: 1.34
+ * Returns: %TRUE if this #GICallableInfo can throw a #GError
  */
 gboolean
 g_callable_info_can_throw_gerror (GICallableInfo *info)
@@ -128,6 +129,7 @@ g_callable_info_can_throw_gerror (GICallableInfo *info)
  * is one more C argument than is exposed by introspection: the "self"
  * or "this" object.
  *
+ * Returns: %TRUE if @info is a method, %FALSE otherwise
  * Since: 1.34
  */
 gboolean
@@ -430,11 +432,17 @@ g_callable_info_iterate_return_attributes (GICallableInfo  *info,
   return TRUE;
 }
 
-/* Extract the correct bits from an ffi_arg return value into
+/**
+ * gi_type_info_extract_ffi_return_value:
+ * @return_info: TODO
+ * @ffi_value: TODO
+ * @arg: (out caller-allocates): TODO
+ *
+ * Extract the correct bits from an ffi_arg return value into
  * GIArgument: https://bugzilla.gnome.org/show_bug.cgi?id=665152
  *
- * Also see the ffi_call man page - the storage requirements for return
- * values are "special".
+ * Also see <citerefentry><refentrytitle>ffi_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+ *  - the storage requirements for return values are "special".
  */
 void
 gi_type_info_extract_ffi_return_value (GITypeInfo                  *return_info,
@@ -501,6 +509,21 @@ gi_type_info_extract_ffi_return_value (GITypeInfo                  *return_info,
     }
 }
 
+/**
+ * g_callable_info_invoke:
+ * @info: TODO
+ * @function: TODO
+ * @in_args: TODO
+ * @n_in_args: TODO
+ * @out_args: TODO
+ * @n_out_args: TODO
+ * @return_value: TODO
+ * @is_method: TODO
+ * @throws: TODO
+ * @error: TODO
+ *
+ * TODO
+ */
 gboolean
 g_callable_info_invoke (GIFunctionInfo *info,
                         gpointer          function,
diff --git a/girepository/gicallableinfo.h b/girepository/gicallableinfo.h
index a7d7079a..71f9d0c6 100644
--- a/girepository/gicallableinfo.h
+++ b/girepository/gicallableinfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_CALLABLE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GICallableInfo or derived from it.
+ */
 #define GI_IS_CALLABLE_INFO(info)					\
     ((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_FUNCTION) || \
      (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_CALLBACK) || \
diff --git a/girepository/giconstantinfo.c b/girepository/giconstantinfo.c
index 88220b4e..7b2f716c 100644
--- a/girepository/giconstantinfo.c
+++ b/girepository/giconstantinfo.c
@@ -29,8 +29,8 @@
 
 /**
  * SECTION:giconstantinfo
- * @Short_description: Struct representing a constant
- * @Title: GIConstantInfo
+ * @title: GIConstantInfo
+ * @short_description: Struct representing a constant
  *
  * GIConstantInfo represents a constant. A constant has a type associated
  * which can be obtained by calling g_constant_info_get_type() and a value,
diff --git a/girepository/giconstantinfo.h b/girepository/giconstantinfo.h
index 2bbf9569..2ce1dcad 100644
--- a/girepository/giconstantinfo.h
+++ b/girepository/giconstantinfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_CONSTANT_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIConstantInfo.
+ */
 #define GI_IS_CONSTANT_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_CONSTANT)
 
diff --git a/girepository/gienuminfo.c b/girepository/gienuminfo.c
index 400a56d6..253ec684 100644
--- a/girepository/gienuminfo.c
+++ b/girepository/gienuminfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:gienuminfo
- * @Short_description: Structs representing an enumeration and its values
- * @Title: GIEnumInfo
+ * @title: GIEnumInfo
+ * @short_description: Structs representing an enumeration and its values
  *
  * A GIEnumInfo represents an enumeration and a GIValueInfo struct represents a value
  * of an enumeration. The GIEnumInfo contains a set of values and a type
@@ -46,13 +46,13 @@
  */
 
 /**
-* g_enum_info_get_n_values:
-* @info: a #GIEnumInfo
-*
-* Obtain the number of values this enumeration contains.
-*
-* Returns: the number of enumeration values
-*/
+ * g_enum_info_get_n_values:
+ * @info: a #GIEnumInfo
+ *
+ * Obtain the number of values this enumeration contains.
+ *
+ * Returns: the number of enumeration values
+ */
 gint
 g_enum_info_get_n_values (GIEnumInfo *info)
 {
@@ -76,7 +76,6 @@ g_enum_info_get_n_values (GIEnumInfo *info)
  *
  * Returns: (transfer none): the string form of the error domain associated
  * with this enum, or %NULL.
- *
  * Since: 1.29.17
  */
 const gchar *
@@ -131,7 +130,6 @@ g_enum_info_get_value (GIEnumInfo *info,
  * Obtain the number of methods that this enum type has.
  *
  * Returns: number of methods
- *
  * Since: 1.29.17
  */
 gint
@@ -157,7 +155,6 @@ g_enum_info_get_n_methods (GIEnumInfo *info)
  *
  * Returns: (transfer full): the #GIFunctionInfo. Free the struct by calling
  * g_base_info_unref() when done.
- *
  * Since: 1.29.17
  */
 GIFunctionInfo *
@@ -189,12 +186,12 @@ g_enum_info_get_method (GIEnumInfo *info,
  *
  * Obtain the tag of the type used for the enum in the C ABI. This will
  * will be a signed or unsigned integral type.
-
+ *
  * Note that in the current implementation the width of the type is
  * computed correctly, but the signed or unsigned nature of the type
  * may not match the sign of the type used by the C compiler.
  *
- * Return Value: the storage type for the enumeration
+ * Returns: the storage type for the enumeration
  */
 GITypeTag
 g_enum_info_get_storage_type (GIEnumInfo *info)
diff --git a/girepository/gienuminfo.h b/girepository/gienuminfo.h
index 0b9a9e1b..257e4c12 100644
--- a/girepository/gienuminfo.h
+++ b/girepository/gienuminfo.h
@@ -31,10 +31,22 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_ENUM_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIEnumInfo.
+ */
 #define GI_IS_ENUM_INFO(info) \
     ((g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_ENUM) || \
      (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_FLAGS))
 
+/**
+ * GI_IS_VALUE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIValueInfo.
+ */
 #define GI_IS_VALUE_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_VALUE)
 
diff --git a/girepository/gifieldinfo.c b/girepository/gifieldinfo.c
index 1d9a20dd..2bbc0214 100644
--- a/girepository/gifieldinfo.c
+++ b/girepository/gifieldinfo.c
@@ -29,13 +29,13 @@
 
 /**
  * SECTION:gifieldinfo
- * @Short_description: Struct representing a struct or union field
- * @Title: GIFieldInfo
+ * @title: GIFieldInfo
+ * @short_description: Struct representing a struct or union field
  *
  * A GIFieldInfo struct represents a field of a struct (see #GIStructInfo),
  * union (see #GIUnionInfo) or an object (see #GIObjectInfo). The GIFieldInfo
  * is fetched by calling g_struct_info_get_field(), g_union_info_get_field()
- * or g_object_info_get_value().
+ * or g_object_info_get_field().
  * A field has a size, type and a struct offset asssociated and a set of flags,
  * which is currently #GI_FIELD_IS_READABLE or #GI_FIELD_IS_WRITABLE.
  *
@@ -167,7 +167,7 @@ g_field_info_get_type (GIFieldInfo *info)
  * @mem: pointer to a block of memory representing a C structure or union
  * @value: a #GIArgument into which to store the value retrieved
  *
- * Reads a field identified by a #GFieldInfo from a C structure or
+ * Reads a field identified by a #GIFieldInfo from a C structure or
  * union.  This only handles fields of simple C types. It will fail
  * for a field of a composite type like a nested structure or union
  * even if that is actually readable.
@@ -355,7 +355,7 @@ g_field_info_get_field (GIFieldInfo *field_info,
  * @mem: pointer to a block of memory representing a C structure or union
  * @value: a #GIArgument holding the value to store
  *
- * Writes a field identified by a #GFieldInfo to a C structure or
+ * Writes a field identified by a #GIFieldInfo to a C structure or
  * union.  This only handles fields of simple C types. It will fail
  * for a field of a composite type like a nested structure or union
  * even if that is actually writable. Note also that that it will refuse
diff --git a/girepository/gifieldinfo.h b/girepository/gifieldinfo.h
index 4ca54093..56a2e22e 100644
--- a/girepository/gifieldinfo.h
+++ b/girepository/gifieldinfo.h
@@ -31,6 +31,13 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_FIELD_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIFieldInfo.
+ *
+ */
 #define GI_IS_FIELD_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_FIELD)
 
diff --git a/girepository/gifunctioninfo.c b/girepository/gifunctioninfo.c
index a5858c76..ecd61275 100644
--- a/girepository/gifunctioninfo.c
+++ b/girepository/gifunctioninfo.c
@@ -30,8 +30,8 @@
 
 /**
  * SECTION:gifunctioninfo
- * @Short_description: Struct representing a function
- * @Title: GIFunctionInfo
+ * @title: GIFunctionInfo
+ * @short_description: Struct representing a function
  *
  * GIFunctionInfo represents a function, method or constructor.
  * To find out what kind of entity a #GIFunctionInfo represents, call
@@ -205,6 +205,13 @@ g_function_info_get_vfunc (GIFunctionInfo *info)
   return g_interface_info_get_vfunc (container, blob->index);
 }
 
+/**
+ * g_invoke_error_quark:
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 GQuark
 g_invoke_error_quark (void)
 {
diff --git a/girepository/gifunctioninfo.h b/girepository/gifunctioninfo.h
index 7a9ecae0..7987c926 100644
--- a/girepository/gifunctioninfo.h
+++ b/girepository/gifunctioninfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_FUNCTION_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIFunctionInfo.
+ */
 #define GI_IS_FUNCTION_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_FUNCTION)
 
@@ -39,6 +45,11 @@ GIFunctionInfoFlags     g_function_info_get_flags      (GIFunctionInfo *info);
 GIPropertyInfo *        g_function_info_get_property   (GIFunctionInfo *info);
 GIVFuncInfo *           g_function_info_get_vfunc      (GIFunctionInfo *info);
 
+/**
+ * G_INVOKE_ERROR:
+ *
+ * TODO
+ */
 #define G_INVOKE_ERROR (g_invoke_error_quark ())
 GQuark g_invoke_error_quark (void);
 
diff --git a/girepository/giinterfaceinfo.c b/girepository/giinterfaceinfo.c
index f998da44..481fc54e 100644
--- a/girepository/giinterfaceinfo.c
+++ b/girepository/giinterfaceinfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:giinterfaceinfo
- * @Short_description: Struct representing a GInterface
- * @Title: GIInterfaceInfo
+ * @title: GIInterfaceInfo
+ * @short_description: Struct representing a GInterface
  *
  * GIInterfaceInfo represents a #GInterface type.
  *
@@ -297,9 +297,10 @@ g_interface_info_get_signal (GIInterfaceInfo *info,
  * @info: a #GIInterfaceInfo
  * @name: Name of signal
  *
+ * TODO
+ *
  * Returns: (transfer full): Info for the signal with name @name in @info, or
  * %NULL on failure.
- *
  * Since: 1.34
  */
 GISignalInfo *
diff --git a/girepository/giinterfaceinfo.h b/girepository/giinterfaceinfo.h
index ce40cda7..ec33a630 100644
--- a/girepository/giinterfaceinfo.h
+++ b/girepository/giinterfaceinfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_INTERFACE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIInterfaceInfo.
+ */
 #define GI_IS_INTERFACE_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_INTERFACE)
 
diff --git a/girepository/ginvoke.c b/girepository/ginvoke.c
index 5c0ace4c..6eba9fcc 100644
--- a/girepository/ginvoke.c
+++ b/girepository/ginvoke.c
@@ -28,6 +28,13 @@
 #include "girffi.h"
 #include "config.h"
 
+/**
+ * value_to_ffi_type:
+ * @gvalue: TODO
+ * @value: TODO
+ *
+ * TODO
+ */
 static ffi_type *
 value_to_ffi_type (const GValue *gvalue, gpointer *value)
 {
@@ -89,7 +96,14 @@ value_to_ffi_type (const GValue *gvalue, gpointer *value)
   return rettype;
 }
 
-/* See comment aboe set_gargument_from_ffi_return_value() */
+/**
+ * g_value_to_ffi_return_type:
+ * @gvalue: TODO
+ * @ffi_value: TODO
+ * @value: TODO
+ *
+ * TODO
+ */
 static ffi_type *
 g_value_to_ffi_return_type (const GValue *gvalue,
 			    const GIArgument *ffi_value,
@@ -153,6 +167,13 @@ g_value_to_ffi_return_type (const GValue *gvalue,
   return rettype;
 }
 
+/**
+ * g_value_from_ffi_value:
+ * @gvalue: TODO
+ * @value: TODO
+ *
+ * TODO
+ */
 static void
 g_value_from_ffi_value (GValue           *gvalue,
                         const GIArgument *value)
@@ -210,6 +231,17 @@ g_value_from_ffi_value (GValue           *gvalue,
 
 }
 
+/**
+ * gi_cclosure_marshal_generic:
+ * @closure: TODO
+ * @return_gvalue: TODO
+ * @n_param_values: TODO
+ * @param_values: TODO
+ * @invocation_hint: TODO
+ * @marshal_data: TODO
+ *
+ * TODO
+ */
 void
 gi_cclosure_marshal_generic (GClosure *closure,
                              GValue *return_gvalue,
diff --git a/girepository/giobjectinfo.c b/girepository/giobjectinfo.c
index 7ba2a93b..b0aff37c 100644
--- a/girepository/giobjectinfo.c
+++ b/girepository/giobjectinfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:giobjectinfo
- * @Short_description: Struct representing a GObject
- * @Title: GIObjectInfo
+ * @title: GIObjectInfo
+ * @short_description: Struct representing a GObject
  *
  * GIObjectInfo represents a #GObject. This doesn't represent a specific
  * instance of a GObject, instead this represent the object type (eg class).
@@ -534,6 +534,8 @@ g_object_info_get_signal (GIObjectInfo *info,
  * @info: a #GIObjectInfo
  * @name: Name of signal
  *
+ * TODO
+ *
  * Returns: Info for the signal with name @name in @info, or %NULL on failure.
  */
 GISignalInfo *
diff --git a/girepository/giobjectinfo.h b/girepository/giobjectinfo.h
index ee4b8a82..06206776 100644
--- a/girepository/giobjectinfo.h
+++ b/girepository/giobjectinfo.h
@@ -46,7 +46,6 @@ typedef void * (*GIObjectInfoRefFunction) (void *object);
  * @object: object instance pointer
  *
  * Decreases the reference count of an object instance.
- *
  */
 typedef void   (*GIObjectInfoUnrefFunction) (void *object);
 
@@ -56,7 +55,6 @@ typedef void   (*GIObjectInfoUnrefFunction) (void *object);
  * @object: object instance pointer
  *
  * Update @value and attach the object instance pointer @object to it.
- *
  */
 typedef void   (*GIObjectInfoSetValueFunction) (GValue *value, void *object);
 
@@ -70,6 +68,12 @@ typedef void   (*GIObjectInfoSetValueFunction) (GValue *value, void *object);
  */
 typedef void * (*GIObjectInfoGetValueFunction) (const GValue *value);
 
+/**
+ * GI_IS_OBJECT_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIObjectInfo.
+ */
 #define GI_IS_OBJECT_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_OBJECT)
 
diff --git a/girepository/gipropertyinfo.c b/girepository/gipropertyinfo.c
index 61316cb9..77a11cb8 100644
--- a/girepository/gipropertyinfo.c
+++ b/girepository/gipropertyinfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:gipropertyinfo
- * @Short_description: Struct representing a property
- * @Title: GIPropertyInfo
+ * @title: GIPropertyInfo
+ * @short_description: Struct representing a property
  *
  * GIPropertyInfo represents a property. A property belongs to
  * either a #GIObjectInfo or a #GIInterfaceInfo.
@@ -47,7 +47,7 @@
  * g_property_info_get_flags:
  * @info: a #GIPropertyInfo
  *
- * Obtain the flags for this property info. See #GParamFags for
+ * Obtain the flags for this property info. See #GParamFlags for
  * more information about possible flag values.
  *
  * Returns: the flags
diff --git a/girepository/gipropertyinfo.h b/girepository/gipropertyinfo.h
index 14b18b41..7644664b 100644
--- a/girepository/gipropertyinfo.h
+++ b/girepository/gipropertyinfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_PROPERTY_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIPropertyInfo.
+ */
 #define GI_IS_PROPERTY_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_PROPERTY)
 
diff --git a/girepository/giregisteredtypeinfo.c b/girepository/giregisteredtypeinfo.c
index 6e3d31e2..e45e0603 100644
--- a/girepository/giregisteredtypeinfo.c
+++ b/girepository/giregisteredtypeinfo.c
@@ -30,8 +30,8 @@
 
 /**
  * SECTION:giregisteredtypeinfo
- * @Short_description: Struct representing a struct with a GType
- * @Title: GIRegisteredTypeInfo
+ * @title: GIRegisteredTypeInfo
+ * @short_description: Struct representing a struct with a GType
  *
  * GIRegisteredTypeInfo represents an entity with a GType associated. Could
  * be either a #GIEnumInfo, #GIInterfaceInfo, #GIObjectInfo, #GIStructInfo or a
diff --git a/girepository/giregisteredtypeinfo.h b/girepository/giregisteredtypeinfo.h
index d46d738b..e5db25b4 100644
--- a/girepository/giregisteredtypeinfo.h
+++ b/girepository/giregisteredtypeinfo.h
@@ -32,6 +32,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_REGISTERED_TYPE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIRegisteredTypeInfo or derived from it.
+ */
 #define GI_IS_REGISTERED_TYPE_INFO(info) \
     ((g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_BOXED) || \
      (g_base_info_get_type((GIBaseInfo*)info) == GI_INFO_TYPE_ENUM) || \
diff --git a/girepository/girepository.c b/girepository/girepository.c
index 93c23728..6fc7c77e 100644
--- a/girepository/girepository.c
+++ b/girepository/girepository.c
@@ -34,6 +34,17 @@
 
 #include "config.h"
 
+
+/**
+ * SECTION:girepository
+ * @short_description: GObject Introspection repository manager
+ * @include: girepository.h
+ *
+ * #GIRepository is used to manage repositories of namespaces. Namespaces
+ * are represented on disk by type libraries (.typelib files).
+ */
+
+
 static GIRepository *default_repository = NULL;
 static GSList *search_path = NULL;
 static GSList *override_search_path = NULL;
@@ -146,8 +157,9 @@ init_globals (void)
       char *typelib_dir;
       const gchar *type_lib_path_env;
 
-      /* This variable is intended to take precedence over both the default
-       * search path, as well as anything written into code with g_irepository_prepend_search_path.
+      /* This variable is intended to take precedence over both:
+       *   - the default search path;
+       *   - all g_irepository_prepend_search_path() calls.
        */
       type_lib_path_env = g_getenv ("GI_TYPELIB_PATH");
 
@@ -186,6 +198,14 @@ init_globals (void)
   g_once_init_leave (&initialized, 1);
 }
 
+/**
+ * g_irepository_prepend_search_path:
+ * @directory: (type filename): directory name to prepend to the typelib
+ *   search path
+ *
+ * Prepends @directory to the typelib search path.
+ * See g_irepository_get_search_path().
+ */
 void
 g_irepository_prepend_search_path (const char *directory)
 {
@@ -196,11 +216,11 @@ g_irepository_prepend_search_path (const char *directory)
 /**
  * g_irepository_get_search_path:
  *
- * Returns the search path the GIRepository will use when looking for typelibs.
- * The string is internal to GIRespository and should not be freed, nor should
- * the elements.
+ * Returns the current search path #GIRepository will use when loading
+ * typelib files. The list is internal to #GIRespository and should not
+ * be freed, nor should its string elements.
  *
- * Return value: (element-type filename) (transfer none): list of strings
+ * Returns: (element-type filename) (transfer none): #GSList of strings
  */
 GSList *
 g_irepository_get_search_path (void)
@@ -412,17 +432,19 @@ register_internal (GIRepository *repository,
 
 /**
  * g_irepository_get_dependencies:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace of interest
  *
- * Return an array of all (transitive) dependencies for namespace
- * @namespace_, including version.  The returned strings are of the
- * form <code>namespace-version</code>.
+ * Return an array of all (transitive) versioned dependencies for
+ * @namespace_. Returned strings are of the form
+ * <code>namespace-version</code>.
  *
- * Note: The namespace must have already been loaded using a function
+ * Note: @namespace_ must have already been loaded using a function
  * such as g_irepository_require() before calling this function.
  *
- * Returns: (transfer full): Zero-terminated string array of versioned dependencies
+ * Returns: (transfer full): Zero-terminated string array of versioned
+ *   dependencies
  */
 char **
 g_irepository_get_dependencies (GIRepository *repository,
@@ -440,6 +462,16 @@ g_irepository_get_dependencies (GIRepository *repository,
   return get_typelib_dependencies (typelib);
 }
 
+/**
+ * g_irepository_load_typelib:
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
+ * @typelib: TODO
+ * @flags: TODO
+ * @error: TODO
+ *
+ * TODO
+ */
 const char *
 g_irepository_load_typelib (GIRepository *repository,
 			    GITypelib     *typelib,
@@ -478,7 +510,8 @@ g_irepository_load_typelib (GIRepository *repository,
 
 /**
  * g_irepository_is_registered:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace of interest
  * @version: (allow-none): Required version, may be %NULL for latest
  *
@@ -503,13 +536,13 @@ g_irepository_is_registered (GIRepository *repository,
 /**
  * g_irepository_get_default:
  *
- * Returns the singleton process-global default #GIRepository.  It is
+ * Returns the singleton process-global default #GIRepository. It is
  * not currently supported to have multiple repositories in a
  * particular process, but this function is provided in the unlikely
  * eventuality that it would become possible, and as a convenience for
  * higher level language bindings to conform to the GObject method
  * call conventions.
-
+ *
  * All methods on #GIRepository also accept %NULL as an instance
  * parameter to mean this default repository, which is usually more
  * convenient for C.
@@ -524,7 +557,8 @@ g_irepository_get_default (void)
 
 /**
  * g_irepository_get_n_infos:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the number of metadata entries in
@@ -555,7 +589,8 @@ g_irepository_get_n_infos (GIRepository *repository,
 
 /**
  * g_irepository_get_info:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  * @index: 0-based offset into namespace metadata for entry
  *
@@ -629,7 +664,8 @@ find_by_gtype (GHashTable *table, FindByGTypeData *data, gboolean check_prefix)
 
 /**
  * g_irepository_find_by_gtype:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @gtype: GType to search for
  *
  * Searches all loaded namespaces for a particular #GType.  Note that
@@ -717,7 +753,8 @@ g_irepository_find_by_gtype (GIRepository *repository,
 
 /**
  * g_irepository_find_by_name:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace which will be searched
  * @name: Entry name to find
  *
@@ -776,7 +813,8 @@ find_by_error_domain_foreach (gpointer key,
 
 /**
  * g_irepository_find_by_error_domain:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @domain: a #GError domain
  *
  * Searches for the enum type corresponding to the given #GError
@@ -786,7 +824,6 @@ find_by_error_domain_foreach (gpointer key,
  *
  * Returns: (transfer full): #GIEnumInfo representing metadata about @domain's
  * enum type, or %NULL
- *
  * Since: 1.29.17
  */
 GIEnumInfo *
@@ -839,7 +876,8 @@ collect_namespaces (gpointer key,
 
 /**
  * g_irepository_get_loaded_namespaces:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  *
  * Return the list of currently loaded namespaces.
  *
@@ -868,7 +906,8 @@ g_irepository_get_loaded_namespaces (GIRepository *repository)
 
 /**
  * g_irepository_get_version:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the loaded version associated with the given
@@ -900,7 +939,8 @@ g_irepository_get_version (GIRepository *repository,
 
 /**
  * g_irepository_get_shared_library:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the full path to the shared C library
@@ -937,7 +977,8 @@ g_irepository_get_shared_library (GIRepository *repository,
 
 /**
  * g_irepository_get_c_prefix:
- * @repository: (allow-none): A #GIRepository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: Namespace to inspect
  *
  * This function returns the "C prefix", or the C level namespace
@@ -973,13 +1014,14 @@ g_irepository_get_c_prefix (GIRepository *repository,
 
 /**
  * g_irepository_get_typelib_path:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: GI namespace to use, e.g. "Gtk"
  *
  * If namespace @namespace_ is loaded, return the full path to the
  * .typelib file it was loaded from.  If the typelib for
  * namespace @namespace_ was included in a shared library, return
- * the special string "$lt;builtin$gt;".
+ * the special string "&lt;builtin&gt;".
  *
  * Returns: Filesystem path (or $lt;builtin$gt;) if successful, %NULL if namespace is not loaded
  */
@@ -1248,7 +1290,8 @@ find_namespace_latest (const gchar  *namespace,
 
 /**
  * g_irepository_enumerate_versions:
- * @repository: (allow-none): the repository
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: GI namespace, e.g. "Gtk"
  *
  * Obtain an unordered list of versions (either currently loaded or
@@ -1408,7 +1451,8 @@ require_internal (GIRepository  *repository,
 
 /**
  * g_irepository_require:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @namespace_: GI namespace to use, e.g. "Gtk"
  * @version: (allow-none): Version of namespace, may be %NULL for latest
  * @flags: Set of %GIRepositoryLoadFlags, may be 0
@@ -1442,7 +1486,8 @@ g_irepository_require (GIRepository  *repository,
 
 /**
  * g_irepository_require_private:
- * @repository: (allow-none): Repository, may be %NULL for the default
+ * @repository: (allow-none): A #GIRepository or %NULL for the singleton
+ *   process-global default #GIRepository
  * @typelib_dir: Private directory where to find the requested typelib
  * @namespace_: GI namespace to use, e.g. "Gtk"
  * @version: (allow-none): Version of namespace, may be %NULL for latest
diff --git a/girepository/girepository.h b/girepository/girepository.h
index 2b2b1713..dea250df 100644
--- a/girepository/girepository.h
+++ b/girepository/girepository.h
@@ -56,29 +56,34 @@ G_BEGIN_DECLS
 #define G_IS_IREPOSITORY_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), G_TYPE_IREPOSITORY))
 #define G_IREPOSITORY_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), G_TYPE_IREPOSITORY, GIRepositoryClass))
 
+/**
+ * GIRepository:
+ *
+ * The GIRepository structure contains private data and should only be
+ * accessed using the provided API.
+ */
 typedef struct _GIRepository         GIRepository;
 typedef struct _GIRepositoryClass    GIRepositoryClass;
 typedef struct _GIRepositoryPrivate  GIRepositoryPrivate;
 
 struct _GIRepository
 {
-  GObject parent;
-
   /*< private >*/
+  GObject parent;
   GIRepositoryPrivate *priv;
 };
 
 struct _GIRepositoryClass
 {
+  /*< private >*/
   GObjectClass parent;
 };
 
 /**
  * GIRepositoryLoadFlags:
- * @G_IREPOSITORY_LOAD_FLAG_LAZY: Load the types lazily.
+ * @G_IREPOSITORY_LOAD_FLAG_LAZY: Lazily load the typelib.
  *
- * Flags that controlls how a typelib is loaded by
- * GIRepositry, used by g_irepository_load_typelib().
+ * Flags that control how a typelib is loaded.
  */
 typedef enum
 {
@@ -144,11 +149,14 @@ gboolean       g_irepository_dump  (const char *arg, GError **error);
  * GIRepositoryError:
  * @G_IREPOSITORY_ERROR_TYPELIB_NOT_FOUND: the typelib could not be found.
  * @G_IREPOSITORY_ERROR_NAMESPACE_MISMATCH: the namespace does not match the
- * requested namespace.
+ *   requested namespace.
  * @G_IREPOSITORY_ERROR_NAMESPACE_VERSION_CONFLICT: the version of the
- * typelib does not match the requested version.
+ *   typelib does not match the requested version.
  * @G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND: the library used by the typelib
- * could not be found.
+ *   could not be found.
+ *
+ * An error code used with #G_IREPOSITORY_ERROR in a #GError returned
+ * from a #GIRepository routine.
  */
 typedef enum
 {
@@ -158,6 +166,13 @@ typedef enum
   G_IREPOSITORY_ERROR_LIBRARY_NOT_FOUND
 } GIRepositoryError;
 
+/**
+ * G_IREPOSITORY_ERROR:
+ *
+ * Error domain for #GIRepository. Errors in this domain will be from the
+ * #GIRepositoryError enumeration. See #GError for more information on
+ * error domains.
+ */
 #define G_IREPOSITORY_ERROR (g_irepository_error_quark ())
 
 GQuark g_irepository_error_quark (void);
diff --git a/girepository/girffi.c b/girepository/girffi.c
index f4c80eaa..30642fe1 100644
--- a/girepository/girffi.c
+++ b/girepository/girffi.c
@@ -33,6 +33,14 @@
 #include "girepository.h"
 #include "girepository-private.h"
 
+/**
+ * SECTION:girffi
+ * @short_description: TODO
+ * @title: girffi
+ *
+ * TODO
+ */
+
 static ffi_type *
 gi_type_tag_get_ffi_type_internal (GITypeTag   tag,
                                    gboolean    is_pointer,
@@ -103,22 +111,26 @@ gi_type_tag_get_ffi_type_internal (GITypeTag   tag,
 
 /**
  * gi_type_tag_get_ffi_type:
- * @tag: A #GITypeTag
+ * @type_tag: A #GITypeTag
  * @is_pointer: Whether or not this is a pointer type
  *
+ * TODO
+ *
  * Returns: A #ffi_type corresponding to the platform default C ABI for @tag and @is_pointer.
  */
 ffi_type *
-gi_type_tag_get_ffi_type (GITypeTag   tag,
+gi_type_tag_get_ffi_type (GITypeTag   type_tag,
 			  gboolean    is_pointer)
 {
-  return gi_type_tag_get_ffi_type_internal (tag, is_pointer, FALSE);
+  return gi_type_tag_get_ffi_type_internal (type_tag, is_pointer, FALSE);
 }
 
 /**
  * g_type_info_get_ffi_type:
  * @info: A #GITypeInfo
  *
+ * TODO
+ *
  * Returns: A #ffi_type corresponding to the platform default C ABI for @info.
  */
 ffi_type *
@@ -150,7 +162,9 @@ g_type_info_get_ffi_type (GITypeInfo *info)
  * @callable_info: a callable info from a typelib
  * @n_args_p: (out): The number of arguments
  *
- * Return value: an array of ffi_type*. The array itself
+ * TODO
+ *
+ * Returns: an array of ffi_type*. The array itself
  * should be freed using g_free() after use.
  */
 static ffi_type **
@@ -217,7 +231,8 @@ g_callable_info_get_ffi_arg_types (GICallableInfo *callable_info,
  *
  * Fetches the ffi_type for a corresponding return value of
  * a #GICallableInfo
- * Return value: the ffi_type for the return value
+ *
+ * Returns: the ffi_type for the return value
  */
 static ffi_type *
 g_callable_info_get_ffi_return_type (GICallableInfo *callable_info)
@@ -316,7 +331,7 @@ g_function_invoker_new_for_address (gpointer           addr,
 }
 
 /**
- * g_function_info_invoker_destroy:
+ * g_function_invoker_destroy:
  * @invoker: A #GIFunctionInvoker
  *
  * Release all resources allocated for the internals of @invoker; callers
@@ -343,8 +358,8 @@ typedef struct {
  *
  * Prepares a callback for ffi invocation.
  *
- * Return value: the ffi_closure or NULL on error.
- * The return value should be freed by calling g_callable_info_free_closure().
+ * Returns: the ffi_closure or NULL on error. The return value
+ *     should be freed by calling g_callable_info_free_closure().
  */
 ffi_closure *
 g_callable_info_prepare_closure (GICallableInfo       *callable_info,
diff --git a/girepository/girffi.h b/girepository/girffi.h
index 56caff73..50cabb17 100644
--- a/girepository/girffi.h
+++ b/girepository/girffi.h
@@ -27,6 +27,15 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GIFFIClosureCallback:
+ * @Param1: TODO
+ * @Param2: TODO
+ * @Param3: TODO
+ * @Param4: TODO
+ *
+ * TODO
+ */
 typedef void (*GIFFIClosureCallback) (ffi_cif *,
                                       void *,
                                       void **,
@@ -35,7 +44,9 @@ typedef void (*GIFFIClosureCallback) (ffi_cif *,
 /**
  * GIFunctionInvoker:
  * @cif: the cif
- * @native_address: the native adress
+ * @native_address: the native address
+ *
+ * TODO
  */
 typedef struct _GIFunctionInvoker GIFunctionInvoker;
 
@@ -46,6 +57,11 @@ struct _GIFunctionInvoker {
   gpointer padding[3];
 };
 
+/**
+ * GIFFIReturnValue:
+ *
+ * TODO
+ */
 typedef GIArgument GIFFIReturnValue;
 
 ffi_type *    gi_type_tag_get_ffi_type            (GITypeTag type_tag, gboolean is_pointer);
diff --git a/girepository/giroffsets.c b/girepository/giroffsets.c
index 368332ea..84278b89 100644
--- a/girepository/giroffsets.c
+++ b/girepository/giroffsets.c
@@ -497,7 +497,7 @@ check_needs_computation (GIrTypelibBuild *build,
   return alignment == 0;
 }
 
-/**
+/*
  * _g_ir_node_compute_offsets:
  * @build: Current typelib build
  * @node: a #GIrNode
diff --git a/girepository/gisignalinfo.c b/girepository/gisignalinfo.c
index f4110c38..be75276e 100644
--- a/girepository/gisignalinfo.c
+++ b/girepository/gisignalinfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:gisignalinfo
- * @Short_description: Struct representing a signal
- * @Title: GISignalInfo
+ * @title: GISignalInfo
+ * @short_description: Struct representing a signal
  *
  * GISignalInfo represents a signal. It's a sub-struct of #GICallableInfo
  * and contains a set of flags and a class closure.
diff --git a/girepository/gisignalinfo.h b/girepository/gisignalinfo.h
index e3a1e4a4..8502610c 100644
--- a/girepository/gisignalinfo.h
+++ b/girepository/gisignalinfo.h
@@ -32,6 +32,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_SIGNAL_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GISignalInfo.
+ */
 #define GI_IS_SIGNAL_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_SIGNAL)
 
diff --git a/girepository/gistructinfo.c b/girepository/gistructinfo.c
index dc17e322..f205e7cf 100644
--- a/girepository/gistructinfo.c
+++ b/girepository/gistructinfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:gistructinfo
- * @Short_description: Struct representing a C structure
- * @Title: GIStructInfo
+ * @title: GIStructInfo
+ * @short_description: Struct representing a C structure
  *
  * GIStructInfo represents a generic C structure type.
  *
@@ -212,6 +212,14 @@ g_struct_info_get_alignment (GIStructInfo *info)
   return blob->alignment;
 }
 
+/**
+ * g_struct_info_is_foreign:
+ * @info: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 gboolean
 g_struct_info_is_foreign (GIStructInfo *info)
 {
diff --git a/girepository/gistructinfo.h b/girepository/gistructinfo.h
index 1d10708e..4300534d 100644
--- a/girepository/gistructinfo.h
+++ b/girepository/gistructinfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_STRUCT_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIStructInfo.
+ */
 #define GI_IS_STRUCT_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_STRUCT)
 
diff --git a/girepository/gitypeinfo.c b/girepository/gitypeinfo.c
index a43fbc1b..3c17f564 100644
--- a/girepository/gitypeinfo.c
+++ b/girepository/gitypeinfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:gitypeinfo
- * @Short_description: Struct representing a type
- * @Title: GITypeInfo
+ * @title: GITypeInfo
+ * @short_description: Struct representing a type
  *
  * GITypeInfo represents a type. You can retrieve a type info from
  * an argument (see #GIArgInfo), a functions return value (see #GIFunctionInfo),
@@ -48,7 +48,6 @@
  *    +----GITypeInfo
  * </synopsis>
  * </refsect1>
- *
  */
 
 /**
diff --git a/girepository/gitypeinfo.h b/girepository/gitypeinfo.h
index ef834b12..7591799a 100644
--- a/girepository/gitypeinfo.h
+++ b/girepository/gitypeinfo.h
@@ -31,9 +31,21 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_TYPE_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GITypeInfo.
+ */
 #define GI_IS_TYPE_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_TYPE)
 
+/**
+ * G_TYPE_TAG_IS_BASIC
+ * @tag: a type tag
+ *
+ * Checks if @tag is a basic type.
+ */
 #define G_TYPE_TAG_IS_BASIC(tag) (tag < GI_TYPE_TAG_ARRAY || tag == GI_TYPE_TAG_UNICHAR)
 
 const gchar*           g_type_tag_to_string            (GITypeTag   type);
diff --git a/girepository/gitypelib-internal.h b/girepository/gitypelib-internal.h
index ac71008d..23f4d625 100644
--- a/girepository/gitypelib-internal.h
+++ b/girepository/gitypelib-internal.h
@@ -30,7 +30,8 @@
 G_BEGIN_DECLS
 
 /**
- * SECTION:gtypelib
+ * SECTION:gitypelib-internal
+ * @title: GITypelib
  * @short_description: Layout and accessors for typelib
  * @stability: Stable
  *
@@ -42,32 +43,31 @@ G_BEGIN_DECLS
  *
  * Some of the differences to XPCOM include:
  * - Type information is stored not quite as compactly (XPCOM stores it inline
- * in function descriptions in variable-sized blobs of 1 to n bytes. We store
- * 16 bits of type information for each parameter, which is enough to encode
- * simple types inline. Complex (e.g. recursive) types are stored out of line
- * in a separate list of types.
+ *   in function descriptions in variable-sized blobs of 1 to n bytes. We store
+ *   16 bits of type information for each parameter, which is enough to encode
+ *   simple types inline. Complex (e.g. recursive) types are stored out of line
+ *   in a separate list of types.
  * - String and complex type data is stored outside of typelib entry blobs,
- * references are stored as offsets relative to the start of the typelib.
- * One possibility is to store the strings and types in a pools at the end
- * of the typelib.
+ *   references are stored as offsets relative to the start of the typelib.
+ *   One possibility is to store the strings and types in a pools at the end
+ *   of the typelib.
  *
- * The typelib has the following general format.
+ * The typelib has the following general format:
  *
- * typelib ::= header, section-index, directory, blobs, attributes, attributedata
+ *   typelib ::= header, section-index, directory, blobs, attributes, attributedata
  *
- * directory ::= list of entries
+ *   directory ::= list of entries
  *
- * entry ::= blob type, name, namespace, offset
- * blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union
- * attributes ::= list of attributes, sorted by offset
- * attribute ::= offset, key, value
- * attributedata ::= string data for attributes
+ *   entry ::= blob type, name, namespace, offset
+ *   blob ::= function|callback|struct|boxed|enum|flags|object|interface|constant|union
+ *   attribute ::= offset, key, value
+ *   attributedata ::= string data for attributes
  *
  * Details
  *
  * We describe the fragments that make up the typelib in the form of C structs
- * (although some fall short of being valid C structs since they contain multiple
- * flexible arrays).
+ * (although some fall short of being valid C structs since they contain
+ * multiple flexible arrays).
  */
 
 /*
@@ -157,10 +157,11 @@ Changes since 0.1:
  * @BLOB_TYPE_OBJECT: An #ObjectBlob
  * @BLOB_TYPE_INTERFACE: An #InterfaceBlob
  * @BLOB_TYPE_CONSTANT: A #ConstantBlob
+ * @BLOB_TYPE_INVALID_0: Deleted, used to be ErrorDomain.
  * @BLOB_TYPE_UNION: A #UnionBlob
  *
- * The integral value of this enumeration appears in each "Blob"
- * component of a typelib to identify its type.
+ * The integral value of this enumeration appears in each "Blob" component of
+ * a typelib to identify its type.
  */
 typedef enum {
   BLOB_TYPE_INVALID,
@@ -173,7 +174,7 @@ typedef enum {
   BLOB_TYPE_OBJECT,
   BLOB_TYPE_INTERFACE,
   BLOB_TYPE_CONSTANT,
-  BLOB_TYPE_INVALID_0, /* DELETED - used to be ErrorDomain */
+  BLOB_TYPE_INVALID_0,
   BLOB_TYPE_UNION
 } GTypelibBlobType;
 
@@ -188,52 +189,54 @@ typedef enum {
 /**
  * Header:
  * @magic: See #G_IR_MAGIC.
- * @major_version: The version of the typelib format. Minor version changes indicate
- * compatible changes and should still allow the typelib to be parsed
- * by a parser designed for the same major_version.
- * @minor_version: See major_version.
+ * @major_version: The major version number of the typelib format. Major version
+ *   number changes indicate incompatible changes to the tyeplib format.
+ * @minor_version: The minor version number of the typelib format. Minor version
+ *   number changes indicate compatible changes and should still allow the
+ *   typelib to be parsed by a parser designed for the same @major_version.
+ * @reserved: Reserved for future use.
  * @n_entries: The number of entries in the directory.
- * @n_local_entries: The number of entries referring to blobs in this typelib. The
- * local entries must occur before the unresolved entries.
+ * @n_local_entries: The number of entries referring to blobs in this typelib.
+ *   The local entries must occur before the unresolved entries.
  * @directory: Offset of the directory in the typelib.
  * @n_attributes: Number of attribute blocks
  * @attributes: Offset of the list of attributes in the typelib.
- * @dependencies: Offset of a single string, which is the list of
- * dependencies, separated by the '|' character.  The
- * dependencies are required in order to avoid having programs
- * consuming a typelib check for an "Unresolved" type return
- * from every API call.
+ * @dependencies: Offset of a single string, which is the list of dependencies,
+ *   separated by the '|' character.  The dependencies are required in order
+ *   to avoid having programs consuming a typelib check for an "Unresolved"
+ *   type return from every API call.
  * @size: The size in bytes of the typelib.
  * @namespace: Offset of the namespace string in the typelib.
  * @nsversion: Offset of the namespace version string in the typelib.
- * @shared_library: This field is the set of shared libraries associated
- * with the typelib.  The entries are separated by the '|' (pipe) character.
+ * @shared_library: This field is the set of shared libraries associated with
+ *   the typelib.  The entries are separated by the '|' (pipe) character.
  * @c_prefix: The prefix for the function names of the library
- * @entry_blob_size: The sizes of fixed-size blobs. Recording this information here
- * allows to write parser which continue to work if the format is
- * extended by adding new fields to the end of the fixed-size blobs.
- * @function_blob_size: See above.
- * @callback_blob_size: See above.
- * @signal_blob_size: See above.
- * @vfunc_blob_size: See above.
- * @arg_blob_size: See above.
- * @property_blob_size: See above.
- * @field_blob_size: See above.
- * @value_blob_size: See above.
- * @attribute_blob_size: See above.
- * @constant_blob_size: See above.
- * @object_blob_size: See above.
- * @union_blob_size: See above.
- * @signature_blob_size: See above.
- * @enum_blob_size: See above.
- * @struct_blob_size: See above.
- * @error_domain_blob_size: See above.
- * @interface_blob_size: For variable-size blobs, the size of the struct up to the first
- * flexible array member. Recording this information here allows to
- * write parser which continue to work if the format is extended by
- * adding new fields before the first flexible array member in
- * variable-size blobs.
+ * @entry_blob_size: The sizes of fixed-size blobs. Recording this information
+ *   here allows to write parser which continue to work if the format is
+ *   extended by adding new fields to the end of the fixed-size blobs.
+ * @function_blob_size: See @entry_blob_size.
+ * @callback_blob_size: See @entry_blob_size.
+ * @signal_blob_size: See @entry_blob_size.
+ * @vfunc_blob_size: See @entry_blob_size.
+ * @arg_blob_size: See @entry_blob_size.
+ * @property_blob_size: See @entry_blob_size.
+ * @field_blob_size: See @entry_blob_size.
+ * @value_blob_size: See @entry_blob_size.
+ * @attribute_blob_size: See @entry_blob_size.
+ * @constant_blob_size: See @entry_blob_size.
+ * @error_domain_blob_size: See @entry_blob_size.
+ * @signature_blob_size: See @entry_blob_size.
+ * @enum_blob_size: See @entry_blob_size.
+ * @struct_blob_size: See @entry_blob_size.
+ * @object_blob_size: See @entry_blob_size.
+ * @interface_blob_size: For variable-size blobs, the size of the struct up to
+ *   the first flexible array member. Recording this information here allows
+ *   to write parser which continue to work if the format is extended by
+ *   adding new fields before the first flexible array member in
+ *   variable-size blobs.
+ * @union_blob_size: See @entry_blob_size.
  * @sections: Offset of section blob array
+ * @padding: TODO
  *
  * The header structure appears exactly once at the beginning of a typelib.  It is a
  * collection of meta-information, such as the number of entries and dependencies.
@@ -242,9 +245,7 @@ typedef struct {
   gchar   magic[16];
   guint8  major_version;
   guint8  minor_version;
-  /* <private> */
   guint16 reserved;
-  /* <public> */
   guint16 n_entries;
   guint16 n_local_entries;
   guint32 directory;
@@ -281,10 +282,16 @@ typedef struct {
 
   guint32 sections;
 
-  /* <private> */
   guint16 padding[6];
 } Header;
 
+/**
+ * SectionType:
+ * @GI_SECTION_END: TODO
+ * @GI_SECTION_DIRECTORY_INDEX: TODO
+ *
+ * TODO
+ */
 typedef enum {
   GI_SECTION_END = 0,
   GI_SECTION_DIRECTORY_INDEX = 1
@@ -299,7 +306,6 @@ typedef enum {
  * and may or may not be present in the typelib.  Presently, just used
  * for the directory index.  This allows a form of dynamic extensibility
  * with different tradeoffs from the format minor version.
- *
  */
 typedef struct {
   guint32 id;
@@ -311,10 +317,11 @@ typedef struct {
  * DirEntry:
  * @blob_type: A #GTypelibBlobType
  * @local: Whether this entry refers to a blob in this typelib.
+ * @reserved: Reserved for future use.
  * @name: The name of the entry.
- * @offset:   If is_local is set, this is the offset of the blob in the typelib.
- * Otherwise, it is the offset of the namespace in which the blob has
- * to be looked up by name.
+ * @offset: If is_local is set, this is the offset of the blob in the typelib.
+ *   Otherwise, it is the offset of the namespace in which the blob has to be
+ *   looked up by name.
  *
  * References to directory entries are stored as 1-based 16-bit indexes.
  *
@@ -325,91 +332,100 @@ typedef struct {
   guint16 blob_type;
 
   guint16 local    : 1;
-  /* <private> */
   guint16 reserved :15;
-  /* <public> */
   guint32 name;
   guint32 offset;
 } DirEntry;
 
 /**
- * SimpleTypeBlob:
- * @is_pointer: Indicates whether the type is passed by reference.
+ * SimpleTypeBlobFlags:
+ * @reserved: Reserved for future use.
+ * @reserved2: Reserved for future use.
+ * @pointer: TODO
+ * @reserved3: Reserved for future use.
  * @tag: A #GITypeTag
- * @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.
+ * TODO
  */
-typedef union
+typedef struct {
+  guint reserved   : 8;
+  guint reserved2  :16;
+  guint pointer    : 1;
+  guint reserved3  : 2;
+  guint tag        : 5;
+} SimpleTypeBlobFlags;
+
+union _SimpleTypeBlob
 {
-  struct
-  {
-    /* <private> */
-    guint reserved   : 8;
-    guint reserved2  :16;
-    /* <public> */
-    guint pointer    : 1;
-    /* <private> */
-    guint reserved3  : 2;
-    /* <public> */
-    guint tag        : 5;
-  } flags;
+  SimpleTypeBlobFlags flags;
   guint32    offset;
-} SimpleTypeBlob;
+};
+
+/**
+ * SimpleTypeBlob:
+ * @flags: TODO
+ * @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 _SimpleTypeBlob SimpleTypeBlob;
 
 /**
  * ArgBlob:
  * @name: A suggested name for the parameter.
  * @in: The parameter is an input to the function
- * @out: The parameter is used to return an output of the function.
- * Parameters can be both in and out. Out parameters implicitly
- * add another level of indirection to the parameter type. Ie if
- * the type is uint32 in an out parameter, the function actually
- * takes an uint32*.
- * @caller_allocates: The parameter is a pointer to a struct or object that will
- * receive an output of the function.
- * @allow_none: Only meaningful for types which are passed as pointers.
- * For an in parameter, indicates if it is ok to pass NULL in, for
- * an out parameter, whether it may return NULL. Note that NULL is a
- * valid GList and GSList value, thus allow_none will normally be set
- * for parameters of these types.
+ * @out: The parameter is used to return an output of the function. Parameters
+ *   can be both in and out. Out parameters implicitly add another level of
+ *   indirection to the parameter type. Ie if the type is uint32 in an out
+ *   parameter, the function actually takes an uint32*.
+ * @caller_allocates: The parameter is a pointer to a struct or object that
+ *   will receive an output of the function.
+ * @allow_none: Only meaningful for types which are passed as pointers. For an
+ *   in parameter, indicates if it is ok to pass NULL in. Gor an out
+ *   parameter, indicates whether it may return NULL. Note that NULL is a
+ *   valid GList and GSList value, thus allow_none will normally be set
+ *   for parameters of these types.
  * @optional: For an out parameter, indicates that NULL may be passed in
- * if the value is not needed.
- * @transfer_ownership: For an in parameter, indicates that the function takes over
- * ownership of the parameter value. For an out parameter, it
- * indicates that the caller is responsible for freeing the return
- * value.
+ *   if the value is not needed.
+ * @transfer_ownership: For an in parameter, indicates that the function takes
+ *   over ownership of the parameter value. For an out parameter, it indicates
+ *   that the caller is responsible for freeing the return value.
  * @transfer_container_ownership: For container types, indicates that the
- * ownership of the container,  but not of its contents is transferred. This is typically the case
- * for out parameters returning lists of statically allocated things.
- * @return_value: The parameter should be considered the return value of the function.
- * Only out parameters can be marked as return value, and there can be
- * at most one per function call. If an out parameter is marked as
- * return value, the actual return value of the function should be
- * either void or a boolean indicating the success of the call.
- * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes the scope
- * of the user_data and the callback function pointer itself
- * (for languages that emit code at run-time).
- * @closure: Index of the closure (user_data) parameter associated with the callback,
- * or -1.
- * @destroy: Index of the destroy notfication callback parameter associated with
- * the callback, or -1.
- * @arg_type: Describes the type of the parameter. See details below.
+ *   ownership of the container, but not of its contents is transferred.
+ *   This is typically the case for out parameters returning lists of
+ *   statically allocated things.
+ * @return_value: The parameter should be considered the return value of the
+ *   function. Only out parameters can be marked as return value, and there
+ *   can be at most one per function call. If an out parameter is marked as
+ *   return value, the actual return value of the function should be either
+ *   void or a boolean indicating the success of the call.
+ * @scope: A #GIScopeType. If the parameter is of a callback type, this denotes
+ *   the scope of the user_data and the callback function pointer itself
+ *   (for languages that emit code at run-time).
  * @skip: Indicates that the parameter is only useful in C and should be skipped.
+ * @reserved: Reserved for future use.
+ * @closure: Index of the closure (user_data) parameter associated with the
+ *   callback, or -1.
+ * @destroy: Index of the destroy notfication callback parameter associated
+ *   with the callback, or -1.
+ * @padding: TODO
+ * @arg_type: Describes the type of the parameter. See details below.
  *
  * Types are specified by four bytes. If the three high bytes are zero,
  * the low byte describes a basic type, otherwise the 32bit number is an
@@ -428,15 +444,11 @@ typedef struct {
   guint          return_value                 : 1;
   guint          scope                        : 3;
   guint          skip                         : 1;
-  /* <private> */
   guint          reserved                     :20;
-  /* <public> */
-  gint8        closure;
-  gint8        destroy;
+  gint8          closure;
+  gint8          destroy;
 
-  /* <private> */
-  guint16      padding;
-  /* <public> */
+  guint16        padding;
 
   SimpleTypeBlob arg_type;
 } ArgBlob;
@@ -444,17 +456,21 @@ typedef struct {
 /**
  * SignatureBlob:
  * @return_type: Describes the type of the return value. See details below.
- * @may_return_null: Only relevant for pointer types. Indicates whether the caller
- * must expect NULL as a return value.
- * @caller_owns_return_value: If set, the caller is responsible for freeing the return value
- * if it is no longer needed.
- * @caller_owns_return_container: This flag is only relevant if the return type is a container type.
- * If the flag is set, the caller is resonsible for freeing the
- * container, but not its contents.
- * @skip_return: Indicates that the return value is only useful in C and should be skipped.
- * @n_arguments: The number of arguments that this function expects, also the length
- * of the array of ArgBlobs.
+ * @may_return_null: Only relevant for pointer types. Indicates whether the
+ *   caller must expect NULL as a return value.
+ * @caller_owns_return_value: If set, the caller is responsible for freeing
+ *   the return value if it is no longer needed.
+ * @caller_owns_return_container: This flag is only relevant if the return type
+ *   is a container type. If the flag is set, the caller is resonsible for
+ *   freeing the container, but not its contents.
+ * @skip_return: Indicates that the return value is only useful in C and should
+ *   be skipped.
+ * @reserved: Reserved for future use.
+ * @n_arguments: The number of arguments that this function expects, also the
+ *   length of the array of ArgBlobs.
  * @arguments: An array of ArgBlob for the arguments of the function.
+ *
+ * TODO
  */
 typedef struct {
   SimpleTypeBlob return_type;
@@ -474,43 +490,50 @@ typedef struct {
  * CommonBlob:
  * @blob_type: A #GTypelibBlobType
  * @deprecated: Whether the blob is deprecated.
+ * @reserved: Reserved for future use.
  * @name: The name of the blob.
  *
  * The #CommonBlob is shared between #FunctionBlob,
  * #CallbackBlob, #SignalBlob.
+ *
+ * TODO
  */
 typedef struct {
   guint16 blob_type;  /* 1 */
 
   guint16 deprecated : 1;
-  /* <private> */
   guint16 reserved   :15;
-  /* <public> */
   guint32 name;
 } CommonBlob;
 
 /**
  * FunctionBlob:
- * @blob_Type: #BLOB_TYPE_FUNCTION
- * @symbol:   The symbol which can be used to obtain the function pointer with
- * dlsym().
+ * @blob_type: #BLOB_TYPE_FUNCTION
  * @deprecated: The function is deprecated.
  * @setter: The function is a setter for a property. Language bindings may
- * prefer to not bind individual setters and rely on the generic
- * g_object_set().
+ *   prefer to not bind individual setters and rely on the generic
+ *   g_object_set().
  * @getter: The function is a getter for a property. Language bindings may
- * prefer to not bind individual getters and rely on the generic
- * g_object_get().
- * @constructor:The function acts as a constructor for the object it is contained
- * in.
+ *   prefer to not bind individual getters and rely on the generic
+ *   g_object_get().
+ * @constructor: The function acts as a constructor for the object it is
+ *   contained in.
  * @wraps_vfunc: The function is a simple wrapper for a virtual function.
+ * @throws: TODO
  * @index: Index of the property that this function is a setter or getter of
- * in the array of properties of the containing interface, or index
- * of the virtual function that this function wraps.
+ *   in the array of properties of the containing interface, or index
+ *   of the virtual function that this function wraps.
+ * @name: TODO
+ * @symbol: The symbol which can be used to obtain the function pointer with
+ *   dlsym().
  * @signature: Offset of the SignatureBlob describing the parameter types and the
- * return value type.
+ *   return value type.
  * @is_static: The function is a "static method"; in other words it's a pure
- * function whose name is conceptually scoped to the object.
+ *   function whose name is conceptually scoped to the object.
+ * @reserved: Reserved for future use.
+ * @reserved2: Reserved for future use.
+ *
+ * TODO
  */
 typedef struct {
   guint16 blob_type;  /* 1 */
@@ -537,16 +560,20 @@ typedef struct {
 
 /**
  * CallbackBlob:
- * @signature: Offset of the #SignatureBlob describing the parameter types and the
- * return value type.
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
+ * @signature: Offset of the #SignatureBlob describing the parameter types and
+ *   the return value type.
+ *
+ * TODO
  */
 typedef struct {
   guint16 blob_type;  /* 2 */
 
   guint16 deprecated : 1;
-  /* <private> */
   guint16 reserved   :15;
-  /* <public> */
   guint32 name;
   guint32 signature;
 } CallbackBlob;
@@ -554,41 +581,52 @@ typedef struct {
 /**
  * InterfaceTypeBlob:
  * @pointer: Whether this type represents an indirection
+ * @reserved: Reserved for future use.
  * @tag: A #GITypeTag
+ * @reserved2: Reserved for future use.
  * @interface: Index of the directory entry for the interface.
  *
  * If the interface is an enum of flags type, is_pointer is 0, otherwise it is 1.
  */
 typedef struct {
   guint8  pointer  :1;
-  /* <private> */
   guint8  reserved :2;
-  /* <public> */
   guint8  tag      :5;
-  /* <private> */
   guint8  reserved2;
-  /* <public> */
   guint16 interface;
 } InterfaceTypeBlob;
 
 /**
+ * ArrayTypeDimension:
+ * @length: TODO
+ * @size: TODO
+ *
+ * TODO
+ */
+typedef union {
+  guint16 length;
+  guint16 size;
+} ArrayTypeDimension;
+
+/**
  * ArrayTypeBlob:
- * @zero_terminated: Indicates that the array must be terminated by a suitable #NULL
- * value.
- * @has_length: Indicates that length points to a parameter specifying the length
- * of the array. If both has_length and zero_terminated are set, the
- * convention is to pass -1 for the length if the array is
- * zero-terminated.
+ * @pointer: TODO
+ * @reserved: Reserved for future use.
+ * @tag: TODO
+ * @zero_terminated: Indicates that the array must be terminated by a suitable
+ *   #NULL value.
+ * @has_length: Indicates that length points to a parameter specifying the
+ *   length of the array. If both has_length and zero_terminated are set, the
+ *   convention is to pass -1 for the length if the array is zero-terminated.
  * @has_size: Indicates that size is the fixed size of the array.
  * @array_type: Indicates whether this is a C array, GArray, GPtrArray, or
- * GByteArray. If something other than a C array, the length and element size
- * are implicit in the structure.
- * @length: The index of the parameter which is used to pass the length of the
- * array. The parameter must be an integer type and have the same
- * direction as this one.
- * @size: The fixed size of the array.
- * @type: The type of the array elements.
- * Arrays are passed by reference, thus is_pointer is always 1.
+ *   GByteArray. If something other than a C array, the length and element
+ *   size are implicit in the structure.
+ * @reserved2: Reserved for future use.
+ * @dimensions: TODO
+ * @type: TODO
+ *
+ * TODO
  */
 typedef struct {
   guint16 pointer         :1;
@@ -601,19 +639,21 @@ typedef struct {
   guint16 array_type      :2;
   guint16 reserved2       :3;
 
-  union {
-    guint16 length;
-    guint16 size;
-  } dimensions;
+  ArrayTypeDimension dimensions;
 
   SimpleTypeBlob type;
 } ArrayTypeBlob;
 
 /**
  * ParamTypeBlob:
+ * @pointer: TODO
+ * @reserved: Reserved for future use.
+ * @tag: TODO
+ * @reserved2: Reserved for future use.
  * @n_types: The number of parameter types to follow.
  * @type: Describes the type of the list elements.
  *
+ * TODO
  */
 typedef struct {
   guint8	 pointer  :1;
@@ -628,6 +668,14 @@ typedef struct {
 
 /**
  * ErrorTypeBlob:
+ * @pointer: TODO
+ * @reserved: TODO
+ * @tag: TODO
+ * @reserved2: TODO
+ * @n_domains: TODO: must be 0
+ * @domains: TODO
+ *
+ * TODO
  */
 typedef struct {
   guint8  pointer  :1;
@@ -644,17 +692,16 @@ typedef struct {
  * ValueBlob:
  * @deprecated: Whether this value is deprecated
  * @unsigned_value: if set, value is a 32-bit unsigned integer cast to gint32
- * @value: The numerical value
+ * @reserved: Reserved for future use.
  * @name: Name of blob
+ * @value: The numerical value
  *
  * Values commonly occur in enums and flags.
  */
 typedef struct {
   guint32 deprecated : 1;
   guint32 unsigned_value : 1;
-  /* <private> */
   guint32 reserved   :30;
-  /* <public> */
   guint32 name;
   gint32 value;
 } ValueBlob;
@@ -662,15 +709,18 @@ typedef struct {
 /**
  * FieldBlob:
  * @name: The name of the field.
- * @readable:
+ * @readable: TODO
  * @writable: How the field may be accessed.
  * @has_embedded_type: An anonymous type follows the FieldBlob.
+ * @reserved: Reserved for future use.
  * @bits: If this field is part of a bitfield, the number of bits which it
- * uses, otherwise 0.
- * @struct_offset:
- * The offset of the field in the struct. The value 0xFFFF indicates
- * that the struct offset is unknown.
+ *   uses, otherwise 0.
+ * @struct_offset: The offset of the field in the struct. The value 0xFFFF
+ *   indicates that the struct offset is unknown.
+ * @reserved2: Reserved for future use.
  * @type: The type of the field.
+ *
+ * TODO
  */
 typedef struct {
   guint32        name;
@@ -690,8 +740,16 @@ typedef struct {
 
 /**
  * RegisteredTypeBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @unregistered: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
  * @gtype_name: The name under which the type is registered with GType.
- * @gtype_init: The symbol name of the get_type() function which registers the type.
+ * @gtype_init: The symbol name of the get_type<!-- -->() function which registers the
+ *   type.
+ *
+ * TODO
  */
 typedef struct {
   guint16 blob_type;
@@ -709,16 +767,22 @@ typedef struct {
  * @blob_type: #BLOB_TYPE_STRUCT
  * @deprecated: Whether this structure is deprecated
  * @unregistered: If this is set, the type is not registered with GType.
+ * @is_gtype_struct: Whether this structure is the class or interface layout
+ *   for a GObject
  * @alignment: The byte boundary that the struct is aligned to in memory
- * @is_gtype_struct: Whether this structure is the class or interface layout for a GObject
  * @foreign: If the type is foreign, eg if it's expected to be overridden by
- * a native language binding instead of relying of introspected bindings.
- * @size: The size of the struct in bytes.
+ *   a native language binding instead of relying of introspected bindings.
+ * @reserved: Reserved for future use.
+ * @name: TODO
  * @gtype_name: String name of the associated #GType
  * @gtype_init: String naming the symbol which gets the runtime #GType
- * @n_fields:
- * @fields: An array of n_fields FieldBlobs.
- * should be considered as methods of the struct.
+ * @size: The size of the struct in bytes.
+ * @n_fields: TODO
+ * @n_methods: TODO
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
+ *
+ * TODO
  */
 typedef struct {
   guint16   blob_type;
@@ -742,29 +806,30 @@ typedef struct {
 
   guint32   reserved2;
   guint32   reserved3;
-
-#if 0
-  /* variable-length parts of the blob */
-  FieldBlob    fields[];
-  FunctionBlob methods[];
-#endif
 } StructBlob;
 
 /**
  * UnionBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
  * @unregistered: If this is set, the type is not registered with GType.
  * @discriminated: Is set if the union is discriminated
  * @alignment: The byte boundary that the union is aligned to in memory
- * @size: The size of the union in bytes.
+ * @reserved: Reserved for future use.
+ * @name: TODO
  * @gtype_name: String name of the associated #GType
  * @gtype_init: String naming the symbol which gets the runtime #GType
+ * @size: TODO
  * @n_fields: Length of the arrays
+ * @n_functions: TODO
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
  * @discriminator_offset: Offset from the beginning of the union where the
- * discriminator of a discriminated union is located.
- * The value 0xFFFF indicates that the discriminator offset
- * is unknown.
+ *   discriminator of a discriminated union is located. The value 0xFFFF
+ *   indicates that the discriminator offset is unknown.
  * @discriminator_type: Type of the discriminator
- * @fields: Array of FieldBlobs describing the alternative branches of the union
+ *
+ * TODO
  */
 typedef struct {
   guint16      blob_type;
@@ -788,27 +853,25 @@ typedef struct {
 
   gint32       discriminator_offset;
   SimpleTypeBlob discriminator_type;
-
-#if 0
-  FieldBlob    fields[];
-  FunctionBlob functions[];
-  ConstantBlob discriminator_values[]
-#endif
 } UnionBlob;
 
 /**
  * EnumBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
  * @unregistered: If this is set, the type is not registered with GType.
  * @storage_type: The tag of the type used for the enum in the C ABI
- * (will be a signed or unsigned integral type)
+ *   (will be a signed or unsigned integral type)
+ * @reserved: Reserved for future use.
+ * @name: TODO
  * @gtype_name: String name of the associated #GType
  * @gtype_init: String naming the symbol which gets the runtime #GType
- * @error_domain: String naming the #GError domain this enum is
- *   associated with
  * @n_values: The length of the values array.
  * @n_methods: The length of the methods array.
- * @values: Describes the enum values.
- * @methods: Describes the enum methods.
+ * @error_domain: String naming the #GError domain this enum is associated with
+ * @values: TODO
+ *
+ * TODO
  */
 typedef struct {
   guint16   blob_type;
@@ -829,25 +892,28 @@ typedef struct {
   guint32   error_domain;
 
   ValueBlob values[];
-#if 0
-  FunctionBlob methods[];
-#endif
 } EnumBlob;
 
 /**
  * PropertyBlob:
- * @name:     The name of the property.
- * @readable:
- * @writable:
- * @construct:
+ * @name: The name of the property.
+ * @deprecated: TODO
+ * @readable: TODO
+ * @writable: TODO
+ * @construct: TODO
  * @construct_only: The ParamFlags used when registering the property.
  * @transfer_ownership: When writing, the type containing the property takes
- * ownership of the value. When reading, the returned value needs to be released
- * by the caller.
+ *   ownership of the value. When reading, the returned value needs to be
+ *   released by the caller.
  * @transfer_container_ownership: For container types indicates that the
- * ownership of the container, but not of its contents, is transferred. This is
- * typically the case when reading lists of statically allocated things.
+ *   ownership of the container, but not of its contents, is transferred.
+ *   This is typically the case when reading lists of statically allocated
+ *   things.
+ * @reserved: Reserved for future use.
+ * @reserved2: Reserved for future use.
  * @type: Describes the type of the property.
+ *
+ * TODO
  */
 typedef struct {
   guint32        name;
@@ -868,20 +934,25 @@ typedef struct {
 
 /**
  * SignalBlob:
- * @name: The name of the signal.
- * @run_first:
- * @run_last:
- * @run_cleanup:
- * @no_recurse:
- * @detailed:
- * @action:
+ * @deprecated: TODO
+ * @run_first: TODO
+ * @run_last: TODO
+ * @run_cleanup: TODO
+ * @no_recurse: TODO
+ * @detailed: TODO
+ * @action: TODO
  * @no_hooks: The flags used when registering the signal.
  * @has_class_closure: Set if the signal has a class closure.
  * @true_stops_emit: Whether the signal has true-stops-emit semantics
- * @class_closure: The index of the class closure in the list of virtual functions
- * of the object or interface on which the signal is defined.
- * @signature: Offset of the SignatureBlob describing the parameter types and the
- * return value type.
+ * @reserved: Reserved for future use.
+ * @class_closure: The index of the class closure in the list of virtual
+ *   functions of the object or interface on which the signal is defined.
+ * @name: The name of the signal.
+ * @reserved2: Reserved for future use.
+ * @signature: Offset of the SignatureBlob describing the parameter types
+ *   and the return value type.
+ *
+ * TODO
  */
 typedef struct {
   guint16 deprecated        : 1;
@@ -909,19 +980,28 @@ typedef struct {
  * VFuncBlob:
  * @name: The name of the virtual function.
  * @must_chain_up: If set, every implementation of this virtual function must
- * chain up to the implementation of the parent class.
- * @must_be_implemented: If set, every derived class must override this virtual function.
- * @must_not_be_implemented: If set, derived class must not override this virtual function.
- * @class_closure: Set if this virtual function is the class closure of a signal.
+ *   chain up to the implementation of the parent class.
+ * @must_be_implemented: If set, every derived class must override this virtual
+ *   function.
+ * @must_not_be_implemented: If set, derived class must not override this
+ *   virtual function.
+ * @class_closure: Set if this virtual function is the class closure of a
+ *   signal.
+ * @throws: TODO
+ * @reserved: Reserved for future use.
  * @signal: The index of the signal in the list of signals of the object or
- * interface to which this virtual function belongs.
- * @struct_offset: The offset of the function pointer in the class struct. The value
- * 0xFFFF indicates that the struct offset is unknown.
- * @invoker: If a method invoker for this virtual exists, this is the offset in the
- * class structure of the method.  If no method is known, this value will be 0x3ff.
- * @signature:
- * Offset of the SignatureBlob describing the parameter types and the
- * return value type.
+ *   interface to which this virtual function belongs.
+ * @struct_offset: The offset of the function pointer in the class struct.
+ *   The value 0xFFFF indicates that the struct offset is unknown.
+ * @invoker: If a method invoker for this virtual exists, this is the offset
+ *   in the class structure of the method. If no method is known, this value
+ *   will be 0x3ff.
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
+ * @signature: Offset of the SignatureBlob describing the parameter types and
+ *   the return value type.
+ *
+ * TODO
  */
 typedef struct {
   guint32 name;
@@ -945,36 +1025,41 @@ typedef struct {
 /**
  * ObjectBlob:
  * @blob_type: #BLOB_TYPE_OBJECT
+ * @deprecated: TODO
+ * @abstract: TODO
  * @fundamental: this object is not a GObject derived type, instead it's
- * an additional fundamental type.
+ *   an additional fundamental type.
+ * @reserved: Reserved for future use.
+ * @name: TODO
  * @gtype_name: String name of the associated #GType
  * @gtype_init: String naming the symbol which gets the runtime #GType
  * @parent: The directory index of the parent type. This is only set for
- * objects. If an object does not have a parent, it is zero.
- * @n_interfaces:
- * @n_fields:
- * @n_properties:
- * @n_methods:
- * @n_signals:
- * @n_vfuncs:
- * @n_constants: The lengths of the arrays.Up to 16bits of padding may be inserted
- * between the arrays to ensure that they start on a 32bit boundary.
- * @interfaces: An array of indices of directory entries for the implemented
- * interfaces.
- * @fields: Describes the fields.
- * @methods: Describes the methods, constructors, setters and getters.
- * @properties: Describes the properties.
- * @signals: Describes the signals.
- * @vfuncs: Describes the virtual functions.
- * @constants: Describes the constants.
+ *   objects. If an object does not have a parent, it is zero.
+ * @gtype_struct: TODO
+ * @n_interfaces: TODO
+ * @n_fields: TODO
+ * @n_properties: TODO
+ * @n_methods: TODO
+ * @n_signals: TODO
+ * @n_vfuncs: TODO
+ * @n_constants: The lengths of the arrays.Up to 16bits of padding may be
+ *   inserted between the arrays to ensure that they start on a 32bit
+ *   boundary.
+ * @reserved2: Reserved for future use.
  * @ref_func: String pointing to a function which can be called to increase
- * the reference count for an instance of this object type.
+ *   the reference count for an instance of this object type.
  * @unref_func: String pointing to a function which can be called to decrease
- * the reference count for an instance of this object type.
+ *   the reference count for an instance of this object type.
  * @set_value_func: String pointing to a function which can be called to
- * convert a pointer of this object to a GValue
+ *   convert a pointer of this object to a GValue
  * @get_value_func: String pointing to a function which can be called to
- * convert extract a pointer to this object from a GValue
+ *   convert extract a pointer to this object from a GValue
+ * @reserved3: Reserved for future use.
+ * @reserved4: Reserved for future use.
+ * @interfaces: An array of indices of directory entries for the implemented
+ *   interfaces.
+ *
+ * TODO
  */
 typedef struct {
   guint16   blob_type;  /* 7 */
@@ -1008,35 +1093,32 @@ typedef struct {
   guint32   reserved4;
 
   guint16   interfaces[];
-
-#if 0
-  /* variable-length parts of the blob */
-  FieldBlob           fields[];
-  PropertyBlob        properties[];
-  FunctionBlob        methods[];
-  SignalBlob          signals[];
-  VFuncBlob           vfuncs[];
-  ConstantBlob        constants[];
-#endif
 } ObjectBlob;
 
 /**
  * InterfaceBlob:
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
+ * @gtype_name: TODO
+ * @gtype_init: TODO
  * @gtype_struct: Name of the interface "class" C structure
  * @n_prerequisites: Number of prerequisites
  * @n_properties: Number of properties
  * @n_methods: Number of methods
  * @n_signals: Number of signals
  * @n_vfuncs: Number of virtual functions
- * @n_constants: The lengths of the arrays.
- * Up to 16bits of padding may be inserted between the arrays to ensure that they
- * start on a 32bit boundary.
- * @prerequisites: An array of indices of directory entries for required interfaces.
- * @methods: Describes the methods, constructors, setters and getters.
- * @properties: Describes the properties.
- * @signals:  Describes the signals.
- * @vfuncs: Describes the virtual functions.
- * @constants: Describes the constants.
+ * @n_constants: The lengths of the arrays. Up to 16bits of padding may be
+ *   inserted between the arrays to ensure that they start on a 32bit
+ *   boundary.
+ * @padding: TODO
+ * @reserved2: Reserved for future use.
+ * @reserved3: Reserved for future use.
+ * @prerequisites: An array of indices of directory entries for required
+ *   interfaces.
+ *
+ * TODO
  */
 typedef struct {
   guint16 blob_type;
@@ -1061,23 +1143,21 @@ typedef struct {
   guint32 reserved3;
 
   guint16 prerequisites[];
-
-#if 0
-  /* variable-length parts of the blob */
-  PropertyBlob        properties[];
-  FunctionBlob        methods[];
-  SignalBlob          signals[];
-  VFuncBlob           vfuncs[];
-  ConstantBlob        constants[];
-#endif
 } InterfaceBlob;
 
 /**
  * ConstantBlob:
- * @type: The type of the value. In most cases this should be a numeric
- * type or string.
+ * @blob_type: TODO
+ * @deprecated: TODO
+ * @reserved: Reserved for future use.
+ * @name: TODO
+ * @type: The type of the value. In most cases this should be a numeric type
+ *   or string.
  * @size: The size of the value in bytes.
  * @offset: The offset of the value in the typelib.
+ * @reserved2: Reserved for future use.
+ *
+ * TODO
  */
 typedef struct {
   guint16        blob_type;
@@ -1096,10 +1176,12 @@ typedef struct {
 /**
  * AttributeBlob:
  * @offset: The offset of the typelib entry to which this attribute refers.
- * Attributes are kept sorted by offset, so that the attributes
- * of an entry can be found by a binary search.
+ *   Attributes are kept sorted by offset, so that the attributes of an
+ *   entry can be found by a binary search.
  * @name: The name of the attribute, a string.
  * @value: The value of the attribute (also a string)
+ *
+ * TODO
  */
 typedef struct {
   guint32 offset;
@@ -1107,9 +1189,6 @@ typedef struct {
   guint32 value;
 } AttributeBlob;
 
-/**
- * GITypelib:
- */
 struct _GITypelib {
   /* <private> */
   guchar *data;
@@ -1137,6 +1216,15 @@ gboolean  g_typelib_matches_gtype_name_prefix (GITypelib *typelib,
 
 void      g_typelib_check_sanity (void);
 
+/**
+ * g_typelib_get_string:
+ * @typelib: TODO
+ * @offset: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 #define   g_typelib_get_string(typelib,offset) ((const gchar*)&(typelib->data)[(offset)])
 
 
@@ -1159,6 +1247,11 @@ typedef enum
   G_TYPELIB_ERROR_INVALID_BLOB
 } GITypelibError;
 
+/**
+ * G_TYPELIB_ERROR:
+ *
+ * TODO
+ */
 #define G_TYPELIB_ERROR (g_typelib_error_quark ())
 
 GQuark g_typelib_error_quark (void);
@@ -1171,6 +1264,11 @@ gboolean g_typelib_validate (GITypelib  *typelib,
 AttributeBlob *_attribute_blob_find_first (GIBaseInfo *info,
                                            guint32     blob_offset);
 
+/**
+ * GITypelibHashBuilder:
+ *
+ * TODO
+ */
 typedef struct _GITypelibHashBuilder GITypelibHashBuilder;
 
 GITypelibHashBuilder * _gi_typelib_hash_builder_new (void);
diff --git a/girepository/gitypelib.c b/girepository/gitypelib.c
index 1436caf1..8883496e 100644
--- a/girepository/gitypelib.c
+++ b/girepository/gitypelib.c
@@ -130,6 +130,15 @@ get_type_blob (GITypelib *typelib,
   return (InterfaceTypeBlob*) get_blob (typelib, simple->offset, error);
 }
 
+/**
+ * g_typelib_get_dir_entry:
+ * @typelib: TODO
+ * @index: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 DirEntry *
 g_typelib_get_dir_entry (GITypelib *typelib,
 			  guint16    index)
@@ -159,6 +168,15 @@ get_section_by_id (GITypelib   *typelib,
   return NULL;
 }
 
+/**
+ * g_typelib_get_dir_entry_by_name:
+ * @typelib: TODO
+ * @name: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 DirEntry *
 g_typelib_get_dir_entry_by_name (GITypelib *typelib,
 				 const char *name)
@@ -196,6 +214,15 @@ g_typelib_get_dir_entry_by_name (GITypelib *typelib,
     }
 }
 
+/**
+ * g_typelib_get_dir_entry_by_gtype_name:
+ * @typelib: TODO
+ * @gtype_name: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 DirEntry *
 g_typelib_get_dir_entry_by_gtype_name (GITypelib *typelib,
 				       const gchar *gtype_name)
@@ -281,6 +308,15 @@ strsplit_iter_clear (StrSplitIter  *iter)
   g_free (iter->buf.str);
 }
 
+/**
+ * g_typelib_matches_gtype_name_prefix:
+ * @typelib: TODO
+ * @gtype_name: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 gboolean
 g_typelib_matches_gtype_name_prefix (GITypelib *typelib,
 				     const gchar *gtype_name)
@@ -326,6 +362,15 @@ g_typelib_matches_gtype_name_prefix (GITypelib *typelib,
   return ret;
 }
 
+/**
+ * g_typelib_get_dir_entry_by_error_domain:
+ * @typelib: TODO
+ * @error_domain: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 DirEntry *
 g_typelib_get_dir_entry_by_error_domain (GITypelib *typelib,
 					 GQuark     error_domain)
@@ -356,6 +401,11 @@ g_typelib_get_dir_entry_by_error_domain (GITypelib *typelib,
   return NULL;
 }
 
+/**
+ * g_typelib_check_sanity:
+ *
+ * TODO
+ */
 void
 g_typelib_check_sanity (void)
 {
@@ -2089,6 +2139,15 @@ prefix_with_context (GError **error,
   g_free (buf);
 }
 
+/**
+ * g_typelib_validate:
+ * @typelib: TODO
+ * @error: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 gboolean
 g_typelib_validate (GITypelib     *typelib,
 		     GError       **error)
@@ -2118,6 +2177,13 @@ g_typelib_validate (GITypelib     *typelib,
   return TRUE;
 }
 
+/**
+ * g_typelib_error_quark:
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 GQuark
 g_typelib_error_quark (void)
 {
@@ -2271,8 +2337,8 @@ _g_typelib_ensure_open (GITypelib *typelib)
  * pointed to by @typelib will be automatically g_free()d when the
  * repository is destroyed.
  *
- * Return value: the new #GITypelib
- **/
+ * Returns: the new #GITypelib
+ */
 GITypelib *
 g_typelib_new_from_memory (guint8  *memory, 
 			   gsize    len,
@@ -2300,8 +2366,8 @@ g_typelib_new_from_memory (guint8  *memory,
  *
  * Creates a new #GITypelib from a memory location.
  *
- * Return value: the new #GITypelib
- **/
+ * Returns: the new #GITypelib
+ */
 GITypelib *
 g_typelib_new_from_const_memory (const guchar *memory, 
 				 gsize         len,
@@ -2328,8 +2394,8 @@ g_typelib_new_from_const_memory (const guchar *memory,
  *
  * Creates a new #GITypelib from a #GMappedFile.
  *
- * Return value: the new #GITypelib
- **/
+ * Returns: the new #GITypelib
+ */
 GITypelib *
 g_typelib_new_from_mapped_file (GMappedFile  *mfile,
 				GError      **error)
@@ -2355,7 +2421,7 @@ g_typelib_new_from_mapped_file (GMappedFile  *mfile,
  * @typelib: a #GITypelib
  *
  * Free a #GITypelib.
- **/
+ */
 void
 g_typelib_free (GITypelib *typelib)
 {
@@ -2372,6 +2438,14 @@ g_typelib_free (GITypelib *typelib)
   g_slice_free (GITypelib, typelib);
 }
 
+/**
+ * g_typelib_get_namespace:
+ * @typelib: TODO
+ *
+ * TODO
+ *
+ * Returns: TODO
+ */
 const gchar *
 g_typelib_get_namespace (GITypelib *typelib)
 {
@@ -2386,8 +2460,8 @@ g_typelib_get_namespace (GITypelib *typelib)
  *
  * Loads a symbol from #GITypelib.
  *
- * Return value: #TRUE on success
- **/
+ * Returns: #TRUE on success
+ */
 gboolean
 g_typelib_symbol (GITypelib *typelib, const char *symbol_name, gpointer *symbol)
 {
diff --git a/girepository/gitypelib.h b/girepository/gitypelib.h
index 52c5c400..0726bf19 100644
--- a/girepository/gitypelib.h
+++ b/girepository/gitypelib.h
@@ -31,6 +31,19 @@
 
 G_BEGIN_DECLS
 
+/**
+ * SECTION:gitypelib
+ * @title: gitypelib
+ * @short_description: TODO
+ *
+ * TODO
+ */
+
+/**
+ * GITypelib:
+ *
+ * TODO
+ */
 typedef struct _GITypelib GITypelib;
 
 GITypelib *    g_typelib_new_from_memory       (guint8        *memory,
diff --git a/girepository/gitypes.h b/girepository/gitypes.h
index 660a98f9..cb8cb344 100644
--- a/girepository/gitypes.h
+++ b/girepository/gitypes.h
@@ -29,7 +29,9 @@
 
 G_BEGIN_DECLS
 
+#ifndef __GTK_DOC_IGNORE__
 typedef struct _GIBaseInfoStub GIBaseInfo;
+#endif
 
 /**
  * GICallableInfo:
@@ -47,6 +49,25 @@ typedef GIBaseInfo GICallableInfo;
 typedef GIBaseInfo GIFunctionInfo;
 
 /**
+ * SECTION:gicallbackinfo
+ * @title: GICallbackInfo
+ * @short_description: Struct representing a callback
+ *
+ * GICallbackInfo represents a callback.
+ *
+ * <refsect1 id="gi-gicallbackinfo.struct-hierarchy" role="struct_hierarchy">
+ * <title role="struct_hierarchy.title">Struct hierarchy</title>
+ * <synopsis>
+ *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
+ *          +----GIFunctionInfo
+ *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
+ *          +----<link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
+ * </synopsis>
+ * </refsect1>
+ */
+
+/**
  * GICallbackInfo:
  *
  * Represents a callback, eg arguments and return value.
@@ -103,6 +124,22 @@ typedef GIBaseInfo GIInterfaceInfo;
 typedef GIBaseInfo GIConstantInfo;
 
 /**
+ * SECTION:givalueinfo
+ * @title: GIValueInfo
+ * @short_description: Struct representing a value
+ *
+ * GIValueInfo represents a value.
+ *
+ * <refsect1 id="gi-givalueinfo.struct-hierarchy" role="struct_hierarchy">
+ * <title role="struct_hierarchy.title">Struct hierarchy</title>
+ * <synopsis>
+ *   <link linkend="gi-GIBaseInfo">GIBaseInfo</link>
+ *    +----GIValueInfo
+ * </synopsis>
+ * </refsect1>
+ */
+
+/**
  * GIValueInfo:
  *
  * Represents a enum value of a #GIEnumInfo.
@@ -158,12 +195,7 @@ typedef GIBaseInfo GITypeInfo;
  */
 typedef struct _GIUnresolvedInfo GIUnresolvedInfo;
 
-/**
- * GIArgument:
- *
- * Stores an argument of varying type
- */
-typedef union
+union _GIArgument
 {
   gboolean v_boolean;
   gint8    v_int8;
@@ -186,7 +218,35 @@ typedef union
   gsize    v_size;
   gchar *  v_string;
   gpointer v_pointer;
-} GIArgument;
+};
+
+/**
+ * GIArgument:
+ * @v_boolean: TODO
+ * @v_int8: TODO
+ * @v_uint8: TODO
+ * @v_int16: TODO
+ * @v_uint16: TODO
+ * @v_int32: TODO
+ * @v_uint32: TODO
+ * @v_int64: TODO
+ * @v_uint64: TODO
+ * @v_float: TODO
+ * @v_double: TODO
+ * @v_short: TODO
+ * @v_ushort: TODO
+ * @v_int: TODO
+ * @v_uint: TODO
+ * @v_long: TODO
+ * @v_ulong: TODO
+ * @v_ssize: TODO
+ * @v_size: TODO
+ * @v_string: TODO
+ * @v_pointer: TODO
+ *
+ * Stores an argument of varying type
+ */
+typedef union _GIArgument GIArgument;
 
 /**
  * GIInfoType:
@@ -200,6 +260,7 @@ typedef union
  * @GI_INFO_TYPE_OBJECT: object, see #GIObjectInfo
  * @GI_INFO_TYPE_INTERFACE: interface, see #GIInterfaceInfo
  * @GI_INFO_TYPE_CONSTANT: contant, see #GIConstantInfo
+ * @GI_INFO_TYPE_INVALID_0: deleted, used to be GI_INFO_TYPE_ERROR_DOMAIN.
  * @GI_INFO_TYPE_UNION: union, see #GIUnionInfo
  * @GI_INFO_TYPE_VALUE: enum value, see #GIValueInfo
  * @GI_INFO_TYPE_SIGNAL: signal, see #GISignalInfo
@@ -209,7 +270,7 @@ typedef union
  * @GI_INFO_TYPE_ARG: argument of a function or callback, see #GIArgInfo
  * @GI_INFO_TYPE_TYPE: type information, see #GITypeInfo
  * @GI_INFO_TYPE_UNRESOLVED: unresolved type, a type which is not present in
- * the typelib, or any of its dependencies.
+ *   the typelib, or any of its dependencies.
  *
  * The type of a GIBaseInfo struct.
  */
@@ -225,7 +286,7 @@ typedef enum
   GI_INFO_TYPE_OBJECT,
   GI_INFO_TYPE_INTERFACE,
   GI_INFO_TYPE_CONSTANT,
-  GI_INFO_TYPE_INVALID_0,    /* 10 */  /* DELETED - used to be ERROR_DOMAIN */
+  GI_INFO_TYPE_INVALID_0,    /* 10 */
   GI_INFO_TYPE_UNION,
   GI_INFO_TYPE_VALUE,
   GI_INFO_TYPE_SIGNAL,
@@ -319,17 +380,17 @@ typedef enum {
  * @GI_TYPE_TAG_UINT64: 64-bit unsigned integer
  * @GI_TYPE_TAG_FLOAT: float
  * @GI_TYPE_TAG_DOUBLE: double floating point
- * @GI_TYPE_TAG_UNICHAR: Unicode character
  * @GI_TYPE_TAG_GTYPE: a #GType
  * @GI_TYPE_TAG_UTF8: a UTF-8 encoded string
  * @GI_TYPE_TAG_FILENAME: a filename, encoded in the same encoding
- * as the native filesystem is using.
+ *   as the native filesystem is using.
  * @GI_TYPE_TAG_ARRAY: an array
  * @GI_TYPE_TAG_INTERFACE: an extended interface object
  * @GI_TYPE_TAG_GLIST: a #GList
  * @GI_TYPE_TAG_GSLIST: a #GSList
  * @GI_TYPE_TAG_GHASH: a #GHashTable
  * @GI_TYPE_TAG_ERROR: a #GError
+ * @GI_TYPE_TAG_UNICHAR: Unicode character
  *
  * The type tag of a #GITypeInfo.
  */
@@ -359,12 +420,17 @@ typedef enum {
   GI_TYPE_TAG_ERROR     = 20,
   /* Another basic type */
   GI_TYPE_TAG_UNICHAR   = 21
-  /* Note - there is only room currently for 32 tags.
-   * See docs/typelib-format.txt SimpleTypeBlob definition */
+  /* Note - there is currently only room for 32 tags */
 } GITypeTag;
 
+/**
+ * GI_TYPE_TAG_N_TYPES:
+ *
+ * TODO
+ */
 #define GI_TYPE_TAG_N_TYPES (GI_TYPE_TAG_UNICHAR+1)
 
+#ifndef __GTK_DOC_IGNORE__
 /* These were removed and no longer appear in the typelib;
  * instead, the machine-specific versions like INT32 are
  * always used.
@@ -372,6 +438,7 @@ typedef enum {
 #define GI_TYPE_TAG_SHORT GI_TYPE_TAG_SHORT_WAS_REMOVED
 #define GI_TYPE_TAG_INT   GI_TYPE_TAG_INT_WAS_REMOVED
 #define GI_TYPE_TAG_LONG  GI_TYPE_TAG_LONG_WAS_REMOVED
+#endif
 
 /**
  * GIArrayType:
@@ -442,10 +509,12 @@ typedef enum
 } GIFunctionInfoFlags;
 
 #ifndef __GI_SCANNER__
+#ifndef __GTK_DOC_IGNORE__
 /* backwards compatibility */
 typedef GIArgument GArgument;
 typedef struct _GITypelib GTypelib;
 #endif
+#endif
 
 G_END_DECLS
 
diff --git a/girepository/giunioninfo.c b/girepository/giunioninfo.c
index 95b71123..8ae1e915 100644
--- a/girepository/giunioninfo.c
+++ b/girepository/giunioninfo.c
@@ -28,8 +28,8 @@
 
 /**
  * SECTION:giunioninfo
- * @Short_description: Struct representing a union.
- * @Title: GIUnionInfo
+ * @title: GIUnionInfo
+ * @short_description: Struct representing a union.
  *
  * GIUnionInfo represents a union type.
  *
@@ -147,7 +147,7 @@ g_union_info_is_discriminated (GIUnionInfo *info)
 }
 
 /**
- * g_union_info_get_discrimintor_offset:
+ * g_union_info_get_discriminator_offset:
  * @info: a #GIUnionInfo
  *
  * Returns offset of the discriminator field in the structure.
diff --git a/girepository/giunioninfo.h b/girepository/giunioninfo.h
index 83696f76..5359346a 100644
--- a/girepository/giunioninfo.h
+++ b/girepository/giunioninfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_UNION_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIUnionInfo.
+ */
 #define GI_IS_UNION_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_UNION)
 
diff --git a/girepository/givfuncinfo.c b/girepository/givfuncinfo.c
index 9d6ea39d..eaf523d2 100644
--- a/girepository/givfuncinfo.c
+++ b/girepository/givfuncinfo.c
@@ -30,8 +30,8 @@
 
 /**
  * SECTION:givfuncinfo
- * @Short_description: Struct representing a virtual function
- * @Title: GIVFuncInfo
+ * @title: GIVFuncInfo
+ * @short_description: Struct representing a virtual function
  *
  * GIVfuncInfo represents a virtual function. A property belongs to
  * either a #GIObjectInfo or a #GIInterfaceInfo.
diff --git a/girepository/givfuncinfo.h b/girepository/givfuncinfo.h
index d8a8533b..f22517a6 100644
--- a/girepository/givfuncinfo.h
+++ b/girepository/givfuncinfo.h
@@ -31,6 +31,12 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GI_IS_VFUNC_INFO
+ * @info: an info structure
+ *
+ * Checks if @info is a #GIVfuncInfo.
+ */
 #define GI_IS_VFUNC_INFO(info) \
     (g_base_info_get_type((GIBaseInfo*)info) ==  GI_INFO_TYPE_VFUNC)