18 files changed, 117 insertions, 246 deletions
diff --git a/girepository/giarginfo.c b/girepository/giarginfo.c
index 381c3839..96afccb6 100644
--- a/girepository/giarginfo.c
+++ b/girepository/giarginfo.c
@@ -35,16 +35,9 @@
  * @title: GIArgInfo
  * @short_description: Struct representing an argument
  *
- * GIArgInfo represents an argument. An argument is always
- * part of a #GICallableInfo.
+ * GIArgInfo represents an argument of a callable.
  *
- * <refsect1 id="gi-giarginfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----GIArgInfo
- * </synopsis>
- * </refsect1>
+ * An argument is always part of a #GICallableInfo.
  */
 
 /**
diff --git a/girepository/gibaseinfo.c b/girepository/gibaseinfo.c
index e47d5390..d7a3a017 100644
--- a/girepository/gibaseinfo.c
+++ b/girepository/gibaseinfo.c
@@ -185,43 +185,45 @@ _g_type_info_init (GIBaseInfo *info,
  * @title: GIBaseInfo
  * @short_description: Base struct for all GITypelib structs
  *
- * GIBaseInfo is the common base struct of all other *Info structs
+ * GIBaseInfo is the common base struct of all other Info structs
  * accessible through the #GIRepository API.
- * All other structs can be casted to a #GIBaseInfo, for instance:
- * <example>
- * <title>Casting a #GIFunctionInfo to #GIBaseInfo</title>
- * <programlisting>
+ *
+ * All info structures can be cast to a #GIBaseInfo, for instance:
+ *
+ * |[<!-- language="C" -->
  *    GIFunctionInfo *function_info = ...;
- *    GIBaseInfo *info = (GIBaseInfo*)function_info;
- * </programlisting>
- * </example>
- * Most #GIRepository APIs returning a #GIBaseInfo is actually creating a new struct, in other
- * words, g_base_info_unref() has to be called when done accessing the data.
- * GIBaseInfos are normally accessed by calling either
- * g_irepository_find_by_name(), g_irepository_find_by_gtype() or g_irepository_get_info().
- *
- * <example>
- * <title>Getting the Button of the Gtk typelib</title>
- * <programlisting>
- *    GIBaseInfo *button_info = g_irepository_find_by_name(NULL, "Gtk", "Button");
- *    ... use button_info ...
- *    g_base_info_unref(button_info);
- * </programlisting>
- * </example>
- *
- * <refsect1 id="gi-gibaseinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
+ *    GIBaseInfo *info = (GIBaseInfo *) function_info;
+ * ]|
+ *
+ * Most #GIRepository APIs returning a #GIBaseInfo is actually
+ * creating a new struct; in other words, g_base_info_unref() has to
+ * be called when done accessing the data.
+ *
+ * #GIBaseInfo structuress are normally accessed by calling either
+ * g_irepository_find_by_name(), g_irepository_find_by_gtype() or
+ * g_irepository_get_info().
+ *
+ * |[<!-- language="C" -->
+ * GIBaseInfo *button_info =
+ *   g_irepository_find_by_name (NULL, "Gtk", "Button");
+ *
+ * // ... use button_info ...
+ *
+ * g_base_info_unref (button_info);
+ * ]|
+ *
+ * ## Hierarchy
+ *
+ * |[<!-- language="plain" -->
  *   GIBaseInfo
- *    +----<link linkend="gi-GIArgInfo">GIArgInfo</link>
- *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
- *    +----<link linkend="gi-GIConstantInfo">GIConstantInfo</link>
- *    +----<link linkend="gi-GIFieldInfo">GIFieldInfo</link>
- *    +----<link linkend="gi-GIPropertyInfo">GIPropertyInfo</link>
- *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
- *    +----<link linkend="gi-GITypeInfo">GITypeInfo</link>
- * </synopsis>
- * </refsect1>
+ *    +---- GIArgInfo
+ *    +---- GICallableInfo
+ *    +---- GIConstantInfo
+ *    +---- GIFieldInfo
+ *    +---- GIPropertyInfo
+ *    +---- GIRegisteredTypeInfo
+ *    +---- GITypeInfo
+ * ]|
  */
 
 /**
@@ -573,9 +575,7 @@ _attribute_blob_find_first (GIBaseInfo *info,
  * Both the @name and @value should be treated as constants
  * and must not be freed.
  *
- * <example>
- * <title>Iterating over attributes</title>
- * <programlisting>
+ * |[<!-- language="C" -->
  * void
  * print_attributes (GIBaseInfo *info)
  * {
@@ -587,8 +587,7 @@ _attribute_blob_find_first (GIBaseInfo *info,
  *       g_print ("attribute name: %s value: %s", name, value);
  *     }
  * }
- * </programlisting>
- * </example>
+ * ]|
  *
  * Returns: %TRUE if there are more attributes
  */
diff --git a/girepository/gicallableinfo.c b/girepository/gicallableinfo.c
index e224ea6f..790c3d6a 100644
--- a/girepository/gicallableinfo.c
+++ b/girepository/gicallableinfo.c
@@ -39,22 +39,15 @@
  * @short_description: Struct representing a callable
  *
  * GICallableInfo represents an entity which is callable.
- * Currently a function (#GIFunctionInfo), virtual function,
- * (#GIVFuncInfo) or callback (#GICallbackInfo).
+ *
+ * Examples of callable are:
+ *
+ *  - functions (#GIFunctionInfo)
+ *  - virtual functions (#GIVFuncInfo)
+ *  - callbacks (#GICallbackInfo).
  *
  * A callable has a list of arguments (#GIArgInfo), a return type,
  * direction and a flag which decides if it returns null.
- *
- * <refsect1 id="gi-gicallableinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----GICallableInfo
- *          +----<link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
- *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
- *          +----<link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
- * </synopsis>
- * </refsect1>
  */
 
 static guint32
@@ -479,14 +472,16 @@ g_callable_info_iterate_return_attributes (GICallableInfo  *info,
  * @return_tag: #GITypeTag of the return value
  * @interface_type: #GIInfoType of the underlying interface type
  * @ffi_value: pointer to #GIFFIReturnValue union containing the return value
- *   from ffi_call()
+ *   from `ffi_call()`
  * @arg: (out caller-allocates): pointer to an allocated #GIArgument
  *
- * Extract the correct bits from an ffi_arg return value into
- * GIArgument: https://bugzilla.gnome.org/show_bug.cgi?id=665152
+ * Extract the correct bits from an `ffi_arg` return value into
+ * GIArgument.
  *
- * Also see <citerefentry><refentrytitle>ffi_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- *  - the storage requirements for return values are "special".
+ * See: https://bugzilla.gnome.org/show_bug.cgi?id=665152
+ *
+ * Also see `ffi_call(3)`: the storage requirements for return values
+ * are "special".
  *
  * The @interface_type argument only applies if @return_tag is
  * %GI_TYPE_TAG_INTERFACE. Otherwise it is ignored.
@@ -553,14 +548,16 @@ gi_type_tag_extract_ffi_return_value (GITypeTag         return_tag,
  * gi_type_info_extract_ffi_return_value:
  * @return_info: #GITypeInfo describing the return type
  * @ffi_value: pointer to #GIFFIReturnValue union containing the return value
- *   from ffi_call()
+ *   from `ffi_call()`
  * @arg: (out caller-allocates): pointer to an allocated #GIArgument
  *
- * Extract the correct bits from an ffi_arg return value into
- * GIArgument: https://bugzilla.gnome.org/show_bug.cgi?id=665152
+ * Extract the correct bits from an `ffi_arg` return value into
+ * #GIArgument.
+ *
+ * See: https://bugzilla.gnome.org/show_bug.cgi?id=665152
  *
- * Also see <citerefentry><refentrytitle>ffi_call</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- *  - the storage requirements for return values are "special".
+ * Also see `ffi_call(3)`: the storage requirements for return values
+ * are "special".
  */
 void
 gi_type_info_extract_ffi_return_value (GITypeInfo                  *return_info,
diff --git a/girepository/giconstantinfo.c b/girepository/giconstantinfo.c
index a9d4cbc0..148d66b6 100644
--- a/girepository/giconstantinfo.c
+++ b/girepository/giconstantinfo.c
@@ -34,17 +34,11 @@
  * @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,
- * which can be obtained by calling g_constant_info_get_value().
+ * GIConstantInfo represents a constant.
  *
- * <refsect1 id="gi-giconstantinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----GIConstantInfo
- * </synopsis>
- * </refsect1>
+ * A constant has a type associated which can be obtained by calling
+ * g_constant_info_get_type() and a value, which can be obtained by
+ * calling g_constant_info_get_value().
  */
 
 
diff --git a/girepository/gienuminfo.c b/girepository/gienuminfo.c
index 2dc4b167..c41d0308 100644
--- a/girepository/gienuminfo.c
+++ b/girepository/gienuminfo.c
@@ -33,18 +33,13 @@
  * @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
- * The GIValueInfo is fetched by calling g_enum_info_get_value() on a #GIEnumInfo.
- *
- * <refsect1 id="gi-gienuminfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
- *          +----GIEnumInfo
- * </synopsis>
- * </refsect1>
+ * A GIEnumInfo represents an enumeration, and a GIValueInfo represents
+ * a value in the enumeration.
+ *
+ * The GIEnumInfo contains a set of values and a type.
+ *
+ * The GIValueInfo is fetched by calling g_enum_info_get_value() on
+ * a GIEnumInfo.
  */
 
 /**
@@ -235,4 +230,3 @@ g_value_info_get_value (GIValueInfo *info)
   else
     return (gint64)blob->value;
 }
-
diff --git a/girepository/gifieldinfo.c b/girepository/gifieldinfo.c
index 0a20bdb2..5bc19899 100644
--- a/girepository/gifieldinfo.c
+++ b/girepository/gifieldinfo.c
@@ -34,20 +34,15 @@
  * @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_field().
+ * A GIFieldInfo struct represents a field of a struct, union, or object.
+ *
+ * The GIFieldInfo is fetched by calling g_struct_info_get_field(),
+ * g_union_info_get_field() 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.
+ * which are currently #GI_FIELD_IS_READABLE or #GI_FIELD_IS_WRITABLE.
  *
- * <refsect1 id="gi-gifieldinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----GIFieldInfo
- * </synopsis>
- * </refsect1>
+ * See also: #GIStructInfo, #GIUnionInfo, #GIObjectInfo
  */
 
 /**
diff --git a/girepository/gifunctioninfo.c b/girepository/gifunctioninfo.c
index b042b4e1..ea6842d5 100644
--- a/girepository/gifunctioninfo.c
+++ b/girepository/gifunctioninfo.c
@@ -36,22 +36,12 @@
  * @short_description: Struct representing a function
  *
  * GIFunctionInfo represents a function, method or constructor.
+ *
  * To find out what kind of entity a #GIFunctionInfo represents, call
  * g_function_info_get_flags().
  *
  * See also #GICallableInfo for information on how to retreive arguments and
  * other metadata.
- *
- * <refsect1 id="gi-gifunctioninfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
- *          +----GIFunctionInfo
- *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
- *          +----<link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
- * </synopsis>
- * </refsect1>
  */
 
 GIFunctionInfo *
diff --git a/girepository/giinterfaceinfo.c b/girepository/giinterfaceinfo.c
index 203113b6..f0d1d7af 100644
--- a/girepository/giinterfaceinfo.c
+++ b/girepository/giinterfaceinfo.c
@@ -37,15 +37,6 @@
  *
  * A GInterface has methods, fields, properties, signals, interfaces, constants,
  * virtual functions and prerequisites.
- *
- * <refsect1 id="gi-giinterfaceinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
- *          +----GIInterfaceInfo
- * </synopsis>
- * </refsect1>
  */
 
 /**
diff --git a/girepository/giobjectinfo.c b/girepository/giobjectinfo.c
index 2042793a..82199b84 100644
--- a/girepository/giobjectinfo.c
+++ b/girepository/giobjectinfo.c
@@ -31,22 +31,18 @@
 /**
  * SECTION: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).
- *
- * A GObject has methods, fields, properties, signals, interfaces, constants
- * and virtual functions.
- *
- * <refsect1 id="gi-giobjectinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
- *          +----GIObjectInfo
- * </synopsis>
- * </refsect1>
+ * @short_description: Struct representing a classed type
+ *
+ * GIObjectInfo represents a classed type.
+ *
+ * Classed types in GType inherit from #GTypeInstance; the most common
+ * type is #GObject.
+ *
+ * A GIObjectInfo doesn't represent a specific instance of a classed type,
+ * instead this represent the object type (eg class).
+ *
+ * A GIObjectInfo has methods, fields, properties, signals, interfaces,
+ * constants and virtual functions.
  */
 
 /**
diff --git a/girepository/gipropertyinfo.c b/girepository/gipropertyinfo.c
index 4a291a06..77bb1339 100644
--- a/girepository/gipropertyinfo.c
+++ b/girepository/gipropertyinfo.c
@@ -33,16 +33,9 @@
  * @title: GIPropertyInfo
  * @short_description: Struct representing a property
  *
- * GIPropertyInfo represents a property. A property belongs to
- * either a #GIObjectInfo or a #GIInterfaceInfo.
- *
- * <refsect1 id="gi-gipropertyinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----GIPropertyInfo
- * </synopsis>
- * </refsect1>
+ * GIPropertyInfo represents a property in a #GObject.
+ *
+ * A property belongs to either a #GIObjectInfo or a #GIInterfaceInfo.
  */
 
 /**
diff --git a/girepository/giregisteredtypeinfo.c b/girepository/giregisteredtypeinfo.c
index 411b9b95..653befec 100644
--- a/girepository/giregisteredtypeinfo.c
+++ b/girepository/giregisteredtypeinfo.c
@@ -35,27 +35,16 @@
  * @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
- * #GIUnionInfo.
+ * GIRegisteredTypeInfo represents an entity with a GType associated.
+ *
+ * Could be either a #GIEnumInfo, #GIInterfaceInfo, #GIObjectInfo,
+ * #GIStructInfo or a #GIUnionInfo.
  *
  * A registered type info struct has a name and a type function.
+ *
  * To get the name call g_registered_type_info_get_type_name().
  * Most users want to call g_registered_type_info_get_g_type() and don't worry
  * about the rest of the details.
- *
- * <refsect1 id="gi-giregisteredtypeinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----GIRegisteredTypeInfo
- *          +----<link linkend="gi-GIEnumInfo">GIEnumInfo</link>
- *          +----<link linkend="gi-GIInterfaceInfo">GIInterfaceInfo</link>
- *          +----<link linkend="gi-GIObjectInfo">GIObjectInfo</link>
- *          +----<link linkend="gi-GIStructInfo">GIStructInfo</link>
- *          +----<link linkend="gi-GIUnionInfo">GIUnionInfo</link>
- * </synopsis>
- * </refsect1>
  */
 
 /**
diff --git a/girepository/girepository.c b/girepository/girepository.c
index d7f6ceb4..a0754f45 100644
--- a/girepository/girepository.c
+++ b/girepository/girepository.c
@@ -455,7 +455,7 @@ register_internal (GIRepository *repository,
  * @namespace_: Namespace of interest
  *
  * Return an array of the immediate versioned dependencies for @namespace_.
- * Returned strings are of the form <code>namespace-version</code>.
+ * Returned strings are of the form `namespace-version`.
  *
  * Note: @namespace_ must have already been loaded using a function
  * such as g_irepository_require() before calling this function.
@@ -537,9 +537,10 @@ get_typelib_dependencies_transitive (GIRepository *repository,
  *   process-global default #GIRepository
  * @namespace_: Namespace of interest
  *
- * Return an array of all (transitive) versioned dependencies for
- * @namespace_. Returned strings are of the form
- * <code>namespace-version</code>.
+ * Retrieves all (transitive) versioned dependencies for
+ * @namespace_.
+ *
+ * The strings are of the form `namespace-version`.
  *
  * Note: @namespace_ must have already been loaded using a function
  * such as g_irepository_require() before calling this function.
@@ -547,7 +548,7 @@ get_typelib_dependencies_transitive (GIRepository *repository,
  * To get only the immediate dependencies for @namespace_, use
  * g_irepository_get_immediate_dependencies().
  *
- * Returns: (transfer full): Zero-terminated string array of all versioned
+ * Returns: (transfer full) (array zero-terminated=1): all versioned
  *   dependencies
  */
 char **
diff --git a/girepository/gisignalinfo.c b/girepository/gisignalinfo.c
index 5f8fa880..9d5abec5 100644
--- a/girepository/gisignalinfo.c
+++ b/girepository/gisignalinfo.c
@@ -33,22 +33,13 @@
  * @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.
+ * GISignalInfo represents a signal.
+ *
+ * It's a sub-struct of #GICallableInfo and contains a set of flags and
+ * a class closure.
  *
  * See #GICallableInfo for information on how to retreive arguments
  * and other metadata from the signal.
- *
- * <refsect1 id="gi-gisignalinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
- *          +----<link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
- *          +----GISignalInfo
- *          +----<link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
- * </synopsis>
- * </refsect1>
  */
 
 /**
diff --git a/girepository/gistructinfo.c b/girepository/gistructinfo.c
index a1edfa9f..a9ad73f6 100644
--- a/girepository/gistructinfo.c
+++ b/girepository/gistructinfo.c
@@ -38,15 +38,6 @@
  * GIStructInfo represents a generic C structure type.
  *
  * A structure has methods and fields.
- *
- * <refsect1 id="gi-giobjectinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
- *          +----GIStructInfo
- * </synopsis>
- * </refsect1>
  */
 
 /**
diff --git a/girepository/gitypeinfo.c b/girepository/gitypeinfo.c
index 4fb7dddd..bdcc1c65 100644
--- a/girepository/gitypeinfo.c
+++ b/girepository/gitypeinfo.c
@@ -33,23 +33,17 @@
  * @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),
- * a field (see #GIFieldInfo), a property (see #GIPropertyInfo), a constant
+ * GITypeInfo represents a type.
+ *
+ * You can retrieve a type info from an argument (see #GIArgInfo), a
+ * functions return value (see #GIFunctionInfo), a field (see
+ * #GIFieldInfo), a property (see #GIPropertyInfo), a constant
  * (see #GIConstantInfo) or for a union discriminator (see #GIUnionInfo).
  *
  * A type can either be a of a basic type which is a standard C primitive
  * type or an interface type. For interface types you need to call
  * g_type_info_get_interface() to get a reference to the base info for that
  * interface.
- *
- * <refsect1 id="gi-gitypeinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----GITypeInfo
- * </synopsis>
- * </refsect1>
  */
 
 /**
diff --git a/girepository/gitypes.h b/girepository/gitypes.h
index 69270720..47b5a3ea 100644
--- a/girepository/gitypes.h
+++ b/girepository/gitypes.h
@@ -64,17 +64,6 @@ typedef GIBaseInfo GIFunctionInfo;
  * @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="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
- *          +----GIFunctionInfo
- *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
- *          +----<link linkend="gi-GIVFuncInfo">GIVFuncInfo</link>
- * </synopsis>
- * </refsect1>
  */
 
 /**
@@ -139,14 +128,6 @@ typedef GIBaseInfo GIConstantInfo;
  * @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="GIBaseInfo">GIBaseInfo</link>
- *    +----GIValueInfo
- * </synopsis>
- * </refsect1>
  */
 
 /**
diff --git a/girepository/giunioninfo.c b/girepository/giunioninfo.c
index 7bc81aa0..0089f11c 100644
--- a/girepository/giunioninfo.c
+++ b/girepository/giunioninfo.c
@@ -38,15 +38,6 @@
  * A union has methods and fields.  Unions can optionally have a
  * discriminator, which is a field deciding what type of real union
  * fields is valid for specified instance.
- *
- * <refsect1 id="gi-giobjectinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GIRegisteredTypeInfo">GIRegisteredTypeInfo</link>
- *          +----GIUnionInfo
- * </synopsis>
- * </refsect1>
  */
 
 /**
diff --git a/girepository/givfuncinfo.c b/girepository/givfuncinfo.c
index 13ab654d..5c3997c5 100644
--- a/girepository/givfuncinfo.c
+++ b/girepository/givfuncinfo.c
@@ -35,19 +35,10 @@
  * @title: GIVFuncInfo
  * @short_description: Struct representing a virtual function
  *
- * GIVfuncInfo represents a virtual function. A property belongs to
- * either a #GIObjectInfo or a #GIInterfaceInfo.
+ * GIVfuncInfo represents a virtual function.
  *
- * <refsect1 id="gi-givfuncinfo.struct-hierarchy" role="struct_hierarchy">
- * <title role="struct_hierarchy.title">Struct hierarchy</title>
- * <synopsis>
- *   <link linkend="GIBaseInfo">GIBaseInfo</link>
- *    +----<link linkend="gi-GICallableInfo">GICallableInfo</link>
- *          +----<link linkend="gi-GIFunctionInfo">GIFunctionInfo</link>
- *          +----<link linkend="gi-GISignalInfo">GISignalInfo</link>
- *          +----GIVFuncInfo
- * </synopsis>
- * </refsect1>
+ * A virtual function is a callable object that belongs to either a
+ * #GIObjectInfo or a #GIInterfaceInfo.
  */
 
 GIVFuncInfo *