[glib] docs: GType documentation cleanup

[Matthias Clasen <matthiasc src gnome org>]

commit adfaf0e456eceaf531d12d667afef8fce85103c1
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat May 31 20:55:00 2014 -0400

    docs: GType documentation cleanup
    
    Still some markup left.

 gobject/gtype.c |    3 +-
 gobject/gtype.h |  325 +++++++++++++++++++++++++++----------------------------
 2 files changed, 160 insertions(+), 168 deletions(-)
---
diff --git a/gobject/gtype.c b/gobject/gtype.c
index 371a0f2..2afec19 100644
--- a/gobject/gtype.c
+++ b/gobject/gtype.c
@@ -4463,8 +4463,7 @@ gobject_init_ctor (void)
  *   my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object,
  *                                                  MY_TYPE_OBJECT,
  *                                                  MyObjectPrivate);
- *   /<!-- -->* my_object->priv->some_field will be
- *    * automatically initialised to 0 *<!-- -->/
+ *   // my_object->priv->some_field will be automatically initialised to 0
  * }
  *
  * static int
diff --git a/gobject/gtype.h b/gobject/gtype.h
index a8b840d..c604d53 100644
--- a/gobject/gtype.h
+++ b/gobject/gtype.h
@@ -256,27 +256,27 @@ G_BEGIN_DECLS
  */
 /**
  * G_TYPE_IS_FUNDAMENTAL:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is a fundamental type.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_FUNDAMENTAL(type)             ((type) <= G_TYPE_FUNDAMENTAL_MAX)
 /**
  * G_TYPE_IS_DERIVED:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is derived (or in object-oriented terminology:
  * inherited) from another type (this holds true for all non-fundamental
  * types).
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_DERIVED(type)                 ((type) > G_TYPE_FUNDAMENTAL_MAX)
 /**
  * G_TYPE_IS_INTERFACE:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is an interface type.
  * An interface type provides a pure API, the implementation
@@ -286,86 +286,86 @@ G_BEGIN_DECLS
  * with the difference that GType interfaces are not derivable (but see
  * g_type_interface_add_prerequisite() for an alternative).
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_INTERFACE(type)               (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
 /**
  * G_TYPE_IS_CLASSED:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is a classed type.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_CLASSED(type)                 (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
 /**
  * G_TYPE_IS_INSTANTIATABLE:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type can be instantiated.  Instantiation is the
  * process of creating an instance (object) of this type.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_INSTANTIATABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
 /**
  * G_TYPE_IS_DERIVABLE:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is a derivable type.  A derivable type can
  * be used as the base class of a flat (single-level) class hierarchy.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_DERIVABLE(type)               (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
 /**
  * G_TYPE_IS_DEEP_DERIVABLE:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is a deep derivable type.  A deep derivable type
  * can be used as the base class of a deep (multi-level) class hierarchy.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_DEEP_DERIVABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
 /**
  * G_TYPE_IS_ABSTRACT:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is an abstract type.  An abstract type cannot be
  * instantiated and is normally used as an abstract base class for
  * derived classes.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_ABSTRACT(type)                (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
 /**
  * G_TYPE_IS_VALUE_ABSTRACT:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is an abstract value type.  An abstract value type introduces
  * a value table, but can't be used for g_value_init() and is normally used as
  * an abstract base type for derived value types.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_VALUE_ABSTRACT(type)          (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
 /**
  * G_TYPE_IS_VALUE_TYPE:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type is a value type and can be used with g_value_init(). 
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_IS_VALUE_TYPE(type)              (g_type_check_is_value_type (type))
 /**
  * G_TYPE_HAS_VALUE_TABLE:
- * @type: A #GType value.
+ * @type: A #GType value
  * 
  * Checks if @type has a #GTypeValueTable.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_HAS_VALUE_TABLE(type)            (g_type_value_table_peek (type) != NULL)
 
@@ -431,13 +431,13 @@ struct _GTypeInterface
 };
 /**
  * GTypeQuery:
- * @type: the #GType value of the type.
- * @type_name: the name of the type.
- * @class_size: the size of the class structure.
- * @instance_size: the size of the instance structure.
+ * @type: the #GType value of the type
+ * @type_name: the name of the type
+ * @class_size: the size of the class structure
+ * @instance_size: the size of the instance structure
  * 
- * A structure holding information for a specific type. It is
- * filled in by the g_type_query() function.
+ * A structure holding information for a specific type.
+ * It is filled in by the g_type_query() function.
  */
 struct _GTypeQuery
 {
@@ -454,21 +454,21 @@ struct _GTypeQuery
 /*< protected >*/
 /**
  * G_TYPE_CHECK_INSTANCE:
- * @instance: Location of a #GTypeInstance structure.
+ * @instance: Location of a #GTypeInstance structure
  * 
  * Checks if @instance is a valid #GTypeInstance structure,
  * otherwise issues a warning and returns %FALSE.
  * 
  * This macro should only be used in type implementations.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_CHECK_INSTANCE(instance)                                (_G_TYPE_CHI ((GTypeInstance*) 
(instance)))
 /**
  * G_TYPE_CHECK_INSTANCE_CAST:
- * @instance: Location of a #GTypeInstance structure.
- * @g_type: The type to be returned.
- * @c_type: The corresponding C type of @g_type.
+ * @instance: Location of a #GTypeInstance structure
+ * @g_type: The type to be returned
+ * @c_type: The corresponding C type of @g_type
  * 
  * Checks that @instance is an instance of the type identified by @g_type
  * and issues a warning if this is not the case. Returns @instance casted 
@@ -486,7 +486,7 @@ struct _GTypeQuery
  * 
  * This macro should only be used in type implementations.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type)            (_G_TYPE_CIT ((instance), (g_type)))
 /**
@@ -498,20 +498,20 @@ struct _GTypeQuery
  *
  * This macro should only be used in type implementations.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE(instance, g_type)            (_G_TYPE_CIFT ((instance), 
(g_type)))
 /**
  * G_TYPE_INSTANCE_GET_CLASS:
- * @instance: Location of the #GTypeInstance structure.
- * @g_type: The #GType of the class to be returned.
- * @c_type: The C type of the class structure.
+ * @instance: Location of the #GTypeInstance structure
+ * @g_type: The #GType of the class to be returned
+ * @c_type: The C type of the class structure
  * 
  * Get the class structure of a given @instance, casted
  * to a specified ancestor type @g_type of the instance.
  * 
- * Note that while calling a GInstanceInitFunc(), the class pointer gets
- * modified, so it might not always return the expected pointer.
+ * Note that while calling a GInstanceInitFunc(), the class pointer
+ * gets modified, so it might not always return the expected pointer.
  * 
  * This macro should only be used in type implementations.
  *
@@ -520,9 +520,9 @@ struct _GTypeQuery
 #define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type)     (_G_TYPE_IGC ((instance), (g_type), c_type))
 /**
  * G_TYPE_INSTANCE_GET_INTERFACE:
- * @instance: Location of the #GTypeInstance structure.
- * @g_type: The #GType of the interface to be returned.
- * @c_type: The C type of the interface structure.
+ * @instance: Location of the #GTypeInstance structure
+ * @g_type: The #GType of the interface to be returned
+ * @c_type: The C type of the interface structure
  * 
  * Get the interface structure for interface @g_type of a given @instance.
  * 
@@ -533,9 +533,9 @@ struct _GTypeQuery
 #define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
 /**
  * G_TYPE_CHECK_CLASS_CAST:
- * @g_class: Location of a #GTypeClass structure.
- * @g_type: The type to be returned.
- * @c_type: The corresponding C type of class structure of @g_type.
+ * @g_class: Location of a #GTypeClass structure
+ * @g_type: The type to be returned
+ * @c_type: The corresponding C type of class structure of @g_type
  * 
  * Checks that @g_class is a class structure of the type identified by @g_type
  * and issues a warning if this is not the case. Returns @g_class casted 
@@ -546,15 +546,15 @@ struct _GTypeQuery
 #define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type)        (_G_TYPE_CCC ((g_class), (g_type), c_type))
 /**
  * G_TYPE_CHECK_CLASS_TYPE:
- * @g_class: Location of a #GTypeClass structure.
- * @g_type: The type to be checked.
+ * @g_class: Location of a #GTypeClass structure
+ * @g_type: The type to be checked
  * 
  * Checks if @g_class is a class structure of the type identified by 
  * @g_type.
  * 
  * This macro should only be used in type implementations.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type)                (_G_TYPE_CCT ((g_class), (g_type)))
 /**
@@ -566,25 +566,25 @@ struct _GTypeQuery
  * 
  * This macro should only be used in type implementations.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_CHECK_VALUE(value)                              (_G_TYPE_CHV ((value)))
 /**
  * G_TYPE_CHECK_VALUE_TYPE:
  * @value: a #GValue
- * @g_type: The type to be checked.
+ * @g_type: The type to be checked
  * 
  * Checks if @value has been initialized to hold values
  * of type @g_type. 
  * 
  * This macro should only be used in type implementations.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  */
 #define G_TYPE_CHECK_VALUE_TYPE(value, g_type)                 (_G_TYPE_CVH ((value), (g_type)))
 /**
  * G_TYPE_FROM_INSTANCE:
- * @instance: Location of a valid #GTypeInstance structure.
+ * @instance: Location of a valid #GTypeInstance structure
  * 
  * Get the type identifier from a given @instance structure. 
  * 
@@ -595,7 +595,7 @@ struct _GTypeQuery
 #define G_TYPE_FROM_INSTANCE(instance)                          (G_TYPE_FROM_CLASS (((GTypeInstance*) 
(instance))->g_class))
 /**
  * G_TYPE_FROM_CLASS:
- * @g_class: Location of a valid #GTypeClass structure.
+ * @g_class: Location of a valid #GTypeClass structure
  * 
  * Get the type identifier from a given @class structure.
  * 
@@ -606,7 +606,7 @@ struct _GTypeQuery
 #define G_TYPE_FROM_CLASS(g_class)                              (((GTypeClass*) (g_class))->g_type)
 /**
  * G_TYPE_FROM_INTERFACE:
- * @g_iface: Location of a valid #GTypeInterface structure.
+ * @g_iface: Location of a valid #GTypeInterface structure
  * 
  * Get the type identifier from a given @interface structure.
  * 
@@ -618,9 +618,9 @@ struct _GTypeQuery
 
 /**
  * G_TYPE_INSTANCE_GET_PRIVATE:
- * @instance: the instance of a type deriving from @private_type.
- * @g_type: the type identifying which private data to retrieve.
- * @c_type: The C type for the private structure.
+ * @instance: the instance of a type deriving from @private_type
+ * @g_type: the type identifying which private data to retrieve
+ * @c_type: The C type for the private structure
  * 
  * Gets the private structure for a particular type.
  * The private structure must have been registered in the
@@ -629,15 +629,15 @@ struct _GTypeQuery
  * This macro should only be used in type implementations.
  * 
  * Since: 2.4
- * Returns: a pointer to the private data structure.
+ * Returns: a pointer to the private data structure
  */
 #define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type)   ((c_type*) g_type_instance_get_private 
((GTypeInstance*) (instance), (g_type)))
 
 /**
  * G_TYPE_CLASS_GET_PRIVATE:
- * @klass: the class of a type deriving from @private_type.
- * @g_type: the type identifying which private data to retrieve.
- * @c_type: The C type for the private structure.
+ * @klass: the class of a type deriving from @private_type
+ * @g_type: the type identifying which private data to retrieve
+ * @c_type: The C type for the private structure
  * 
  * Gets the private class structure for a particular type.
  * The private structure must have been registered in the
@@ -646,16 +646,16 @@ struct _GTypeQuery
  * This macro should only be used in type implementations.
  * 
  * Since: 2.24
- * Returns: a pointer to the private data structure.
+ * Returns: a pointer to the private data structure
  */
 #define G_TYPE_CLASS_GET_PRIVATE(klass, g_type, c_type)   ((c_type*) g_type_class_get_private ((GTypeClass*) 
(klass), (g_type)))
 
 /**
  * GTypeDebugFlags:
- * @G_TYPE_DEBUG_NONE: Print no messages.
- * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping.
- * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions.
- * @G_TYPE_DEBUG_MASK: Mask covering all debug flags.
+ * @G_TYPE_DEBUG_NONE: Print no messages
+ * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping
+ * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions
+ * @G_TYPE_DEBUG_MASK: Mask covering all debug flags
  *
  * These flags used to be passed to g_type_init_with_debug_flags() which
  * is now deprecated.
@@ -742,7 +742,7 @@ void                      g_type_query                   (GType            type,
 /* --- type registration --- */
 /**
  * GBaseInitFunc:
- * @g_class: The #GTypeClass structure to initialize.
+ * @g_class: The #GTypeClass structure to initialize
  * 
  * A callback function used by the type system to do base initialization
  * of the class structures of derived types. It is called as part of the
@@ -756,7 +756,7 @@ void                      g_type_query                   (GType            type,
 typedef void   (*GBaseInitFunc)              (gpointer         g_class);
 /**
  * GBaseFinalizeFunc:
- * @g_class: The #GTypeClass structure to finalize.
+ * @g_class: The #GTypeClass structure to finalize
  * 
  * A callback function used by the type system to finalize those portions
  * of a derived types class structure that were setup from the corresponding
@@ -773,24 +773,17 @@ typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
  * A callback function used by the type system to initialize the class
  * of a specific type. This function should initialize all static class
  * members.
+ *
  * The initialization process of a class involves:
- * <itemizedlist>
- * <listitem><para>
- *     1 - Copying common members from the parent class over to the
- *     derived class structure.
- * </para></listitem>
- * <listitem><para>
- *     2 -  Zero initialization of the remaining members not copied
- *     over from the parent class.
- * </para></listitem>
- * <listitem><para>
- *     3 - Invocation of the GBaseInitFunc() initializers of all parent
- *     types and the class' type.
- * </para></listitem>
- * <listitem><para>
- *     4 - Invocation of the class' GClassInitFunc() initializer.
- * </para></listitem>
- * </itemizedlist>
+ * 
+ * - Copying common members from the parent class over to the
+ *   derived class structure.
+ * - Zero initialization of the remaining members not copied
+ *   over from the parent class.
+ * - Invocation of the GBaseInitFunc() initializers of all parent
+ *   types and the class' type.
+ * - Invocation of the class' GClassInitFunc() initializer.
+ *
  * Since derived classes are partially initialized through a memory copy
  * of the parent class, the general rule is that GBaseInitFunc() and
  * GBaseFinalizeFunc() should take care of necessary reinitialization
@@ -801,10 +794,11 @@ typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
  * or reference counted resources) are better handled by a GBaseInitFunc()
  * for this type, so proper initialization of the dynamic class members
  * is performed for class initialization of derived types as well.
+ *
  * An example may help to correspond the intend of the different class
  * initializers:
  * 
- * |[
+ * |[<!-- language="C" -->
  * typedef struct {
  *   GObjectClass parent_class;
  *   gint         static_integer;
@@ -850,6 +844,7 @@ typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
  * Initialization of TypeBClass will first cause initialization of
  * TypeAClass (derived classes reference their parent classes, see
  * g_type_class_ref() on this).
+ *
  * Initialization of TypeAClass roughly involves zero-initializing its fields,
  * then calling its GBaseInitFunc() type_a_base_class_init() to allocate
  * its dynamic members (dynamic_string), and finally calling its GClassInitFunc()
@@ -860,11 +855,13 @@ typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
  * The dynamic members of TypeAClass within TypeBClass now need
  * reinitialization which is performed by calling type_a_base_class_init()
  * with an argument of TypeBClass.
+ *
  * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init()
  * is called to allocate the dynamic members of TypeBClass (dynamic_gstring),
  * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(),
  * is called to complete the initialization process with the static members
  * (static_float).
+ *
  * Corresponding finalization counter parts to the GBaseInitFunc() functions
  * have to be provided to release allocated resources at class finalization
  * time.
@@ -873,8 +870,8 @@ typedef void   (*GClassInitFunc)             (gpointer         g_class,
                                              gpointer         class_data);
 /**
  * GClassFinalizeFunc:
- * @g_class: The #GTypeClass structure to finalize.
- * @class_data: The @class_data member supplied via the #GTypeInfo structure.
+ * @g_class: The #GTypeClass structure to finalize
+ * @class_data: The @class_data member supplied via the #GTypeInfo structure
  * 
  * A callback function used by the type system to finalize a class.
  * This function is rarely needed, as dynamically allocated class resources
@@ -888,8 +885,8 @@ typedef void   (*GClassFinalizeFunc)         (gpointer         g_class,
                                              gpointer         class_data);
 /**
  * GInstanceInitFunc:
- * @instance: The instance to initialize.
- * @g_class: The class of the type the instance is created for.
+ * @instance: The instance to initialize
+ * @g_class: The class of the type the instance is created for
  * 
  * A callback function used by the type system to initialize a new
  * instance of a type. This function initializes all instance members and
@@ -907,8 +904,8 @@ typedef void   (*GInstanceInitFunc)          (GTypeInstance   *instance,
                                              gpointer         g_class);
 /**
  * GInterfaceInitFunc:
- * @g_iface: The interface structure to initialize.
- * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ * @g_iface: The interface structure to initialize
+ * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure
  * 
  * A callback function used by the type system to initialize a new
  * interface.  This function should initialize all internal data and
@@ -921,8 +918,8 @@ typedef void   (*GInterfaceInitFunc)         (gpointer         g_iface,
                                              gpointer         iface_data);
 /**
  * GInterfaceFinalizeFunc:
- * @g_iface: The interface structure to finalize.
- * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure.
+ * @g_iface: The interface structure to finalize
+ * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure
  * 
  * A callback function used by the type system to finalize an interface.
  * This function should destroy any internal data and release any resources
@@ -946,13 +943,13 @@ typedef void   (*GInterfaceFinalizeFunc)     (gpointer         g_iface,
  * classes are routed through the same #GTypeClassCacheFunc chain.
  * 
  * Returns: %TRUE to stop further #GTypeClassCacheFuncs from being 
- *  called, %FALSE to continue.
+ *  called, %FALSE to continue
  */
 typedef gboolean (*GTypeClassCacheFunc)             (gpointer         cache_data,
                                              GTypeClass      *g_class);
 /**
  * GTypeInterfaceCheckFunc:
- * @check_data: data passed to g_type_add_interface_check().
+ * @check_data: data passed to g_type_add_interface_check()
  * @g_iface: the interface that has been initialized
  * 
  * A callback called after an interface vtable is initialized.
@@ -964,10 +961,10 @@ typedef void     (*GTypeInterfaceCheckFunc)  (gpointer           check_data,
                                              gpointer         g_iface);
 /**
  * GTypeFundamentalFlags:
- * @G_TYPE_FLAG_CLASSED: Indicates a classed type.
- * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed).
- * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type.
- * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable).
+ * @G_TYPE_FLAG_CLASSED: Indicates a classed type
+ * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed)
+ * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type
+ * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable)
  * 
  * Bit masks used to check or determine specific characteristics of a
  * fundamental type.
@@ -982,10 +979,10 @@ typedef enum    /*< skip >*/
 /**
  * GTypeFlags:
  * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be
- *  created for an abstract type.
+ *  created for an abstract type
  * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type
  *  that introduces a value table, but can't be used for
- *  g_value_init().
+ *  g_value_init()
  * 
  * Bit masks used to check or determine characteristics of a type.
  */
@@ -996,9 +993,9 @@ typedef enum    /*< skip >*/
 } GTypeFlags;
 /**
  * GTypeInfo:
- * @class_size: Size of the class structure (required for interface, classed and instantiatable types).
- * @base_init: Location of the base initialization function (optional).
- * @base_finalize: Location of the base finalization function (optional).
+ * @class_size: Size of the class structure (required for interface, classed and instantiatable types)
+ * @base_init: Location of the base initialization function (optional)
+ * @base_finalize: Location of the base finalization function (optional)
  * @class_init: Location of the class initialization function for
  *  classed and instantiatable types. Location of the default vtable 
  *  inititalization function for interface types. (optional) This function 
@@ -1008,16 +1005,17 @@ typedef enum    /*< skip >*/
  * @class_finalize: Location of the class finalization function for
  *  classed and instantiatable types. Location of the default vtable
  *  finalization function for interface types. (optional)
- * @class_data: User-supplied data passed to the class init/finalize functions.
- * @instance_size: Size of the instance (object) structure (required for instantiatable types only).
+ * @class_data: User-supplied data passed to the class init/finalize functions
+ * @instance_size: Size of the instance (object) structure (required for instantiatable types only)
  * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve 
memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the 
[slice allocator][glib-Memory-Slices] now.
- * @instance_init: Location of the instance initialization function (optional, for instantiatable types 
only).
- * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only
- *  useful for fundamental types).
+ * @instance_init: Location of the instance initialization function (optional, for instantiatable types only)
+ * @value_table: A #GTypeValueTable function table for generic handling of GValues
+ *  of this type (usually only useful for fundamental types)
  * 
  * This structure is used to provide the type system with the information
  * required to initialize and destruct (finalize) a type's class and
  * its instances.
+ *
  * The initialized structure is passed to the g_type_register_static() function
  * (or is copied into the provided #GTypeInfo structure in the
  * g_type_plugin_complete_type_info()). The type system will perform a deep
@@ -1080,14 +1078,14 @@ struct _GInterfaceInfo
  *  old contents. E.g. for the implementation of a string
  *  value that may never be %NULL, the implementation might
  *  look like:
- *  |[
+ *  |[<!-- language="C" -->
  *  value->data[0].v_pointer = g_strdup ("");
  *  ]|
  * @value_free: Free any old contents that might be left in the
  *  data array of the passed in @value. No resources may
  *  remain allocated through the #GValue contents after
  *  this function returns. E.g. for our above string type:
- *  |[
+ *  |[<!-- language="C" -->
  *  // only free strings without a specific flag for static storage
  *  if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS))
  *    g_free (value->data[0].v_pointer);
@@ -1099,33 +1097,25 @@ struct _GInterfaceInfo
  *  @src_value into @dest_value in a way, that even after
  *  @src_value has been freed, the contents of @dest_value
  *  remain valid. String type example:
- *  |[
+ *  |[<!-- language="C" -->
  *  dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer);
  *  ]|
  * @value_peek_pointer: If the value contents fit into a pointer, such as objects
  *  or strings, return this pointer, so the caller can peek at
  *  the current contents. To extend on our above string example:
- *  |[
+ *  |[<!-- language="C" -->
  *  return value->data[0].v_pointer;
  *  ]|
  * @collect_format: A string format describing how to collect the contents of
  *  this value bit-by-bit. Each character in the format represents
  *  an argument to be collected, and the characters themselves indicate
  *  the type of the argument. Currently supported arguments are:
- *  <variablelist>
- *  <varlistentry><term /><listitem><para>
- *  'i' - Integers. passed as collect_values[].v_int.
- *  </para></listitem></varlistentry>
- *  <varlistentry><term /><listitem><para>
- *  'l' - Longs. passed as collect_values[].v_long.
- *  </para></listitem></varlistentry>
- *  <varlistentry><term /><listitem><para>
- *  'd' - Doubles. passed as collect_values[].v_double.
- *  </para></listitem></varlistentry>
- *  <varlistentry><term /><listitem><para>
- *  'p' - Pointers. passed as collect_values[].v_pointer.
- *  </para></listitem></varlistentry>
- *  </variablelist>
+ *
+ *  - 'i' - Integers. passed as collect_values[].v_int.
+ *  - 'l' - Longs. passed as collect_values[].v_long.
+ *  - 'd' - Doubles. passed as collect_values[].v_double.
+ *  - 'p' - Pointers. passed as collect_values[].v_pointer.
+ *
  *  It should be noted that for variable argument list construction,
  *  ANSI C promotes every type smaller than an integer to an int, and
  *  floats to doubles. So for collection of short int or char, 'i'
@@ -1150,7 +1140,7 @@ struct _GInterfaceInfo
  *  Thus an extra copy of the contents stored in @collect_values is
  *  not required for assignment to @value.
  *  For our above string example, we continue with:
- *  |[
+ *  |[<!-- language="C" -->
  *  if (!collect_values[0].v_pointer)
  *    value->data[0].v_pointer = g_strdup ("");
  *  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS)
@@ -1171,7 +1161,7 @@ struct _GInterfaceInfo
  *  array.  To deviate from our string example for a moment, and taking
  *  a look at an exemplary implementation for collect_value() of
  *  #GObject:
- *  |[
+ *  |[<!-- language="C" -->
  *  if (collect_values[0].v_pointer)
  *  {
  *    GObject *object = G_OBJECT (collect_values[0].v_pointer);
@@ -1211,7 +1201,7 @@ struct _GInterfaceInfo
  *  Similar to collect_value() the function may prematurely abort
  *  by returning a newly allocated string describing an error condition.
  *  To complete the string example:
- *  |[
+ *  |[<!-- language="C" -->
  *  gchar **string_p = collect_values[0].v_pointer;
  *  if (!string_p)
  *    return g_strdup_printf ("string location passed as NULL");
@@ -1222,21 +1212,21 @@ struct _GInterfaceInfo
  *  ]|
  *  And an illustrative version of lcopy_value() for
  *  reference-counted types:
- *  |[
+ *  |[<!-- language="C" -->
  *  GObject **object_p = collect_values[0].v_pointer;
  *  if (!object_p)
  *    return g_strdup_printf ("object location passed as NULL");
  *  if (!value->data[0].v_pointer)
  *    *object_p = NULL;
- *  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) /&ast; always honour &ast;/
+ *  else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour
  *    *object_p = value->data[0].v_pointer;
  *  else
  *    *object_p = g_object_ref (value->data[0].v_pointer);
  *  return NULL;
  *  ]|
  * 
- * The #GTypeValueTable provides the functions required by the #GValue implementation,
- * to serve as a container for values of a type.
+ * The #GTypeValueTable provides the functions required by the #GValue
+ * implementation, to serve as a container for values of a type.
  */
 
 struct _GTypeValueTable
@@ -1333,10 +1323,11 @@ guint     g_type_get_type_registration_serial (void);
  *  separated by '_'.
  * @T_P: The #GType of the parent type.
  * 
- * A convenience macro for type implementations, which declares a 
- * class initialization function, an instance initialization function (see #GTypeInfo for information about 
- * these) and a static variable named @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, 
it defines 
- * a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example.
+ * A convenience macro for type implementations, which declares a class
+ * initialization function, an instance initialization function (see #GTypeInfo
+ * for information about these) and a static variable named `t_n_parent_class`
+ * pointing to the parent class. Furthermore, it defines  a *_get_type() function.
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
  * 
  * Since: 2.4
  */
@@ -1363,14 +1354,15 @@ guint     g_type_get_type_registration_serial (void);
  *  separated by '_'.
  * @T_P: The #GType of the parent type.
  * 
- * A convenience macro for type implementations, which declares a 
- * class initialization function, an instance initialization function (see #GTypeInfo for information about 
- * these), a static variable named @t_n<!-- -->_parent_class pointing to the parent class, and adds private
- * instance data to the type. Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED()
+ * A convenience macro for type implementations, which declares a class
+ * initialization function, an instance initialization function (see #GTypeInfo
+ * for information about these), a static variable named `t_n_parent_class`
+ * pointing to the parent class, and adds private instance data to the type.
+ * Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED()
  * for an example.
  * 
  * Note that private structs added with this macros must have a struct
- * name of the form <replaceable>@TN</replaceable>Private.
+ * name of the form @TN Private.
  *
  * Since: 2.38
  */
@@ -1398,9 +1390,10 @@ guint     g_type_get_type_registration_serial (void);
  * @_C_: Custom code that gets inserted in the @type_name_get_type() function.
  * 
  * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and allows you to 
- * insert custom code into the *_get_type() function, e.g. interface implementations 
- * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example.
+ * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and
+ * allows you to insert custom code into the *_get_type() function, e.g.
+ * interface implementations  via G_IMPLEMENT_INTERFACE().
+ * See G_DEFINE_TYPE_EXTENDED() for an example.
  * 
  * Since: 2.4
  */
@@ -1430,7 +1423,7 @@ guint     g_type_get_type_registration_serial (void);
  * The most general convenience macro for type implementations, on which
  * G_DEFINE_TYPE(), etc are based.
  *
- * |[
+ * |[<!-- language="C" -->
  * G_DEFINE_TYPE_EXTENDED (GtkGadget,
  *                         gtk_gadget,
  *                         GTK_TYPE_WIDGET,
@@ -1439,7 +1432,7 @@ guint     g_type_get_type_registration_serial (void);
  *                                                gtk_gadget_gizmo_init));
  * ]|
  * expands to
- * |[
+ * |[<!-- language="C" -->
  * static void     gtk_gadget_init       (GtkGadget      *self);
  * static void     gtk_gadget_class_init (GtkGadgetClass *klass);
  * static gpointer gtk_gadget_parent_class = NULL;
@@ -1525,7 +1518,7 @@ guint     g_type_get_type_registration_serial (void);
  * @TYPE_IFACE: The #GType of the interface to add
  * @iface_init: The interface init function
  *
- * A convenience macro to ease interface addition in the @_C_ section
+ * A convenience macro to ease interface addition in the `_C_` section
  * of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE().
  * See G_DEFINE_TYPE_EXTENDED() for an example.
  *
@@ -1551,7 +1544,7 @@ guint     g_type_get_type_registration_serial (void);
  *
  * For instance:
  *
- * |[
+ * |[<!-- language="C" -->
  *   typedef struct _MyObject MyObject;
  *   typedef struct _MyObjectClass MyObjectClass;
  *
@@ -1571,7 +1564,7 @@ guint     g_type_get_type_registration_serial (void);
  * based on the arguments to this macro, which can be used to safely
  * retrieve the private data from an instance of the type; for instance:
  *
- * |[
+ * |[<!-- language="C" -->
  *   gint
  *   my_object_get_foo (MyObject *obj)
  *   {
@@ -1595,7 +1588,7 @@ guint     g_type_get_type_registration_serial (void);
  * macros, since it depends on variable names from those macros.
  *
  * Also note that private structs added with these macros must have a struct
- * name of the form <replaceable>TypeName</replaceable>Private.
+ * name of the form `TypeNamePrivate`.
  *
  * Since: 2.38
  */
@@ -1751,9 +1744,9 @@ type_name##_get_type (void) \
 
 /**
  * G_DEFINE_BOXED_TYPE:
- * @TypeName: The name of the new type, in Camel case.
+ * @TypeName: The name of the new type, in Camel case
  * @type_name: The name of the new type, in lowercase, with words
- *  separated by '_'.
+ *  separated by '_'
  * @copy_func: the #GBoxedCopyFunc for the new type
  * @free_func: the #GBoxedFreeFunc for the new type
  *
@@ -1765,12 +1758,12 @@ type_name##_get_type (void) \
 #define G_DEFINE_BOXED_TYPE(TypeName, type_name, copy_func, free_func) G_DEFINE_BOXED_TYPE_WITH_CODE 
(TypeName, type_name, copy_func, free_func, {})
 /**
  * G_DEFINE_BOXED_TYPE_WITH_CODE:
- * @TypeName: The name of the new type, in Camel case.
+ * @TypeName: The name of the new type, in Camel case
  * @type_name: The name of the new type, in lowercase, with words
- *  separated by '_'.
+ *  separated by '_'
  * @copy_func: the #GBoxedCopyFunc for the new type
  * @free_func: the #GBoxedFreeFunc for the new type
- * @_C_: Custom code that gets inserted in the *_get_type() function.
+ * @_C_: Custom code that gets inserted in the *_get_type() function
  *
  * A convenience macro for boxed type implementations.
  * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
@@ -1826,9 +1819,9 @@ type_name##_get_type (void) \
 
 /**
  * G_DEFINE_POINTER_TYPE:
- * @TypeName: The name of the new type, in Camel case.
+ * @TypeName: The name of the new type, in Camel case
  * @type_name: The name of the new type, in lowercase, with words
- *  separated by '_'.
+ *  separated by '_'
  *
  * A convenience macro for pointer type implementations, which defines a
  * type_name_get_type() function registering the pointer type.
@@ -1838,14 +1831,14 @@ type_name##_get_type (void) \
 #define G_DEFINE_POINTER_TYPE(TypeName, type_name) G_DEFINE_POINTER_TYPE_WITH_CODE (TypeName, type_name, {})
 /**
  * G_DEFINE_POINTER_TYPE_WITH_CODE:
- * @TypeName: The name of the new type, in Camel case.
+ * @TypeName: The name of the new type, in Camel case
  * @type_name: The name of the new type, in lowercase, with words
- *  separated by '_'.
- * @_C_: Custom code that gets inserted in the *_get_type() function.
+ *  separated by '_'
+ * @_C_: Custom code that gets inserted in the *_get_type() function
  *
  * A convenience macro for pointer type implementations.
- * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the
- * type_name_get_type() function.
+ * Similar to G_DEFINE_POINTER_TYPE(), but allows to insert
+ * custom code into the type_name_get_type() function.
  *
  * Since: 2.26
  */