luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-10-31 00:12:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Start stanzas with a single paragraph

Browse Source 
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
This commit is contained in:
Emmanuele Bassi
2021-07-31 22:47:26 +01:00
parent 069308ab54
commit f62622fc7b
19 changed files with 285 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
gobject/gbinding.c
View File

@@ -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);
* ]|
*

5
gobject/gbinding.h
View File

@@ -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,

16
gobject/gboxed.c
View File

@@ -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.
*/

92
gobject/gclosure.c
View File

@@ -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,

12
gobject/gclosure.h
View File

@@ -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);
/**

17
gobject/gobject.c
View File

@@ -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.

59
gobject/gobject.h
View File

@@ -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

17
gobject/gparam.c
View File

@@ -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.
*/

5
gobject/gparam.h
View File

@@ -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

13
gobject/gparamspecs.h
View File

@@ -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.

34
gobject/gsignal.h
View File

@@ -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
{

2
gobject/gtype.c
View File

@@ -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.
*

97
gobject/gtype.h
View File

@@ -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:

13
gobject/gtypemodule.c
View File

@@ -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;

23
gobject/gtypemodule.h
View File

@@ -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

5
gobject/gtypeplugin.c
View File

@@ -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

1
gobject/gvalue.c
View File

@@ -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.
*

5
gobject/gvalue.h
View File

@@ -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;
* ]|
*

18
gobject/gvaluecollector.h
View File

@@ -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) \