docs: Start stanzas with a single paragraph

When rendering the contents of the GLib documentation stored inside the
introspection data, a common behaviour is to take the first paragraph as
a summary of the symbol being documented.

The documentation is assumed to be in Markdown format, which means:

 - paragraphs must be separated by newlines
 - lines that have an indentation of four or more spaces are considered
   code blocks
 - lines that start with a `#` are considered titles

This means we need to slightly tweak the documentation in our sources to
ensure that it can be rendered appropriately by tools that are not
gtk-doc.

See issue: #2365

gobject/gbinding.c

@@ -25,9 +25,10 @@
  *
  * #GBinding is the representation of a binding between a property on a
  * #GObject instance (or source) and another property on another #GObject
- * instance (or target). Whenever the source property changes, the same
+ * instance (or target).
- * value is applied to the target property; for instance, the following
+ *
- * binding:
+ * Whenever the source property changes, the same value is applied to the
+ * target property; for instance, the following binding:
  *
  * |[<!-- language="C" -->
  *   g_object_bind_property (object1, "property-a",
@@ -1409,10 +1410,12 @@ g_object_bind_property_full (gpointer               source,
  * @flags: flags to pass to #GBinding
  *
  * Creates a binding between @source_property on @source and @target_property
- * on @target. Whenever the @source_property is changed the @target_property is
+ * on @target.
+ *
+ * Whenever the @source_property is changed the @target_property is
  * updated using the same value. For instance:
  *
- * |[
+ * |[<!-- language="C" -->
  *   g_object_bind_property (action, "active", widget, "sensitive", 0);
  * ]|
  *

gobject/gbinding.h

@@ -53,8 +53,9 @@ typedef struct _GBinding        GBinding;
  * @to_value: the #GValue in which to store the transformed value
  * @user_data: data passed to the transform function
  *
- * A function to be called to transform @from_value to @to_value. If
+ * A function to be called to transform @from_value to @to_value.
- * this is the @transform_to function of a binding, then @from_value
+ *
+ * If this is the @transform_to function of a binding, then @from_value
  * is the @source_property on the @source object, and @to_value is the
  * @target_property on the @target object. If this is the
  * @transform_from function of a %G_BINDING_BIDIRECTIONAL binding,

gobject/gboxed.c

@@ -39,10 +39,11 @@
  * @see_also: #GParamSpecBoxed, g_param_spec_boxed()
  * @title: Boxed Types
  *
- * #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
+ * #GBoxed is a generic wrapper mechanism for arbitrary C structures.
- * thing the type system needs to know about the structures is how to copy them
+ *
- * (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that
+ * The only thing the type system needs to know about the structures is how to
- * they are treated as opaque chunks of memory.
+ * copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc);
+ * beyond that, they are treated as opaque chunks of memory.
  *
  * Boxed types are useful for simple value-holder structures like rectangles or
  * points. They can also be used for wrapping structures defined in non-#GObject
@@ -280,8 +281,10 @@ boxed_proxy_lcopy_value (const GValue *value,
  * @boxed_free: Boxed structure free function.
  *
  * This function creates a new %G_TYPE_BOXED derived type id for a new
- * boxed type with name @name. Boxed type handling functions have to be
+ * boxed type with name @name.
- * provided to copy and free opaque boxed structures of this type.
+ *
+ * Boxed type handling functions have to be provided to copy and free
+ * opaque boxed structures of this type.
  *
  * For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE 
  * instead of calling g_boxed_type_register_static() directly. The macro 
@@ -510,6 +513,7 @@ g_value_set_boxed (GValue       *value,
  * @v_boxed: (nullable): static boxed value to be set
  *
  * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+ *
  * The boxed value is assumed to be static, and is thus not duplicated
  * when setting the #GValue.
  */

gobject/gclosure.c

@@ -41,8 +41,9 @@
  * @short_description: Functions as first-class objects
  * @title: Closures
  *
- * A #GClosure represents a callback supplied by the programmer. It
+ * A #GClosure represents a callback supplied by the programmer.
- * will generally comprise a function of some kind and a marshaller
+ *
+ * It will generally comprise a function of some kind and a marshaller
  * used to call it. It is the responsibility of the marshaller to
  * convert the arguments for the invocation from #GValues into
  * a suitable form, perform the callback on the converted arguments,
@@ -150,8 +151,9 @@ enum {
  * @data: data to store in the @data field of the newly allocated #GClosure
  *
  * Allocates a struct of the given size and initializes the initial
- * part as a #GClosure. This function is mainly useful when
+ * part as a #GClosure.
- * implementing new types of closures.
+ *
+ * This function is mainly useful when implementing new types of closures:
  *
  * |[<!-- language="C" --> 
  * typedef struct _MyClosure MyClosure;
@@ -327,12 +329,15 @@ g_closure_set_meta_va_marshal (GClosure       *closure,
  *  to @meta_marshal
  * @meta_marshal: a #GClosureMarshal function
  *
- * Sets the meta marshaller of @closure.  A meta marshaller wraps
+ * Sets the meta marshaller of @closure.
- * @closure->marshal and modifies the way it is called in some
+ *
- * fashion. The most common use of this facility is for C callbacks.
+ * A meta marshaller wraps the @closure's marshal and modifies the way
+ * it is called in some fashion. The most common use of this facility
+ * is for C callbacks.
+ *
  * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
  * are used everywhere, but the way that we get the callback function
- * differs. In most cases we want to use @closure->callback, but in
+ * differs. In most cases we want to use the @closure's callback, but in
  * other cases we want to use some different technique to retrieve the
  * callback function.
  *
@@ -373,9 +378,11 @@ g_closure_set_meta_marshal (GClosure       *closure,
  * @post_marshal_notify: a function to call after the closure callback
  *
  * Adds a pair of notifiers which get invoked before and after the
- * closure callback, respectively. This is typically used to protect
+ * closure callback, respectively.
- * the extra arguments for the duration of the callback. See
+ *
- * g_object_watch_closure() for an example of marshal guards.
+ * This is typically used to protect the extra arguments for the
+ * duration of the callback. See g_object_watch_closure() for an
+ * example of marshal guards.
  */
 void
 g_closure_add_marshal_guards (GClosure      *closure,
@@ -428,11 +435,12 @@ g_closure_add_marshal_guards (GClosure      *closure,
  * @notify_func: the callback function to register
  *
  * Registers a finalization notifier which will be called when the
- * reference count of @closure goes down to 0. Multiple finalization
+ * reference count of @closure goes down to 0.
- * notifiers on a single closure are invoked in unspecified order. If
+ *
- * a single call to g_closure_unref() results in the closure being
+ * Multiple finalization notifiers on a single closure are invoked in
- * both invalidated and finalized, then the invalidate notifiers will
+ * unspecified order. If a single call to g_closure_unref() results in
- * be run before the finalize notifiers.
+ * the closure being both invalidated and finalized, then the invalidate
+ * notifiers will be run before the finalize notifiers.
  */
 void
 g_closure_add_finalize_notifier (GClosure      *closure,
@@ -464,9 +472,10 @@ g_closure_add_finalize_notifier (GClosure      *closure,
  * @notify_func: the callback function to register
  *
  * Registers an invalidation notifier which will be called when the
- * @closure is invalidated with g_closure_invalidate(). Invalidation
+ * @closure is invalidated with g_closure_invalidate().
- * notifiers are invoked before finalization notifiers, in an
+ *
- * unspecified order.
+ * Invalidation notifiers are invoked before finalization notifiers,
+ * in an unspecified order.
  */
 void
 g_closure_add_invalidate_notifier (GClosure      *closure,
@@ -561,7 +570,9 @@ g_closure_ref (GClosure *closure)
  * Sets a flag on the closure to indicate that its calling
  * environment has become invalid, and thus causes any future
  * invocations of g_closure_invoke() on this @closure to be
- * ignored. Also, invalidation notifiers installed on the closure will
+ * ignored.
+ *
+ * Also, invalidation notifiers installed on the closure will
  * be called at this point. Note that unless you are holding a
  * reference to the closure yourself, the invalidation notifiers may
  * unref the closure and cause it to be destroyed, so if you need to
@@ -594,8 +605,10 @@ g_closure_invalidate (GClosure *closure)
  * @closure: #GClosure to decrement the reference count on
  *
  * Decrements the reference count of a closure after it was previously
- * incremented by the same caller. If no other callers are using the
+ * incremented by the same caller.
- * closure, then the closure will be destroyed and freed.
+ *
+ * If no other callers are using the closure, then the closure will be
+ * destroyed and freed.
  */
 void
 g_closure_unref (GClosure *closure)
@@ -640,27 +653,34 @@ g_closure_unref (GClosure *closure)
  * @closure: #GClosure to decrement the initial reference count on, if it's
  *           still being held
  *
- * Takes over the initial ownership of a closure.  Each closure is
+ * Takes over the initial ownership of a closure.
- * initially created in a "floating" state, which means that the initial
+ *
- * reference count is not owned by any caller. g_closure_sink() checks
+ * Each closure is initially created in a "floating" state, which means
- * to see if the object is still floating, and if so, unsets the
+ * that the initial reference count is not owned by any caller.
- * floating state and decreases the reference count. If the closure
+ *
- * is not floating, g_closure_sink() does nothing. The reason for the
+ * This function checks to see if the object is still floating, and if so,
- * existence of the floating state is to prevent cumbersome code
+ * unsets the floating state and decreases the reference count. If the
- * sequences like:
+ * closure is not floating, g_closure_sink() does nothing.
+ *
+ * The reason for the existence of the floating state is to prevent
+ * cumbersome code sequences like:
+ *
  * |[<!-- language="C" --> 
  * closure = g_cclosure_new (cb_func, cb_data);
  * g_source_set_closure (source, closure);
  * g_closure_unref (closure); // GObject doesn't really need this
  * ]|
+ *
  * Because g_source_set_closure() (and similar functions) take ownership of the
  * initial reference count, if it is unowned, we instead can write:
+ *
  * |[<!-- language="C" --> 
  * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
  * ]|
  *
  * Generally, this function is used together with g_closure_ref(). An example
  * of storing a closure for later notification looks like:
+ *
  * |[<!-- language="C" --> 
  * static GClosure *notify_closure = NULL;
  * void
@@ -888,12 +908,16 @@ _g_closure_invoke_va (GClosure       *closure,
  * @closure: a #GClosure
  * @marshal: a #GClosureMarshal function
  *
- * Sets the marshaller of @closure. The `marshal_data`
+ * Sets the marshaller of @closure.
- * of @marshal provides a way for a meta marshaller to provide additional
+ *
- * information to the marshaller. (See g_closure_set_meta_marshal().) For
+ * The `marshal_data` of @marshal provides a way for a meta marshaller to
- * GObject's C predefined marshallers (the g_cclosure_marshal_*()
+ * provide additional information to the marshaller.
+ *
+ * For GObject's C predefined marshallers (the `g_cclosure_marshal_*()`
  * functions), what it provides is a callback function to use instead of
  * @closure->callback.
+ *
+ * See also: g_closure_set_meta_marshal()
  */
 void
 g_closure_set_marshal (GClosure       *closure,

gobject/gclosure.h

@@ -42,6 +42,7 @@ G_BEGIN_DECLS
  * @cl: a #GClosure
  * 
  * Get the total number of notifiers connected with the closure @cl. 
+ *
  * The count includes the meta marshaller, the finalize and invalidate notifiers 
  * and the marshal guards. Note that each guard counts as two notifiers. 
  * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
@@ -78,10 +79,13 @@ typedef struct _GClosureNotifyData	 GClosureNotifyData;
  * GCallback:
  * 
  * The type used for callback functions in structure definitions and function 
- * signatures. This doesn't mean that all callback functions must take no 
+ * signatures.
- * parameters and return void. The required signature of a callback function 
+ *
- * is determined by the context in which is used (e.g. the signal to which it 
+ * This doesn't mean that all callback functions must take no  parameters and
- * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. 
+ * return void. The required signature of a callback function is determined by
+ * the context in which is used (e.g. the signal to which it is connected).
+ *
+ * Use G_CALLBACK() to cast the callback function to a #GCallback. 
  */
 typedef void  (*GCallback)              (void);
 /**

gobject/gobject.c

@@ -66,15 +66,18 @@
  * claimed to be "owned" by any code portion. The main motivation for
  * providing floating references is C convenience. In particular, it
  * allows code to be written as:
+ * 
  * |[<!-- language="C" --> 
  * container = create_container ();
  * container_add_child (container, create_child());
  * ]|
+ * 
  * If container_add_child() calls g_object_ref_sink() on the passed-in child,
  * no reference of the newly created child is leaked. Without floating
  * references, container_add_child() can only g_object_ref() the new child,
  * so to implement this code without reference leaks, it would have to be
  * written as:
+ *
  * |[<!-- language="C" --> 
  * Child *child;
  * container = create_container ();
@@ -82,6 +85,7 @@
  * container_add_child (container, child);
  * g_object_unref (child);
  * ]|
+ *
  * The floating reference can be converted into an ordinary reference by
  * calling g_object_ref_sink(). For already sunken objects (objects that
  * don't have a floating reference anymore), g_object_ref_sink() is equivalent
@@ -537,11 +541,13 @@ g_object_do_class_init (GObjectClass *class)
    * This signal is typically used to obtain change notification for a
    * single property, by specifying the property name as a detail in the
    * g_signal_connect() call, like this:
+   *
    * |[<!-- language="C" --> 
    * g_signal_connect (text_view->buffer, "notify::paste-target-list",
    *                   G_CALLBACK (gtk_text_view_target_list_notify),
    *                   text_view)
    * ]|
+   *
    * It is important to note that you must use
    * [canonical parameter names][canonical-parameter-names] as
    * detail strings for the notify signal.
@@ -4530,11 +4536,12 @@ g_initially_unowned_class_init (GInitiallyUnownedClass *klass)
 /**
  * GWeakRef:
  *
- * A structure containing a weak reference to a #GObject.  It can either
+ * A structure containing a weak reference to a #GObject.
- * be empty (i.e. point to %NULL), or point to an object for as long as
+ *
- * at least one "strong" reference to that object exists. Before the
+ * A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an
- * object's #GObjectClass.dispose method is called, every #GWeakRef
+ * object for as long as at least one "strong" reference to that object
- * associated with becomes empty (i.e. points to %NULL).
+ * exists. Before the object's #GObjectClass.dispose method is called,
+ * every #GWeakRef associated with becomes empty (i.e. points to %NULL).
  *
  * Like #GValue, #GWeakRef can be statically allocated, stack- or
  * heap-allocated, or embedded in larger structures.

gobject/gobject.h

@@ -45,6 +45,7 @@ G_BEGIN_DECLS
  * @object: Object which is subject to casting.
  * 
  * Casts a #GObject or derived pointer into a (GObject*) pointer.
+ *
  * Depending on the current debugging level, this function may invoke
  * certain runtime checks to identify invalid casts.
  */
@@ -144,7 +145,9 @@ G_BEGIN_DECLS
  * @object: Object which is subject to casting.
  * 
  * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) 
- * pointer. Depending on the current debugging level, this function may invoke
+ * pointer.
+ *
+ * Depending on the current debugging level, this function may invoke
  * certain runtime checks to identify invalid casts.
  */
 #define G_INITIALLY_UNOWNED(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnowned))
@@ -230,17 +233,21 @@ typedef void (*GObjectFinalizeFunc)     (GObject      *object);
  * @where_the_object_was: the object being disposed
  * 
  * A #GWeakNotify function can be added to an object as a callback that gets
- * triggered when the object is finalized. Since the object is already being
+ * triggered when the object is finalized.
- * disposed when the #GWeakNotify is called, there's not much you could do 
+ *
- * with the object, apart from e.g. using its address as hash-index or the like. 
+ * Since the object is already being disposed when the #GWeakNotify is called,
+ * there's not much you could do with the object, apart from e.g. using its
+ * address as hash-index or the like.
  */
 typedef void (*GWeakNotify)		(gpointer      data,
 					 GObject      *where_the_object_was);
 /**
  * GObject:
  *
- * All the fields in the GObject structure are private 
+ * The base object type.
- * to the #GObject implementation and should never be accessed directly.
+ * 
+ * All the fields in the `GObject` structure are private to the implementation
+ * and should never be accessed directly.
  */
 struct  _GObject
 {
@@ -352,14 +359,14 @@ struct  _GObjectClass
   /* padding */
   gpointer	pdummy[6];
 };
+
 /**
  * GObjectConstructParam:
  * @pspec: the #GParamSpec of the construct parameter
  * @value: the value to set the parameter to
  * 
- * The GObjectConstructParam struct is an auxiliary 
+ * The GObjectConstructParam struct is an auxiliary structure used to hand
- * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
+ * #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass.
- * a #GObjectClass.
  */
 struct _GObjectConstructParam
 {
@@ -370,9 +377,10 @@ struct _GObjectConstructParam
 /**
  * GInitiallyUnowned:
  *
- * All the fields in the GInitiallyUnowned structure 
+ * A type for objects that have an initially floating reference.
- * are private to the #GInitiallyUnowned implementation and should never be 
+ * 
- * accessed directly.
+ * All the fields in the `GInitiallyUnowned` structure are private to the
+ * implementation and should never be accessed directly.
  */
 /**
  * GInitiallyUnownedClass:
@@ -531,7 +539,9 @@ void        g_object_remove_weak_pointer      (GObject        *object,
  *  references.
  * 
  * A callback function used for notification when the state
- * of a toggle reference changes. See g_object_add_toggle_ref().
+ * of a toggle reference changes.
+ *
+ * See also: g_object_add_toggle_ref()
  */
 typedef void (*GToggleNotify) (gpointer      data,
 			       GObject      *object,
@@ -685,10 +695,11 @@ void    g_clear_object (GObject **object_ptr);
  * @new_object: (nullable) (transfer none): a pointer to the new #GObject to
  *   assign to @object_ptr, or %NULL to clear the pointer
  *
- * Updates a #GObject pointer to refer to @new_object. It increments the
+ * Updates a #GObject pointer to refer to @new_object.
- * reference count of @new_object (if non-%NULL), decrements the reference
+ *
- * count of the current value of @object_ptr (if non-%NULL), and assigns
+ * It increments the reference count of @new_object (if non-%NULL), decrements
- * @new_object to @object_ptr. The assignment is not atomic.
+ * the reference count of the current value of @object_ptr (if non-%NULL), and
+ * assigns @new_object to @object_ptr. The assignment is not atomic.
  *
  * @object_ptr must not be %NULL, but can point to a %NULL value.
  *
@@ -838,13 +849,15 @@ static inline void
  * @new_object: (nullable) (transfer none): a pointer to the new #GObject to
  *   assign to it, or %NULL to clear the pointer
  *
- * Updates a pointer to weakly refer to @new_object. It assigns @new_object
+ * Updates a pointer to weakly refer to @new_object.
- * to @weak_pointer_location and ensures that @weak_pointer_location will
- * automatically be set to %NULL if @new_object gets destroyed. The assignment
- * is not atomic. The weak reference is not thread-safe, see
- * g_object_add_weak_pointer() for details.
  *
- * @weak_pointer_location must not be %NULL.
+ * It assigns @new_object to @weak_pointer_location and ensures
+ * that @weak_pointer_location will automatically be set to %NULL
+ * if @new_object gets destroyed. The assignment is not atomic.
+ * The weak reference is not thread-safe, see g_object_add_weak_pointer()
+ * for details.
+ *
+ * The @weak_pointer_location argument must not be %NULL.
  *
  * A macro is also included that allows this function to be used without
  * pointer casts. The function itself is static inline, so its address may vary

gobject/gparam.c

@@ -890,9 +890,10 @@ value_param_lcopy_value (const GValue *value,
  * GParamSpecPool:
  *
  * A #GParamSpecPool maintains a collection of #GParamSpecs which can be
- * quickly accessed by owner and name. The implementation of the #GObject property
+ * quickly accessed by owner and name.
- * system uses such a pool to store the #GParamSpecs of the properties all object
+ *
- * types.
+ * The implementation of the #GObject property system uses such a pool to
+ * store the #GParamSpecs of the properties all object types.
  */
 struct _GParamSpecPool
 {
@@ -1401,10 +1402,12 @@ default_values_cmp (GParamSpec   *pspec,
  * @name: 0-terminated string used as the name of the new #GParamSpec type.
  * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
  *
- * Registers @name as the name of a new static type derived from
+ * Registers @name as the name of a new static type derived
- * #G_TYPE_PARAM. The type system uses the information contained in
+ * from #G_TYPE_PARAM.
- * the #GParamSpecTypeInfo structure pointed to by @info to manage the
+ *
- * #GParamSpec type and its instances.
+ * The type system uses the information contained in the #GParamSpecTypeInfo
+ * structure pointed to by @info to manage the #GParamSpec type and its
+ * instances.
  *
  * Returns: The new type identifier.
  */

gobject/gparam.h

@@ -145,7 +145,9 @@ G_BEGIN_DECLS
  *  Since 2.26
  * 
  * Through the #GParamFlags flag values, certain aspects of parameters
- * can be configured. See also #G_PARAM_STATIC_STRINGS.
+ * can be configured.
+ *
+ * See also: %G_PARAM_STATIC_STRINGS
  */
 typedef enum
 {
@@ -368,6 +370,7 @@ typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
  * This structure is used to provide the type system with the information
  * required to initialize and destruct (finalize) a parameter's class and
  * instances thereof.
+ *
  * The initialized structure is passed to the g_param_type_register_static() 
  * The type system will perform a deep copy of this structure, so its memory 
  * does not need to be persistent across invocation of 

gobject/gparamspecs.h

@@ -923,11 +923,14 @@ struct _GParamSpecObject
 /**
  * GParamSpecOverride:
  *
- * This is a type of #GParamSpec type that simply redirects operations to
+ * A #GParamSpec derived structure that redirects operations to
- * another paramspec.  All operations other than getting or
+ * other types of #GParamSpec.
- * setting the value are redirected, including accessing the nick and
+ * 
- * blurb, validating a value, and so forth. See
+ * All operations other than getting or setting the value are redirected,
- * g_param_spec_get_redirect_target() for retrieving the overridden
+ * including accessing the nick and blurb, validating a value, and so
+ * forth.
+ *
+ * See g_param_spec_get_redirect_target() for retrieving the overridden
  * property. #GParamSpecOverride is used in implementing
  * g_object_class_override_property(), and will not be directly useful
  * unless you are implementing a new base type similar to GObject.

gobject/gsignal.h

@@ -36,9 +36,11 @@ typedef struct _GSignalInvocationHint	 GSignalInvocationHint;
  * 
  * This is the signature of marshaller functions, required to marshall
  * arrays of parameter values to signal emissions into C language callback
- * invocations. It is merely an alias to #GClosureMarshal since the #GClosure
+ * invocations.
- * mechanism takes over responsibility of actual function invocation for the
+ *
- * signal system.
+ * It is merely an alias to #GClosureMarshal since the #GClosure mechanism
+ * takes over responsibility of actual function invocation for the signal
+ * system.
  */
 typedef GClosureMarshal			 GSignalCMarshaller;
 /**
@@ -58,9 +60,10 @@ typedef GVaClosureMarshal		 GSignalCVaMarshaller;
  *  the signal was emitted, followed by the parameters of the emission.
  * @data: user data associated with the hook.
  * 
- * A simple function pointer to get invoked when the signal is emitted. This 
+ * A simple function pointer to get invoked when the signal is emitted.
- * allows you to tie a hook to the signal type, so that it will trap all 
+ *
- * emissions of that signal, from any object.
+ * Emission hooks allow you to tie a hook to the signal type, so that it will
+ * trap all emissions of that signal, from any object.
  * 
  * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
  * 
@@ -81,10 +84,12 @@ typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint,
  * 
  * The signal accumulator is a special callback function that can be used
  * to collect return values of the various callbacks that are called
- * during a signal emission. The signal accumulator is specified at signal
+ * during a signal emission.
- * creation time, if it is left %NULL, no accumulation of callback return
+ *
- * values is performed. The return value of signal emissions is then the
+ * The signal accumulator is specified at signal creation time, if it is
- * value returned by the last callback.
+ * left %NULL, no accumulation of callback return values is performed.
+ * The return value of signal emissions is then the value returned by the
+ * last callback.
  * 
  * Returns: The accumulator function returns whether the signal emission
  *  should be aborted. Returning %TRUE will continue with
@@ -126,9 +131,7 @@ typedef gboolean (*GSignalAccumulator)	(GSignalInvocationHint *ihint,
  *   functions for the #GSignalInvocationHint::run_type field to mark the first
  *   call to the accumulator function for a signal emission.  Since 2.68.
  *
- * The signal flags are used to specify a signal's behaviour, the overall
+ * The signal flags are used to specify a signal's behaviour.
- * signal description outlines how especially the RUN flags control the
- * stages of a signal emission.
  */
 typedef enum
 {
@@ -253,8 +256,9 @@ struct _GSignalInvocationHint
  *  gpointer     data2);
  *  ]|
  * 
- * A structure holding in-depth information for a specific signal. It is
+ * A structure holding in-depth information for a specific signal.
- * filled in by the g_signal_query() function.
+ *
+ * See also: g_signal_query()
  */
 struct _GSignalQuery
 {

gobject/gtype.c

@@ -48,7 +48,7 @@
  *     management system
  * @title:Type Information
  *
- * The GType API is the foundation of the GObject system.  It provides the
+ * The GType API is the foundation of the GObject system. It provides the
  * facilities for registering and managing all fundamental data types,
  * user-defined object and interface types.
  *

gobject/gtype.h

@@ -32,6 +32,7 @@ G_BEGIN_DECLS
  * @type: A #GType value.
  * 
  * The fundamental type which is the ancestor of @type.
+ *
  * Fundamental types are types that serve as ultimate bases for the derived types, 
  * thus they are the roots of distinct inheritance hierarchies.
  */
@@ -70,6 +71,7 @@ G_BEGIN_DECLS
  * G_TYPE_CHAR:
  * 
  * The fundamental type corresponding to #gchar.
+ *
  * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
  * This may or may not be the same type a the C type "gchar".
  */
@@ -213,6 +215,7 @@ G_BEGIN_DECLS
  * @x: the fundamental type number.
  * 
  * Get the type ID for the fundamental type number @x.
+ *
  * Use g_type_fundamental_next() instead of this macro to create new fundamental 
  * types.
  *
@@ -281,6 +284,7 @@ G_BEGIN_DECLS
  * @type: A #GType value
  * 
  * Checks if @type is an interface type.
+ *
  * An interface type provides a pure API, the implementation
  * of which is provided by another type (which is then said to conform
  * to the interface).  GLib interfaces are somewhat analogous to Java
@@ -451,7 +455,8 @@ struct _GTypeInterface
  * @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.
+ *
+ * See also: g_type_query()
  */
 struct _GTypeQuery
 {
@@ -642,6 +647,7 @@ struct _GTypeQuery
  * @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
  * class_init function with g_type_class_add_private().
  * 
@@ -661,6 +667,7 @@ struct _GTypeQuery
  * @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
  * get_type() function with g_type_add_class_private().
  * 
@@ -773,9 +780,12 @@ int                   g_type_get_instance_count      (GType            type);
  * @g_class: (type GObject.TypeClass): 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
+ * of the class structures of derived types.
- * initialization process of all derived classes and should reallocate
+ *
- * or reset all dynamic class members copied over from the parent class.
+ * This function is called as part of the initialization process of all derived
+ * classes and should reallocate or reset all dynamic class members copied over
+ * from the parent class.
+ *
  * For example, class members (such as strings) that are not sufficiently
  * handled by a plain memory copy of the parent class into the derived class
  * have to be altered. See GClassInitFunc() for a discussion of the class
@@ -788,8 +798,11 @@ typedef void   (*GBaseInitFunc)              (gpointer         g_class);
  * 
  * A callback function used by the type system to finalize those portions
  * of a derived types class structure that were setup from the corresponding
- * GBaseInitFunc() function. Class finalization basically works the inverse
+ * GBaseInitFunc() function.
- * way in which class initialization is performed.
+ *
+ * Class finalization basically works the inverse way in which class
+ * initialization is performed.
+ *
  * See GClassInitFunc() for a discussion of the class initialization process.
  */
 typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
@@ -799,8 +812,9 @@ typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
  * @class_data: The @class_data member supplied via the #GTypeInfo structure.
  * 
  * A callback function used by the type system to initialize the class
- * of a specific type. This function should initialize all static class
+ * of a specific type.
- * members.
+ *
+ * This function should initialize all static class members.
  *
  * The initialization process of a class involves:
  * 
@@ -869,6 +883,7 @@ typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
  *   class->static_float = 3.14159265358979323846;
  * }
  * ]|
+ *
  * Initialization of TypeBClass will first cause initialization of
  * TypeAClass (derived classes reference their parent classes, see
  * g_type_class_ref() on this).
@@ -902,8 +917,10 @@ typedef void   (*GClassInitFunc)             (gpointer         g_class,
  * @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
  * should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
+ *
  * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
  * structure of a static type is invalid, because classes of static types
  * will never be finalized (they are artificially kept alive when their
@@ -918,8 +935,10 @@ typedef void   (*GClassFinalizeFunc)         (gpointer         g_class,
  *    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
+ * instance of a type.
- * allocates any resources required by it.
+ *
+ * This function initializes all instance members and allocates any resources
+ * required by it.
  *
  * Initialization of a derived instance involves calling all its parent
  * types instance initializers, so the class member of the instance
@@ -937,8 +956,10 @@ typedef void   (*GInstanceInitFunc)          (GTypeInstance   *instance,
  * @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
+ * interface.
- * allocate any resources required by the interface.
+ *
+ * This function should initialize all internal data and* allocate any
+ * resources required by the interface.
  *
  * The members of @iface_data are guaranteed to have been filled with
  * zeros before this function is called.
@@ -951,6 +972,7 @@ typedef void   (*GInterfaceInitFunc)         (gpointer         g_iface,
  * @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
  * allocated by the corresponding GInterfaceInitFunc() function.
  */
@@ -963,10 +985,11 @@ typedef void   (*GInterfaceFinalizeFunc)     (gpointer         g_iface,
  *    unreferenced
  * 
  * A callback function which is called when the reference count of a class 
- * drops to zero. It may use g_type_class_ref() to prevent the class from
+ * drops to zero.
- * being freed. You should not call g_type_class_unref() from a 
+ *
- * #GTypeClassCacheFunc function to prevent infinite recursion, use 
+ * It may use g_type_class_ref() to prevent the class from being freed. You
- * g_type_class_unref_uncached() instead.
+ * should not call g_type_class_unref() from a #GTypeClassCacheFunc function
+ * to prevent infinite recursion, use g_type_class_unref_uncached() instead.
  * 
  * The functions have to check the class id passed in to figure 
  * whether they actually want to cache the class of this type, since all
@@ -984,6 +1007,7 @@ typedef gboolean (*GTypeClassCacheFunc)	     (gpointer	       cache_data,
  *    initialized
  * 
  * A callback called after an interface vtable is initialized.
+ *
  * See g_type_add_interface_check().
  * 
  * Since: 2.4
@@ -1356,12 +1380,12 @@ guint     g_type_get_type_registration_serial (void);
  * @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
  * @ParentName: the name of the parent type, in camel case (like `GtkWidget`)
  *
- * A convenience macro for emitting the usual declarations in the header file for a type which is not (at the
+ * A convenience macro for emitting the usual declarations in the header file
- * present time) intended to be subclassed.
+ * for a type which is not (at the present time) intended to be subclassed.
  *
  * You might use it in a header as follows:
  *
- * |[
+ * |[<!-- language="C" -->
  * #ifndef _myapp_window_h_
  * #define _myapp_window_h_
  *
@@ -1442,7 +1466,7 @@ guint     g_type_get_type_registration_serial (void);
  *
  * You might use it in a header as follows:
  *
- * |[
+ * |[<!-- language="C" -->
  * #ifndef _gtk_frobber_h_
  * #define _gtk_frobber_h_
  *
@@ -1539,7 +1563,7 @@ guint     g_type_get_type_registration_serial (void);
  *
  * You might use it in a header as follows:
  *
- * |[
+ * |[<!-- language="C" -->
  * #ifndef _my_model_h_
  * #define _my_model_h_
  *
@@ -1624,6 +1648,7 @@ guint     g_type_get_type_registration_serial (void);
  * @_C_: Custom code that gets inserted in the `*_get_type()` function.
  * 
  * A convenience macro for type implementations.
+ *
  * Similar to G_DEFINE_TYPE(), but 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.
@@ -1642,6 +1667,7 @@ guint     g_type_get_type_registration_serial (void);
  * 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.
  * 
@@ -1664,6 +1690,7 @@ guint     g_type_get_type_registration_serial (void);
  * @T_P: The #GType of the parent type.
  * 
  * A convenience macro for type implementations.
+ *
  * Similar to G_DEFINE_TYPE(), but defines an abstract type.
  * See G_DEFINE_TYPE_EXTENDED() for an example.
  * 
@@ -1679,9 +1706,11 @@ 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.
  * 
  * Since: 2.4
@@ -1695,6 +1724,7 @@ guint     g_type_get_type_registration_serial (void);
  * @T_P: The #GType of the parent type.
  *
  * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type.
+ *
  * See G_DEFINE_TYPE_EXTENDED() for an example.
  * 
  * Since: 2.38
@@ -1772,7 +1802,9 @@ guint     g_type_get_type_registration_serial (void);
  *                         G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
  *                                                gtk_gadget_gizmo_init));
  * ]|
+ *
  * expands to
+ *
  * |[<!-- language="C" -->
  * static void     gtk_gadget_init       (GtkGadget      *self);
  * static void     gtk_gadget_class_init (GtkGadgetClass *klass);
@@ -1819,6 +1851,7 @@ guint     g_type_get_type_registration_serial (void);
  *   return static_g_define_type_id;
  * }
  * ]|
+ *
  * The only pieces which have to be manually provided are the definitions of
  * the instance and class structure and the definitions of the instance and
  * class init functions.
@@ -1860,11 +1893,13 @@ guint     g_type_get_type_registration_serial (void);
  * for no prerequisite type.
  * @_C_: Custom code that gets inserted in the `*_get_type()` function.
  *
- * A convenience macro for #GTypeInterface definitions. Similar to
+ * A convenience macro for #GTypeInterface definitions.
- * G_DEFINE_INTERFACE(), but allows you to insert custom code into the
+ *
- * `*_get_type()` function, e.g. additional interface implementations
+ * Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code
- * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
+ * into the `*_get_type()` function, e.g. additional interface implementations
- * G_DEFINE_TYPE_EXTENDED() for a similar example using
+ * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types.
+ *
+ * See G_DEFINE_TYPE_EXTENDED() for a similar example using
  * G_DEFINE_TYPE_WITH_CODE().
  *
  * Since: 2.24
@@ -2153,7 +2188,6 @@ type_name##_get_type (void) \
  *   GType type = my_struct_get_type ();
  *   // ... your code ...
  * }
- *
  * ]|
  *
  * Since: 2.26
@@ -2169,6 +2203,7 @@ type_name##_get_type (void) \
  * @_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
  * `type_name_get_type()` function, e.g. to register value transformations with
  * g_value_register_transform_func(), for instance:

gobject/gtypemodule.c

@@ -30,16 +30,20 @@
  * @title: GTypeModule
  *
  * #GTypeModule provides a simple implementation of the #GTypePlugin
- * interface. The model of #GTypeModule is a dynamically loaded module
+ * interface.
- * which implements some number of types and interface implementations.
+ *
+ * The model of #GTypeModule is a dynamically loaded module which
+ * implements some number of types and interface implementations.
+ *
  * When the module is loaded, it registers its types and interfaces
  * using g_type_module_register_type() and g_type_module_add_interface().
  * As long as any instances of these types and interface implementations
  * are in use, the module is kept loaded. When the types and interfaces
  * are gone, the module may be unloaded. If the types and interfaces
  * become used again, the module will be reloaded. Note that the last
- * unref cannot happen in module code, since that would lead to the
+ * reference cannot be released from within the module code, since that
- * caller's code being unloaded before g_object_unref() returns to it.
+ * would lead to the caller's code being unloaded before g_object_unref()
+ * returns to it.
  *
  * Keeping track of whether the module should be loaded or not is done by
  * using a use count - it starts at zero, and whenever it is greater than
@@ -57,7 +61,6 @@
  * in #GTypeModuleClass.
  */
 
-
 typedef struct _ModuleTypeInfo ModuleTypeInfo;
 typedef struct _ModuleInterfaceInfo ModuleInterfaceInfo;
 

gobject/gtypemodule.h

@@ -93,9 +93,10 @@ struct _GTypeModuleClass
  * A convenience macro for dynamic 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,
+ * `t_n`_parent_class pointing to the parent class.
- * it defines a `*_get_type()` and a static `*_register_type()` functions
+ *
- * for use in your `module_init()`.
+ * Furthermore, it defines a `*_get_type()` and a static `*_register_type()`
+ * functions for use in your `module_init()`.
  *
  * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
  * 
@@ -114,7 +115,7 @@ struct _GTypeModuleClass
  * A more general version of G_DEFINE_DYNAMIC_TYPE() which
  * allows to specify #GTypeFlags and custom code.
  * 
- * |[
+ * |[<!-- language="C" -->
  * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
  *                                 gtk_gadget,
  *                                 GTK_TYPE_THING,
@@ -122,8 +123,10 @@ struct _GTypeModuleClass
  *                                 G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
  *                                                                gtk_gadget_gizmo_init));
  * ]|
+ *
  * expands to
- * |[
+ *
+ * |[<!-- language="C" -->
  * static void     gtk_gadget_init              (GtkGadget      *self);
  * static void     gtk_gadget_class_init        (GtkGadgetClass *klass);
  * static void     gtk_gadget_class_finalize    (GtkGadgetClass *klass);
@@ -227,8 +230,9 @@ type_name##_register_type (GTypeModule *type_module) \
  * @iface_init: The interface init function
  *
  * A convenience macro to ease interface addition in the @_C_ section
- * of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED()
+ * of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
- * for an example.
+ *
+ * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
  *
  * Note that this macro can only be used together with the
  * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
@@ -248,8 +252,9 @@ type_name##_register_type (GTypeModule *type_module) \
  * @TypeName: the name of the type in CamelCase
  *
  * A convenience macro to ease adding private data to instances of a new dynamic
- * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See
+ * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
- * G_ADD_PRIVATE() for details, it is similar but for static types.
+ *
+ * See G_ADD_PRIVATE() for details, it is similar but for static types.
  *
  * Note that this macro can only be used together with the
  * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable

gobject/gtypeplugin.c

@@ -26,9 +26,10 @@
  * @see_also: #GTypeModule and g_type_register_dynamic().
  * @title: GTypePlugin
  *
+ * An interface that handles the lifecycle of dynamically loaded types.
+ *
  * The GObject type system supports dynamic loading of types.
- * The #GTypePlugin interface is used to handle the lifecycle
+ * It goes as follows:
- * of dynamically loaded types. It goes as follows:
  *
  * 1. The type is initially introduced (usually upon loading the module
  *    the first time, or by your main application that knows what modules

gobject/gvalue.c

@@ -42,6 +42,7 @@
  *
  * The #GValue structure is basically a variable container that consists
  * of a type identifier and a specific value of that type.
+ *
  * The type identifier within a #GValue structure always determines the
  * type of the associated value.
  *

gobject/gvalue.h

@@ -33,6 +33,7 @@ G_BEGIN_DECLS
  * @type: A #GType value.
  * 
  * Checks whether the passed in type ID can be used for g_value_init().
+ *
  * That is, this macro checks whether this type provides an implementation
  * of the #GTypeValueTable functions required for a type to create a #GValue of.
  * 
@@ -97,10 +98,12 @@ typedef void (*GValueTransform) (const GValue *src_value,
  * GValue:
  * 
  * An opaque structure used to hold different types of values.
+ *
  * The data within the structure has protected scope: it is accessible only
  * to functions within a #GTypeValueTable structure, or implementations of
  * the g_value_*() API. That is, code portions which implement new fundamental
  * types.
+ *
  * #GValue users cannot make any assumptions about how data is stored
  * within the 2 element @data union, and the @g_type member should
  * only be accessed through the G_VALUE_TYPE() macro.
@@ -193,7 +196,7 @@ void	g_value_register_transform_func	(GType		 src_type,
  * be used as initializer instead of an explicit `{ 0 }` when declaring
  * a variable, but it cannot be assigned to a variable.
  *
- * |[
+ * |[<!-- language="C" -->
  *   GValue value = G_VALUE_INIT;
  * ]|
  *

gobject/gvaluecollector.h

@@ -23,6 +23,7 @@
  * 
  * The macros in this section provide the varargs parsing support needed
  * in variadic GObject functions such as g_object_new() or g_object_set().
+ *
  * They currently support the collection of integral types, floating point 
  * types and pointers.
  */
@@ -79,9 +80,10 @@ union _GTypeCValue
  * @__error: a #gchar** variable that will be modified to hold a g_new()
  *  allocated error messages if something fails
  * 
- * Collects a variable argument value from a va_list. We have to
+ * Collects a variable argument value from a `va_list`.
- * implement the varargs collection as a macro, because on some systems
+ *
- * va_list variables cannot be passed by reference.
+ * We have to implement the varargs collection as a macro, because on some
+ * systems `va_list` variables cannot be passed by reference.
  *
  * Since: 2.24
  */
@@ -136,9 +138,10 @@ G_STMT_START {										\
  * @__error: a #gchar** variable that will be modified to hold a g_new()
  *  allocated error messages if something fails
  *
- * Collects a variable argument value from a va_list. We have to
+ * Collects a variable argument value from a `va_list`.
- * implement the varargs collection as a macro, because on some systems
+ *
- * va_list variables cannot be passed by reference.
+ * We have to implement the varargs collection as a macro, because on some systems
+ * `va_list` variables cannot be passed by reference.
  *
  * Note: If you are creating the @value argument just before calling this macro,
  * you should use the #G_VALUE_COLLECT_INIT variant and pass the uninitialized
@@ -203,7 +206,8 @@ G_STMT_START {										\
  * @__error: a #gchar** variable that will be modified to hold a g_new()
  *  allocated error message if something fails
  *
- * Stores a value’s value into one or more argument locations from a va_list.
+ * Stores a value’s value into one or more argument locations from a `va_list`.
+ *
  * This is the inverse of G_VALUE_COLLECT().
  */
 #define G_VALUE_LCOPY(value, var_args, flags, __error)					\