From 264ebbbb2b9e9f2224e9a1a2c6e57f0b8fa5195a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 13:09:52 +0100 Subject: [PATCH 01/25] docs: Move the GDBusMethodInvocation SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gdbusmethodinvocation.c | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/gio/gdbusmethodinvocation.c b/gio/gdbusmethodinvocation.c index e5a916681..00a6de26e 100644 --- a/gio/gdbusmethodinvocation.c +++ b/gio/gdbusmethodinvocation.c @@ -40,17 +40,18 @@ #include "glibintl.h" /** - * SECTION:gdbusmethodinvocation - * @short_description: Object for handling remote calls - * @include: gio/gio.h + * GDBusMethodInvocation: * - * Instances of the #GDBusMethodInvocation class are used when + * Instances of the `GDBusMethodInvocation` class are used when * handling D-Bus method calls. It provides a way to asynchronously * return results and errors. * - * The normal way to obtain a #GDBusMethodInvocation object is to receive - * it as an argument to the handle_method_call() function in a - * #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object(). + * The normal way to obtain a `GDBusMethodInvocation` object is to receive + * it as an argument to the `handle_method_call()` function in a + * [type@Gio.DBusInterfaceVTable] that was passed to + * [method@Gio.DBusConnection.register_object]. + * + * Since: 2.26 */ typedef struct _GDBusMethodInvocationClass GDBusMethodInvocationClass; @@ -68,14 +69,6 @@ struct _GDBusMethodInvocationClass GObjectClass parent_class; }; -/** - * GDBusMethodInvocation: - * - * The #GDBusMethodInvocation structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.26 - */ struct _GDBusMethodInvocation { /*< private >*/ From 99e25e74efb0fc9d7c71fec390a25639733e3eb8 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 13:10:10 +0100 Subject: [PATCH 02/25] docs: Move the GDBusObjectManagerClient SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gdbusobjectmanagerclient.c | 111 +++++++++++++++++---------------- gio/gdbusobjectmanagerclient.h | 8 --- 2 files changed, 57 insertions(+), 62 deletions(-) diff --git a/gio/gdbusobjectmanagerclient.c b/gio/gdbusobjectmanagerclient.c index b6b3b212c..ea6ec9093 100644 --- a/gio/gdbusobjectmanagerclient.c +++ b/gio/gdbusobjectmanagerclient.c @@ -43,85 +43,88 @@ #include "gmarshal-internal.h" /** - * SECTION:gdbusobjectmanagerclient - * @short_description: Client-side object manager - * @include: gio/gio.h + * GDBusObjectManagerClient: * - * #GDBusObjectManagerClient is used to create, monitor and delete object - * proxies for remote objects exported by a #GDBusObjectManagerServer (or any - * code implementing the + * `GDBusObjectManagerClient` is used to create, monitor and delete object + * proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer] + * (or any code implementing the * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * interface). * * Once an instance of this type has been created, you can connect to - * the #GDBusObjectManager::object-added and - * #GDBusObjectManager::object-removed signals and inspect the - * #GDBusObjectProxy objects returned by - * g_dbus_object_manager_get_objects(). + * the [signal@Gio.DBusObjectManager::object-added] and + * [signal@Gio.DBusObjectManager::object-removed signals] and inspect the + * [class@Gio.DBusObjectProxy] objects returned by + * [method@Gio.DBusObjectManager.get_objects]. * - * If the name for a #GDBusObjectManagerClient is not owned by anyone at + * If the name for a `GDBusObjectManagerClient` is not owned by anyone at * object construction time, the default behavior is to request the * message bus to launch an owner for the name. This behavior can be - * disabled using the %G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START - * flag. It's also worth noting that this only works if the name of + * disabled using the `G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START` + * flag. It’s also worth noting that this only works if the name of * interest is activatable in the first place. E.g. in some cases it * is not possible to launch an owner for the requested name. In this - * case, #GDBusObjectManagerClient object construction still succeeds but + * case, `GDBusObjectManagerClient` object construction still succeeds but * there will be no object proxies - * (e.g. g_dbus_object_manager_get_objects() returns the empty list) and - * the #GDBusObjectManagerClient:name-owner property is %NULL. + * (e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and + * the [property@Gio.DBusObjectManagerClient:name-owner] property is `NULL`. * * The owner of the requested name can come and go (for example - * consider a system service being restarted) – #GDBusObjectManagerClient - * handles this case too; simply connect to the #GObject::notify - * signal to watch for changes on the #GDBusObjectManagerClient:name-owner - * property. When the name owner vanishes, the behavior is that - * #GDBusObjectManagerClient:name-owner is set to %NULL (this includes - * emission of the #GObject::notify signal) and then - * #GDBusObjectManager::object-removed signals are synthesized + * consider a system service being restarted) – `GDBusObjectManagerClient` + * handles this case too; simply connect to the [signal@GObject.Object::notify] + * signal to watch for changes on the + * [property@Gio.DBusObjectManagerClient:name-owner] property. When the name + * owner vanishes, the behavior is that + * [property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this + * includes emission of the [signal@GObject.Object::notify] signal) and then + * [signal@Gio.DBusObjectManager::object-removed] signals are synthesized * for all currently existing object proxies. Since - * #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can - * use this information to disambiguate a synthesized signal from a - * genuine signal caused by object removal on the remote - * #GDBusObjectManager. Similarly, when a new name owner appears, - * #GDBusObjectManager::object-added signals are synthesized - * while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all - * object proxies have been added, the #GDBusObjectManagerClient:name-owner - * is set to the new name owner (this includes emission of the - * #GObject::notify signal). Furthermore, you are guaranteed that - * #GDBusObjectManagerClient:name-owner will alternate between a name owner - * (e.g. `:1.42`) and %NULL even in the case where + * [property@Gio.DBusObjectManagerClient:name-owner] is `NULL` when this + * happens, you can use this information to disambiguate a synthesized signal + * from a genuine signal caused by object removal on the remote + * [iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears, + * [signal@Gio.DBusObjectManager::object-added] signals are synthesized + * while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only + * when all object proxies have been added, the + * [property@Gio.DBusObjectManagerClient:name-owner] is set to the new name + * owner (this includes emission of the [signal@GObject.Object::notify] signal). + * Furthermore, you are guaranteed that + * [property@Gio.DBusObjectManagerClient:name-owner] will alternate between a + * name owner (e.g. `:1.42`) and `NULL` even in the case where * the name of interest is atomically replaced * - * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy - * instances. All signals (including the - * org.freedesktop.DBus.Properties::PropertiesChanged signal) - * delivered to #GDBusProxy instances are guaranteed to originate + * Ultimately, `GDBusObjectManagerClient` is used to obtain + * [class@Gio.DBusProxy] instances. All signals (including the + * `org.freedesktop.DBus.Properties::PropertiesChanged` signal) + * delivered to [class@Gio.DBusProxy] instances are guaranteed to originate * from the name owner. This guarantee along with the behavior * described above, means that certain race conditions including the - * "half the proxy is from the old owner and the other half is from - * the new owner" problem cannot happen. + * “half the proxy is from the old owner and the other half is from + * the new owner” problem cannot happen. * * To avoid having the application connect to signals on the returned - * #GDBusObjectProxy and #GDBusProxy objects, the - * #GDBusObject::interface-added, - * #GDBusObject::interface-removed, - * #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals - * are also emitted on the #GDBusObjectManagerClient instance managing these + * [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the + * [signal@Gio.DBusObject::interface-added], + * [signal@Gio.DBusObject::interface-removed], + * [signal@Gio.DBusProxy::g-properties-changed] and + * [signal@Gio.DBusProxy::g-signal] signals + * are also emitted on the `GDBusObjectManagerClient` instance managing these * objects. The signals emitted are - * #GDBusObjectManager::interface-added, - * #GDBusObjectManager::interface-removed, - * #GDBusObjectManagerClient::interface-proxy-properties-changed and - * #GDBusObjectManagerClient::interface-proxy-signal. + * [signal@Gio.DBusObjectManager::interface-added], + * [signal@Gio.DBusObjectManager::interface-removed], + * [signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and + * [signal@Gio.DBusObjectManagerClient::interface-proxy-signal]. * * Note that all callbacks and signals are emitted in the - * [thread-default main context][g-main-context-push-thread-default] - * that the #GDBusObjectManagerClient object was constructed - * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects - * originating from the #GDBusObjectManagerClient object will be created in + * thread-default main context (see + * [method@GLib.MainContext.push_thread_default]) that the + * `GDBusObjectManagerClient` object was constructed in. Additionally, the + * [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects + * originating from the `GDBusObjectManagerClient` object will be created in * the same context and, consequently, will deliver signals in the * same main loop. + * + * Since: 2.30 */ struct _GDBusObjectManagerClientPrivate diff --git a/gio/gdbusobjectmanagerclient.h b/gio/gdbusobjectmanagerclient.h index 2ebeedc02..f02c69389 100644 --- a/gio/gdbusobjectmanagerclient.h +++ b/gio/gdbusobjectmanagerclient.h @@ -37,14 +37,6 @@ G_BEGIN_DECLS typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass; typedef struct _GDBusObjectManagerClientPrivate GDBusObjectManagerClientPrivate; -/** - * GDBusObjectManagerClient: - * - * The #GDBusObjectManagerClient structure contains private data and should - * only be accessed using the provided API. - * - * Since: 2.30 - */ struct _GDBusObjectManagerClient { /*< private >*/ From 47e58fb4c64857a3096359baa3553bec90690f63 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 13:10:34 +0100 Subject: [PATCH 03/25] docs: Move the GDBusObjectProxy SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gdbusobjectproxy.c | 10 ++++------ gio/gdbusobjectproxy.h | 8 -------- 2 files changed, 4 insertions(+), 14 deletions(-) diff --git a/gio/gdbusobjectproxy.c b/gio/gdbusobjectproxy.c index ac5e4482a..46c3282a3 100644 --- a/gio/gdbusobjectproxy.c +++ b/gio/gdbusobjectproxy.c @@ -32,13 +32,11 @@ #include "glibintl.h" /** - * SECTION:gdbusobjectproxy - * @short_description: Client-side D-Bus object - * @include: gio/gio.h + * GDBusObjectProxy: * - * A #GDBusObjectProxy is an object used to represent a remote object - * with one or more D-Bus interfaces. Normally, you don't instantiate - * a #GDBusObjectProxy yourself - typically #GDBusObjectManagerClient + * A `GDBusObjectProxy` is an object used to represent a remote object + * with one or more D-Bus interfaces. Normally, you don’t instantiate + * a `GDBusObjectProxy` yourself — typically [class@Gio.DBusObjectManagerClient] * is used to obtain it. * * Since: 2.30 diff --git a/gio/gdbusobjectproxy.h b/gio/gdbusobjectproxy.h index ea5af0f09..8397dba37 100644 --- a/gio/gdbusobjectproxy.h +++ b/gio/gdbusobjectproxy.h @@ -37,14 +37,6 @@ G_BEGIN_DECLS typedef struct _GDBusObjectProxyClass GDBusObjectProxyClass; typedef struct _GDBusObjectProxyPrivate GDBusObjectProxyPrivate; -/** - * GDBusObjectProxy: - * - * The #GDBusObjectProxy structure contains private data and should - * only be accessed using the provided API. - * - * Since: 2.30 - */ struct _GDBusObjectProxy { /*< private >*/ From 6c930587ad76561274b067043038ebcb70bdfefa Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 13:11:07 +0100 Subject: [PATCH 04/25] docs: Move the GDesktopAppInfo SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gdesktopappinfo.c | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/gio/gdesktopappinfo.c b/gio/gdesktopappinfo.c index 292d7aa3b..4a76b3e51 100644 --- a/gio/gdesktopappinfo.c +++ b/gio/gdesktopappinfo.c @@ -63,12 +63,9 @@ #endif /** - * SECTION:gdesktopappinfo - * @title: GDesktopAppInfo - * @short_description: Application information from desktop files - * @include: gio/gdesktopappinfo.h + * GDesktopAppInfo: * - * #GDesktopAppInfo is an implementation of #GAppInfo based on + * `GDesktopAppInfo` is an implementation of [iface@Gio.AppInfo] based on * desktop files. * * Note that `` belongs to the UNIX-specific @@ -95,11 +92,6 @@ static gboolean g_desktop_app_info_ensure_saved (GDesktopAppInfo *info, GError **error); static gboolean g_desktop_app_info_load_file (GDesktopAppInfo *self); -/** - * GDesktopAppInfo: - * - * Information about an installed application from a desktop file. - */ struct _GDesktopAppInfo { GObject parent_instance; From 607eb851ba078a2c643ac3a13bf18437d719ea24 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 13:11:33 +0100 Subject: [PATCH 05/25] docs: Move the GFile*Stream SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gfileinputstream.c | 15 ++++++--------- gio/gfileinputstream.h | 8 -------- gio/gfileoutputstream.c | 19 ++++++++----------- gio/gfileoutputstream.h | 8 -------- 4 files changed, 14 insertions(+), 36 deletions(-) diff --git a/gio/gfileinputstream.c b/gio/gfileinputstream.c index a78db7e81..d98b7cccb 100644 --- a/gio/gfileinputstream.c +++ b/gio/gfileinputstream.c @@ -33,20 +33,17 @@ /** - * SECTION:gfileinputstream - * @short_description: File input streaming operations - * @include: gio/gio.h - * @see_also: #GInputStream, #GDataInputStream, #GSeekable + * GFileInputStream: * - * GFileInputStream provides input streams that take their + * `GFileInputStream` provides input streams that take their * content from a file. * - * GFileInputStream implements #GSeekable, which allows the input + * `GFileInputStream` implements [iface@Gio.Seekable], which allows the input * stream to jump to arbitrary positions in the file, provided the * filesystem of the file allows it. To find the position of a file - * input stream, use g_seekable_tell(). To find out if a file input - * stream supports seeking, use g_seekable_can_seek(). - * To position a file input stream, use g_seekable_seek(). + * input stream, use [method@Gio.Seekable.tell]. To find out if a file input + * stream supports seeking, use [iface@Gio.Seekable.can_seek]. + * To position a file input stream, use [iface@Gio.Seekable.seek]. **/ static void g_file_input_stream_seekable_iface_init (GSeekableIface *iface); diff --git a/gio/gfileinputstream.h b/gio/gfileinputstream.h index 54626951d..a1227654a 100644 --- a/gio/gfileinputstream.h +++ b/gio/gfileinputstream.h @@ -38,14 +38,6 @@ G_BEGIN_DECLS #define G_IS_FILE_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_INPUT_STREAM)) #define G_FILE_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_INPUT_STREAM, GFileInputStreamClass)) -/** - * GFileInputStream: - * - * A subclass of GInputStream for opened files. This adds - * a few file-specific operations and seeking. - * - * #GFileInputStream implements #GSeekable. - **/ typedef struct _GFileInputStreamClass GFileInputStreamClass; typedef struct _GFileInputStreamPrivate GFileInputStreamPrivate; diff --git a/gio/gfileoutputstream.c b/gio/gfileoutputstream.c index d767c53a1..05ae0c42e 100644 --- a/gio/gfileoutputstream.c +++ b/gio/gfileoutputstream.c @@ -33,25 +33,22 @@ /** - * SECTION:gfileoutputstream - * @short_description: File output streaming operations - * @include: gio/gio.h - * @see_also: #GOutputStream, #GDataOutputStream, #GSeekable + * GFileOutputStream: * - * GFileOutputStream provides output streams that write their + * `GFileOutputStream` provides output streams that write their * content to a file. * - * GFileOutputStream implements #GSeekable, which allows the output + * `GFileOutputStream` implements [iface@Gio.Seekable], which allows the output * stream to jump to arbitrary positions in the file and to truncate * the file, provided the filesystem of the file supports these * operations. * - * To find the position of a file output stream, use g_seekable_tell(). + * To find the position of a file output stream, use [method@Gio.Seekable.tell]. * To find out if a file output stream supports seeking, use - * g_seekable_can_seek().To position a file output stream, use - * g_seekable_seek(). To find out if a file output stream supports - * truncating, use g_seekable_can_truncate(). To truncate a file output - * stream, use g_seekable_truncate(). + * [method@Gio.Seekable.can_seek].To position a file output stream, use + * [method@Gio.Seekable.seek]. To find out if a file output stream supports + * truncating, use [method@Gio.Seekable.can_truncate]. To truncate a file output + * stream, use [method@Gio.Seekable.truncate]. **/ static void g_file_output_stream_seekable_iface_init (GSeekableIface *iface); diff --git a/gio/gfileoutputstream.h b/gio/gfileoutputstream.h index 576b21fb8..edc9b1032 100644 --- a/gio/gfileoutputstream.h +++ b/gio/gfileoutputstream.h @@ -38,14 +38,6 @@ G_BEGIN_DECLS #define G_IS_FILE_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILE_OUTPUT_STREAM)) #define G_FILE_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILE_OUTPUT_STREAM, GFileOutputStreamClass)) -/** - * GFileOutputStream: - * - * A subclass of GOutputStream for opened files. This adds - * a few file-specific operations and seeking and truncating. - * - * #GFileOutputStream implements GSeekable. - **/ typedef struct _GFileOutputStreamClass GFileOutputStreamClass; typedef struct _GFileOutputStreamPrivate GFileOutputStreamPrivate; From 822521215bbd2b50fc042f62044faf013907b2ac Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 13:11:56 +0100 Subject: [PATCH 06/25] docs: Move the GFilter*Stream SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gfilterinputstream.c | 4 +--- gio/gfilterinputstream.h | 5 ----- gio/gfilteroutputstream.c | 4 +--- gio/gfilteroutputstream.h | 5 ----- 4 files changed, 2 insertions(+), 16 deletions(-) diff --git a/gio/gfilterinputstream.c b/gio/gfilterinputstream.c index 46cb0ef77..f70319ec7 100644 --- a/gio/gfilterinputstream.c +++ b/gio/gfilterinputstream.c @@ -27,9 +27,7 @@ /** - * SECTION:gfilterinputstream - * @short_description: Filter Input Stream - * @include: gio/gio.h + * GFilterInputStream: * * Base class for input stream implementations that perform some * kind of filtering operation on a base stream. Typical examples diff --git a/gio/gfilterinputstream.h b/gio/gfilterinputstream.h index df6032c27..6009eea8d 100644 --- a/gio/gfilterinputstream.h +++ b/gio/gfilterinputstream.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_FILTER_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_INPUT_STREAM)) #define G_FILTER_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_INPUT_STREAM, GFilterInputStreamClass)) -/** - * GFilterInputStream: - * - * A base class for all input streams that work on an underlying stream. - **/ typedef struct _GFilterInputStreamClass GFilterInputStreamClass; struct _GFilterInputStream diff --git a/gio/gfilteroutputstream.c b/gio/gfilteroutputstream.c index 637f448ff..7da6c7f16 100644 --- a/gio/gfilteroutputstream.c +++ b/gio/gfilteroutputstream.c @@ -27,9 +27,7 @@ /** - * SECTION:gfilteroutputstream - * @short_description: Filter Output Stream - * @include: gio/gio.h + * GFilterOutputStream: * * Base class for output stream implementations that perform some * kind of filtering operation on a base stream. Typical examples diff --git a/gio/gfilteroutputstream.h b/gio/gfilteroutputstream.h index 472f9d80d..160e80daf 100644 --- a/gio/gfilteroutputstream.h +++ b/gio/gfilteroutputstream.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_FILTER_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_FILTER_OUTPUT_STREAM)) #define G_FILTER_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_FILTER_OUTPUT_STREAM, GFilterOutputStreamClass)) -/** - * GFilterOutputStream: - * - * A base class for all output streams that work on an underlying stream. - **/ typedef struct _GFilterOutputStreamClass GFilterOutputStreamClass; struct _GFilterOutputStream From 06c2e3370763cd6cc272ad782decbd1747af7e23 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:04:03 +0100 Subject: [PATCH 07/25] docs: Move the GNetworkService SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gnetworkservice.c | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/gio/gnetworkservice.c b/gio/gnetworkservice.c index dac0814d0..cca17f0af 100644 --- a/gio/gnetworkservice.c +++ b/gio/gnetworkservice.c @@ -43,28 +43,19 @@ /** - * SECTION:gnetworkservice - * @short_description: A GSocketConnectable for resolving SRV records - * @include: gio/gio.h + * GNetworkService: * - * Like #GNetworkAddress does with hostnames, #GNetworkService + * Like [class@Gio.NetworkAddress] does with hostnames, `GNetworkService` * provides an easy way to resolve a SRV record, and then attempt to * connect to one of the hosts that implements that service, handling * service priority/weighting, multiple IP addresses, and multiple * address families. * - * See #GSrvTarget for more information about SRV records, and see - * #GSocketConnectable for an example of using the connectable + * See [struct@Gio.SrvTarget] for more information about SRV records, and see + * [iface@Gio.SocketConnectable] for an example of using the connectable * interface. */ -/** - * GNetworkService: - * - * A #GSocketConnectable for resolving a SRV record and connecting to - * that service. - */ - struct _GNetworkServicePrivate { gchar *service, *protocol, *domain, *scheme; From 34fc02d5acb128f5dc6c9abad7ec8543805dbfbd Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:04:21 +0100 Subject: [PATCH 08/25] docs: Move the GProxy SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gproxy.c | 12 +++++------- gio/gproxy.h | 7 ------- 2 files changed, 5 insertions(+), 14 deletions(-) diff --git a/gio/gproxy.c b/gio/gproxy.c index 40ba78f7c..31d32245f 100644 --- a/gio/gproxy.c +++ b/gio/gproxy.c @@ -29,16 +29,14 @@ #include "glibintl.h" /** - * SECTION:gproxy - * @short_description: Interface for proxy handling - * @include: gio/gio.h + * GProxy: * - * A #GProxy handles connecting to a remote host via a given type of - * proxy server. It is implemented by the 'gio-proxy' extension point. + * A `GProxy` handles connecting to a remote host via a given type of + * proxy server. It is implemented by the `gio-proxy` extension point. * The extensions are named after their proxy protocol name. As an * example, a SOCKS5 proxy implementation can be retrieved with the - * name 'socks5' using the function - * g_io_extension_point_get_extension_by_name(). + * name `socks5` using the function + * [method@Gio.IOExtensionPoint.get_extension_by_name]. * * Since: 2.26 **/ diff --git a/gio/gproxy.h b/gio/gproxy.h index de82410f9..9fcf7cc01 100644 --- a/gio/gproxy.h +++ b/gio/gproxy.h @@ -48,13 +48,6 @@ G_BEGIN_DECLS */ #define G_PROXY_EXTENSION_POINT_NAME "gio-proxy" -/** - * GProxy: - * - * Interface that handles proxy connection and payload. - * - * Since: 2.26 - */ typedef struct _GProxyInterface GProxyInterface; /** From 7b32b5a9f089a3c4e82e89a52627bfaef6431846 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:04:40 +0100 Subject: [PATCH 09/25] docs: Move the GProxyAddressEnumerator SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gproxyaddressenumerator.c | 19 +++++++++---------- gio/gproxyaddressenumerator.h | 8 -------- 2 files changed, 9 insertions(+), 18 deletions(-) diff --git a/gio/gproxyaddressenumerator.c b/gio/gproxyaddressenumerator.c index 98987f227..bf9215b8f 100644 --- a/gio/gproxyaddressenumerator.c +++ b/gio/gproxyaddressenumerator.c @@ -42,19 +42,18 @@ #include "gsocketconnectable.h" /** - * SECTION:gproxyaddressenumerator - * @short_description: Proxy wrapper enumerator for socket addresses - * @include: gio/gio.h + * GProxyAddressEnumerator: * - * #GProxyAddressEnumerator is a wrapper around #GSocketAddressEnumerator which - * takes the #GSocketAddress instances returned by the #GSocketAddressEnumerator - * and wraps them in #GProxyAddress instances, using the given - * #GProxyAddressEnumerator:proxy-resolver. + * `GProxyAddressEnumerator` is a wrapper around + * [class@Gio.SocketAddressEnumerator] which takes the [class@Gio.SocketAddress] + * instances returned by the [class@Gio.SocketAddressEnumerator] + * and wraps them in [class@Gio.ProxyAddress] instances, using the given + * [property@Gio.ProxyAddressEnumerator:proxy-resolver]. * * This enumerator will be returned (for example, by - * g_socket_connectable_enumerate()) as appropriate when a proxy is configured; - * there should be no need to manually wrap a #GSocketAddressEnumerator instance - * with one. + * [method@Gio.SocketConnectable.enumerate]) as appropriate when a proxy is + * configured; there should be no need to manually wrap a + * [class@Gio.SocketAddressEnumerator] instance with one. */ #define GET_PRIVATE(o) (G_PROXY_ADDRESS_ENUMERATOR (o)->priv) diff --git a/gio/gproxyaddressenumerator.h b/gio/gproxyaddressenumerator.h index b8d36a685..7d36ef03e 100644 --- a/gio/gproxyaddressenumerator.h +++ b/gio/gproxyaddressenumerator.h @@ -38,14 +38,6 @@ G_BEGIN_DECLS #define G_IS_PROXY_ADDRESS_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_PROXY_ADDRESS_ENUMERATOR)) #define G_PROXY_ADDRESS_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_PROXY_ADDRESS_ENUMERATOR, GProxyAddressEnumeratorClass)) -/** - * GProxyAddressEnumerator: - * - * A subclass of #GSocketAddressEnumerator that takes another address - * enumerator and wraps each of its results in a #GProxyAddress as - * directed by the default #GProxyResolver. - */ - typedef struct _GProxyAddressEnumeratorClass GProxyAddressEnumeratorClass; typedef struct _GProxyAddressEnumeratorPrivate GProxyAddressEnumeratorPrivate; From dfab5a3d298bbc7def124b4fa8e900eac5e780bd Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:05:06 +0100 Subject: [PATCH 10/25] docs: Move the GProxyResolver SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gproxyresolver.c | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/gio/gproxyresolver.c b/gio/gproxyresolver.c index c24323404..c21fc8d26 100644 --- a/gio/gproxyresolver.c +++ b/gio/gproxyresolver.c @@ -36,17 +36,16 @@ #include "gnetworkingprivate.h" /** - * SECTION:gproxyresolver - * @short_description: Asynchronous and cancellable network proxy resolver - * @include: gio/gio.h + * GProxyResolver: * - * #GProxyResolver provides synchronous and asynchronous network proxy - * resolution. #GProxyResolver is used within #GSocketClient through - * the method g_socket_connectable_proxy_enumerate(). + * `GProxyResolver` provides synchronous and asynchronous network proxy + * resolution. `GProxyResolver` is used within [class@Gio.SocketClient] through + * the method [method@Gio.SocketConnectable.proxy_enumerate]. * - * Implementations of #GProxyResolver based on libproxy and GNOME settings can - * be found in glib-networking. GIO comes with an implementation for use inside - * Flatpak portals. + * Implementations of `GProxyResolver` based on + * [libproxy](https://github.com/libproxy/libproxy) and GNOME settings can be + * found in [glib-networking](https://gitlab.gnome.org/GNOME/glib-networking). + * GIO comes with an implementation for use inside Flatpak portals. */ /** From bbb5479d5a63c25bcffd3882a0c3289337cdfab2 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:05:24 +0100 Subject: [PATCH 11/25] docs: Move the GResolver SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gresolver.c | 40 ++++++++++++++++++---------------------- 1 file changed, 18 insertions(+), 22 deletions(-) diff --git a/gio/gresolver.c b/gio/gresolver.c index 4c29d5873..695f9dd8d 100644 --- a/gio/gresolver.c +++ b/gio/gresolver.c @@ -43,22 +43,27 @@ /** - * SECTION:gresolver - * @short_description: Asynchronous and cancellable DNS resolver - * @include: gio/gio.h + * GResolver: * - * #GResolver provides cancellable synchronous and asynchronous DNS - * resolution, for hostnames (g_resolver_lookup_by_address(), - * g_resolver_lookup_by_name() and their async variants) and SRV - * (service) records (g_resolver_lookup_service()). + * The object that handles DNS resolution. Use [func@Gio.Resolver.get_default] + * to get the default resolver. * - * #GNetworkAddress and #GNetworkService provide wrappers around - * #GResolver functionality that also implement #GSocketConnectable, - * making it easy to connect to a remote host/service. + * `GResolver` provides cancellable synchronous and asynchronous DNS + * resolution, for hostnames ([method@Gio.Resolver.lookup_by_address], + * [method@Gio.Resolver.lookup_by_name] and their async variants) and SRV + * (service) records ([method@Gio.Resolver.lookup_service]). * - * The default resolver (see g_resolver_get_default()) has a timeout of 30s set - * on it since GLib 2.78. Earlier versions of GLib did not support resolver - * timeouts. + * [class@Gio.NetworkAddress] and [class@Gio.NetworkService] provide wrappers + * around `GResolver` functionality that also implement + * [iface@Gio.SocketConnectable], making it easy to connect to a remote + * host/service. + * + * The default resolver (see [func@Gio.Resolver.get_default]) has a timeout of + * 30s set on it since GLib 2.78. Earlier versions of GLib did not support + * resolver timeouts. + * + * This is an abstract type; subclasses of it implement different resolvers for + * different platforms and situations. */ typedef enum { @@ -83,15 +88,6 @@ struct _GResolverPrivate { #endif }; -/** - * GResolver: - * - * The object that handles DNS resolution. Use g_resolver_get_default() - * to get the default resolver. - * - * This is an abstract type; subclasses of it implement different resolvers for - * different platforms and situations. - */ G_DEFINE_ABSTRACT_TYPE_WITH_CODE (GResolver, g_resolver, G_TYPE_OBJECT, G_ADD_PRIVATE (GResolver) g_networking_init ();) From b0b5ed8c34a7c0fe85cc5c21b8a44291f30fd3b0 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:05:43 +0100 Subject: [PATCH 12/25] docs: Move the GResource SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gresource.c | 193 +++++++++++++++++++++++++++--------------------- 1 file changed, 107 insertions(+), 86 deletions(-) diff --git a/gio/gresource.c b/gio/gresource.c index 9965e2698..042e8207c 100644 --- a/gio/gresource.c +++ b/gio/gresource.c @@ -48,69 +48,72 @@ static void register_lazy_static_resources (void); G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref) /** - * SECTION:gresource - * @short_description: Resource framework - * @include: gio/gio.h + * GResource: * * Applications and libraries often contain binary or textual data that is * really part of the application, rather than user data. For instance - * #GtkBuilder .ui files, splashscreen images, GMenu markup XML, CSS files, - * icons, etc. These are often shipped as files in `$datadir/appname`, or - * manually included as literal strings in the code. + * [class@Gtk.Builder] `.ui` files, splashscreen images, [class@Gio.Menu] markup + * XML, CSS files, icons, etc. These are often shipped as files in + * `$datadir/appname`, or manually included as literal strings in the code. * - * The #GResource API and the [glib-compile-resources][glib-compile-resources] program - * provide a convenient and efficient alternative to this which has some nice properties. You - * maintain the files as normal files, so its easy to edit them, but during the build the files - * are combined into a binary bundle that is linked into the executable. This means that loading - * the resource files are efficient (as they are already in memory, shared with other instances) and - * simple (no need to check for things like I/O errors or locate the files in the filesystem). It + * The `GResource` API and the + * [`glib-compile-resources`](glib-compile-resources.html) program provide a + * convenient and efficient alternative to this which has some nice properties. + * You maintain the files as normal files, so it’s easy to edit them, but during + * the build the files are combined into a binary bundle that is linked into the + * executable. This means that loading the resource files are efficient (as they + * are already in memory, shared with other instances) and simple (no need to + * check for things like I/O errors or locate the files in the filesystem). It * also makes it easier to create relocatable applications. * - * Resource files can also be marked as compressed. Such files will be included in the resource bundle - * in a compressed form, but will be automatically uncompressed when the resource is used. This - * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away. + * Resource files can also be marked as compressed. Such files will be included + * in the resource bundle in a compressed form, but will be automatically + * uncompressed when the resource is used. This is very useful e.g. for larger + * text files that are parsed once (or rarely) and then thrown away. * * Resource files can also be marked to be preprocessed, by setting the value of the * `preprocess` attribute to a comma-separated list of preprocessing options. * The only options currently supported are: * - * `xml-stripblanks` which will use the xmllint command - * to strip ignorable whitespace from the XML file. For this to work, - * the `XMLLINT` environment variable must be set to the full path to - * the xmllint executable, or xmllint must be in the `PATH`; otherwise - * the preprocessing step is skipped. + * - `xml-stripblanks` which will use the [`xmllint`](man:xmllint(1)) command + * to strip ignorable whitespace from the XML file. For this to work, + * the `XMLLINT` environment variable must be set to the full path to + * the xmllint executable, or xmllint must be in the `PATH`; otherwise + * the preprocessing step is skipped. * - * `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the - * `gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format, - * which allows you to create pixbufs directly using the data inside the - * resource file, rather than an (uncompressed) copy of it. For this, the - * `gdk-pixbuf-pixdata` program must be in the `PATH`, or the - * `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the - * `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort. - * `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource - * supports embedding modern image formats just as well. Instead of using it, - * embed a PNG or SVG file in your #GResource. + * - `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the + * `gdk-pixbuf-pixdata` command to convert images to the [class@Gdk.Pixdata] + * format, which allows you to create pixbufs directly using the data inside + * the resource file, rather than an (uncompressed) copy of it. For this, the + * `gdk-pixbuf-pixdata` program must be in the `PATH`, or the + * `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to + * the `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will + * abort. `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as + * `GResource` supports embedding modern image formats just as well. Instead + * of using it, embed a PNG or SVG file in your `GResource`. * - * `json-stripblanks` which will use the `json-glib-format` command to strip - * ignorable whitespace from the JSON file. For this to work, the - * `JSON_GLIB_FORMAT` environment variable must be set to the full path to the - * `json-glib-format` executable, or it must be in the `PATH`; - * otherwise the preprocessing step is skipped. In addition, at least version - * 1.6 of `json-glib-format` is required. + * - `json-stripblanks` which will use the + * [`json-glib-format`](man:json-glib-format(1)) command to strip ignorable + * whitespace from the JSON file. For this to work, the `JSON_GLIB_FORMAT` + * environment variable must be set to the full path to the + * `json-glib-format` executable, or it must be in the `PATH`; otherwise the + * preprocessing step is skipped. In addition, at least version 1.6 of + * `json-glib-format` is required. * - * Resource files will be exported in the GResource namespace using the + * Resource files will be exported in the `GResource` namespace using the * combination of the given `prefix` and the filename from the `file` element. * The `alias` attribute can be used to alter the filename to expose them at a * different location in the resource namespace. Typically, this is used to * include files from a different source directory without exposing the source * directory in the resource namespace, as in the example below. * - * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program - * which takes an XML file that describes the bundle, and a set of files that the XML references. These - * are combined into a binary resource bundle. + * Resource bundles are created by the + * [`glib-compile-resources`](glib-compile-resources.html) program + * which takes an XML file that describes the bundle, and a set of files that + * the XML references. These are combined into a binary resource bundle. * * An example resource description: - * |[ + * ```xml * * * @@ -120,74 +123,92 @@ G_DEFINE_BOXED_TYPE (GResource, g_resource, g_resource_ref, g_resource_unref) * data/example.css * * - * ]| + * ``` * * This will create a resource bundle with the following files: - * |[ + * ``` * /org/gtk/Example/data/splashscreen.png * /org/gtk/Example/dialog.ui * /org/gtk/Example/menumarkup.xml * /org/gtk/Example/example.css - * ]| + * ``` * - * Note that all resources in the process share the same namespace, so use Java-style - * path prefixes (like in the above example) to avoid conflicts. + * Note that all resources in the process share the same namespace, so use + * Java-style path prefixes (like in the above example) to avoid conflicts. * - * You can then use [glib-compile-resources][glib-compile-resources] to compile the XML to a - * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and - * --generate-header arguments to create a source file and header to link directly into your application. + * You can then use [`glib-compile-resources`](glib-compile-resources.html) to + * compile the XML to a binary bundle that you can load with + * [func@Gio.Resource.load]. However, it’s more common to use the + * `--generate-source` and `--generate-header` arguments to create a source file + * and header to link directly into your application. * This will generate `get_resource()`, `register_resource()` and * `unregister_resource()` functions, prefixed by the `--c-name` argument passed - * to [glib-compile-resources][glib-compile-resources]. `get_resource()` returns - * the generated #GResource object. The register and unregister functions - * register the resource so its files can be accessed using - * g_resources_lookup_data(). + * to [`glib-compile-resources`](glib-compile-resources.html). `get_resource()` + * returns the generated `GResource` object. The register and unregister + * functions register the resource so its files can be accessed using + * [func@Gio.resources_lookup_data]. * - * Once a #GResource has been created and registered all the data in it can be accessed globally in the process by - * using API calls like g_resources_open_stream() to stream the data or g_resources_lookup_data() to get a direct pointer - * to the data. You can also use URIs like "resource:///org/gtk/Example/data/splashscreen.png" with #GFile to access - * the resource data. + * Once a `GResource` has been created and registered all the data in it can be + * accessed globally in the process by using API calls like + * [func@Gio.resources_open_stream] to stream the data or + * [func@Gio.resources_lookup_data] to get a direct pointer to the data. You can + * also use URIs like `resource:///org/gtk/Example/data/splashscreen.png` with + * [iface@Gio.File] to access the resource data. * - * Some higher-level APIs, such as #GtkApplication, will automatically load - * resources from certain well-known paths in the resource namespace as a + * Some higher-level APIs, such as [class@Gtk.Application], will automatically + * load resources from certain well-known paths in the resource namespace as a * convenience. See the documentation for those APIs for details. * - * There are two forms of the generated source, the default version uses the compiler support for constructor - * and destructor functions (where available) to automatically create and register the #GResource on startup - * or library load time. If you pass `--manual-register`, two functions to register/unregister the resource are created - * instead. This requires an explicit initialization call in your application/library, but it works on all platforms, - * even on the minor ones where constructors are not supported. (Constructor support is available for at least Win32, Mac OS and Linux.) + * There are two forms of the generated source, the default version uses the + * compiler support for constructor and destructor functions (where available) + * to automatically create and register the `GResource` on startup or library + * load time. If you pass `--manual-register`, two functions to + * register/unregister the resource are created instead. This requires an + * explicit initialization call in your application/library, but it works on all + * platforms, even on the minor ones where constructors are not supported. + * (Constructor support is available for at least Win32, Mac OS and Linux.) * - * Note that resource data can point directly into the data segment of e.g. a library, so if you are unloading libraries - * during runtime you need to be very careful with keeping around pointers to data from a resource, as this goes away - * when the library is unloaded. However, in practice this is not generally a problem, since most resource accesses - * are for your own resources, and resource data is often used once, during parsing, and then released. + * Note that resource data can point directly into the data segment of e.g. a + * library, so if you are unloading libraries during runtime you need to be very + * careful with keeping around pointers to data from a resource, as this goes + * away when the library is unloaded. However, in practice this is not generally + * a problem, since most resource accesses are for your own resources, and + * resource data is often used once, during parsing, and then released. * - * When debugging a program or testing a change to an installed version, it is often useful to be able to - * replace resources in the program or library, without recompiling, for debugging or quick hacking and testing - * purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to selectively overlay - * resources with replacements from the filesystem. It is a %G_SEARCHPATH_SEPARATOR-separated list of substitutions to perform - * during resource lookups. It is ignored when running in a setuid process. + * # Overlays + * + * When debugging a program or testing a change to an installed version, it is + * often useful to be able to replace resources in the program or library, + * without recompiling, for debugging or quick hacking and testing purposes. + * Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment + * variable to selectively overlay resources with replacements from the + * filesystem. It is a `G_SEARCHPATH_SEPARATOR`-separated list of substitutions + * to perform during resource lookups. It is ignored when running in a setuid + * process. * * A substitution has the form * - * |[ - * /org/gtk/libgtk=/home/desrt/gtk-overlay - * ]| + * ``` + * /org/gtk/libgtk=/home/desrt/gtk-overlay + * ``` * - * The part before the `=` is the resource subpath for which the overlay applies. The part after is a - * filesystem path which contains files and subdirectories as you would like to be loaded as resources with the + * The part before the `=` is the resource subpath for which the overlay + * applies. The part after is a filesystem path which contains files and + * subdirectories as you would like to be loaded as resources with the * equivalent names. * - * In the example above, if an application tried to load a resource with the resource path - * `/org/gtk/libgtk/ui/gtkdialog.ui` then GResource would check the filesystem path - * `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was found there, it would be used instead. This is an - * overlay, not an outright replacement, which means that if a file is not found at that path, the built-in - * version will be used instead. Whiteouts are not currently supported. + * In the example above, if an application tried to load a resource with the + * resource path `/org/gtk/libgtk/ui/gtkdialog.ui` then `GResource` would check + * the filesystem path `/home/desrt/gtk-overlay/ui/gtkdialog.ui`. If a file was + * found there, it would be used instead. This is an overlay, not an outright + * replacement, which means that if a file is not found at that path, the + * built-in version will be used instead. Whiteouts are not currently + * supported. * - * Substitutions must start with a slash, and must not contain a trailing slash before the '='. The path after - * the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the - * location of a single resource with an individual file. + * Substitutions must start with a slash, and must not contain a trailing slash + * before the `=`. The path after the slash should ideally be absolute, but + * this is not strictly required. It is possible to overlay the location of a + * single resource with an individual file. * * Since: 2.32 */ From 838388cc683fc280d534b071719cce73b2910f96 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:06:03 +0100 Subject: [PATCH 13/25] docs: Move the GSimpleAction SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsimpleaction.c | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/gio/gsimpleaction.c b/gio/gsimpleaction.c index 4e7e5b5ee..1ffc71ac5 100644 --- a/gio/gsimpleaction.c +++ b/gio/gsimpleaction.c @@ -26,25 +26,15 @@ #include "gaction.h" #include "glibintl.h" -/** - * SECTION:gsimpleaction - * @title: GSimpleAction - * @short_description: A simple GAction implementation - * @include: gio/gio.h - * - * A #GSimpleAction is the obvious simple implementation of the #GAction - * interface. This is the easiest way to create an action for purposes of - * adding it to a #GSimpleActionGroup. - * - * See also #GtkAction. - */ - /** * GSimpleAction: * - * #GSimpleAction is an opaque data structure and can only be accessed - * using the following functions. - **/ + * A `GSimpleAction` is the obvious simple implementation of the + * [iface@Gio.Action] interface. This is the easiest way to create an action for + * purposes of adding it to a [class@Gio.SimpleActionGroup]. + * + * See also [class@Gtk.Action]. + */ struct _GSimpleAction { From 481c856e042362059514c1fd0759c0714ac9df37 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:06:25 +0100 Subject: [PATCH 14/25] docs: Move the GSimpleActionGroup SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsimpleactiongroup.c | 12 ++++++------ gio/gsimpleactiongroup.h | 7 ------- 2 files changed, 6 insertions(+), 13 deletions(-) diff --git a/gio/gsimpleactiongroup.c b/gio/gsimpleactiongroup.c index 28ca21ab5..cd768a0a1 100644 --- a/gio/gsimpleactiongroup.c +++ b/gio/gsimpleactiongroup.c @@ -28,13 +28,13 @@ #include "gaction.h" /** - * SECTION:gsimpleactiongroup - * @title: GSimpleActionGroup - * @short_description: A simple GActionGroup implementation - * @include: gio/gio.h + * GSimpleActionGroup: * - * #GSimpleActionGroup is a hash table filled with #GAction objects, - * implementing the #GActionGroup and #GActionMap interfaces. + * `GSimpleActionGroup` is a hash table filled with [iface@Gio.Action] objects, + * implementing the [iface@Gio.ActionGroup] and [iface@Gio.ActionMap] + * interfaces. + * + * Since: 2.28 **/ struct _GSimpleActionGroupPrivate diff --git a/gio/gsimpleactiongroup.h b/gio/gsimpleactiongroup.h index 99282baff..48f669db8 100644 --- a/gio/gsimpleactiongroup.h +++ b/gio/gsimpleactiongroup.h @@ -46,13 +46,6 @@ G_BEGIN_DECLS typedef struct _GSimpleActionGroupPrivate GSimpleActionGroupPrivate; typedef struct _GSimpleActionGroupClass GSimpleActionGroupClass; -/** - * GSimpleActionGroup: - * - * The #GSimpleActionGroup structure contains private data and should only be accessed using the provided API. - * - * Since: 2.28 - */ struct _GSimpleActionGroup { /*< private >*/ From 1b94e0351f8b94ca030fb38688d0c8250cd7cd26 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:06:45 +0100 Subject: [PATCH 15/25] docs: Move the GSrvTarget SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsrvtarget.c | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/gio/gsrvtarget.c b/gio/gsrvtarget.c index cecd4eb7d..f5f17ef64 100644 --- a/gio/gsrvtarget.c +++ b/gio/gsrvtarget.c @@ -31,24 +31,24 @@ /** - * SECTION:gsrvtarget - * @short_description: DNS SRV record target - * @include: gio/gio.h + * GSrvTarget: + * + * A single target host/port that a network service is running on. * * SRV (service) records are used by some network protocols to provide * service-specific aliasing and load-balancing. For example, XMPP * (Jabber) uses SRV records to locate the XMPP server for a domain; - * rather than connecting directly to "example.com" or assuming a - * specific server hostname like "xmpp.example.com", an XMPP client - * would look up the "xmpp-client" SRV record for "example.com", and + * rather than connecting directly to ‘example.com’ or assuming a + * specific server hostname like ‘xmpp.example.com’, an XMPP client + * would look up the `xmpp-client` SRV record for ‘example.com’, and * then connect to whatever host was pointed to by that record. * - * You can use g_resolver_lookup_service() or - * g_resolver_lookup_service_async() to find the #GSrvTargets + * You can use [method@Gio.Resolver.lookup_service] or + * [method@Gio.Resolver.lookup_service_async] to find the `GSrvTarget`s * for a given service. However, if you are simply planning to connect - * to the remote service, you can use #GNetworkService's - * #GSocketConnectable interface and not need to worry about - * #GSrvTarget at all. + * to the remote service, you can use [class@Gio.NetworkService]’s + * [iface@Gio.SocketConnectable] interface and not need to worry about + * `GSrvTarget` at all. */ struct _GSrvTarget { @@ -59,12 +59,6 @@ struct _GSrvTarget { guint16 weight; }; -/** - * GSrvTarget: - * - * A single target host/port that a network service is running on. - */ - G_DEFINE_BOXED_TYPE (GSrvTarget, g_srv_target, g_srv_target_copy, g_srv_target_free) From 8d45e4c66bfa04a8380de89b0c1ed0e955085238 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:07:05 +0100 Subject: [PATCH 16/25] docs: Move the GSubprocessLauncher SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsubprocesslauncher.c | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/gio/gsubprocesslauncher.c b/gio/gsubprocesslauncher.c index 6142213a4..cb64e870f 100644 --- a/gio/gsubprocesslauncher.c +++ b/gio/gsubprocesslauncher.c @@ -17,16 +17,13 @@ */ /** - * SECTION:gsubprocesslauncher - * @title: GSubprocess Launcher - * @short_description: Environment options for launching a child process - * @include: gio/gio.h + * GSubprocessLauncher: * * This class contains a set of options for launching child processes, * such as where its standard input and output will be directed, the * argument list, the environment, and more. * - * While the #GSubprocess class has high level functions covering + * While the [class@Gio.Subprocess] class has high level functions covering * popular cases, use of this class allows access to more advanced * options. It can also be used to launch multiple subprocesses with * a similar configuration. From 97886412e8d8002ae27316dab762c4ba88c67e3e Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:07:25 +0100 Subject: [PATCH 17/25] docs: Move the GTcpConnection SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtcpconnection.c | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/gio/gtcpconnection.c b/gio/gtcpconnection.c index e0865d859..c89cf98e2 100644 --- a/gio/gtcpconnection.c +++ b/gio/gtcpconnection.c @@ -13,13 +13,9 @@ */ /** - * SECTION:gtcpconnection - * @title: GTcpConnection - * @short_description: A TCP GSocketConnection - * @include: gio/gio.h - * @see_also: #GSocketConnection. + * GTcpConnection: * - * This is the subclass of #GSocketConnection that is created + * This is the subclass of [class@Gio.SocketConnection] that is created * for TCP/IP sockets. * * Since: 2.22 From ed875eb4c98df16b4b44abfa3a160ed90e8fda1c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:07:42 +0100 Subject: [PATCH 18/25] docs: Move the GTcpWrapperConnection SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtcpwrapperconnection.c | 25 +++++++------------------ 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/gio/gtcpwrapperconnection.c b/gio/gtcpwrapperconnection.c index 686aa42e0..151c71307 100644 --- a/gio/gtcpwrapperconnection.c +++ b/gio/gtcpwrapperconnection.c @@ -21,29 +21,18 @@ */ /** - * SECTION:gtcpwrapperconnection - * @title: GTcpWrapperConnection - * @short_description: Wrapper for non-GSocketConnection-based, - * GSocket-based GIOStreams - * @include: gio/gio.h - * @see_also: #GSocketConnection. + * GTcpWrapperConnection: * - * A #GTcpWrapperConnection can be used to wrap a #GIOStream that is - * based on a #GSocket, but which is not actually a - * #GSocketConnection. This is used by #GSocketClient so that it can - * always return a #GSocketConnection, even when the connection it has - * actually created is not directly a #GSocketConnection. + * A `GTcpWrapperConnection` can be used to wrap a [class@Gio.IOStream] that is + * based on a [class@Gio.Socket], but which is not actually a + * [class@Gio.SocketConnection]. This is used by [class@Gio.SocketClient] so + * that it can always return a [class@Gio.SocketConnection], even when the + * connection it has actually created is not directly a + * [class@Gio.SocketConnection]. * * Since: 2.28 */ -/** - * GTcpWrapperConnection: - * - * #GTcpWrapperConnection is an opaque data structure and can only be accessed - * using the following functions. - **/ - #include "config.h" #include "gtcpwrapperconnection.h" From 5817f52222647d3339c5c639c295de2149ae63ea Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:08:03 +0100 Subject: [PATCH 19/25] docs: Move the GTestDBus SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtestdbus.c | 81 ++++++++++++++++++++++++------------------------- 1 file changed, 40 insertions(+), 41 deletions(-) diff --git a/gio/gtestdbus.c b/gio/gtestdbus.c index 2f93c229d..09083ad27 100644 --- a/gio/gtestdbus.c +++ b/gio/gtestdbus.c @@ -333,25 +333,23 @@ _g_test_watcher_remove_pid (GPid pid) /* GTestDBus object implementation */ /** - * SECTION:gtestdbus - * @short_description: D-Bus testing helper - * @include: gio/gio.h + * GTestDBus: * - * A helper class for testing code which uses D-Bus without touching the user's + * A helper class for testing code which uses D-Bus without touching the user’s * session bus. * - * Note that #GTestDBus modifies the user’s environment, calling setenv(). - * This is not thread-safe, so all #GTestDBus calls should be completed before - * threads are spawned, or should have appropriate locking to ensure no access - * conflicts to environment variables shared between #GTestDBus and other - * threads. + * Note that `GTestDBus` modifies the user’s environment, calling + * [`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus` + * calls should be completed before threads are spawned, or should have + * appropriate locking to ensure no access conflicts to environment variables + * shared between `GTestDBus` and other threads. * - * ## Creating unit tests using GTestDBus + * ## Creating unit tests using `GTestDBus` * * Testing of D-Bus services can be tricky because normally we only ever run * D-Bus services over an existing instance of the D-Bus daemon thus we - * usually don't activate D-Bus services that are not yet installed into the - * target system. The #GTestDBus object makes this easier for us by taking care + * usually don’t activate D-Bus services that are not yet installed into the + * target system. The `GTestDBus` object makes this easier for us by taking care * of the lower level tasks such as running a private D-Bus daemon and looking * up uninstalled services in customizable locations, typically in your source * code tree. @@ -364,20 +362,24 @@ _g_test_watcher_remove_pid (GPid pid) * uninstalled service executable in your source tree. Using autotools we would * achieve this by adding a file such as `my-server.service.in` in the services * directory and have it processed by configure. - * |[ - * [D-BUS Service] - * Name=org.gtk.GDBus.Examples.ObjectManager - * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server - * ]| + * + * ``` + * [D-BUS Service] + * Name=org.gtk.GDBus.Examples.ObjectManager + * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server + * ``` + * * You will also need to indicate this service directory in your test * fixtures, so you will need to pass the path while compiling your * test cases. Typically this is done with autotools with an added * preprocessor flag specified to compile your tests such as: - * |[ - * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" - * ]| - * Once you have a service definition file which is local to your source tree, - * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. + * + * ``` + * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\" + * ``` + * + * Once you have a service definition file which is local to your source tree, + * you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding. * * An example of a test fixture for D-Bus services can be found * here: @@ -386,42 +388,39 @@ _g_test_watcher_remove_pid (GPid pid) * Note that these examples only deal with isolating the D-Bus aspect of your * service. To successfully run isolated unit tests on your service you may need * some additional modifications to your test case fixture. For example; if your - * service uses GSettings and installs a schema then it is important that your test service - * not load the schema in the ordinary installed location (chances are that your service - * and schema files are not yet installed, or worse; there is an older version of the - * schema file sitting in the install location). + * service uses [class@Gio.Settings] and installs a schema then it is important + * that your test service not load the schema in the ordinary installed location + * (chances are that your service and schema files are not yet installed, or + * worse; there is an older version of the schema file sitting in the install + * location). * * Most of the time we can work around these obstacles using the * environment. Since the environment is inherited by the D-Bus daemon - * created by #GTestDBus and then in turn inherited by any services the + * created by `GTestDBus` and then in turn inherited by any services the * D-Bus daemon activates, using the setup routine for your fixture is * a practical place to help sandbox your runtime environment. For the * rather typical GSettings case we can work around this by setting * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas - * in the above fixture_setup() routine. + * in the above `fixture_setup()` routine. * - * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved - * by compiling the schemas locally as a step before running test cases, an autotools setup might - * do the following in the directory holding schemas: - * |[ + * The GSettings schemas need to be locally pre-compiled for this to work. This + * can be achieved by compiling the schemas locally as a step before running + * test cases, an autotools setup might do the following in the directory + * holding schemas: + * + * ``` * all-am: * $(GLIB_COMPILE_SCHEMAS) . * * CLEANFILES += gschemas.compiled - * ]| + * ``` + * + * Since: 2.34 */ typedef struct _GTestDBusClass GTestDBusClass; typedef struct _GTestDBusPrivate GTestDBusPrivate; -/** - * GTestDBus: - * - * The #GTestDBus structure contains only private data and - * should only be accessed using the provided API. - * - * Since: 2.34 - */ struct _GTestDBus { GObject parent; From 325e3a6f5b45f5075e1821e95f9e9388d2147582 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:08:21 +0100 Subject: [PATCH 20/25] docs: Move the GThemedIcon SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gthemedicon.c | 15 +++++++-------- gio/gthemedicon.h | 5 ----- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/gio/gthemedicon.c b/gio/gthemedicon.c index 8551bd27d..178a68162 100644 --- a/gio/gthemedicon.c +++ b/gio/gthemedicon.c @@ -31,16 +31,15 @@ /** - * SECTION:gthemedicon - * @short_description: Icon theming support - * @include: gio/gio.h - * @see_also: #GIcon, #GLoadableIcon + * GThemedIcon: * - * #GThemedIcon is an implementation of #GIcon that supports icon themes. - * #GThemedIcon contains a list of all of the icons present in an icon - * theme, so that icons can be looked up quickly. #GThemedIcon does + * `GThemedIcon` is an implementation of [iface@Gio.Icon] that supports icon + * themes. + * + * `GThemedIcon` contains a list of all of the icons present in an icon + * theme, so that icons can be looked up quickly. `GThemedIcon` does * not provide actual pixmaps for icons, just the icon names. - * Ideally something like gtk_icon_theme_choose_icon() should be used to + * Ideally something like [method@Gtk.IconTheme.choose_icon] should be used to * resolve the list of names so that fallback icons work nicely with * themes that inherit other themes. **/ diff --git a/gio/gthemedicon.h b/gio/gthemedicon.h index 5ac36ce4f..432896d58 100644 --- a/gio/gthemedicon.h +++ b/gio/gthemedicon.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_THEMED_ICON_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_THEMED_ICON)) #define G_THEMED_ICON_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_THEMED_ICON, GThemedIconClass)) -/** - * GThemedIcon: - * - * An implementation of #GIcon for themed icons. - **/ typedef struct _GThemedIconClass GThemedIconClass; GIO_AVAILABLE_IN_ALL From 74fbc7592035c9e77b9bdebd76156362e7e96b39 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:08:40 +0100 Subject: [PATCH 21/25] docs: Move the GThreadedSocketService SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gthreadedsocketservice.c | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/gio/gthreadedsocketservice.c b/gio/gthreadedsocketservice.c index 63dc2a883..5a19744bf 100644 --- a/gio/gthreadedsocketservice.c +++ b/gio/gthreadedsocketservice.c @@ -23,27 +23,24 @@ */ /** - * SECTION:gthreadedsocketservice - * @title: GThreadedSocketService - * @short_description: A threaded GSocketService - * @include: gio/gio.h - * @see_also: #GSocketService. + * GThreadedSocketService: * - * A #GThreadedSocketService is a simple subclass of #GSocketService + * A `GThreadedSocketService` is a simple subclass of [class@Gio.SocketService] * that handles incoming connections by creating a worker thread and * dispatching the connection to it by emitting the - * #GThreadedSocketService::run signal in the new thread. + * [signal@Gio.ThreadedSocketService::run signal] in the new thread. * - * The signal handler may perform blocking IO and need not return + * The signal handler may perform blocking I/O and need not return * until the connection is closed. * * The service is implemented using a thread pool, so there is a * limited amount of threads available to serve incoming requests. - * The service automatically stops the #GSocketService from accepting + * The service automatically stops the [class@Gio.SocketService] from accepting * new connections when all threads are busy. * - * As with #GSocketService, you may connect to #GThreadedSocketService::run, - * or subclass and override the default handler. + * As with [class@Gio.SocketService], you may connect to + * [signal@Gio.ThreadedSocketService::run], or subclass and override the default + * handler. */ #include "config.h" From 850878dfaa5b7539428f07e1b5831b04c73f9965 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:09:00 +0100 Subject: [PATCH 22/25] docs: Move the GTlsFileDatabase SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtlsfiledatabase.c | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/gio/gtlsfiledatabase.c b/gio/gtlsfiledatabase.c index e32faf94c..6050008ab 100644 --- a/gio/gtlsfiledatabase.c +++ b/gio/gtlsfiledatabase.c @@ -30,25 +30,15 @@ #include "glibintl.h" /** - * SECTION:gtlsfiledatabase - * @short_description: TLS file based database type - * @include: gio/gio.h + * GTlsFileDatabase: * - * #GTlsFileDatabase is implemented by #GTlsDatabase objects which load - * their certificate information from a file. It is an interface which + * `GTlsFileDatabase` is implemented by [class@Gio.TlsDatabase] objects which + * load their certificate information from a file. It is an interface which * TLS library specific subtypes implement. * * Since: 2.30 */ -/** - * GTlsFileDatabase: - * - * Implemented by a #GTlsDatabase which allows you to load certificates - * from a file. - * - * Since: 2.30 - */ G_DEFINE_INTERFACE (GTlsFileDatabase, g_tls_file_database, G_TYPE_TLS_DATABASE) static void From c015ecf0b7fdc8d8ceb2c9b0a9841b921016028d Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:09:21 +0100 Subject: [PATCH 23/25] docs: Move the GTlsInteraction SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtlsinteraction.c | 25 ++++++++----------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/gio/gtlsinteraction.c b/gio/gtlsinteraction.c index 9b15fcc30..acafd4fe5 100644 --- a/gio/gtlsinteraction.c +++ b/gio/gtlsinteraction.c @@ -36,37 +36,28 @@ /** - * SECTION:gtlsinteraction - * @short_description: Interaction with the user during TLS operations. - * @include: gio/gio.h + * GTlsInteraction: * - * #GTlsInteraction provides a mechanism for the TLS connection and database + * `GTlsInteraction` provides a mechanism for the TLS connection and database * code to interact with the user. It can be used to ask the user for passwords. * - * To use a #GTlsInteraction with a TLS connection use - * g_tls_connection_set_interaction(). + * To use a `GTlsInteraction` with a TLS connection use + * [method@Gio.TlsConnection.set_interaction]. * * Callers should instantiate a derived class that implements the various * interaction methods to show the required dialogs. * * Callers should use the 'invoke' functions like - * g_tls_interaction_invoke_ask_password() to run interaction methods. These - * functions make sure that the interaction is invoked in the main loop + * [method@Gio.TlsInteraction.invoke_ask_password] to run interaction methods. + * These functions make sure that the interaction is invoked in the main loop * and not in the current thread, if the current thread is not running the * main loop. * - * Derived classes can choose to implement whichever interactions methods they'd + * Derived classes can choose to implement whichever interactions methods they’d * like to support by overriding those virtual methods in their class * initialization function. Any interactions not implemented will return - * %G_TLS_INTERACTION_UNHANDLED. If a derived class implements an async method, + * `G_TLS_INTERACTION_UNHANDLED`. If a derived class implements an async method, * it must also implement the corresponding finish method. - */ - -/** - * GTlsInteraction: - * - * An object representing interaction that the TLS connection and database - * might have with the user. * * Since: 2.30 */ From 2f662b6063c90547fc980bbf55c4a14118581f59 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:09:37 +0100 Subject: [PATCH 24/25] docs: Move the GTlsPassword SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtlspassword.c | 9 --------- 1 file changed, 9 deletions(-) diff --git a/gio/gtlspassword.c b/gio/gtlspassword.c index b3a6f4a94..f64a658ff 100644 --- a/gio/gtlspassword.c +++ b/gio/gtlspassword.c @@ -29,15 +29,6 @@ #include -/** - * SECTION:gtlspassword - * @title: GTlsPassword - * @short_description: TLS Passwords for prompting - * @include: gio/gio.h - * - * Holds a password used in TLS. - */ - /** * GTlsPassword: * From 14b02d2631cf932b76ca5643f6d5b9ac1c040699 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 25 Oct 2023 15:09:51 +0100 Subject: [PATCH 25/25] docs: Move the GUnixFDList SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gunixfdlist.c | 22 ++++++---------------- 1 file changed, 6 insertions(+), 16 deletions(-) diff --git a/gio/gunixfdlist.c b/gio/gunixfdlist.c index e06171414..f17bb8dc0 100644 --- a/gio/gunixfdlist.c +++ b/gio/gunixfdlist.c @@ -15,18 +15,15 @@ */ /** - * SECTION:gunixfdlist - * @title: GUnixFDList - * @short_description: An object containing a set of UNIX file descriptors - * @include: gio/gunixfdlist.h - * @see_also: #GUnixFDMessage + * GUnixFDList: * - * A #GUnixFDList contains a list of file descriptors. It owns the file + * A `GUnixFDList` contains a list of file descriptors. It owns the file * descriptors that it contains, closing them when finalized. * - * It may be wrapped in a #GUnixFDMessage and sent over a #GSocket in - * the %G_SOCKET_FAMILY_UNIX family by using g_socket_send_message() - * and received using g_socket_receive_message(). + * It may be wrapped in a [class@Gio.UnixFDMessage] and sent over a + * [class@Gio.Socket] in the `G_SOCKET_FAMILY_UNIX` family by using + * [method@Gio.Socket.send_message] and received using + * [method@Gio.Socket.receive_message]. * * Before 2.74, `` belonged to the UNIX-specific GIO * interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file when @@ -35,13 +32,6 @@ * Since 2.74, the API is available for Windows. */ -/** - * GUnixFDList: - * - * #GUnixFDList is an opaque data structure and can only be accessed - * using the following functions. - **/ - #include "config.h" #include