From f62622fc7b0254859d10b59c5d9a9cb65b59ce2e Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Sat, 31 Jul 2021 22:47:26 +0100 Subject: [PATCH] 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). * - * |[ + * Whenever the source property changes, the same value is applied to the + * target property; for instance, the following binding: + * + * |[ * 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: * - * |[ + * |[ * 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: * * |[ * 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: + * * |[ * 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: + * * |[ * 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: + * * |[ * 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: + * * |[ * 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: + * * |[ * 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: + * * |[ * 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: * - * |[ + * |[ * #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: * - * |[ + * |[ * #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: * - * |[ + * |[ * #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 + * * |[ * 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. * - * |[ + * |[ * 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 - * |[ + * + * |[ * 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. * - * |[ + * |[ * 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) \