Merge branch 'migrate-to-gi-docgen3' into 'main'

Switch to using gi-docgen for docs (batch 3)

See merge request GNOME/glib!3645

docs/reference/gobject/gobject.toml.in

@@ -44,6 +44,8 @@ urlmap_file = "urlmap.js"
 content_files = [
   "concepts.md",
   "tutorial.md",
+  "types.md",
+  "signals.md",
   "floating-refs.md",
   "boxed.md",
   "enum-types.md",

docs/reference/gobject/meson.build

@@ -72,6 +72,8 @@ expand_content_files = [
   'floating-refs.md',
   'gvalue.md',
   'tutorial.md',
+  'types.md',
+  'signals.md',
 ]
 
 gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir'

docs/reference/gobject/signals.md

@@ -0,0 +1,95 @@
+Title: Signals
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2000, 2001 Tim Janik
+SPDX-FileCopyrightText: 2000 Owen Taylor
+SPDX-FileCopyrightText: 2002, 2014 Matthias Clasen
+SPDX-FileCopyrightText: 2014 Collabora, Ltd.
+SPDX-FileCopyrightText: 2019 Endless Mobile, Inc.
+
+# Signals
+
+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.
+
+A signal emission consists of five stages, unless prematurely stopped:
+
+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 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 [func@GObject.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
+wildcard and matches any detail argument passed in to emission.
+
+While the `detail` argument is typically used to pass an object property name
+(as with `GObject::notify`), no specific format is mandated for the detail
+string, other than that it must be non-empty.
+
+## Memory management of signal handlers
+
+If you are connecting handlers to signals and using a `GObject` instance as
+your signal handler user data, you should remember to pair calls to
+[func@GObject.signal_connect] with calls to [func@GObject.signal_handler_disconnect]
+or [func@GObject.signal_handlers_disconnect_by_func]. While signal handlers are
+automatically disconnected when the object emitting the signal is finalised,
+they are not automatically disconnected when the signal handler user data is
+destroyed. If this user data is a `GObject` instance, using it from a
+signal handler after it has been finalised is an error.
+
+There are two strategies for managing such user data. The first is to
+disconnect the signal handler (using [func@GObject.signal_handler_disconnect]
+or [func@GObject.signal_handlers_disconnect_by_func]) when the user data (object)
+is finalised; this has to be implemented manually. For non-threaded programs,
+[func@GObject.signal_connect_object] can be used to implement this automatically.
+Currently, however, it is unsafe to use in threaded programs.
+
+The second is to hold a strong reference on the user data until after the
+signal is disconnected for other reasons. This can be implemented
+automatically using [func@GObject.signal_connect_data].
+
+The first approach is recommended, as the second approach can result in
+effective memory leaks of the user data if the signal handler is never
+disconnected for some reason.
+

docs/reference/gobject/types.md

@@ -0,0 +1,64 @@
+Title: Types
+SPDX-License-Identifier: LGPL-2.1-or-later
+SPDX-FileCopyrightText: 2001, 2003 Owen Taylor
+SPDX-FileCopyrightText: 2002, 2003, 2004, 2005 Matthias Clasen
+SPDX-FileCopyrightText: 2003, 2006 Josh Parsons
+SPDX-FileCopyrightText: 2005 Stefan Kost
+SPDX-FileCopyrightText: 2015 Collabora, Ltd.
+SPDX-FileCopyrightText: 2021 Emmanuele Bassi
+SPDX-FileCopyrightText: 2023 Endless OS Foundation, LLC
+
+# Types
+
+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.
+
+For type creation and registration purposes, all types fall into one of
+two categories: static or dynamic. Static types are never loaded or
+unloaded at run-time as dynamic types may be.  Static types are created
+with [func@GObject.type_register_static] that gets type specific
+information passed in via a `GTypeInfo` structure.
+
+Dynamic types are created with [func@GObject.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 [func@GObject.type_register_fundamental], which requires
+both a `GTypeInfo` structure and a `GTypeFundamentalInfo` structure, but it
+is rarely used since most fundamental types are predefined rather than user-defined.
+
+Type instance and class structs are limited to a total of 64 KiB,
+including all parent types. Similarly, type instances' private data
+(as created by `G_ADD_PRIVATE()`) are limited to a total of
+64 KiB. If a type instance needs a large static buffer, allocate it
+separately (typically by using [`struct@GLib.Array`] or [`struct@GLib.PtrArray`])
+and put a pointer to the buffer in the structure.
+
+As mentioned in the [GType conventions](concepts.html#conventions), type names must
+be at least three characters long. There is no upper length limit. The first
+character must be a letter (a–z or A–Z) or an underscore (‘\_’). Subsequent
+characters can be letters, numbers or any of ‘-\_+’.
+
+# Runtime Debugging
+
+When `G_ENABLE_DEBUG` is defined during compilation, the GObject library
+supports an environment variable `GOBJECT_DEBUG` that can be set to a
+combination of flags to trigger debugging messages about
+object bookkeeping and signal emissions during runtime.
+
+The currently supported flags are:
+
+ - `objects`: Tracks all `GObject` instances in a global hash table called
+   `debug_objects_ht`, and prints the still-alive objects on exit.
+ - `instance-count`: Tracks the number of instances of every `GType` and makes
+   it available via the [func@GObject.type_get_instance_count] function.
+ - `signals`: Currently unused.

gobject/gbinding.c

@@ -21,36 +21,33 @@
  */
 
 /**
- * SECTION:gbinding
+ * GBinding:
- * @Title: GBinding
- * @Short_Description: Bind two object properties
  *
- * #GBinding is the representation of a binding between a property on a
+ * `GObject` instance (or source) and another property on another `GObject`
- * #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:
  *
- * |[<!-- language="C" -->
+ * ```c
  *   g_object_bind_property (object1, "property-a",
  *                           object2, "property-b",
  *                           G_BINDING_DEFAULT);
- * ]|
+ * ```
  *
  * 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
+ * every time [method@GObject.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
+ * of two `GObject` instances, so that if either property changes, the
  * other is updated as well, for instance:
  *
- * |[<!-- language="C" --> 
+ * ```c
  *   g_object_bind_property (object1, "property-a",
  *                           object2, "property-b",
  *                           G_BINDING_BIDIRECTIONAL);
- * ]|
+ * ```
  *
  * will keep the two properties in sync.
  *
@@ -59,14 +56,14 @@
  * transformation from the source value to the target value before
  * applying it; for instance, the following binding:
  *
- * |[<!-- language="C" --> 
+ * ```c
  *   g_object_bind_property_full (adjustment1, "value",
  *                                adjustment2, "value",
  *                                G_BINDING_BIDIRECTIONAL,
  *                                celsius_to_fahrenheit,
  *                                fahrenheit_to_celsius,
  *                                NULL, NULL);
- * ]|
+ * ```
  *
  * will keep the "value" property of the two adjustments in sync; the
  * @celsius_to_fahrenheit function will be called whenever the "value"
@@ -80,29 +77,29 @@
  *
  * Note that #GBinding does not resolve cycles by itself; a cycle like
  *
- * |[
+ * ```
  *   object1:propertyA -> object2:propertyB
  *   object2:propertyB -> object3:propertyC
  *   object3:propertyC -> object1:propertyA
- * ]|
+ * ```
  *
  * might lead to an infinite loop. The loop, in this particular case,
- * can be avoided if the objects emit the #GObject::notify signal only
+ * can be avoided if the objects emit the `GObject::notify` signal only
  * if the value has effectively been changed. A binding is implemented
- * using the #GObject::notify signal, so it is susceptible to all the
+ * using the `GObject::notify` signal, so it is susceptible to all the
- * various ways of blocking a signal emission, like g_signal_stop_emission()
+ * various ways of blocking a signal emission, like [func@GObject.signal_stop_emission]
- * or g_signal_handler_block().
+ * or [func@GObject.signal_handler_block].
  *
  * A binding will be severed, and the resources it allocates freed, whenever
- * either one of the #GObject instances it refers to are finalized, or when
+ * either one of the `GObject` instances it refers to are finalized, or when
  * the #GBinding instance loses its last reference.
  *
  * Bindings for languages with garbage collection can use
- * g_binding_unbind() to explicitly release a binding between the source
+ * [method@GObject.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.
  *
- * #GBinding is available since GObject 2.26
+ * Since: 2.26
  */
 
 #include "config.h"

gobject/gbinding.h

@@ -38,14 +38,6 @@ G_BEGIN_DECLS
 #define G_BINDING(obj)          (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_BINDING, GBinding))
 #define G_IS_BINDING(obj)       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_BINDING))
 
-/**
- * GBinding:
- *
- * GBinding is an opaque structure whose members
- * cannot be accessed directly.
- *
- * Since: 2.26
- */
 typedef struct _GBinding        GBinding;
 
 /**

gobject/gbindinggroup.c

@@ -27,18 +27,15 @@
 #include "gparamspecs.h"
 
 /**
- * SECTION:gbindinggroup
+ * GBindingGroup:
- * @Title: GBindingGroup
- * @Short_description: Binding multiple properties as a group
- * @include: glib-object.h
  *
- * The #GBindingGroup can be used to bind multiple properties
+ * `GBindingGroup` can be used to bind multiple properties
  * from an object collectively.
  *
  * Use the various methods to bind properties from a single source
  * object to multiple destination objects. Properties can be bound
  * bidirectionally and are connected when the source object is set
- * with g_binding_group_set_source().
+ * with [method@GObject.BindingGroup.set_source].
  *
  * Since: 2.72
  */

gobject/gbindinggroup.h

@@ -36,14 +36,6 @@ G_BEGIN_DECLS
 #define G_IS_BINDING_GROUP(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_BINDING_GROUP))
 #define G_TYPE_BINDING_GROUP    (g_binding_group_get_type())
 
-/**
- * GBindingGroup:
- *
- * GBindingGroup is an opaque structure whose members
- * cannot be accessed directly.
- *
- * Since: 2.72
- */
 typedef struct _GBindingGroup GBindingGroup;
 
 GOBJECT_AVAILABLE_IN_2_72

gobject/gclosure.c

@@ -39,11 +39,13 @@
 
 
 /**
- * SECTION:gclosure
+ * GClosure:
- * @short_description: Functions as first-class objects
+ * @in_marshal: Indicates whether the closure is currently being invoked with
- * @title: Closures
+ *   g_closure_invoke()
+ * @is_invalid: Indicates whether the closure has been invalidated by
+ *   g_closure_invalidate()
  *
- * A #GClosure represents a callback supplied by the programmer.
+ * 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

gobject/gclosure.h

@@ -169,15 +169,7 @@ struct _GClosureNotifyData
   gpointer       data;
   GClosureNotify notify;
 };
-/**
+
- * GClosure:
- * @in_marshal: Indicates whether the closure is currently being invoked with 
- *  g_closure_invoke()
- * @is_invalid: Indicates whether the closure has been invalidated by 
- *  g_closure_invalidate()
- * 
- * A #GClosure represents a callback supplied by the programmer.
- */
 struct _GClosure
 {
   /*< private >*/

gobject/gobject.c

@@ -38,22 +38,30 @@
 #include "gconstructor.h"
 
 /**
- * SECTION:objects
+ * GObject:
- * @title: GObject
- * @short_description: The base object type
- * @see_also: #GParamSpecObject, g_param_spec_object()
  *
- * GObject is the fundamental type providing the common attributes and
+ * The base object type.
+ *
+ * `GObject` is the fundamental type providing the common attributes and
  * methods for all object types in GTK, Pango and other libraries
- * based on GObject.  The GObject class provides methods for object
+ * based on GObject. The `GObject` class provides methods for object
  * construction and destruction, property access methods, and signal
  * support. Signals are described in detail [here][gobject-Signals].
  *
- * For a tutorial on implementing a new GObject class, see [How to define and
+ * For a tutorial on implementing a new `GObject` class, see [How to define and
- * implement a new GObject][howto-gobject]. For a list of naming conventions for
+ * implement a new GObject](tutorial.html#how-to-define-and-implement-a-new-gobject).
- * GObjects and their methods, see the [GType conventions][gtype-conventions].
+ * For a list of naming conventions for GObjects and their methods, see the
- * For the high-level concepts behind GObject, read [Instantiatable classed types:
+ * [GType conventions](concepts.html#conventions). For the high-level concepts
- * Objects][gtype-instantiatable-classed].
+ * behind GObject, read
+ * [Instantiatable classed types: Objects](concepts.html#instantiatable-classed-types-objects).
+ *
+ * Since GLib 2.72, all `GObject`s are guaranteed to be aligned to at least the
+ * alignment of the largest basic GLib type (typically this is `guint64` or
+ * `gdouble`). If you need larger alignment for an element in a `GObject`, you
+ * should allocate it on the heap (aligned), or arrange for your `GObject` to be
+ * appropriately padded. This guarantee applies to the `GObject` (or derived)
+ * struct, the `GObjectClass` (or derived) struct, and any private data allocated
+ * by `G_ADD_PRIVATE()`.
  */
 
 /* --- macros --- */

gobject/gobject.h

@@ -248,22 +248,7 @@ typedef void (*GObjectFinalizeFunc)     (GObject      *object);
  */
 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 implementation
- * and should never be accessed directly.
- *
- * Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
- * alignment of the largest basic GLib type (typically this is #guint64 or
- * #gdouble). If you need larger alignment for an element in a #GObject, you
- * should allocate it on the heap (aligned), or arrange for your #GObject to be
- * appropriately padded. This guarantee applies to the #GObject (or derived)
- * struct, the #GObjectClass (or derived) struct, and any private data allocated
- * by G_ADD_PRIVATE().
- */
 struct  _GObject
 {
   GTypeInstance  g_type_instance;

gobject/gparam.c

@@ -31,29 +31,27 @@
 #include "gtype-private.h"
 
 /**
- * SECTION:gparamspec
+ * GParamSpec: (ref-func g_param_spec_ref_sink) (unref-func g_param_spec_unref) (set-value-func g_value_set_param) (get-value-func g_value_get_param)
- * @short_description: Metadata for parameter specifications
+ * @g_type_instance: private `GTypeInstance` portion
- * @see_also: g_object_class_install_property(), g_object_set(),
+ * @name: name of this parameter: always an interned string
- *     g_object_get(), g_object_set_property(), g_object_get_property(),
+ * @flags: `GParamFlags` flags for this parameter
- *     g_value_register_transform_func()
+ * @value_type: the `GValue` type for this parameter
- * @title: GParamSpec
+ * @owner_type: `GType` type that uses (introduces) this parameter
  *
- * #GParamSpec is an object structure that encapsulates the metadata
+ * `GParamSpec` encapsulates the metadata required to specify parameters, such as `GObject` properties.
- * required to specify parameters, such as e.g. #GObject properties.
  *
- * ## Parameter names # {#canonical-parameter-names}
+ * ## Parameter names
  *
  * A property name consists of one or more segments consisting of ASCII letters
  * and digits, separated by either the `-` or `_` character. The first
  * character of a property name must be a letter. These are the same rules as
- * for signal naming (see g_signal_new()).
+ * for signal naming (see [func@GObject.signal_new]).
  *
- * When creating and looking up a #GParamSpec, either separator can be
+ * When creating and looking up a `GParamSpec`, either separator can be
  * used, but they cannot be mixed. Using `-` is considerably more
  * efficient, and is the ‘canonical form’. Using `_` is discouraged.
  */
 
-
 /* --- defines --- */
 #define PARAM_FLOATING_FLAG                     0x2
 #define	G_PARAM_USER_MASK			(~0U << G_PARAM_USER_SHIFT)

gobject/gparam.h

@@ -203,17 +203,7 @@ typedef struct _GParamSpec      GParamSpec;
 typedef struct _GParamSpecClass GParamSpecClass;
 typedef struct _GParameter	GParameter GOBJECT_DEPRECATED_TYPE_IN_2_54;
 typedef struct _GParamSpecPool  GParamSpecPool;
-/**
+
- * GParamSpec: (ref-func g_param_spec_ref_sink) (unref-func g_param_spec_unref) (set-value-func g_value_set_param) (get-value-func g_value_get_param)
- * @g_type_instance: private #GTypeInstance portion
- * @name: name of this parameter: always an interned string
- * @flags: #GParamFlags flags for this parameter
- * @value_type: the #GValue type for this parameter
- * @owner_type: #GType type that uses (introduces) this parameter
- * 
- * All other fields of the GParamSpec struct are private and
- * should not be used directly.
- */
 struct _GParamSpec
 {
   GTypeInstance  g_type_instance;

gobject/gparamspecs.c

@@ -37,29 +37,6 @@
 #include "gvaluearray.h"
 
 
-/**
- * SECTION:param_value_types
- * @short_description: Standard Parameter and Value Types
- * @see_also: #GParamSpec, #GValue, g_object_class_install_property().
- * @title: Parameters and Values
- *
- * #GValue provides an abstract container structure which can be
- * copied, transformed and compared while holding a value of any
- * (derived) type, which is registered as a #GType with a
- * #GTypeValueTable in its #GTypeInfo structure.  Parameter
- * specifications for most value types can be created as #GParamSpec
- * derived instances, to implement e.g. #GObject properties which
- * operate on #GValue containers.
- *
- * 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.
- *
- * See also #GValue for more information.
- *
- */
-
-
 #define	G_FLOAT_EPSILON		(1e-30)
 #define	G_DOUBLE_EPSILON	(1e-90)
 

gobject/gsignal.c

@@ -39,99 +39,6 @@
 #include "gobject_trace.h"
 
 
-/**
- * SECTION:signals
- * @short_description: A means for customization of object behaviour
- *     and a general purpose notification mechanism
- * @title: Signals
- *
- * 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.
- *
- * A signal emission consists of five stages, unless prematurely stopped:
- *
- * 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 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
- * 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
- * wildcard and matches any detail argument passed in to emission.
- *
- * While the @detail argument is typically used to pass an object property name
- * (as with #GObject::notify), no specific format is mandated for the detail
- * string, other than that it must be non-empty.
- *
- * ## Memory management of signal handlers # {#signal-memory-management}
- *
- * If you are connecting handlers to signals and using a #GObject instance as
- * your signal handler user data, you should remember to pair calls to
- * g_signal_connect() with calls to g_signal_handler_disconnect() or
- * g_signal_handlers_disconnect_by_func(). While signal handlers are
- * automatically disconnected when the object emitting the signal is finalised,
- * they are not automatically disconnected when the signal handler user data is
- * destroyed. If this user data is a #GObject instance, using it from a
- * signal handler after it has been finalised is an error.
- *
- * There are two strategies for managing such user data. The first is to
- * disconnect the signal handler (using g_signal_handler_disconnect() or
- * g_signal_handlers_disconnect_by_func()) when the user data (object) is
- * finalised; this has to be implemented manually. For non-threaded programs,
- * g_signal_connect_object() can be used to implement this automatically.
- * Currently, however, it is unsafe to use in threaded programs.
- *
- * The second is to hold a strong reference on the user data until after the
- * signal is disconnected for other reasons. This can be implemented
- * automatically using g_signal_connect_data().
- *
- * The first approach is recommended, as the second approach can result in
- * effective memory leaks of the user data if the signal handler is never
- * disconnected for some reason.
- */
-
-
 #define REPORT_BUG      "please report occurrence circumstances to https://gitlab.gnome.org/GNOME/glib/issues/new"
 
 /* --- typedefs --- */

gobject/gsignalgroup.c

@@ -28,13 +28,12 @@
 #include "gvaluetypes.h"
 
 /**
- * SECTION:gsignalgroup
+ * GSignalGroup:
- * @Title: GSignalGroup
- * @Short_description: Manage a collection of signals on a GObject
  *
- * #GSignalGroup manages to simplify the process of connecting
+ * `GSignalGroup` manages a collection of signals on a `GObject`.
- * many signals to a #GObject as a group. As such there is no API
+ *
- * to disconnect a signal from the group.
+ * `GSignalGroup` simplifies the process of connecting  many signals to a `GObject`
+ * as a group. As such there is no API to disconnect a signal from the group.
  *
  * In particular, this allows you to:
  *
@@ -43,12 +42,12 @@
  *  - Block and unblock signals as a group
  *  - Ensuring that blocked state transfers across target instances.
  *
- * One place you might want to use such a structure is with #GtkTextView and
+ * One place you might want to use such a structure is with `GtkTextView` and
- * #GtkTextBuffer. Often times, you'll need to connect to many signals on
+ * `GtkTextBuffer`. Often times, you'll need to connect to many signals on
- * #GtkTextBuffer from a #GtkTextView subclass. This allows you to create a
+ * `GtkTextBuffer` from a `GtkTextView` subclass. This allows you to create a
  * signal group during instance construction, simply bind the
- * #GtkTextView:buffer property to #GSignalGroup:target and connect
+ * `GtkTextView:buffer` property to `GSignalGroup:target` and connect
- * all the signals you need. When the #GtkTextView:buffer property changes
+ * all the signals you need. When the `GtkTextView:buffer` property changes
  * all of the signals will be transitioned correctly.
  *
  * Since: 2.72

gobject/gsignalgroup.h

@@ -36,14 +36,6 @@ G_BEGIN_DECLS
 #define G_IS_SIGNAL_GROUP(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_SIGNAL_GROUP))
 #define G_TYPE_SIGNAL_GROUP    (g_signal_group_get_type())
 
-/**
- * GSignalGroup:
- *
- * #GSignalGroup is an opaque structure whose members
- * cannot be accessed directly.
- *
- * Since: 2.72
- */
 typedef struct _GSignalGroup GSignalGroup;
 
 GOBJECT_AVAILABLE_IN_2_72

gobject/gtype.c

@@ -44,65 +44,6 @@
 #define	IF_DEBUG(debug_type)	if (_g_type_debug_flags & G_TYPE_DEBUG_ ## debug_type)
 #endif
 
-/**
- * SECTION:gtype
- * @short_description: The GLib Runtime type identification and
- *     management system
- * @title:Type Information
- *
- * 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.
- *
- * For type creation and registration purposes, all types fall into one of
- * two categories: static or dynamic.  Static types are never loaded or
- * 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
- * since most fundamental types are predefined rather than user-defined.
- *
- * Type instance and class structs are limited to a total of 64 KiB,
- * including all parent types. Similarly, type instances' private data
- * (as created by G_ADD_PRIVATE()) are limited to a total of
- * 64 KiB. If a type instance needs a large static buffer, allocate it
- * separately (typically by using #GArray or #GPtrArray) and put a pointer
- * to the buffer in the structure.
- *
- * As mentioned in the [GType conventions][gtype-conventions], type names must
- * be at least three characters long. There is no upper length limit. The first
- * character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent
- * characters can be letters, numbers or any of ‘-_+’.
- *
- * # Runtime Debugging
- *
- * When `G_ENABLE_DEBUG` is defined during compilation, the GObject library
- * supports an environment variable `GOBJECT_DEBUG` that can be set to a
- * combination of flags to trigger debugging messages about
- * object bookkeeping and signal emissions during runtime.
- *
- * The currently supported flags are:
- *  - `objects`: Tracks all #GObject instances in a global hash table called
- *    `debug_objects_ht`, and prints the still-alive objects on exit.
- *  - `instance-count`: Tracks the number of instances of every #GType and makes
- *    it available via the g_type_get_instance_count() function.
- *  - `signals`: Currently unused.
- */
-
 
 /* NOTE: some functions (some internal variants and exported ones)
  * invalidate data portions of the TypeNodes. if external functions/callbacks

gobject/gtypemodule.c

@@ -26,41 +26,40 @@
 
 
 /**
- * SECTION:gtypemodule
+ * GTypeModule:
- * @short_description: Type loading modules
+ * @name: the name of the module
- * @see_also: #GTypePlugin, #GModule
- * @title: GTypeModule
  *
- * #GTypeModule provides a simple implementation of the #GTypePlugin
+ * `GTypeModule` provides a simple implementation of the `GTypePlugin`
  * interface.
  *
- * The model of #GTypeModule is a dynamically loaded module which
+ * 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().
+ * using [method@GObject.TypeModule.register_type] and
+ * [method@GObject.TypeModule.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
  * reference cannot be released from within the module code, since that
- * would lead to the caller's code being unloaded before g_object_unref()
+ * 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
  * zero, the module is loaded. The use count is maintained internally by
  * the type system, but also can be explicitly controlled by
- * g_type_module_use() and g_type_module_unuse(). Typically, when loading
+ * [func@GObject.type_module_use] and [func@GObject.type_module_unuse].
- * a module for the first type, g_type_module_use() will be used to load
+ * Typically, when loading a module for the first type, `g_type_module_use()`
- * it so that it can initialize its types. At some later point, when the
+ * will be used to load it so that it can initialize its types. At some later
- * module no longer needs to be loaded except for the type
+ * point, when the module no longer needs to be loaded except for the type
- * implementations it contains, g_type_module_unuse() is called.
+ * implementations it contains, `g_type_module_unuse()` is called.
  *
- * #GTypeModule does not actually provide any implementation of module
+ * `GTypeModule` does not actually provide any implementation of module
  * loading and unloading. To create a particular module type you must
- * derive from #GTypeModule and implement the load and unload functions
+ * derive from `GTypeModule` and implement the load and unload functions
- * in #GTypeModuleClass.
+ * in `GTypeModuleClass`.
  */
 
 typedef struct _ModuleTypeInfo ModuleTypeInfo;

gobject/gtypemodule.h

@@ -40,13 +40,6 @@ typedef struct _GTypeModuleClass GTypeModuleClass;
 
 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GTypeModule, g_object_unref)
 
-/**
- * GTypeModule:
- * @name: the name of the module
- * 
- * The members of the GTypeModule structure should not 
- * be accessed directly, except for the @name field.
- */
 struct _GTypeModule 
 {
   GObject parent_instance;

gobject/gtypeplugin.c

@@ -23,10 +23,7 @@
 
 
 /**
- * SECTION:gtypeplugin
+ * GTypePlugin:
- * @short_description: An interface for dynamically loadable types
- * @see_also: #GTypeModule and g_type_register_dynamic().
- * @title: GTypePlugin
  *
  * An interface that handles the lifecycle of dynamically loaded types.
  *
@@ -36,45 +33,45 @@
  * 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" --> 
+ *    ```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.
+ *    `GTypePlugin` interface.
  *
  * 2. The type's implementation is referenced, e.g. through
- *    g_type_class_ref() or through g_type_create_instance() (this is
+ *    [func@GObject.type_class_ref] or through [func@GObject.type_create_instance]
- *    being called by g_object_new()) or through one of the above done on
+ *    (this is being called by [func@GObject.object_new]) or through one of the above
- *    a type derived from @new_type_id.
+ *    done on a type derived from @new_type_id.
  *
- * 3. This causes the type system to load the type's implementation by
+ * 3. This causes the type system to load the type's implementation by calling
- *    calling g_type_plugin_use() and g_type_plugin_complete_type_info()
+ *    [func@GObject.type_plugin_use] and [method@GObject.TypePlugin.complete_type_info]
  *    on @new_type_plugin.
  *
- * 4. At some point the type's implementation isn't required anymore,
+ * 4. At some point the type's implementation isn't required anymore, e.g. after
- *    e.g. after g_type_class_unref() or g_type_free_instance() (called
+ *    [func@GObject.type_class_unref] or [func@GObject.type_free_instance]
- *    when the reference count of an instance drops to zero).
+ *    (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
+ *    from [method@GObject.TypePlugin.complete_type_info] and then it calls
- *    g_type_plugin_unuse() on @new_type_plugin.
+ *    [method@GObject.TypePlugin.unuse] on @new_type_plugin.
  *
  * 6. Things may repeat from the second step.
  *
- * So basically, you need to implement a #GTypePlugin type that
+ * So basically, you need to implement a `GTypePlugin` type that
  * carries a use_count, once use_count goes from zero to one, you need
  * to load the implementation to successfully handle the upcoming
- * g_type_plugin_complete_type_info() call. Later, maybe after
+ * [method@GObject.TypePlugin.complete_type_info] call. Later, maybe after
  * succeeding use/unuse calls, once use_count drops to zero, you can
  * unload the implementation again. The type system makes sure to call
- * g_type_plugin_use() and g_type_plugin_complete_type_info() again
+ * [method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info]
- * when the type is needed again.
+ * again when the type is needed again.
  *
- * #GTypeModule is an implementation of #GTypePlugin that already
+ * [struct@GObject.TypeModule] is an implementation of `GTypePlugin` that
- * implements most of this except for the actual module loading and
+ * already implements most of this except for the actual module loading and
  * unloading. It even handles multiple registered types per module.
  */
 

gobject/gtypeplugin.h

@@ -80,12 +80,6 @@ typedef void  (*GTypePluginCompleteInterfaceInfo) (GTypePlugin     *plugin,
 						   GType            instance_type,
 						   GType            interface_type,
 						   GInterfaceInfo  *info);
-/**
- * GTypePlugin:
- * 
- * The GTypePlugin typedef is used as a placeholder 
- * for objects that implement the GTypePlugin interface.
- */
 /**
  * GTypePluginClass:
  * @use_plugin: Increases the use count of the plugin.

gobject/gvaluearray.c

@@ -30,35 +30,35 @@
 
 
 /**
- * SECTION:value_arrays
+ * GValueArray:
- * @short_description: A container structure to maintain an array of
+ * @n_values: number of values contained in the array
- *     generic values
+ * @values: array of values
- * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array()
- * @title: Value arrays
  *
- * The prime purpose of a #GValueArray is for it to be used as an
+ * A `GValueArray` is a container structure to hold an array of generic values.
- * object property that holds an array of values. A #GValueArray wraps
- * an array of #GValue elements in order for it to be used as a boxed
- * type through %G_TYPE_VALUE_ARRAY.
  *
- * #GValueArray is deprecated in favour of #GArray since GLib 2.32. It
+ * The prime purpose of a `GValueArray` is for it to be used as an
- * is possible to create a #GArray that behaves like a #GValueArray by
+ * object property that holds an array of values. A `GValueArray` wraps
- * using the size of #GValue as the element size, and by setting
+ * an array of `GValue` elements in order for it to be used as a boxed
- * g_value_unset() as the clear function using g_array_set_clear_func(),
+ * type through `G_TYPE_VALUE_ARRAY`.
- * for instance, the following code:
  *
- * |[<!-- language="C" --> 
+ * `GValueArray` is deprecated in favour of `GArray` since GLib 2.32.
+ * It is possible to create a `GArray` that behaves like a `GValueArray`
+ * by using the size of `GValue` as the element size, and by setting
+ * [func@GObject.value_unset] as the clear function using
+ * [method@GLib.Array.set_clear_func], for instance, the following code:
+ *
+ * ```c
  *   GValueArray *array = g_value_array_new (10);
- * ]|
+ * ```
  *
  * can be replaced by:
  *
- * |[<!-- language="C" --> 
+ * ```c
  *   GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
  *   g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
- * ]|
+ * ```
  *
- * Deprecated: 2.32: Use #GArray instead, if possible for the given use case,
+ * Deprecated: 2.32: Use `GArray` instead, if possible for the given use case,
  *    as described above.
  */
 

gobject/gvaluearray.h

@@ -41,13 +41,6 @@ G_BEGIN_DECLS
 
 /* --- typedefs & structs --- */
 typedef struct _GValueArray GValueArray;
-/**
- * GValueArray:
- * @n_values: number of values contained in the array
- * @values: array of values
- * 
- * A #GValueArray contains an array of #GValue elements.
- */
 struct _GValueArray
 {
   guint   n_values;