diff options
Diffstat (limited to 'gir/gobject-2.0.c')
| -rw-r--r-- | gir/gobject-2.0.c | 996 |
1 files changed, 454 insertions, 542 deletions
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index ab618f62..b25b8d0b 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -63,7 +63,7 @@ * 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) @@ -77,7 +77,7 @@ /** * GParamSpecPool: * - * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be + * 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. @@ -102,9 +102,9 @@ * objects. * * If the object's #GObjectClass.dispose method results in additional - * references to the object being held, any #GWeakRef<!-- -->s taken + * references to the object being held, any #GWeakRefs taken * before it was disposed will continue to point to %NULL. If - * #GWeakRef<!-- -->s are taken after the object is disposed and + * #GWeakRefs are taken after the object is disposed and * re-referenced, they will continue to point to it until its refcount * goes back to zero, at which point they too will be invalidated. */ @@ -146,21 +146,21 @@ * 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); * ]| * - * will cause <emphasis>object2:property-b</emphasis> to be updated every - * time g_object_set() or the specific accessor changes the value of - * <emphasis>object1:property-a</emphasis>. + * will cause the property named "property-b" of @object2 to be updated + * every time g_object_set() or the specific accessor changes the value of + * the property "property-a" of @object1. * * It is possible to create a bidirectional binding between two properties * of two #GObject instances, so that if either property changes, the * other is updated as well, for instance: * - * |[ + * |[<!-- language="C" --> * g_object_bind_property (object1, "property-a", * object2, "property-b", * G_BINDING_BIDIRECTIONAL); @@ -173,7 +173,7 @@ * transformation from the source value to the target value before * applying it; for instance, the following binding: * - * |[ + * |[<!-- language="C" --> * g_object_bind_property_full (adjustment1, "value", * adjustment2, "value", * G_BINDING_BIDIRECTIONAL, @@ -182,15 +182,15 @@ * NULL, NULL); * ]| * - * will keep the <emphasis>value</emphasis> property of the two adjustments - * in sync; the <function>celsius_to_fahrenheit</function> function will be - * called whenever the <emphasis>adjustment1:value</emphasis> property changes - * and will transform the current value of the property before applying it - * to the <emphasis>adjustment2:value</emphasis> property; vice versa, the - * <function>fahrenheit_to_celsius</function> function will be called whenever - * the <emphasis>adjustment2:value</emphasis> property changes, and will - * transform the current value of the property before applying it to the - * <emphasis>adjustment1:value</emphasis>. + * will keep the "value" property of the two adjustments in sync; the + * @celsius_to_fahrenheit function will be called whenever the "value" + * property of @adjustment1 changes and will transform the current value + * of the property before applying it to the "value" property of @adjustment2. + * + * Vice versa, the @fahrenheit_to_celsius function will be called whenever + * the "value" property of @adjustment2 changes, and will transform the + * current value of the property before applying it to the "value" property + * of @adjustment1. * * Note that #GBinding does not resolve cycles by itself; a cycle like * @@ -211,10 +211,10 @@ * either one of the #GObject instances it refers to are finalized, or when * the #GBinding instance loses its last reference. * - * <note><para>Bindings for languages with garbage collection can use + * Bindings for languages with garbage collection can use * g_binding_unbind() to explicitly release a binding between the source * and target properties, instead of relying on the last reference on the - * binding, source, and target instances to drop.</para></note> + * binding, source, and target instances to drop. * * #GBinding is available since GObject 2.26 */ @@ -245,13 +245,13 @@ * 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 reponsibility of the marshaller to - * convert the arguments for the invocation from #GValue<!-- -->s into + * convert the arguments for the invocation from #GValues into * a suitable form, perform the callback on the converted arguments, * and transform the return value back into a #GValue. * * In the case of C programs, a closure usually just holds a pointer * to a function and maybe a data argument, and the marshaller - * converts between #GValue<!-- --> and native C types. The GObject + * converts between #GValue and native C types. The GObject * library provides the #GCClosure type for this purpose. Bindings for * other languages need marshallers which convert between #GValue<!-- * -->s and suitable representations in the runtime of the language in @@ -273,22 +273,17 @@ * * Using closures has a number of important advantages over a simple * callback function/data pointer combination: - * <itemizedlist> - * <listitem><para> - * Closures allow the callee to get the types of the callback parameters, - * which means that language bindings don't have to write individual glue - * for each callback type. - * </para></listitem> - * <listitem><para> - * The reference counting of #GClosure makes it easy to handle reentrancy - * right; if a callback is removed while it is being invoked, the closure - * and its parameters won't be freed until the invocation finishes. - * </para></listitem> - * <listitem><para> - * g_closure_invalidate() and invalidation notifiers allow callbacks to be - * automatically removed when the objects they point to go away. - * </para></listitem> - * </itemizedlist> + * + * - Closures allow the callee to get the types of the callback parameters, + * which means that language bindings don't have to write individual glue + * for each callback type. + * + * - The reference counting of #GClosure makes it easy to handle reentrancy + * right; if a callback is removed while it is being invoked, the closure + * and its parameters won't be freed until the invocation finishes. + * + * - g_closure_invalidate() and invalidation notifiers allow callbacks to be + * automatically removed when the objects they point to go away. */ @@ -318,8 +313,8 @@ * The code in the example program below demonstrates #GValue's * features. * - * |[ - * #include <glib-object.h> + * |[<!-- language="C" --> + * #include <glib-object.h> * * static void * int2string (const GValue *src_value, @@ -341,34 +336,34 @@ * const gchar *message; * * /* The GValue starts empty */ - * g_assert (!G_VALUE_HOLDS_STRING (&a)); + * g_assert (!G_VALUE_HOLDS_STRING (&a)); * * /* Put a string in it */ - * g_value_init (&a, G_TYPE_STRING); - * g_assert (G_VALUE_HOLDS_STRING (&a)); - * g_value_set_static_string (&a, "Hello, world!"); - * g_printf ("%s\n", g_value_get_string (&a)); + * g_value_init (&a, G_TYPE_STRING); + * g_assert (G_VALUE_HOLDS_STRING (&a)); + * g_value_set_static_string (&a, "Hello, world!"); + * g_printf ("%s\n", g_value_get_string (&a)); * * /* Reset it to its pristine state */ - * g_value_unset (&a); + * g_value_unset (&a); * * /* It can then be reused for another type */ - * g_value_init (&a, G_TYPE_INT); - * g_value_set_int (&a, 42); + * g_value_init (&a, G_TYPE_INT); + * g_value_set_int (&a, 42); * * /* Attempt to transform it into a GValue of type STRING */ - * g_value_init (&b, G_TYPE_STRING); + * g_value_init (&b, G_TYPE_STRING); * * /* An INT is transformable to a STRING */ * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); * - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); * * /* Attempt to transform it again using a custom transform function */ * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); * return 0; * } * ]| @@ -386,13 +381,13 @@ * #GParamSpec is an object structure that encapsulates the metadata * required to specify parameters, such as e.g. #GObject properties. * - * <para id="canonical-parameter-name"> - * Parameter names need to start with a letter (a-z or A-Z). Subsequent - * characters can be letters, numbers or a '-'. + * ## Parameter names # {#canonical-parameter-names} + * + * Parameter names need to start with a letter (a-z or A-Z). + * Subsequent characters can be letters, numbers or a '-'. * All other characters are replaced by a '-' during construction. - * The result of this replacement is called the canonical name of the - * parameter. - * </para> + * The result of this replacement is called the canonical name of + * the parameter. */ @@ -411,15 +406,18 @@ * unloaded at run-time as dynamic types may be. Static types are created * with g_type_register_static() that gets type specific information passed * in via a #GTypeInfo structure. + * * Dynamic types are created with g_type_register_dynamic() which takes a * #GTypePlugin structure instead. The remaining type information (the * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin * and the g_type_plugin_*() API. + * * These registration functions are usually called only once from a * function whose only purpose is to return the type identifier for a * specific class. Once the type (or class or interface) is registered, * it may be instantiated, inherited, or implemented depending on exactly * what sort of type it is. + * * There is also a third registration function for registering fundamental * types called g_type_register_fundamental() which requires both a #GTypeInfo * structure and a #GTypeFundamentalInfo structure but it is seldom used @@ -432,41 +430,30 @@ * separately (typically by using #GArray or #GPtrArray) and put a pointer * to the buffer in the structure. * - * A final word about type names. - * Such an identifier needs to be at least three characters long. There is no - * upper length limit. The first character needs to be a letter (a-z or A-Z) - * or an underscore '_'. Subsequent characters can be letters, numbers or - * any of '-_+'. + * A final word about type names: Such an identifier needs to be at least + * three characters long. There is no upper length limit. The first character + * needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent + * characters can be letters, numbers or any of '-_+'. */ /** * SECTION:gtypemodule * @short_description: Type loading modules - * @see_also: <variablelist> - * <varlistentry> - * <term>#GTypePlugin</term> - * <listitem><para>The abstract type loader interface.</para></listitem> - * </varlistentry> - * <varlistentry> - * <term>#GModule</term> - * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> - * </varlistentry> - * </variablelist> + * @see_also: #GTypePlugin, #GModule * @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. 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. + * 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. * * 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 @@ -491,49 +478,40 @@ * @see_also: #GTypeModule and g_type_register_dynamic(). * @title: GTypePlugin * - * 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: - * - * <orderedlist> - * <listitem><para> - * The type is initially introduced (usually upon loading the module - * the first time, or by your main application that knows what modules - * introduces what types), like this: - * |[ - * new_type_id = g_type_register_dynamic (parent_type_id, - * "TypeName", - * new_type_plugin, - * type_flags); - * ]| - * where <literal>new_type_plugin</literal> is an implementation of the - * #GTypePlugin interface. - * </para></listitem> - * <listitem><para> - * The type's implementation is referenced, e.g. through + * 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: + * + * 1. The type is initially introduced (usually upon loading the module + * the first time, or by your main application that knows what modules + * introduces what types), like this: + * |[<!-- language="C" --> + * new_type_id = g_type_register_dynamic (parent_type_id, + * "TypeName", + * new_type_plugin, + * type_flags); + * ]| + * where @new_type_plugin is an implementation of the + * #GTypePlugin interface. + * + * 2. The type's implementation is referenced, e.g. through * g_type_class_ref() or through g_type_create_instance() (this is * being called by g_object_new()) or through one of the above done on - * a type derived from <literal>new_type_id</literal>. - * </para></listitem> - * <listitem><para> - * This causes the type system to load the type's implementation by calling - * g_type_plugin_use() and g_type_plugin_complete_type_info() on - * <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * At some point the type's implementation isn't required anymore, e.g. after - * g_type_class_unref() or g_type_free_instance() (called when the reference - * count of an instance drops to zero). - * </para></listitem> - * <listitem><para> - * This causes the type system to throw away the information retrieved from - * g_type_plugin_complete_type_info() and then it calls - * g_type_plugin_unuse() on <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * Things may repeat from the second step. - * </para></listitem> - * </orderedlist> + * a type derived from @new_type_id. + * + * 3. This causes the type system to load the type's implementation by + * calling g_type_plugin_use() and g_type_plugin_complete_type_info() + * on @new_type_plugin. + * + * 4. At some point the type's implementation isn't required anymore, + * e.g. after g_type_class_unref() or g_type_free_instance() (called + * when the reference count of an instance drops to zero). + * + * 5. This causes the type system to throw away the information retrieved + * from g_type_plugin_complete_type_info() and then it calls + * g_type_plugin_unuse() on @new_type_plugin. + * + * 6. Things may repeat from the second step. * * So basically, you need to implement a #GTypePlugin type that * carries a use_count, once use_count goes from zero to one, you need @@ -563,45 +541,45 @@ * support. Signals are described in detail in <xref * linkend="gobject-Signals"/>. * - * <para id="floating-ref"> + * ## Floating references # {#floating-ref} + * * GInitiallyUnowned is derived from GObject. The only difference between * the two is that the initial reference of a GInitiallyUnowned is flagged - * as a <firstterm>floating</firstterm> reference. - * This means that it is not specifically 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: - * |[ + * as a "floating" reference. This means that it is not specifically + * 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 <function>container_add_child()</function> will g_object_ref_sink() the - * passed in child, no reference of the newly created child is leaked. - * Without floating references, <function>container_add_child()</function> - * can only g_object_ref() the new child, so to implement this code without - * reference leaks, it would have to be written as: - * |[ + * 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 (); * child = create_child (); * 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 to g_object_ref() and returns - * a new reference. + * 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 + * to g_object_ref() and returns a new reference. + * * Since floating references are useful almost exclusively for C convenience, * language bindings that provide automated reference and memory ownership * maintenance (such as smart pointers or garbage collection) should not * expose floating references in their API. - * </para> * * Some object implementations may need to save an objects floating state * across certain code portions (an example is #GtkMenu), to achieve this, * the following sequence can be used: * - * |[ + * |[<!-- language="C" --> * /* save floating state */ * gboolean was_floating = g_object_is_floating (object); * g_object_ref_sink (object); @@ -642,58 +620,56 @@ * and a general purpose notification mechanism * @title: Signals * - * The basic concept of the signal system is that of the - * <emphasis>emission</emphasis> of a signal. Signals are introduced - * per-type and are identified through strings. Signals introduced - * for a parent type are available in derived types as well, so - * basically they are a per-type facility that is inherited. A signal - * emission mainly involves invocation of a certain set of callbacks - * in precisely defined manner. There are two main categories of such - * callbacks, per-object - * <footnote><para>Although signals can deal with any kind of instantiatable - * type, i'm referring to those types as "object types" in the following, - * simply because that is the context most users will encounter signals in. - * </para></footnote> - * ones and user provided ones. + * The basic concept of the signal system is that of the emission + * of a signal. Signals are introduced per-type and are identified + * through strings. Signals introduced for a parent type are available + * in derived types as well, so basically they are a per-type facility + * that is inherited. + * + * A signal emission mainly involves invocation of a certain set of + * callbacks in precisely defined manner. There are two main categories + * of such callbacks, per-object ones and user provided ones. + * (Although signals can deal with any kind of instantiatable type, I'm + * referring to those types as "object types" in the following, simply + * because that is the context most users will encounter signals in.) * The per-object callbacks are most often referred to as "object method * handler" or "default (signal) handler", while user provided callbacks are * usually just called "signal handler". + * * The object method handler is provided at signal creation time (this most * frequently happens at the end of an object class' creation), while user - * provided handlers are frequently connected and disconnected to/from a certain - * signal on certain object instances. + * provided handlers are frequently connected and disconnected to/from a + * certain signal on certain object instances. * * A signal emission consists of five stages, unless prematurely stopped: - * <variablelist> - * <varlistentry><term></term><listitem><para> - * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * </para></listitem></varlistentry> - * </variablelist> + * + * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + * + * 2. Invocation of normal user-provided signal handlers (where the @after + * flag is not set) + * + * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + * + * 4. Invocation of user provided signal handlers (where the @after flag is set) + * + * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + * * The user-provided signal handlers are called in the order they were * connected in. + * * All handlers may prematurely stop a signal emission, and any number of * handlers may be connected, disconnected, blocked or unblocked during * a signal emission. + * * There are certain criteria for skipping user handlers in stages 2 and 4 * of a signal emission. - * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted - * during callback invocation, to return from the "blocked" state, a - * handler has to get unblocked exactly the same amount of times - * it has been blocked before. + * + * First, user handlers may be blocked. Blocked handlers are omitted during + * callback invocation, to return from the blocked state, a handler has to + * get unblocked exactly the same amount of times it has been blocked before. + * * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional - * "detail" argument passed in to g_signal_emit() has to match the detail + * @detail argument passed in to g_signal_emit() has to match the detail * argument of the signal handler currently subject to invocation. * Specification of no detail argument for signal handlers (omission of the * detail part of the signal specification upon connection) serves as a @@ -719,13 +695,13 @@ * g_value_unset() as the clear function using g_array_set_clear_func(), * for instance, the following code: * - * |[ + * |[<!-- language="C" --> * GValueArray *array = g_value_array_new (10); * ]| * * can be replaced by: * - * |[ + * |[<!-- language="C" --> * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); * ]| @@ -736,7 +712,7 @@ * g_binding_get_flags: * @binding: a #GBinding * - * Retrieves the flags passed when constructing the #GBinding + * Retrieves the flags passed when constructing the #GBinding. * * Returns: the #GBindingFlags used by the #GBinding * Since: 2.26 @@ -747,7 +723,7 @@ * g_binding_get_source: * @binding: a #GBinding * - * Retrieves the #GObject instance used as the source of the binding + * Retrieves the #GObject instance used as the source of the binding. * * Returns: (transfer none): the source #GObject * Since: 2.26 @@ -759,7 +735,7 @@ * @binding: a #GBinding * * Retrieves the name of the property of #GBinding:source used as the source - * of the binding + * of the binding. * * Returns: the name of the source property * Since: 2.26 @@ -770,7 +746,7 @@ * g_binding_get_target: * @binding: a #GBinding * - * Retrieves the #GObject instance used as the target of the binding + * Retrieves the #GObject instance used as the target of the binding. * * Returns: (transfer none): the target #GObject * Since: 2.26 @@ -782,7 +758,7 @@ * @binding: a #GBinding * * Retrieves the name of the property of #GBinding:target used as the target - * of the binding + * of the binding. * * Returns: the name of the target property * Since: 2.26 @@ -796,10 +772,10 @@ * Explicitly releases the binding between the source and the target * property expressed by @binding. * - * <note>This function will release the reference that is being held on + * This function will release the reference that is being held on * the @binding instance; if you want to hold on to the #GBinding instance * after calling g_binding_unbind(), you will need to hold a reference - * to it.</note> + * to it. * * Since: 2.38 */ @@ -850,7 +826,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter + * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter * denotes a flags type. */ @@ -866,7 +842,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)</literal>. + * `gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)`. * * Since: 2.26 */ @@ -890,7 +866,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>. + * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. */ @@ -905,7 +881,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. */ @@ -920,7 +896,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. */ @@ -935,7 +911,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. */ @@ -950,7 +926,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. */ @@ -965,7 +941,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type.. + * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. */ @@ -980,7 +956,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type. + * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. */ @@ -995,7 +971,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. */ @@ -1010,7 +986,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. */ @@ -1025,7 +1001,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. */ @@ -1040,7 +1016,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. */ @@ -1055,7 +1031,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. */ @@ -1070,7 +1046,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. */ @@ -1085,7 +1061,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. */ @@ -1100,7 +1076,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. */ @@ -1115,7 +1091,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. */ @@ -1130,7 +1106,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. */ @@ -1145,7 +1121,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. */ @@ -1160,7 +1136,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. * * Since: 2.26 */ @@ -1177,7 +1153,7 @@ * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>. + * `void (*callback) (gpointer instance, gpointer user_data)`. */ @@ -1187,7 +1163,7 @@ * @return_gvalue: A #GValue to store the return value. May be %NULL * if the callback of closure doesn't return a value. * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValue<!-- -->s holding the arguments + * @param_values: An array of #GValues holding the arguments * on which to invoke the callback of closure. * @invocation_hint: The invocation hint given as the last argument to * g_closure_invoke(). @@ -1195,8 +1171,8 @@ * marshaller, see g_closure_set_marshal() and * g_closure_set_meta_marshal() * - * A generic marshaller function implemented via <ulink - * url="http://sourceware.org/libffi/">libffi</ulink>. + * A generic marshaller function implemented via + * [libffi](http://sourceware.org/libffi/). * * Since: 2.30 */ @@ -1351,7 +1327,7 @@ * doesn't return a value. * @n_param_values: the length of the @param_values array * @param_values: (array length=n_param_values): an array of - * #GValue<!-- -->s holding the arguments on which to + * #GValues holding the arguments on which to * invoke the callback of @closure * @invocation_hint: (allow-none): a context-dependent invocation hint * @@ -1362,7 +1338,7 @@ /** * g_closure_new_object: * @sizeof_closure: the size of the structure to allocate, must be at least - * <literal>sizeof (GClosure)</literal> + * `sizeof (GClosure)` * @object: a #GObject pointer to store in the @data field of the newly * allocated #GClosure * @@ -1378,19 +1354,19 @@ /** * g_closure_new_simple: * @sizeof_closure: the size of the structure to allocate, must be at least - * <literal>sizeof (GClosure)</literal> + * `sizeof (GClosure)` * @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. * - * |[ + * |[<!-- language="C" --> * typedef struct _MyClosure MyClosure; * struct _MyClosure * { * GClosure closure; - * // extra data goes here + * /* extra data goes here */ * }; * * static void @@ -1399,7 +1375,7 @@ * { * MyClosure *my_closure = (MyClosure *)closure; * - * // free extra data here + * /* free extra data here */ * } * * MyClosure *my_closure_new (gpointer data) @@ -1410,7 +1386,7 @@ * closure = g_closure_new_simple (sizeof (MyClosure), data); * my_closure = (MyClosure *) closure; * - * // initialize extra data here + * /* initialize extra data here */ * * g_closure_add_finalize_notifier (closure, notify_data, * my_closure_finalize); @@ -1464,7 +1440,7 @@ * @closure: a #GClosure * @marshal: a #GClosureMarshal function * - * Sets the marshaller of @closure. The <literal>marshal_data</literal> + * 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_*() @@ -1503,27 +1479,27 @@ * still being held * * Takes over the initial ownership of a closure. Each closure is - * initially created in a <firstterm>floating</firstterm> 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: - * |[ + * 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: + * |[<!-- language="C" --> * closure = g_cclosure_new (cb_func, cb_data); * g_source_set_closure (source, closure); - * g_closure_unref (closure); // XXX GObject doesn't really need this + * 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(). Ane example * of storing a closure for later notification looks like: - * |[ + * |[<!-- language="C" --> * static GClosure *notify_closure = NULL; * void * foo_notify_set_closure (GClosure *closure) @@ -1563,11 +1539,11 @@ * enumeration values. The array is terminated by a struct with all * members being 0. * - * This function is meant to be called from the <literal>complete_type_info</literal> + * This function is meant to be called from the `complete_type_info` * function of a #GTypePlugin implementation, as in the following * example: * - * |[ + * |[<!-- language="C" --> * static void * my_enum_complete_type_info (GTypePlugin *plugin, * GType g_type, @@ -1735,8 +1711,8 @@ * to the proxy object, but when there are other references held to * @object, a strong reference is held. The @notify callback is called * when the reference from @object to the proxy object should be - * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref - * true) or weak to strong (@is_last_ref false). + * "toggled" from strong to weak (@is_last_ref true) or weak to strong + * (@is_last_ref false). * * Since a (normal) reference must be held to the object before * calling g_object_add_toggle_ref(), the initial state of the reverse @@ -1801,8 +1777,8 @@ * A #GObject can have multiple bindings. * * Returns: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * Since: 2.26 */ @@ -1815,13 +1791,13 @@ * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding * @transform_to: (scope notified) (allow-none): the transformation function - * from the @source to the @target, or %NULL to use the default + * from the @source to the @target, or %NULL to use the default * @transform_from: (scope notified) (allow-none): the transformation function - * from the @target to the @source, or %NULL to use the default + * from the @target to the @source, or %NULL to use the default * @user_data: custom data to be passed to the transformation functions, - * or %NULL + * or %NULL * @notify: function to be called when disposing the binding, to free the - * resources used by the transformation functions + * resources used by the transformation functions * * Complete version of g_object_bind_property(). * @@ -1841,15 +1817,15 @@ * * A #GObject can have multiple bindings. * - * <note>The same @user_data parameter will be used for both @transform_to + * The same @user_data parameter will be used for both @transform_to * and @transform_from transformation functions; the @notify function will * be called once, when the binding is removed. If you need different data * for each transformation function, please use - * g_object_bind_property_with_closures() instead.</note> + * g_object_bind_property_with_closures() instead. * * Returns: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * Since: 2.26 */ @@ -1862,21 +1838,21 @@ * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding * @transform_to: a #GClosure wrapping the transformation function - * from the @source to the @target, or %NULL to use the default + * from the @source to the @target, or %NULL to use the default * @transform_from: a #GClosure wrapping the transformation function - * from the @target to the @source, or %NULL to use the default + * from the @target to the @source, or %NULL to use the default * * Creates a binding between @source_property on @source and @target_property * on @target, allowing you to set the transformation functions to be used by * the binding. * * This function is the language bindings friendly version of - * g_object_bind_property_full(), using #GClosure<!-- -->s instead of + * g_object_bind_property_full(), using #GClosures instead of * function pointers. * * Returns: (transfer none): the #GBinding instance representing the - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * Since: 2.26 */ @@ -1896,11 +1872,11 @@ /** * g_object_class_install_properties: * @oclass: a #GObjectClass - * @n_pspecs: the length of the #GParamSpec<!-- -->s array - * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array + * @n_pspecs: the length of the #GParamSpecs array + * @pspecs: (array length=n_pspecs): the #GParamSpecs array * defining the new properties * - * Installs new properties from an array of #GParamSpec<!-- -->s. This is + * Installs new properties from an array of #GParamSpecs. This is * usually done in the class initializer. * * The property id of each property is the index of each #GParamSpec in @@ -1910,10 +1886,10 @@ * be used to store a #GParamSpec. * * This function should be used if you plan to use a static array of - * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this + * #GParamSpecs and g_object_notify_by_pspec(). For instance, this * class initialization: * - * |[ + * |[<!-- language="C" --> * enum { * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES * }; @@ -1946,7 +1922,7 @@ * * allows calling g_object_notify_by_pspec() to notify of property changes: * - * |[ + * |[<!-- language="C" --> * void * my_object_set_foo (MyObject *self, gint foo) * { @@ -1995,13 +1971,12 @@ * @name: the name of a property registered in a parent class or * in an interface of this class. * - * Registers @property_id as referring to a property with the - * name @name in a parent class or in an interface implemented - * by @oclass. This allows this class to <firstterm>override</firstterm> - * a property implementation in a parent class or to provide - * the implementation of a property from an interface. + * Registers @property_id as referring to a property with the name + * @name in a parent class or in an interface implemented by @oclass. + * This allows this class to "override" a property implementation in + * a parent class or to provide the implementation of a property from + * an interface. * - * <note> * Internally, overriding is implemented by creating a property of type * #GParamSpecOverride; generally operations that query the properties of * the object class, such as g_object_class_find_property() or @@ -2012,7 +1987,6 @@ * correct. For virtually all uses, this makes no difference. If you * need to get the overridden property, you can call * g_param_spec_get_redirect_target(). - * </note> * * Since: 2.4 */ @@ -2030,72 +2004,23 @@ * * The signal specs expected by this function have the form * "modifier::signal_name", where modifier can be one of the following: - * <variablelist> - * <varlistentry> - * <term>signal</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_data (..., NULL, 0)</literal> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>object_signal</term> - * <term>object-signal</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_object (..., 0)</literal> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>swapped_signal</term> - * <term>swapped-signal</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)</literal> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>swapped_object_signal</term> - * <term>swapped-object-signal</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>signal_after</term> - * <term>signal-after</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_AFTER)</literal> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>object_signal_after</term> - * <term>object-signal-after</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>swapped_signal_after</term> - * <term>swapped-signal-after</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal> - * </para></listitem> - * </varlistentry> - * <varlistentry> - * <term>swapped_object_signal_after</term> - * <term>swapped-object-signal-after</term> - * <listitem><para> - * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal> - * </para></listitem> - * </varlistentry> - * </variablelist> - * - * |[ + * * - signal: equivalent to g_signal_connect_data (..., NULL, 0) + * - object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) + * - swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) + * - swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) + * - signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) + * - object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) + * - swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) + * - swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) + * + * |[<!-- language="C" --> * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, * "type", GTK_WINDOW_POPUP, * "child", menu, * NULL), * "signal::event", gtk_menu_window_event, menu, * "signal::size_request", gtk_menu_window_size_request, menu, - * "signal::destroy", gtk_widget_destroyed, &menu->toplevel, + * "signal::destroy", gtk_widget_destroyed, &menu->toplevel, * NULL); * ]| * @@ -2187,7 +2112,7 @@ * This function is intended for #GObject implementations to re-enforce a * <link linkend="floating-ref">floating</link> object reference. * Doing this is seldom required: all - * #GInitiallyUnowned<!-- -->s are created with a floating reference which + * #GInitiallyUnowneds are created with a floating reference which * usually just needs to be sunken by calling g_object_ref_sink(). * * Since: 2.10 @@ -2223,12 +2148,9 @@ * is responsible for freeing the memory in the appropriate manner for * the type, for instance by calling g_free() or g_object_unref(). * - * <example> - * <title>Using g_object_get(<!-- -->)</title> - * An example of using g_object_get() to get the contents - * of three properties - one of type #G_TYPE_INT, - * one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT: - * <programlisting> + * Here is an example of using g_object_get() to get the contents + * of three properties: an integer, a string and an object: + * |[<!-- language="C" --> * gint intval; * gchar *strval; * GObject *objval; @@ -2239,12 +2161,11 @@ * "obj-property", &objval, * NULL); * - * // Do something with intval, strval, objval + * /* Do something with intval, strval, objval */ * * g_free (strval); * g_object_unref (objval); - * </programlisting> - * </example> + * ]| */ @@ -2463,7 +2384,7 @@ * instead, is to store the GParamSpec used with * g_object_class_install_property() inside a static array, e.g.: * - * |[ + * |[<!-- language="C" --> * enum * { * PROP_0, @@ -2488,7 +2409,7 @@ * * and then notify a change on the "foo" property with: * - * |[ + * |[<!-- language="C" --> * g_object_notify_by_pspec (self, properties[PROP_FOO]); * ]| * @@ -2741,7 +2662,7 @@ * set). * Usually, calling this function is only required to update * user data pointers with a destroy notifier, for example: - * |[ + * |[<!-- language="C" --> * void * object_add_to_user_list (GObject *object, * const gchar *new_string) @@ -3119,7 +3040,7 @@ * efficient and in fact required when using property names as detail * strings for signals. * - * Beyond the name, #GParamSpec<!-- -->s have two more descriptive + * Beyond the name, #GParamSpecs have two more descriptive * strings associated with them, the @nick, which should be suitable * for use as a label for the property in a property editor, and the * @blurb, which should be a somewhat longer description, suitable for @@ -3226,7 +3147,7 @@ * @owner_type: the owner to look for * @n_pspecs_p: (out): return location for the length of the returned array * - * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in + * Gets an array of all #GParamSpecs owned by @owner_type in * the pool. * * Returns: (array length=n_pspecs_p) (transfer container): a newly @@ -3240,12 +3161,12 @@ * @pool: a #GParamSpecPool * @owner_type: the owner to look for * - * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in + * Gets an #GList of all #GParamSpecs owned by @owner_type in * the pool. * * Returns: (transfer container) (element-type GObject.ParamSpec): a - * #GList of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool#GParamSpec<!-- -->s. + * #GList of all #GParamSpecs owned by @owner_type in + * the pool#GParamSpecs. */ @@ -3333,7 +3254,7 @@ * be freed * * This function works like g_param_spec_set_qdata(), but in addition, - * a <literal>void (*destroy) (gpointer)</literal> function may be + * a `void (*destroy) (gpointer)` function may be * specified which is called with @data as argument when the @pspec is * finalized, or the data is being overwritten by a call to * g_param_spec_set_qdata() with the same @quark. @@ -3347,8 +3268,8 @@ * The initial reference count of a newly created #GParamSpec is 1, * even though no one has explicitly called g_param_spec_ref() on it * yet. So the initial reference count is flagged as "floating", until - * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink - * (pspec);</literal> in sequence on it, taking over the initial + * someone calls `g_param_spec_ref (pspec); g_param_spec_sink + * (pspec);` in sequence on it, taking over the initial * reference count (thus ending up with a @pspec that has a reference * count of 1 still, but is not flagged "floating" anymore). */ @@ -3655,8 +3576,8 @@ * that a return of %TRUE stops the signal emission: no further * callbacks will be invoked, while a return of %FALSE allows * the emission to continue. The idea here is that a %TRUE return - * indicates that the callback <emphasis>handled</emphasis> the signal, - * and no further handling is needed. + * indicates that the callback handled the signal, and no further + * handling is needed. * * Since: 2.4 * Returns: standard #GSignalAccumulator result @@ -3750,8 +3671,8 @@ * Connects a #GCallback function to a signal for a particular object. Similar * to g_signal_connect(), but allows to provide a #GClosureNotify for the data * which will be called when the signal handler is disconnected and no longer - * used. Specify @connect_flags if you need <literal>..._after()</literal> or - * <literal>..._swapped()</literal> variants of this function. + * used. Specify @connect_flags if you need `..._after()` or + * `..._swapped()` variants of this function. * * Returns: the handler id (always greater than 0 for successful connections) */ @@ -4104,9 +4025,8 @@ * be used, but they cannot be mixed. * * If 0 is used for @class_offset subclasses cannot override the class handler - * in their <code>class_init</code> method by doing - * <code>super_class->signal_handler = my_signal_handler</code>. Instead they - * will have to use g_signal_override_class_handler(). + * in their class_init method by doing super_class->signal_handler = my_signal_handler. + * Instead they will have to use g_signal_override_class_handler(). * * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as * the marshaller for this signal. @@ -4397,8 +4317,8 @@ /** * g_type_add_class_private: - * @class_type: GType of an classed type. - * @private_size: size of private structure. + * @class_type: GType of an classed type + * @private_size: size of private structure * * Registers a private class structure for a classed type; * when the class is allocated, the private structures for @@ -4417,14 +4337,14 @@ * g_type_add_interface_check: (skip) * @check_data: data to pass to @check_func * @check_func: function to be called after each interface - * is initialized. + * is initialized * * Adds a function to be called after an interface vtable is - * initialized for any class (i.e. after the @interface_init member of - * #GInterfaceInfo has been called). + * initialized for any class (i.e. after the @interface_init + * member of #GInterfaceInfo has been called). * - * This function is useful when you want to check an invariant that - * depends on the interfaces of a class. For instance, the + * This function is useful when you want to check an invariant + * that depends on the interfaces of a class. For instance, the * implementation of #GObject uses this facility to check that an * object implements all of the properties that are defined on its * interfaces. @@ -4435,9 +4355,9 @@ /** * g_type_add_interface_dynamic: - * @instance_type: the #GType value of an instantiable type. - * @interface_type: the #GType value of an interface type. - * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. + * @instance_type: #GType value of an instantiable type + * @interface_type: #GType value of an interface type + * @plugin: #GTypePlugin structure to retrieve the #GInterfaceInfo from * * Adds the dynamic @interface_type to @instantiable_type. The information * contained in the #GTypePlugin structure pointed to by @plugin @@ -4447,46 +4367,46 @@ /** * g_type_add_interface_static: - * @instance_type: #GType value of an instantiable type. - * @interface_type: #GType value of an interface type. - * @info: The #GInterfaceInfo structure for this - * (@instance_type, @interface_type) combination. + * @instance_type: #GType value of an instantiable type + * @interface_type: #GType value of an interface type + * @info: #GInterfaceInfo structure for this + * (@instance_type, @interface_type) combination * - * Adds the static @interface_type to @instantiable_type. The - * information contained in the #GInterfaceInfo structure pointed to by - * @info is used to manage the relationship. + * Adds the static @interface_type to @instantiable_type. + * The information contained in the #GInterfaceInfo structure + * pointed to by @info is used to manage the relationship. */ /** * g_type_check_instance: - * @instance: A valid #GTypeInstance structure. + * @instance: a valid #GTypeInstance structure * - * Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() - * macro. + * Private helper function to aid implementation of the + * G_TYPE_CHECK_INSTANCE() macro. * - * Returns: %TRUE if @instance is valid, %FALSE otherwise. + * Returns: %TRUE if @instance is valid, %FALSE otherwise */ /** * g_type_children: - * @type: The parent type. - * @n_children: (out) (allow-none): Optional #guint pointer to contain - * the number of child types. + * @type: the parent type + * @n_children: (out) (allow-none): location to store the length of + * the returned array, or %NULL * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * child types of @type. The return value has to be g_free()ed after use. + * Return a newly allocated and 0-terminated array of type IDs, listing + * the child types of @type. * * Returns: (array length=n_children) (transfer full): Newly allocated - * and 0-terminated array of child types. + * and 0-terminated array of child types, free with g_free() */ /** * g_type_class_add_private: * @g_class: class structure for an instantiatable type - * @private_size: size of private structure. + * @private_size: size of private structure * * Registers a private structure for an instantiatable type. * @@ -4503,14 +4423,13 @@ * G_TYPE_INSTANCE_GET_PRIVATE() macro. * * The following example shows attaching a private structure - * <structname>MyObjectPrivate</structname> to an object - * <structname>MyObject</structname> defined in the standard GObject - * fashion. - * type's class_init() function. + * MyObjectPrivate to an object MyObject defined in the standard + * GObject fashion in the type's class_init() function. + * * Note the use of a structure member "priv" to avoid the overhead * of repeatedly calling MY_OBJECT_GET_PRIVATE(). * - * |[ + * |[<!-- language="C" --> * typedef struct _MyObject MyObject; * typedef struct _MyObjectPrivate MyObjectPrivate; * @@ -4575,71 +4494,69 @@ /** * g_type_class_peek: - * @type: Type ID of a classed type. + * @type: type ID of a classed type * - * This function is essentially the same as g_type_class_ref(), except that - * the classes reference count isn't incremented. As a consequence, this function - * may return %NULL if the class of the type passed in does not currently - * exist (hasn't been referenced before). + * This function is essentially the same as g_type_class_ref(), + * except that the classes reference count isn't incremented. + * As a consequence, this function may return %NULL if the class + * of the type passed in does not currently exist (hasn't been + * referenced before). * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - * structure for the given type ID or %NULL if the class does not - * currently exist. + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID or %NULL if the class does not + * currently exist */ /** * g_type_class_peek_parent: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to - * retrieve the parent class for. + * @g_class: (type GObject.TypeClass): the #GTypeClass structure to + * retrieve the parent class for * * This is a convenience function often needed in class initializers. * It returns the class structure of the immediate parent type of the * class passed in. Since derived classes hold a reference count on * their parent classes as long as they are instantiated, the returned - * class will always exist. This function is essentially equivalent - * to: + * class will always exist. * - * <programlisting> - * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); - * </programlisting> + * This function is essentially equivalent to: + * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))) * - * Returns: (type GObject.TypeClass) (transfer none): The parent class - * of @g_class. + * Returns: (type GObject.TypeClass) (transfer none): the parent class + * of @g_class */ /** * g_type_class_peek_static: - * @type: Type ID of a classed type. + * @type: type ID of a classed type * * A more efficient version of g_type_class_peek() which works only for * static types. * + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID or %NULL if the class does not + * currently exist or is dynamically loaded * Since: 2.4 - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - * structure for the given type ID or %NULL if the class does not - * currently exist or is dynamically loaded. */ /** * g_type_class_ref: - * @type: Type ID of a classed type. + * @type: type ID of a classed type * * Increments the reference count of the class structure belonging to * @type. This function will demand-create the class if it doesn't * exist already. * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - * structure for the given type ID. + * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass + * structure for the given type ID */ /** * g_type_class_unref: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to - * unreference. + * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref * * Decrements the reference count of the class structure being passed in. * Once the last reference count of a class has been released, classes @@ -4650,19 +4567,18 @@ /** * g_type_class_unref_uncached: (skip) - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to - * unreference. + * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref * * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc * implementations. It unreferences a class without consulting the chain - * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur + * of #GTypeClassCacheFuncs, avoiding the recursion which would occur * otherwise. */ /** * g_type_create_instance: (skip) - * @type: An instantiatable type to create an instance for. + * @type: an instantiatable type to create an instance for * * Creates and initializes an instance of @type if @type is valid and * can be instantiated. The type system only performs basic allocation @@ -4670,16 +4586,16 @@ * happen through functions supplied by the type's fundamental type * implementation. So use of g_type_create_instance() is reserved for * implementators of fundamental types only. E.g. instances of the - * #GObject hierarchy should be created via g_object_new() and - * <emphasis>never</emphasis> directly through - * g_type_create_instance() which doesn't handle things like singleton - * objects or object construction. Note: Do <emphasis>not</emphasis> - * use this function, unless you're implementing a fundamental - * type. Also language bindings should <emphasis>not</emphasis> use - * this function but g_object_new() instead. + * #GObject hierarchy should be created via g_object_new() and never + * directly through g_type_create_instance() which doesn't handle things + * like singleton objects or object construction. + * + * Note: Do not use this function, unless you're implementing a + * fundamental type. Also language bindings should not use this + * function, but g_object_new() instead. * - * Returns: An allocated and initialized instance, subject to further - * treatment by the fundamental type implementation. + * Returns: an allocated and initialized instance, subject to further + * treatment by the fundamental type implementation */ @@ -4692,8 +4608,8 @@ * * Since: 2.4 * Returns: (type GObject.TypeInterface) (transfer none): the default - * vtable for the interface, or %NULL if the type is not currently in - * use. + * vtable for the interface, or %NULL if the type is not currently + * in use */ @@ -4707,31 +4623,28 @@ * If the type is not currently in use, then the default vtable * for the type will be created and initalized by calling * the base interface init and default vtable init functions for - * the type (the @<structfield>base_init</structfield> - * and <structfield>class_init</structfield> members of #GTypeInfo). + * the type (the @base_init and @class_init members of #GTypeInfo). * Calling g_type_default_interface_ref() is useful when you * want to make sure that signals and properties for an interface * have been installed. * * Since: 2.4 * Returns: (type GObject.TypeInterface) (transfer none): the default - * vtable for the interface; call g_type_default_interface_unref() - * when you are done using the interface. + * vtable for the interface; call g_type_default_interface_unref() + * when you are done using the interface. */ /** * g_type_default_interface_unref: * @g_iface: (type GObject.TypeInterface): the default vtable - * structure for a interface, as returned by - * g_type_default_interface_ref() + * structure for a interface, as returned by g_type_default_interface_ref() * * Decrements the reference count for the type corresponding to the * interface default vtable @g_iface. If the type is dynamic, then * when no one is using the interface and all references have * been released, the finalize function for the interface's default - * vtable (the <structfield>class_finalize</structfield> member of - * #GTypeInfo) will be called. + * vtable (the @class_finalize member of #GTypeInfo) will be called. * * Since: 2.4 */ @@ -4739,18 +4652,18 @@ /** * g_type_depth: - * @type: A #GType value. + * @type: a #GType * * Returns the length of the ancestry of the passed in type. This * includes the type itself, so that e.g. a fundamental type has depth 1. * - * Returns: The depth of @type. + * Returns: the depth of @type */ /** * g_type_ensure: - * @type: a #GType. + * @type: a #GType * * Ensures that the indicated @type has been registered with the * type system, and its _class_init() method has been run. @@ -4771,7 +4684,7 @@ /** * g_type_free_instance: - * @instance: an instance of a type. + * @instance: an instance of a type * * Frees an instance of a type, returning it to the instance pool for * the type, if there is one. @@ -4783,14 +4696,14 @@ /** * g_type_from_name: - * @name: Type name to lookup. + * @name: type name to lookup * * Lookup the type ID from a given type name, returning 0 if no type * has been registered under this name (this is the preferred method * to find out by name whether a specific type has been registered * yet). * - * Returns: Corresponding type ID or 0. + * Returns: corresponding type ID or 0 */ @@ -4799,7 +4712,7 @@ * @type_id: valid type ID * * Internal function, used to extract the fundamental type ID portion. - * use G_TYPE_FUNDAMENTAL() instead. + * Use G_TYPE_FUNDAMENTAL() instead. * * Returns: fundamental type ID */ @@ -4813,20 +4726,19 @@ * The returned type ID represents the highest currently registered * fundamental type identifier. * - * Returns: The nextmost fundamental type ID to be registered, - * or 0 if the type system ran out of fundamental type IDs. + * Returns: the next available fundamental type ID to be registered, + * or 0 if the type system ran out of fundamental type IDs */ /** * g_type_get_plugin: - * @type: The #GType to retrieve the plugin for. + * @type: #GType to retrieve the plugin for * - * Returns the #GTypePlugin structure for @type or - * %NULL if @type does not have a #GTypePlugin structure. + * Returns the #GTypePlugin structure for @type. * - * Returns: (transfer none): The corresponding plugin if @type is a - * dynamic type, %NULL otherwise. + * Returns: (transfer none): the corresponding plugin + * if @type is a dynamic type, %NULL otherwise */ @@ -4849,14 +4761,14 @@ /** * g_type_get_type_registration_serial: * - * Returns an opaque serial number that represents the state of the set of - * registered types. Any time a type is registered this serial changes, + * Returns an opaque serial number that represents the state of the set + * of registered types. Any time a type is registered this serial changes, * which means you can cache information based on type lookups (such as * g_type_from_name()) and know if the cache is still valid at a later * time by comparing the current serial with the one at the type lookup. * * Since: 2.36 - * Returns: An unsigned int, representing the state of type registrations. + * Returns: An unsigned int, representing the state of type registrations */ @@ -4873,8 +4785,8 @@ /** * g_type_init_with_debug_flags: - * @debug_flags: Bitwise combination of #GTypeDebugFlags values for - * debugging purposes. + * @debug_flags: bitwise combination of #GTypeDebugFlags values for + * debugging purposes * * This function used to initialise the type system with debugging * flags. Since GLib 2.36, the type system is initialised automatically @@ -4889,8 +4801,8 @@ /** * g_type_interface_add_prerequisite: - * @interface_type: #GType value of an interface type. - * @prerequisite_type: #GType value of an interface or instantiatable type. + * @interface_type: #GType value of an interface type + * @prerequisite_type: #GType value of an interface or instantiatable type * * Adds @prerequisite_type to the list of prerequisites of @interface_type. * This means that any type implementing @interface_type must also implement @@ -4902,46 +4814,46 @@ /** * g_type_interface_get_plugin: - * @instance_type: the #GType value of an instantiatable type. - * @interface_type: the #GType value of an interface type. + * @instance_type: #GType of an instantiatable type + * @interface_type: #GType of an interface type * * Returns the #GTypePlugin structure for the dynamic interface - * @interface_type which has been added to @instance_type, or %NULL if - * @interface_type has not been added to @instance_type or does not - * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + * @interface_type which has been added to @instance_type, or %NULL + * if @interface_type has not been added to @instance_type or does + * not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). * * Returns: (transfer none): the #GTypePlugin for the dynamic - * interface @interface_type of @instance_type. + * interface @interface_type of @instance_type */ /** * g_type_interface_peek: - * @instance_class: (type GObject.TypeClass): A #GTypeClass structure. - * @iface_type: An interface ID which this class conforms to. + * @instance_class: (type GObject.TypeClass): a #GTypeClass structure + * @iface_type: an interface ID which this class conforms to * * Returns the #GTypeInterface structure of an interface to which the * passed in class conforms. * - * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface - * structure of iface_type if implemented by @instance_class, %NULL - * otherwise + * Returns: (type GObject.TypeInterface) (transfer none): the #GTypeInterface + * structure of @iface_type if implemented by @instance_class, %NULL + * otherwise */ /** * g_type_interface_peek_parent: - * @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure. + * @g_iface: (type GObject.TypeInterface): a #GTypeInterface structure * * Returns the corresponding #GTypeInterface structure of the parent type * of the instance type to which @g_iface belongs. This is useful when * deriving the implementation of an interface from the parent type and * then possibly overriding some methods. * - * Returns: (transfer none) (type GObject.TypeInterface): The - * corresponding #GTypeInterface structure of the parent type of the - * instance type to which @g_iface belongs, or %NULL if the parent - * type doesn't conform to the interface. + * Returns: (transfer none) (type GObject.TypeInterface): the + * corresponding #GTypeInterface structure of the parent type of the + * instance type to which @g_iface belongs, or %NULL if the parent + * type doesn't conform to the interface */ @@ -4949,42 +4861,42 @@ * g_type_interface_prerequisites: * @interface_type: an interface type * @n_prerequisites: (out) (allow-none): location to return the number - * of prerequisites, or %NULL + * of prerequisites, or %NULL * * Returns the prerequisites of an interfaces type. * * Since: 2.2 * Returns: (array length=n_prerequisites) (transfer full): a - * newly-allocated zero-terminated array of #GType containing - * the prerequisites of @interface_type + * newly-allocated zero-terminated array of #GType containing + * the prerequisites of @interface_type */ /** * g_type_interfaces: - * @type: The type to list interface types for. - * @n_interfaces: (out) (allow-none): Optional #guint pointer to - * contain the number of interface types. + * @type: the type to list interface types for + * @n_interfaces: (out) (allow-none): location to store the length of + * the returned array, or %NULL * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * interface types that @type conforms to. The return value has to be - * g_free()ed after use. + * Return a newly allocated and 0-terminated array of type IDs, listing + * the interface types that @type conforms to. * - * Returns: (array length=n_interfaces) (transfer full): Newly - * allocated and 0-terminated array of interface types. + * Returns: (array length=n_interfaces) (transfer full): Newly allocated + * and 0-terminated array of interface types, free with g_free() */ /** * g_type_is_a: - * @type: Type to check anchestry for. - * @is_a_type: Possible anchestor of @type or interface @type could conform to. + * @type: type to check anchestry for + * @is_a_type: possible anchestor of @type or interface that @type + * could conform to * * If @is_a_type is a derivable type, check whether @type is a - * descendant of @is_a_type. If @is_a_type is an interface, check + * descendant of @is_a_type. If @is_a_type is an interface, check * whether @type conforms to it. * - * Returns: %TRUE if @type is_a @is_a_type holds true. + * Returns: %TRUE if @type is a @is_a_type */ @@ -5109,7 +5021,7 @@ /** * g_type_name: - * @type: Type to return name for. + * @type: type to return name for * * Get the unique name that is assigned to a type ID. Note that this * function (like all other GType API) cannot cope with invalid type @@ -5117,35 +5029,35 @@ * other validly registered type ID, but randomized type IDs should * not be passed in and will most likely lead to a crash. * - * Returns: Static type name or %NULL. + * Returns: static type name or %NULL */ /** * g_type_next_base: - * @leaf_type: Descendant of @root_type and the type to be returned. - * @root_type: Immediate parent of the returned type. + * @leaf_type: descendant of @root_type and the type to be returned + * @root_type: immediate parent of the returned type * * Given a @leaf_type and a @root_type which is contained in its * anchestry, return the type that @root_type is the immediate parent - * of. In other words, this function determines the type that is + * of. In other words, this function determines the type that is * derived directly from @root_type which is also a base class of * @leaf_type. Given a root type and a leaf type, this function can * be used to determine the types and order in which the leaf type is * descended from the root type. * - * Returns: Immediate child of @root_type and anchestor of @leaf_type. + * Returns: immediate child of @root_type and anchestor of @leaf_type */ /** * g_type_parent: - * @type: The derived type. + * @type: the derived type * - * Return the direct parent type of the passed in type. If the passed + * Return the direct parent type of the passed in type. If the passed * in type has no parent, i.e. is a fundamental type, 0 is returned. * - * Returns: The parent type. + * Returns: the parent type */ @@ -5198,19 +5110,19 @@ /** * g_type_qname: - * @type: Type to return quark of type name for. + * @type: type to return quark of type name for * * Get the corresponding quark of the type IDs name. * - * Returns: The type names quark or 0. + * Returns: the type names quark or 0 */ /** * g_type_query: - * @type: the #GType value of a static, classed type. - * @query: (out caller-allocates): A user provided structure that is - * filled in with constant values upon success. + * @type: #GType of a static, classed type + * @query: (out caller-allocates): a user provided structure that is + * filled in with constant values upon success * * Queries the type system for information about a specific type. * This function will fill in a user-provided structure to hold @@ -5223,10 +5135,10 @@ /** * g_type_register_dynamic: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from. - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @plugin: #GTypePlugin structure to retrieve the #GTypeInfo from + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_name as the name of a new dynamic type derived from * @parent_type. The type system uses the information contained in the @@ -5234,56 +5146,56 @@ * instances (if not abstract). The value of @flags determines the nature * (e.g. abstract or not) of the type. * - * Returns: The new type identifier or #G_TYPE_INVALID if registration failed. + * Returns: the new type identifier or #G_TYPE_INVALID if registration failed */ /** * g_type_register_fundamental: - * @type_id: A predefined type identifier. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @finfo: The #GTypeFundamentalInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * @type_id: a predefined type identifier + * @type_name: 0-terminated string used as the name of the new type + * @info: #GTypeInfo structure for this type + * @finfo: #GTypeFundamentalInfo structure for this type + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_id as the predefined identifier and @type_name as the - * name of a fundamental type. If @type_id is already registered, or a type - * named @type_name is already registered, the behaviour is undefined. The type - * system uses the information contained in the #GTypeInfo structure pointed to - * by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to - * manage the type and its instances. The value of @flags determines additional - * characteristics of the fundamental type. + * name of a fundamental type. If @type_id is already registered, or a + * type named @type_name is already registered, the behaviour is undefined. + * The type system uses the information contained in the #GTypeInfo structure + * pointed to by @info and the #GTypeFundamentalInfo structure pointed to by + * @finfo to manage the type and its instances. The value of @flags determines + * additional characteristics of the fundamental type. * - * Returns: The predefined type identifier. + * Returns: the predefined type identifier */ /** * g_type_register_static: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @info: #GTypeInfo structure for this type + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_name as the name of a new static type derived from - * @parent_type. The type system uses the information contained in the + * @parent_type. The type system uses the information contained in the * #GTypeInfo structure pointed to by @info to manage the type and its - * instances (if not abstract). The value of @flags determines the nature + * instances (if not abstract). The value of @flags determines the nature * (e.g. abstract or not) of the type. * - * Returns: The new type identifier. + * Returns: the new type identifier */ /** * g_type_register_static_simple: (skip) - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @class_size: Size of the class structure (see #GTypeInfo) - * @class_init: Location of the class initialization function (see #GTypeInfo) - * @instance_size: Size of the instance structure (see #GTypeInfo) - * @instance_init: Location of the instance initialization function (see #GTypeInfo) - * @flags: Bitwise combination of #GTypeFlags values. + * @parent_type: type from which this type will be derived + * @type_name: 0-terminated string used as the name of the new type + * @class_size: size of the class structure (see #GTypeInfo) + * @class_init: location of the class initialization function (see #GTypeInfo) + * @instance_size: size of the instance structure (see #GTypeInfo) + * @instance_init: location of the instance initialization function (see #GTypeInfo) + * @flags: bitwise combination of #GTypeFlags values * * Registers @type_name as the name of a new static type derived from * @parent_type. The value of @flags determines the nature (e.g. @@ -5291,7 +5203,7 @@ * struct and calling g_type_register_static(). * * Since: 2.12 - * Returns: The new type identifier. + * Returns: the new type identifier */ @@ -5330,15 +5242,16 @@ /** * g_type_value_table_peek: (skip) - * @type: A #GType value. + * @type: a #GType * * Returns the location of the #GTypeValueTable associated with @type. - * <emphasis>Note that this function should only be used from source code + * + * Note that this function should only be used from source code * that implements or has internal knowledge of the implementation of - * @type.</emphasis> + * @type. * - * Returns: Location of the #GTypeValueTable associated with @type or - * %NULL if there is no #GTypeValueTable associated with @type. + * Returns: location of the #GTypeValueTable associated with @type or + * %NULL if there is no #GTypeValueTable associated with @type */ @@ -5433,8 +5346,7 @@ * g_value_array_remove: * @value_array: #GValueArray to remove an element from * @index_: position of value to remove, which must be less than - * <code>value_array-><link - * linkend="GValueArray.n-values">n_values</link></code> + * @value_array->n_values * * Remove the value at position @index_ from @value_array. * |