[glib/docgen-fixes: 8/15] docs: Start stanzas with a single paragraph
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib/docgen-fixes: 8/15] docs: Start stanzas with a single paragraph
- Date: Mon, 2 Aug 2021 15:06:46 +0000 (UTC)
commit f62622fc7b0254859d10b59c5d9a9cb65b59ce2e
Author: Emmanuele Bassi <ebassi gnome org>
Date: Sat Jul 31 22:47:26 2021 +0100
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 | 15 +++++---
gobject/gbinding.h | 5 ++-
gobject/gboxed.c | 16 +++++---
gobject/gclosure.c | 92 +++++++++++++++++++++++++++-----------------
gobject/gclosure.h | 12 ++++--
gobject/gobject.c | 17 ++++++---
gobject/gobject.h | 59 +++++++++++++++++-----------
gobject/gparam.c | 17 +++++----
gobject/gparam.h | 5 ++-
gobject/gparamspecs.h | 13 ++++---
gobject/gsignal.h | 34 +++++++++--------
gobject/gtype.c | 2 +-
gobject/gtype.h | 97 ++++++++++++++++++++++++++++++++---------------
gobject/gtypemodule.c | 13 ++++---
gobject/gtypemodule.h | 23 ++++++-----
gobject/gtypeplugin.c | 5 ++-
gobject/gvalue.c | 1 +
gobject/gvalue.h | 5 ++-
gobject/gvaluecollector.h | 18 +++++----
19 files changed, 285 insertions(+), 164 deletions(-)
---
diff --git a/gobject/gbinding.c b/gobject/gbinding.c
index 48b4fbaec..a0b5de102 100644
--- a/gobject/gbinding.c
+++ b/gobject/gbinding.c
@@ -25,11 +25,12 @@
*
* #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
- * value is applied to the target property; for instance, the following
- * binding:
+ * instance (or target).
*
- * |[<!-- language="C" -->
+ * 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",
* object2, "property-b",
* G_BINDING_DEFAULT);
@@ -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);
* ]|
*
diff --git a/gobject/gbinding.h b/gobject/gbinding.h
index 84dad7f86..2b2521423 100644
--- a/gobject/gbinding.h
+++ b/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
- * this is the @transform_to function of a binding, then @from_value
+ * A function to be called to transform @from_value to @to_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,
diff --git a/gobject/gboxed.c b/gobject/gboxed.c
index e6bd786ab..c1624a598 100644
--- a/gobject/gboxed.c
+++ b/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
- * 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
- * they are treated as opaque chunks of memory.
+ * #GBoxed is a generic wrapper mechanism for arbitrary C structures.
+ *
+ * The only 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, 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
- * provided to copy and free opaque boxed structures of this type.
+ * boxed type with name @name.
+ *
+ * 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.
*/
diff --git a/gobject/gclosure.c b/gobject/gclosure.c
index 364f4aab1..e6720524a 100644
--- a/gobject/gclosure.c
+++ b/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
- * will generally comprise a function of some kind and a marshaller
+ * A #GClosure represents a callback supplied by the programmer.
+ *
+ * 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
- * implementing new types of closures.
+ * part as a #GClosure.
+ *
+ * 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
- * @closure->marshal and modifies the way it is called in some
- * fashion. The most common use of this facility is for C callbacks.
+ * Sets the meta marshaller of @closure.
+ *
+ * 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
- * the extra arguments for the duration of the callback. See
- * g_object_watch_closure() for an example of marshal guards.
+ * closure callback, respectively.
+ *
+ * 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
- * notifiers on a single closure are invoked in unspecified order. If
- * a single call to g_closure_unref() results in the closure being
- * both invalidated and finalized, then the invalidate notifiers will
- * be run before the finalize notifiers.
+ * reference count of @closure goes down to 0.
+ *
+ * Multiple finalization notifiers on a single closure are invoked in
+ * unspecified order. If a single call to g_closure_unref() results in
+ * 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
- * notifiers are invoked before finalization notifiers, in an
- * unspecified order.
+ * @closure is invalidated with g_closure_invalidate().
+ *
+ * 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
- * closure, then the closure will be destroyed and freed.
+ * incremented by the same caller.
+ *
+ * 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
- * initially created in a "floating" state, which means that the initial
- * reference count is not owned by any caller. g_closure_sink() checks
- * to see if the object is still floating, and if so, unsets the
- * floating state and decreases the reference count. If the 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:
+ * Takes over the initial ownership of a closure.
+ *
+ * Each closure is initially created in a "floating" state, which means
+ * that the initial reference count is not owned by any caller.
+ *
+ * This function checks to see if the object is still floating, and if so,
+ * unsets the floating state and decreases the reference count. If the
+ * 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`
- * of @marshal provides a way for a meta marshaller to provide additional
- * information to the marshaller. (See g_closure_set_meta_marshal().) For
- * GObject's C predefined marshallers (the g_cclosure_marshal_*()
+ * Sets the marshaller of @closure.
+ *
+ * The `marshal_data` of @marshal provides a way for a meta marshaller to
+ * 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,
diff --git a/gobject/gclosure.h b/gobject/gclosure.h
index 884e403a8..f30499e86 100644
--- a/gobject/gclosure.h
+++ b/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
- * 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
- * is connected). Use G_CALLBACK() to cast the callback function to a #GCallback.
+ * signatures.
+ *
+ * This doesn't mean that all callback functions must take no 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 is connected).
+ *
+ * Use G_CALLBACK() to cast the callback function to a #GCallback.
*/
typedef void (*GCallback) (void);
/**
diff --git a/gobject/gobject.c b/gobject/gobject.c
index a88682360..9776d7c95 100644
--- a/gobject/gobject.c
+++ b/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
- * 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
- * object's #GObjectClass.dispose method is called, every #GWeakRef
- * associated with becomes empty (i.e. points to %NULL).
+ * A structure containing a weak reference to a #GObject.
+ *
+ * A `GWeakRef` can either 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 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.
diff --git a/gobject/gobject.h b/gobject/gobject.h
index 86e2b7de1..f62f9c902 100644
--- a/gobject/gobject.h
+++ b/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
- * 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.
+ * triggered when the object is finalized.
+ *
+ * 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:
+ *
+ * The base object type.
*
- * All the fields in the GObject structure are private
- * 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
- * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
- * a #GObjectClass.
+ * The GObjectConstructParam struct is an auxiliary structure used to hand
+ * #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass.
*/
struct _GObjectConstructParam
{
@@ -369,10 +376,11 @@ struct _GObjectConstructParam
/**
* GInitiallyUnowned:
+ *
+ * A type for objects that have an initially floating reference.
*
- * All the fields in the GInitiallyUnowned structure
- * 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
- * reference count of @new_object (if non-%NULL), decrements 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.
+ * Updates a #GObject pointer to refer to @new_object.
+ *
+ * It increments the reference count of @new_object (if non-%NULL), decrements
+ * 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
- * 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.
+ * Updates a pointer to weakly refer to @new_object.
*
- * @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
diff --git a/gobject/gparam.c b/gobject/gparam.c
index 2c09f5bd6..b3e4c671f 100644
--- a/gobject/gparam.c
+++ b/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
- * system uses such a pool to store the #GParamSpecs of the properties all object
- * types.
+ * quickly accessed by owner and name.
+ *
+ * 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
- * #G_TYPE_PARAM. The type system uses the information contained in
- * the #GParamSpecTypeInfo structure pointed to by @info to manage the
- * #GParamSpec type and its instances.
+ * Registers @name as the name of a new static type derived
+ * from #G_TYPE_PARAM.
+ *
+ * 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.
*/
diff --git a/gobject/gparam.h b/gobject/gparam.h
index 7294ed515..367d4760f 100644
--- a/gobject/gparam.h
+++ b/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
diff --git a/gobject/gparamspecs.h b/gobject/gparamspecs.h
index 9aac2c423..78bf6b82b 100644
--- a/gobject/gparamspecs.h
+++ b/gobject/gparamspecs.h
@@ -922,12 +922,15 @@ struct _GParamSpecObject
};
/**
* GParamSpecOverride:
+ *
+ * A #GParamSpec derived structure that redirects operations to
+ * other types of #GParamSpec.
*
- * This is a type of #GParamSpec type that simply redirects operations to
- * another paramspec. All operations other than getting or
- * setting the value are redirected, including accessing the nick and
- * blurb, validating a value, and so forth. See
- * g_param_spec_get_redirect_target() for retrieving the overridden
+ * All operations other than getting or setting the value are redirected,
+ * 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.
diff --git a/gobject/gsignal.h b/gobject/gsignal.h
index b027f54c0..96e4eb38a 100644
--- a/gobject/gsignal.h
+++ b/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
- * mechanism takes over responsibility of actual function invocation for the
- * signal system.
+ * invocations.
+ *
+ * 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
- * allows you to tie a hook to the signal type, so that it will trap all
- * emissions of that signal, from any object.
+ * A simple function pointer to get invoked when the signal is emitted.
+ *
+ * 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
- * creation time, if it is 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.
+ * during a signal emission.
+ *
+ * The signal accumulator is specified at signal creation time, if it is
+ * 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
- * signal description outlines how especially the RUN flags control the
- * stages of a signal emission.
+ * The signal flags are used to specify a signal's behaviour.
*/
typedef enum
{
@@ -253,8 +256,9 @@ struct _GSignalInvocationHint
* gpointer data2);
* ]|
*
- * A structure holding in-depth information for a specific signal. It is
- * filled in by the g_signal_query() function.
+ * A structure holding in-depth information for a specific signal.
+ *
+ * See also: g_signal_query()
*/
struct _GSignalQuery
{
diff --git a/gobject/gtype.c b/gobject/gtype.c
index 422e1cae4..34f62ecba 100644
--- a/gobject/gtype.c
+++ b/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.
*
diff --git a/gobject/gtype.h b/gobject/gtype.h
index f80c4a580..874a7c00c 100644
--- a/gobject/gtype.h
+++ b/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
- * initialization process of all derived classes and should reallocate
- * or reset all dynamic class members copied over from the parent class.
+ * of the class structures of derived types.
+ *
+ * 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
- * way in which class initialization is performed.
+ * GBaseInitFunc() function.
+ *
+ * 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
- * members.
+ * of a specific type.
+ *
+ * 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
- * allocates any resources required by it.
+ * instance of a type.
+ *
+ * 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
- * allocate any resources required by the interface.
+ * 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
- * being freed. You should not call g_type_class_unref() from a
- * #GTypeClassCacheFunc function to prevent infinite recursion, use
- * g_type_class_unref_uncached() instead.
+ * drops to zero.
+ *
+ * It may use g_type_class_ref() to prevent the class from being freed. You
+ * 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
- * present time) intended to be subclassed.
+ * A convenience macro for emitting the usual declarations in the header file
+ * 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_
*
@@ -1623,7 +1647,8 @@ guint g_type_get_type_registration_serial (void);
* @T_P: The #GType of the parent type.
* @_C_: Custom code that gets inserted in the `*_get_type()` function.
*
- * A convenience macro for type implementations.
+ * 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.
*
@@ -1663,8 +1689,9 @@ guint g_type_get_type_registration_serial (void);
* separated by `_`.
* @T_P: The #GType of the parent type.
*
- * A convenience macro for type implementations.
- * Similar to G_DEFINE_TYPE(), but defines an abstract 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.
*
* Since: 2.4
@@ -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
@@ -1694,7 +1723,8 @@ guint g_type_get_type_registration_serial (void);
* separated by `_`.
* @T_P: The #GType of the parent type.
*
- * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract 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
- * G_DEFINE_INTERFACE(), but allows you to insert custom code into the
- * `*_get_type()` function, e.g. additional interface implementations
- * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See
- * G_DEFINE_TYPE_EXTENDED() for a similar example using
+ * A convenience macro for #GTypeInterface definitions.
+ *
+ * Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code
+ * into the `*_get_type()` function, e.g. additional interface implementations
+ * 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:
diff --git a/gobject/gtypemodule.c b/gobject/gtypemodule.c
index 014b5fc3c..1c2ab43ea 100644
--- a/gobject/gtypemodule.c
+++ b/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
- * which implements some number of types and interface implementations.
+ * interface.
+ *
+ * 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
- * caller's code being unloaded before g_object_unref() returns to it.
+ * reference cannot be released from within the module code, since that
+ * 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;
diff --git a/gobject/gtypemodule.h b/gobject/gtypemodule.h
index 5c4025063..400d7f1b0 100644
--- a/gobject/gtypemodule.h
+++ b/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,
- * it defines a `*_get_type()` and a static `*_register_type()` functions
- * for use in your `module_init()`.
+ * `t_n`_parent_class pointing to the parent class.
+ *
+ * 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()
- * for an example.
+ * of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
+ *
+ * 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
- * G_ADD_PRIVATE() for details, it is similar but for static types.
+ * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
+ *
+ * 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
diff --git a/gobject/gtypeplugin.c b/gobject/gtypeplugin.c
index eba85151d..30e38c1a9 100644
--- a/gobject/gtypeplugin.c
+++ b/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
- * of dynamically loaded types. It goes as follows:
+ * 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
diff --git a/gobject/gvalue.c b/gobject/gvalue.c
index 797aa186b..097755069 100644
--- a/gobject/gvalue.c
+++ b/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.
*
diff --git a/gobject/gvalue.h b/gobject/gvalue.h
index dc6e5ac3b..3630c0b53 100644
--- a/gobject/gvalue.h
+++ b/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;
* ]|
*
diff --git a/gobject/gvaluecollector.h b/gobject/gvaluecollector.h
index b1304595f..2714b36a7 100644
--- a/gobject/gvaluecollector.h
+++ b/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
- * implement the varargs collection as a macro, because on some systems
- * va_list variables cannot be passed by reference.
+ * Collects a variable argument value from a `va_list`.
+ *
+ * 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
- * implement the varargs collection as a macro, because on some systems
- * va_list variables cannot be passed by reference.
+ * Collects a variable argument value from a `va_list`.
+ *
+ * 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) \
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
