From 226e9f16ea5d649e3945510a3bd5a369d311d587 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:52:39 +0100 Subject: [PATCH 01/18] docs: Move the GDBusServer SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gdbusserver.c | 31 ++++++++++++------------------- 1 file changed, 12 insertions(+), 19 deletions(-) diff --git a/gio/gdbusserver.c b/gio/gdbusserver.c index db0c9ab50..fa769bebb 100644 --- a/gio/gdbusserver.c +++ b/gio/gdbusserver.c @@ -63,35 +63,28 @@ G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER) /** - * SECTION:gdbusserver - * @short_description: Helper for accepting connections - * @include: gio/gio.h + * GDBusServer: * - * #GDBusServer is a helper for listening to and accepting D-Bus + * `GDBusServer` is a helper for listening to and accepting D-Bus * connections. This can be used to create a new D-Bus server, allowing two * peers to use the D-Bus protocol for their own specialized communication. * A server instance provided in this way will not perform message routing or - * implement the org.freedesktop.DBus interface. + * implement the + * [`org.freedesktop.DBus` interface](https://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-messages). * * To just export an object on a well-known name on a message bus, such as the - * session or system bus, you should instead use g_bus_own_name(). + * session or system bus, you should instead use [func@Gio.bus_own_name]. * * An example of peer-to-peer communication with GDBus can be found * in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). * - * Note that a minimal #GDBusServer will accept connections from any - * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver - * that only accepts connections that have successfully authenticated - * as the same user that is running the #GDBusServer. Since GLib 2.68 this can - * be achieved more simply by passing the - * %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server. - */ - -/** - * GDBusServer: - * - * The #GDBusServer structure contains only private data and - * should only be accessed using the provided API. + * Note that a minimal `GDBusServer` will accept connections from any + * peer. In many use-cases it will be necessary to add a + * [class@Gio.DBusAuthObserver] that only accepts connections that have + * successfully authenticated as the same user that is running the + * `GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing + * the `G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER` flag to the + * server. * * Since: 2.26 */ From 22275f389b18c039d03ef60c768711e9f4521469 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:52:58 +0100 Subject: [PATCH 02/18] docs: Move the GLoadableIcon SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gloadableicon.c | 9 +++------ gio/gloadableicon.h | 6 ------ 2 files changed, 3 insertions(+), 12 deletions(-) diff --git a/gio/gloadableicon.c b/gio/gloadableicon.c index 1d3460d3c..13012bae2 100644 --- a/gio/gloadableicon.c +++ b/gio/gloadableicon.c @@ -29,13 +29,10 @@ /** - * SECTION:gloadableicon - * @short_description: Loadable Icons - * @include: gio/gio.h - * @see_also: #GIcon, #GThemedIcon + * GLoadableIcon: * - * Extends the #GIcon interface and adds the ability to - * load icons from streams. + * `GLoadableIcon` extends the [iface@Gio.Icon] interface and adds the ability + * to load icons from streams. **/ static void g_loadable_icon_real_load_async (GLoadableIcon *icon, diff --git a/gio/gloadableicon.h b/gio/gloadableicon.h index 7a576ef9c..bde104b07 100644 --- a/gio/gloadableicon.h +++ b/gio/gloadableicon.h @@ -36,12 +36,6 @@ G_BEGIN_DECLS #define G_IS_LOADABLE_ICON(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_LOADABLE_ICON)) #define G_LOADABLE_ICON_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_LOADABLE_ICON, GLoadableIconIface)) -/** - * GLoadableIcon: - * - * Generic type for all kinds of icons that can be loaded - * as a stream. - **/ typedef struct _GLoadableIconIface GLoadableIconIface; /** From ffff217a9d20cbea641c4f6bc842831729e37016 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:53:24 +0100 Subject: [PATCH 03/18] docs: Move the GMemory*Stream SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gmemoryinputstream.c | 11 ++++------- gio/gmemoryinputstream.h | 5 ----- gio/gmemoryoutputstream.c | 11 ++++------- gio/gmemoryoutputstream.h | 5 ----- 4 files changed, 8 insertions(+), 24 deletions(-) diff --git a/gio/gmemoryinputstream.c b/gio/gmemoryinputstream.c index 80f77d107..de164542d 100644 --- a/gio/gmemoryinputstream.c +++ b/gio/gmemoryinputstream.c @@ -32,16 +32,13 @@ /** - * SECTION:gmemoryinputstream - * @short_description: Streaming input operations on memory chunks - * @include: gio/gio.h - * @see_also: #GMemoryOutputStream + * GMemoryInputStream: * - * #GMemoryInputStream is a class for using arbitrary + * `GMemoryInputStream` is a class for using arbitrary * memory chunks as input for GIO streaming input operations. * - * As of GLib 2.34, #GMemoryInputStream implements - * #GPollableInputStream. + * As of GLib 2.34, `GMemoryInputStream` implements + * [iface@Gio.PollableInputStream]. */ struct _GMemoryInputStreamPrivate { diff --git a/gio/gmemoryinputstream.h b/gio/gmemoryinputstream.h index fb72f2314..b34656700 100644 --- a/gio/gmemoryinputstream.h +++ b/gio/gmemoryinputstream.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_MEMORY_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MEMORY_INPUT_STREAM)) #define G_MEMORY_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MEMORY_INPUT_STREAM, GMemoryInputStreamClass)) -/** - * GMemoryInputStream: - * - * Implements #GInputStream for arbitrary memory chunks. - **/ typedef struct _GMemoryInputStreamClass GMemoryInputStreamClass; typedef struct _GMemoryInputStreamPrivate GMemoryInputStreamPrivate; diff --git a/gio/gmemoryoutputstream.c b/gio/gmemoryoutputstream.c index 0339a7ad7..b5b8265b2 100644 --- a/gio/gmemoryoutputstream.c +++ b/gio/gmemoryoutputstream.c @@ -35,16 +35,13 @@ /** - * SECTION:gmemoryoutputstream - * @short_description: Streaming output operations on memory chunks - * @include: gio/gio.h - * @see_also: #GMemoryInputStream + * GMemoryOutputStream: * - * #GMemoryOutputStream is a class for using arbitrary + * `GMemoryOutputStream` is a class for using arbitrary * memory chunks as output for GIO streaming output operations. * - * As of GLib 2.34, #GMemoryOutputStream trivially implements - * #GPollableOutputStream: it always polls as ready. + * As of GLib 2.34, `GMemoryOutputStream` trivially implements + * [iface@Gio.PollableOutputStream]: it always polls as ready. */ #define MIN_ARRAY_SIZE 16 diff --git a/gio/gmemoryoutputstream.h b/gio/gmemoryoutputstream.h index 08f5dcffb..6fb077beb 100644 --- a/gio/gmemoryoutputstream.h +++ b/gio/gmemoryoutputstream.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_MEMORY_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_MEMORY_OUTPUT_STREAM)) #define G_MEMORY_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_MEMORY_OUTPUT_STREAM, GMemoryOutputStreamClass)) -/** - * GMemoryOutputStream: - * - * Implements #GOutputStream for arbitrary memory chunks. - **/ typedef struct _GMemoryOutputStreamClass GMemoryOutputStreamClass; typedef struct _GMemoryOutputStreamPrivate GMemoryOutputStreamPrivate; From e044045ea4fefd6330f2f604f36f396da3958bd0 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:53:48 +0100 Subject: [PATCH 04/18] docs: Move the GNetworkMonitor SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gnetworkmonitor.c | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/gio/gnetworkmonitor.c b/gio/gnetworkmonitor.c index f017b168b..754914e4b 100644 --- a/gio/gnetworkmonitor.c +++ b/gio/gnetworkmonitor.c @@ -31,24 +31,14 @@ #include "gtask.h" /** - * SECTION:gnetworkmonitor - * @title: GNetworkMonitor - * @short_description: Network status monitor - * @include: gio/gio.h + * GNetworkMonitor: * - * #GNetworkMonitor provides an easy-to-use cross-platform API + * `GNetworkMonitor` provides an easy-to-use cross-platform API * for monitoring network connectivity. On Linux, the available * implementations are based on the kernel's netlink interface and * on NetworkManager. * * There is also an implementation for use inside Flatpak sandboxes. - */ - -/** - * GNetworkMonitor: - * - * #GNetworkMonitor monitors the status of network connections and - * indicates when a possibly-user-visible change has occurred. * * Since: 2.32 */ From 723fc462235c5ce985ceefc7d143716f4a931f19 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:54:12 +0100 Subject: [PATCH 05/18] docs: Move the GNotification SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gnotification.c | 60 +++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 35 deletions(-) diff --git a/gio/gnotification.c b/gio/gnotification.c index abe68a215..0e48ef077 100644 --- a/gio/gnotification.c +++ b/gio/gnotification.c @@ -28,63 +28,53 @@ #include "gioenumtypes.h" /** - * SECTION:gnotification - * @short_description: User Notifications (pop up messages) - * @include: gio/gio.h + * GNotification: * - * #GNotification is a mechanism for creating a notification to be shown - * to the user -- typically as a pop-up notification presented by the + * `GNotification` is a mechanism for creating a notification to be shown + * to the user — typically as a pop-up notification presented by the * desktop environment shell. * - * The key difference between #GNotification and other similar APIs is + * The key difference between `GNotification` and other similar APIs is * that, if supported by the desktop environment, notifications sent - * with #GNotification will persist after the application has exited, + * with `GNotification` will persist after the application has exited, * and even across system reboots. * * Since the user may click on a notification while the application is - * not running, applications using #GNotification should be able to be - * started as a D-Bus service, using #GApplication. + * not running, applications using `GNotification` should be able to be + * started as a D-Bus service, using [class@Gio.Application]. * - * In order for #GNotification to work, the application must have installed + * In order for `GNotification` to work, the application must have installed * a `.desktop` file. For example: - * |[ - * [Desktop Entry] - * Name=Test Application - * Comment=Description of what Test Application does - * Exec=gnome-test-application - * Icon=org.gnome.TestApplication - * Terminal=false - * Type=Application - * Categories=GNOME;GTK;TestApplication Category; - * StartupNotify=true - * DBusActivatable=true - * X-GNOME-UsesNotifications=true - * ]| + * ``` + * [Desktop Entry] + * Name=Test Application + * Comment=Description of what Test Application does + * Exec=gnome-test-application + * Icon=org.gnome.TestApplication + * Terminal=false + * Type=Application + * Categories=GNOME;GTK;TestApplication Category; + * StartupNotify=true + * DBusActivatable=true + * X-GNOME-UsesNotifications=true + * ``` * * The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center * that this application uses notifications, so it can be listed in the * Control Center’s ‘Notifications’ panel. * * The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, - * where `org.gnome.TestApplication` is the ID passed to g_application_new(). + * where `org.gnome.TestApplication` is the ID passed to + * [ctor@Gio.Application.new]. * * User interaction with a notification (either the default action, or * buttons) must be associated with actions on the application (ie: - * "app." actions). It is not possible to route user interaction + * `app.` actions). It is not possible to route user interaction * through the notification itself, because the object will not exist if * the application is autostarted as a result of a notification being * clicked. * - * A notification can be sent with g_application_send_notification(). - * - * Since: 2.40 - **/ - -/** - * GNotification: - * - * This structure type is private and should only be accessed using the - * public APIs. + * A notification can be sent with [method@Gio.Application.send_notification]. * * Since: 2.40 **/ From ed34ddc355f6df3e6d30b9f3dcb7e100fa56fd76 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:54:31 +0100 Subject: [PATCH 06/18] docs: Move the GPermission SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gpermission.c | 23 ++++++----------------- 1 file changed, 6 insertions(+), 17 deletions(-) diff --git a/gio/gpermission.c b/gio/gpermission.c index 957e57f2d..9dc3e90a2 100644 --- a/gio/gpermission.c +++ b/gio/gpermission.c @@ -31,13 +31,9 @@ /** - * SECTION:gpermission - * @title: GPermission - * @short_description: An object representing the permission - * to perform a certain action - * @include: gio/gio.h + * GPermission: * - * A #GPermission represents the status of the caller's permission to + * A `GPermission` represents the status of the caller’s permission to * perform a certain action. * * You can query if the action is currently allowed and if it is @@ -47,20 +43,13 @@ * There is also an API to actually acquire the permission and one to * release it. * - * As an example, a #GPermission might represent the ability for the - * user to write to a #GSettings object. This #GPermission object could - * then be used to decide if it is appropriate to show a "Click here to - * unlock" button in a dialog and to provide the mechanism to invoke + * As an example, a `GPermission` might represent the ability for the + * user to write to a [class@Gio.Settings] object. This `GPermission` object + * could then be used to decide if it is appropriate to show a “Click here to + * unlock” button in a dialog and to provide the mechanism to invoke * when that button is clicked. **/ -/** - * GPermission: - * - * #GPermission is an opaque data structure and can only be accessed - * using the following functions. - **/ - struct _GPermissionPrivate { gboolean allowed; From d9e35c264b063f74a14737023dc0af317d90d632 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:54:52 +0100 Subject: [PATCH 07/18] docs: Move the GPolllable*Stream SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gpollableinputstream.c | 13 +++++-------- gio/gpollableinputstream.h | 7 ------- gio/gpollableoutputstream.c | 13 +++++-------- gio/gpollableoutputstream.h | 7 ------- 4 files changed, 10 insertions(+), 30 deletions(-) diff --git a/gio/gpollableinputstream.c b/gio/gpollableinputstream.c index 28eedbf6a..a57d5abe2 100644 --- a/gio/gpollableinputstream.c +++ b/gio/gpollableinputstream.c @@ -27,19 +27,16 @@ #include "glibintl.h" /** - * SECTION:gpollableinputstream - * @short_description: Interface for pollable input streams - * @include: gio/gio.h - * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased + * GPollableInputStream: * - * #GPollableInputStream is implemented by #GInputStreams that + * `GPollableInputStream` is implemented by [class@Gio.InputStream]s that * can be polled for readiness to read. This can be used when * interfacing with a non-GIO API that expects * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. * - * Some classes may implement #GPollableInputStream but have only certain - * instances of that class be pollable. If g_pollable_input_stream_can_poll() - * returns %FALSE, then the behavior of other #GPollableInputStream methods is + * Some classes may implement `GPollableInputStream` but have only certain + * instances of that class be pollable. If [method@Gio.PollableInputStream.can_poll] + * returns false, then the behavior of other `GPollableInputStream` methods is * undefined. * * Since: 2.28 diff --git a/gio/gpollableinputstream.h b/gio/gpollableinputstream.h index 7b659477c..924b52ee6 100644 --- a/gio/gpollableinputstream.h +++ b/gio/gpollableinputstream.h @@ -34,13 +34,6 @@ G_BEGIN_DECLS #define G_IS_POLLABLE_INPUT_STREAM(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_POLLABLE_INPUT_STREAM)) #define G_POLLABLE_INPUT_STREAM_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_POLLABLE_INPUT_STREAM, GPollableInputStreamInterface)) -/** - * GPollableInputStream: - * - * An interface for a #GInputStream that can be polled for readability. - * - * Since: 2.28 - */ typedef struct _GPollableInputStreamInterface GPollableInputStreamInterface; /** diff --git a/gio/gpollableoutputstream.c b/gio/gpollableoutputstream.c index 9a85225ef..f36ac139b 100644 --- a/gio/gpollableoutputstream.c +++ b/gio/gpollableoutputstream.c @@ -28,19 +28,16 @@ #include "glibintl.h" /** - * SECTION:gpollableoutputstream - * @short_description: Interface for pollable output streams - * @include: gio/gio.h - * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream + * GPollableOutputStream: * - * #GPollableOutputStream is implemented by #GOutputStreams that + * `GPollableOutputStream` is implemented by [class@Gio.OutputStream]s that * can be polled for readiness to write. This can be used when * interfacing with a non-GIO API that expects * UNIX-file-descriptor-style asynchronous I/O rather than GIO-style. * - * Some classes may implement #GPollableOutputStream but have only certain - * instances of that class be pollable. If g_pollable_output_stream_can_poll() - * returns %FALSE, then the behavior of other #GPollableOutputStream methods is + * Some classes may implement `GPollableOutputStream` but have only certain + * instances of that class be pollable. If [method@Gio.PollableOutputStream.can_poll] + * returns false, then the behavior of other `GPollableOutputStream` methods is * undefined. * * Since: 2.28 diff --git a/gio/gpollableoutputstream.h b/gio/gpollableoutputstream.h index a98bfa2a8..e20c2f3b8 100644 --- a/gio/gpollableoutputstream.h +++ b/gio/gpollableoutputstream.h @@ -34,13 +34,6 @@ G_BEGIN_DECLS #define G_IS_POLLABLE_OUTPUT_STREAM(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_POLLABLE_OUTPUT_STREAM)) #define G_POLLABLE_OUTPUT_STREAM_GET_INTERFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_POLLABLE_OUTPUT_STREAM, GPollableOutputStreamInterface)) -/** - * GPollableOutputStream: - * - * An interface for a #GOutputStream that can be polled for writeability. - * - * Since: 2.28 - */ typedef struct _GPollableOutputStreamInterface GPollableOutputStreamInterface; /** From ca02613987ef79c386c1a38a1193710c9c62840a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:55:15 +0100 Subject: [PATCH 08/18] docs: Move the GPowerProfileMonitor SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gpowerprofilemonitor.c | 27 ++++++++------------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/gio/gpowerprofilemonitor.c b/gio/gpowerprofilemonitor.c index 9c22411f0..38eb05f9f 100644 --- a/gio/gpowerprofilemonitor.c +++ b/gio/gpowerprofilemonitor.c @@ -32,15 +32,12 @@ #include "gtask.h" /** - * SECTION:gpowerprofilemonitor - * @title: GPowerProfileMonitor - * @short_description: Power profile monitor - * @include: gio/gio.h + * GPowerProfileMonitor: * - * #GPowerProfileMonitor makes it possible for applications as well as OS components - * to monitor system power profiles and act upon them. It currently only exports - * whether the system is in “Power Saver” mode (known as “Low Power” mode on - * some systems). + * `GPowerProfileMonitor` makes it possible for applications as well as OS + * components to monitor system power profiles and act upon them. It currently + * only exports whether the system is in “Power Saver” mode (known as + * “Low Power” mode on some systems). * * When in “Low Power” mode, it is recommended that applications: * - disable automatic downloads; @@ -57,17 +54,9 @@ * or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to * profile GPU usage. * - * Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled - * signal, and unref the #GPowerProfileMonitor itself when exiting. - * - * Since: 2.70 - */ - -/** - * GPowerProfileMonitor: - * - * #GPowerProfileMonitor monitors system power profile and notifies on - * changes. + * Don’t forget to disconnect the [signal@GObject.Object::notify] signal for + * [property@Gio.PowerProfileMonitor:power-saver-enabled], and unref the + * `GPowerProfileMonitor` itself when exiting. * * Since: 2.70 */ From 658bb30f061e46612cd36bccd049e15f2d32637c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:55:38 +0100 Subject: [PATCH 09/18] docs: Move the GPropertyAction SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gpropertyaction.c | 53 +++++++++++++++++-------------------------- 1 file changed, 21 insertions(+), 32 deletions(-) diff --git a/gio/gpropertyaction.c b/gio/gpropertyaction.c index 52eae84e5..ae8903c04 100644 --- a/gio/gpropertyaction.c +++ b/gio/gpropertyaction.c @@ -28,17 +28,14 @@ #include "glibintl.h" /** - * SECTION:gpropertyaction - * @title: GPropertyAction - * @short_description: A GAction reflecting a GObject property - * @include: gio/gio.h + * GPropertyAction: * - * A #GPropertyAction is a way to get a #GAction with a state value - * reflecting and controlling the value of a #GObject property. + * A `GPropertyAction` is a way to get a [iface@Gio.Action] with a state value + * reflecting and controlling the value of a [class@GObject.Object] property. * * The state of the action will correspond to the value of the property. * Changing it will change the property (assuming the requested value - * matches the requirements as specified in the #GParamSpec). + * matches the requirements as specified in the [type@GObject.ParamSpec]). * * Only the most common types are presently supported. Booleans are * mapped to booleans, strings to strings, signed/unsigned integers to @@ -46,16 +43,16 @@ * * If the property is an enum then the state will be string-typed and * conversion will automatically be performed between the enum value and - * "nick" string as per the #GEnumValue table. + * ‘nick’ string as per the [type@GObject.EnumValue] table. * * Flags types are not currently supported. * * Properties of object types, boxed types and pointer types are not * supported and probably never will be. * - * Properties of #GVariant types are not currently supported. + * Properties of [type@GLib.Variant] types are not currently supported. * - * If the property is boolean-valued then the action will have a NULL + * If the property is boolean-valued then the action will have a `NULL` * parameter type, and activating the action (with no parameter) will * toggle the value of the property. * @@ -64,26 +61,26 @@ * * The general idea here is to reduce the number of locations where a * particular piece of state is kept (and therefore has to be synchronised - * between). #GPropertyAction does not have a separate state that is kept - * in sync with the property value -- its state is the property value. + * between). `GPropertyAction` does not have a separate state that is kept + * in sync with the property value — its state is the property value. * - * For example, it might be useful to create a #GAction corresponding to - * the "visible-child-name" property of a #GtkStack so that the current - * page can be switched from a menu. The active radio indication in the + * For example, it might be useful to create a [iface@Gio.Action] corresponding + * to the `visible-child-name` property of a [class@Gtk.Stack] so that the + * current page can be switched from a menu. The active radio indication in the * menu is then directly determined from the active page of the - * #GtkStack. + * [class@Gtk.Stack]. * - * An anti-example would be binding the "active-id" property on a - * #GtkComboBox. This is because the state of the combobox itself is + * An anti-example would be binding the `active-id` property on a + * [class@Gtk.ComboBox]. This is because the state of the combobox itself is * probably uninteresting and is actually being used to control * something else. * - * Another anti-example would be to bind to the "visible-child-name" - * property of a #GtkStack if this value is actually stored in - * #GSettings. In that case, the real source of the value is - * #GSettings. If you want a #GAction to control a setting stored in - * #GSettings, see g_settings_create_action() instead, and possibly - * combine its use with g_settings_bind(). + * Another anti-example would be to bind to the `visible-child-name` + * property of a [class@Gtk.Stack] if this value is actually stored in + * [class@Gio.Settings]. In that case, the real source of the value is + * [class@Gio.Settings]. If you want a [iface@Gio.Action] to control a setting + * stored in [class@Gio.Settings], see [method@Gio.Settings.create_action] + * instead, and possibly combine its use with [method@Gio.Settings.bind]. * * Since: 2.38 **/ @@ -98,14 +95,6 @@ struct _GPropertyAction gboolean invert_boolean; }; -/** - * GPropertyAction: - * - * This type is opaque. - * - * Since: 2.38 - **/ - typedef GObjectClass GPropertyActionClass; static void g_property_action_iface_init (GActionInterface *iface); From bea92c488224ba98ed33b6271d38c517f2ccba09 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:55:55 +0100 Subject: [PATCH 10/18] docs: Move the GProxyAddress SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gproxyaddress.c | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/gio/gproxyaddress.c b/gio/gproxyaddress.c index 764e6f5d7..f600c91e2 100644 --- a/gio/gproxyaddress.c +++ b/gio/gproxyaddress.c @@ -29,21 +29,13 @@ #include "gproxyaddress.h" #include "glibintl.h" -/** - * SECTION:gproxyaddress - * @short_description: An internet address with proxy information - * @include: gio/gio.h - * - * Support for proxied #GInetSocketAddress. - */ - /** * GProxyAddress: * - * A #GInetSocketAddress representing a connection via a proxy server + * A [class@Gio.InetSocketAddress] representing a connection via a proxy server. * * Since: 2.26 - **/ + */ /** * GProxyAddressClass: From 0d39a138c7711ad924befbf2034d08213febeb3a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:56:19 +0100 Subject: [PATCH 11/18] docs: Move the GSeekable SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gseekable.c | 21 +++++++++------------ gio/gseekable.h | 5 ----- 2 files changed, 9 insertions(+), 17 deletions(-) diff --git a/gio/gseekable.c b/gio/gseekable.c index 805e0a055..0b0ec27aa 100644 --- a/gio/gseekable.c +++ b/gio/gseekable.c @@ -26,25 +26,22 @@ /** - * SECTION:gseekable - * @short_description: Stream seeking interface - * @include: gio/gio.h - * @see_also: #GInputStream, #GOutputStream + * GSeekable: * - * #GSeekable is implemented by streams (implementations of - * #GInputStream or #GOutputStream) that support seeking. + * `GSeekable` is implemented by streams (implementations of + * [class@Gio.InputStream] or [class@Gio.OutputStream]) that support seeking. * * Seekable streams largely fall into two categories: resizable and * fixed-size. * - * #GSeekable on fixed-sized streams is approximately the same as POSIX - * lseek() on a block device (for example: attempting to seek past the - * end of the device is an error). Fixed streams typically cannot be + * `GSeekable` on fixed-sized streams is approximately the same as POSIX + * [`lseek()`](man:lseek(2)) on a block device (for example: attempting to seek + * past the end of the device is an error). Fixed streams typically cannot be * truncated. * - * #GSeekable on resizable streams is approximately the same as POSIX - * lseek() on a normal file. Seeking past the end and writing data will - * usually cause the stream to resize by introducing zero bytes. + * `GSeekable` on resizable streams is approximately the same as POSIX + * [`lseek()`](man:lseek(2)) on a normal file. Seeking past the end and writing + * data will usually cause the stream to resize by introducing zero bytes. **/ typedef GSeekableIface GSeekableInterface; diff --git a/gio/gseekable.h b/gio/gseekable.h index 34510de6f..e9978016b 100644 --- a/gio/gseekable.h +++ b/gio/gseekable.h @@ -36,11 +36,6 @@ G_BEGIN_DECLS #define G_IS_SEEKABLE(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_SEEKABLE)) #define G_SEEKABLE_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_SEEKABLE, GSeekableIface)) -/** - * GSeekable: - * - * Seek object for streaming operations. - **/ typedef struct _GSeekableIface GSeekableIface; /** From dcb382457d85b458c9767250973af2cec2838765 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:56:40 +0100 Subject: [PATCH 12/18] docs: Move the GSimpleAsyncResult SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsimpleasyncresult.c | 92 ++++++++++++++++++++-------------------- gio/gsimpleasyncresult.h | 5 --- 2 files changed, 45 insertions(+), 52 deletions(-) diff --git a/gio/gsimpleasyncresult.c b/gio/gsimpleasyncresult.c index 43a063adf..ef5492f8e 100644 --- a/gio/gsimpleasyncresult.c +++ b/gio/gsimpleasyncresult.c @@ -33,83 +33,81 @@ /** - * SECTION:gsimpleasyncresult - * @short_description: Simple asynchronous results implementation - * @include: gio/gio.h - * @see_also: #GAsyncResult, #GTask + * GSimpleAsyncResult: * - * As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of - * #GTask, which provides a simpler API. + * As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of + * [class@Gio.Task], which provides a simpler API. * - * #GSimpleAsyncResult implements #GAsyncResult. + * `GSimpleAsyncResult` implements [iface@Gio.AsyncResult]. * - * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error + * `GSimpleAsyncResult` handles [type@Gio.AsyncReadyCallback]s, error * reporting, operation cancellation and the final state of an operation, * completely transparent to the application. Results can be returned * as a pointer e.g. for functions that return data that is collected * asynchronously, a boolean value for checking the success or failure - * of an operation, or a #gssize for operations which return the number + * of an operation, or a `gssize` for operations which return the number * of bytes modified by the operation; all of the simple return cases * are covered. * * Most of the time, an application will not need to know of the details * of this API; it is handled transparently, and any necessary operations - * are handled by #GAsyncResult's interface. However, if implementing a - * new GIO module, for writing language bindings, or for complex + * are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing + * a new GIO module, for writing language bindings, or for complex * applications that need better control of how asynchronous operations * are completed, it is important to understand this functionality. * - * GSimpleAsyncResults are tagged with the calling function to ensure + * `GSimpleAsyncResult`s are tagged with the calling function to ensure * that asynchronous functions and their finishing functions are used * together correctly. * - * To create a new #GSimpleAsyncResult, call g_simple_async_result_new(). - * If the result needs to be created for a #GError, use - * g_simple_async_result_new_from_error() or - * g_simple_async_result_new_take_error(). If a #GError is not available - * (e.g. the asynchronous operation's doesn't take a #GError argument), + * To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new]. + * If the result needs to be created for a `GError`, use + * [ctor@Gio.SimpleAsyncResult.new_from_error] or + * [ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available + * (e.g. the asynchronous operation doesn’t take a `GError` argument), * but the result still needs to be created for an error condition, use - * g_simple_async_result_new_error() (or g_simple_async_result_set_error_va() - * if your application or binding requires passing a variable argument list - * directly), and the error can then be propagated through the use of - * g_simple_async_result_propagate_error(). + * [ctor@Gio.SimpleAsyncResult.new_error] (or + * [method@Gio.SimpleAsyncResult.set_error_va] if your application or binding + * requires passing a variable argument list directly), and the error can then + * be propagated through the use of + * [method@Gio.SimpleAsyncResult.propagate_error]. * * An asynchronous operation can be made to ignore a cancellation event by - * calling g_simple_async_result_set_handle_cancellation() with a - * #GSimpleAsyncResult for the operation and %FALSE. This is useful for + * calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a + * `GSimpleAsyncResult` for the operation and `FALSE`. This is useful for * operations that are dangerous to cancel, such as close (which would * cause a leak if cancelled before being run). * - * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop, - * or it can use #GThreads. - * g_simple_async_result_complete() will finish an I/O task directly - * from the point where it is called. g_simple_async_result_complete_in_idle() - * will finish it from an idle handler in the - * [thread-default main context][g-main-context-push-thread-default] - * where the #GSimpleAsyncResult was created. - * g_simple_async_result_run_in_thread() will run the job in a - * separate thread and then use - * g_simple_async_result_complete_in_idle() to deliver the result. + * `GSimpleAsyncResult` can integrate into GLib’s event loop, + * [type@GLib.MainLoop], or it can use [type@GLib.Thread]s. + * [method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly + * from the point where it is called. + * [method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle + * handler in the thread-default main context (see + * [method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult` + * was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in + * a separate thread and then use + * [method@Gio.SimpleAsyncResult.complete_in_idle] to deliver the result. * * To set the results of an asynchronous function, - * g_simple_async_result_set_op_res_gpointer(), - * g_simple_async_result_set_op_res_gboolean(), and - * g_simple_async_result_set_op_res_gssize() - * are provided, setting the operation's result to a gpointer, gboolean, or - * gssize, respectively. + * [method@Gio.SimpleAsyncResult.set_op_res_gpointer], + * [method@Gio.SimpleAsyncResult.set_op_res_gboolean], and + * [method@Gio.SimpleAsyncResult.set_op_res_gssize] + * are provided, setting the operation's result to a `gpointer`, `gboolean`, or + * `gssize`, respectively. * * Likewise, to get the result of an asynchronous function, - * g_simple_async_result_get_op_res_gpointer(), - * g_simple_async_result_get_op_res_gboolean(), and - * g_simple_async_result_get_op_res_gssize() are - * provided, getting the operation's result as a gpointer, gboolean, and - * gssize, respectively. + * [method@Gio.SimpleAsyncResult.get_op_res_gpointer], + * [method@Gio.SimpleAsyncResult.get_op_res_gboolean], and + * [method@Gio.SimpleAsyncResult.get_op_res_gssize] are + * provided, getting the operation’s result as a `gpointer`, `gboolean`, and + * `gssize`, respectively. * * For the details of the requirements implementations must respect, see - * #GAsyncResult. A typical implementation of an asynchronous operation - * using GSimpleAsyncResult looks something like this: + * [iface@Gio.AsyncResult]. A typical implementation of an asynchronous + * operation using `GSimpleAsyncResult` looks something like this: * - * |[ + * ```c * static void * baked_cb (Cake *cake, * gpointer user_data) @@ -202,7 +200,7 @@ * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple)); * return g_object_ref (cake); * } - * ]| + * ``` */ G_GNUC_BEGIN_IGNORE_DEPRECATIONS diff --git a/gio/gsimpleasyncresult.h b/gio/gsimpleasyncresult.h index 12efb9ce7..94ad35571 100644 --- a/gio/gsimpleasyncresult.h +++ b/gio/gsimpleasyncresult.h @@ -38,11 +38,6 @@ G_BEGIN_DECLS #define G_IS_SIMPLE_ASYNC_RESULT_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SIMPLE_ASYNC_RESULT)) #define G_SIMPLE_ASYNC_RESULT_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SIMPLE_ASYNC_RESULT, GSimpleAsyncResultClass)) -/** - * GSimpleAsyncResult: - * - * A simple implementation of #GAsyncResult. - **/ typedef struct _GSimpleAsyncResultClass GSimpleAsyncResultClass; From 2fc8f47358eaf8ddfc9b52321972eb6be04a7f41 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:56:58 +0100 Subject: [PATCH 13/18] docs: Move the GSimpleIOStream SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsimpleiostream.c | 27 ++++++++------------------- 1 file changed, 8 insertions(+), 19 deletions(-) diff --git a/gio/gsimpleiostream.c b/gio/gsimpleiostream.c index da6df2489..8e04f679e 100644 --- a/gio/gsimpleiostream.c +++ b/gio/gsimpleiostream.c @@ -27,28 +27,17 @@ #include "gsimpleiostream.h" #include "gtask.h" -/** - * SECTION:gsimpleiostream - * @short_description: A wrapper around an input and an output stream. - * @include: gio/gio.h - * @see_also: #GIOStream - * - * GSimpleIOStream creates a #GIOStream from an arbitrary #GInputStream and - * #GOutputStream. This allows any pair of input and output streams to be used - * with #GIOStream methods. - * - * This is useful when you obtained a #GInputStream and a #GOutputStream - * by other means, for instance creating them with platform specific methods as - * g_unix_input_stream_new() or g_win32_input_stream_new(), and you want - * to take advantage of the methods provided by #GIOStream. - * - * Since: 2.44 - */ - /** * GSimpleIOStream: * - * A wrapper around a #GInputStream and a #GOutputStream. + * `GSimpleIOStream` creates a [class@Gio.IOStream] from an arbitrary + * [class@Gio.InputStream] and [class@Gio.OutputStream]. This allows any pair of + * input and output streams to be used with [class@Gio.IOStream] methods. + * + * This is useful when you obtained a [class@Gio.InputStream] and a + * [class@Gio.OutputStream] by other means, for instance creating them with + * platform specific methods as [ctor@Gio.UnixInputStream.new], and you want to + * take advantage of the methods provided by [class@Gio.IOStream]. * * Since: 2.44 */ From 0b0179678a1e30d1b8aa495bd86979746cbfa1c8 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:57:17 +0100 Subject: [PATCH 14/18] docs: Move the GSimplePermission SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsimplepermission.c | 21 ++++++--------------- 1 file changed, 6 insertions(+), 15 deletions(-) diff --git a/gio/gsimplepermission.c b/gio/gsimplepermission.c index 36358eb08..316550992 100644 --- a/gio/gsimplepermission.c +++ b/gio/gsimplepermission.c @@ -25,24 +25,15 @@ #include "gpermission.h" -/** - * SECTION:gsimplepermission - * @title: GSimplePermission - * @short_description: A GPermission that doesn't change value - * @include: gio/gio.h - * - * #GSimplePermission is a trivial implementation of #GPermission that - * represents a permission that is either always or never allowed. The - * value is given at construction and doesn't change. - * - * Calling request or release will result in errors. - **/ - /** * GSimplePermission: * - * #GSimplePermission is an opaque data structure. There are no methods - * except for those defined by #GPermission. + * `GSimplePermission` is a trivial implementation of [class@Gio.Permission] + * that represents a permission that is either always or never allowed. The + * value is given at construction and doesn’t change. + * + * Calling [method@Gio.Permission.acquire] or [method@Gio.Permission.release] + * on a `GSimplePermission` will result in errors. **/ typedef GPermissionClass GSimplePermissionClass; From bd753fb87cb1bf4194203685ad117e6a878fb6d7 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:57:35 +0100 Subject: [PATCH 15/18] docs: Move the GSocket SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsocket.c | 52 +++++++++++++++++++++++++-------------------------- 1 file changed, 25 insertions(+), 27 deletions(-) diff --git a/gio/gsocket.c b/gio/gsocket.c index 8689cf97c..084a5e8e1 100644 --- a/gio/gsocket.c +++ b/gio/gsocket.c @@ -83,46 +83,44 @@ #endif /** - * SECTION:gsocket - * @short_description: Low-level socket object - * @include: gio/gio.h - * @see_also: #GInitable, [][gio-gnetworking.h] + * GSocket: * - * A #GSocket is a low-level networking primitive. It is a more or less + * A `GSocket` is a low-level networking primitive. It is a more or less * direct mapping of the BSD socket API in a portable GObject based API. * It supports both the UNIX socket implementations and winsock2 on Windows. * - * #GSocket is the platform independent base upon which the higher level + * `GSocket` is the platform independent base upon which the higher level * network primitives are based. Applications are not typically meant to - * use it directly, but rather through classes like #GSocketClient, - * #GSocketService and #GSocketConnection. However there may be cases where - * direct use of #GSocket is useful. + * use it directly, but rather through classes like [class@Gio.SocketClient], + * [class@Gio.SocketService] and [class@Gio.SocketConnection]. However there may + * be cases where direct use of `GSocket` is useful. * - * #GSocket implements the #GInitable interface, so if it is manually constructed - * by e.g. g_object_new() you must call g_initable_init() and check the - * results before using the object. This is done automatically in - * g_socket_new() and g_socket_new_from_fd(), so these functions can return - * %NULL. + * `GSocket` implements the [iface@Gio.Initable] interface, so if it is manually + * constructed by e.g. [ctor@GObject.Object.new] you must call + * [method@Gio.Initable.init] and check the results before using the object. + * This is done automatically in [ctor@Gio.Socket.new] and + * [ctor@Gio.Socket.new_from_fd], so these functions can return `NULL`. * * Sockets operate in two general modes, blocking or non-blocking. When * in blocking mode all operations (which don’t take an explicit blocking * parameter) block until the requested operation * is finished or there is an error. In non-blocking mode all calls that - * would block return immediately with a %G_IO_ERROR_WOULD_BLOCK error. - * To know when a call would successfully run you can call g_socket_condition_check(), - * or g_socket_condition_wait(). You can also use g_socket_create_source() and - * attach it to a #GMainContext to get callbacks when I/O is possible. + * would block return immediately with a `G_IO_ERROR_WOULD_BLOCK` error. + * To know when a call would successfully run you can call + * [method@Gio.Socket.condition_check], or [method@Gio.Socket.condition_wait]. + * You can also use [method@Gio.Socket.create_source] and attach it to a + * [type@GLib.MainContext] to get callbacks when I/O is possible. * Note that all sockets are always set to non blocking mode in the system, and - * blocking mode is emulated in GSocket. + * blocking mode is emulated in `GSocket`. * * When working in non-blocking mode applications should always be able to - * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other + * handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other * function said that I/O was possible. This can easily happen in case * of a race condition in the application, but it can also happen for other * reasons. For instance, on Windows a socket is always seen as writable - * until a write returns %G_IO_ERROR_WOULD_BLOCK. + * until a write returns `G_IO_ERROR_WOULD_BLOCK`. * - * #GSockets can be either connection oriented or datagram based. + * `GSocket`s can be either connection oriented or datagram based. * For connection oriented types you must first establish a connection by * either connecting to an address or accepting a connection from another * address. For connectionless socket types the target/source address is @@ -130,14 +128,14 @@ * * All socket file descriptors are set to be close-on-exec. * - * Note that creating a #GSocket causes the signal %SIGPIPE to be + * Note that creating a `GSocket` causes the signal `SIGPIPE` to be * ignored for the remainder of the program. If you are writing a - * command-line utility that uses #GSocket, you may need to take into + * command-line utility that uses `GSocket`, you may need to take into * account the fact that your program will not automatically be killed - * if it tries to write to %stdout after it has been closed. + * if it tries to write to `stdout` after it has been closed. * - * Like most other APIs in GLib, #GSocket is not inherently thread safe. To use - * a #GSocket concurrently from multiple threads, you must implement your own + * Like most other APIs in GLib, `GSocket` is not inherently thread safe. To use + * a `GSocket` concurrently from multiple threads, you must implement your own * locking. * * Since: 2.22 From 4f4ca75b4dccc2dc2afe695145a718d54ff405ac Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:57:51 +0100 Subject: [PATCH 16/18] docs: Move the GSocketAddress SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsocketaddress.c | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/gio/gsocketaddress.c b/gio/gsocketaddress.c index 994037c05..d89fdc9d5 100644 --- a/gio/gsocketaddress.c +++ b/gio/gsocketaddress.c @@ -44,22 +44,13 @@ #endif -/** - * SECTION:gsocketaddress - * @short_description: Abstract base class representing endpoints - * for socket communication - * @include: gio/gio.h - * - * #GSocketAddress is the equivalent of struct sockaddr in the BSD - * sockets API. This is an abstract class; use #GInetSocketAddress - * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets. - */ - /** * GSocketAddress: * - * A socket endpoint address, corresponding to struct sockaddr - * or one of its subtypes. + * `GSocketAddress` is the equivalent of + * [`struct sockaddr`](man:sockaddr(3type)) and its subtypes in the BSD sockets + * API. This is an abstract class; use [class@Gio.InetSocketAddress] for + * internet sockets, or [class@Gio.UnixSocketAddress] for UNIX domain sockets. */ enum From 43b4e7e0973962c68e3e89226374ee1f62ae8456 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:58:10 +0100 Subject: [PATCH 17/18] docs: Move the GSocketClient SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsocketclient.c | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c index 6eb41260a..bfd3d9f60 100644 --- a/gio/gsocketclient.c +++ b/gio/gsocketclient.c @@ -64,23 +64,20 @@ #define HAPPY_EYEBALLS_CONNECTION_ATTEMPT_TIMEOUT_MS 250 /** - * SECTION:gsocketclient - * @short_description: Helper for connecting to a network service - * @include: gio/gio.h - * @see_also: #GSocketConnection, #GSocketListener + * GSocketClient: * - * #GSocketClient is a lightweight high-level utility class for connecting to + * `GSocketClient` is a lightweight high-level utility class for connecting to * a network host using a connection oriented socket type. * - * You create a #GSocketClient object, set any options you want, and then - * call a sync or async connect operation, which returns a #GSocketConnection - * subclass on success. + * You create a `GSocketClient` object, set any options you want, and then + * call a sync or async connect operation, which returns a + * [class@Gio.SocketConnection] subclass on success. * - * The type of the #GSocketConnection object returned depends on the type of - * the underlying socket that is in use. For instance, for a TCP/IP connection - * it will be a #GTcpConnection. + * The type of the [class@Gio.SocketConnection] object returned depends on the + * type of the underlying socket that is in use. For instance, for a TCP/IP + * connection it will be a [class@Gio.TcpConnection]. * - * As #GSocketClient is a lightweight object, you don't need to cache it. You + * As `GSocketClient` is a lightweight object, you don't need to cache it. You * can just create a new one any time you need one. * * Since: 2.22 From 051c5336d4f42ce63f027d5d884e126ca02de3bf Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Tue, 24 Oct 2023 10:58:28 +0100 Subject: [PATCH 18/18] docs: Move the GSocketConnection SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsocketconnection.c | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/gio/gsocketconnection.c b/gio/gsocketconnection.c index 67e8f3dcb..372899644 100644 --- a/gio/gsocketconnection.c +++ b/gio/gsocketconnection.c @@ -40,27 +40,24 @@ /** - * SECTION:gsocketconnection - * @short_description: A socket connection - * @include: gio/gio.h - * @see_also: #GIOStream, #GSocketClient, #GSocketListener + * GSocketConnection: * - * #GSocketConnection is a #GIOStream for a connected socket. They - * can be created either by #GSocketClient when connecting to a host, - * or by #GSocketListener when accepting a new client. + * `GSocketConnection` is a [class@Gio.IOStream] for a connected socket. They + * can be created either by [class@Gio.SocketClient] when connecting to a host, + * or by [class@Gio.SocketListener] when accepting a new client. * - * The type of the #GSocketConnection object returned from these calls + * The type of the `GSocketConnection` object returned from these calls * depends on the type of the underlying socket that is in use. For - * instance, for a TCP/IP connection it will be a #GTcpConnection. + * instance, for a TCP/IP connection it will be a [class@Gio.TcpConnection]. * * Choosing what type of object to construct is done with the socket - * connection factory, and it is possible for 3rd parties to register + * connection factory, and it is possible for third parties to register * custom socket connection types for specific combination of socket - * family/type/protocol using g_socket_connection_factory_register_type(). + * family/type/protocol using [func@Gio.SocketConnection.factory_register_type]. * - * To close a #GSocketConnection, use g_io_stream_close(). Closing both - * substreams of the #GIOStream separately will not close the underlying - * #GSocket. + * To close a `GSocketConnection`, use [method@Gio.IOStream.close]. Closing both + * substreams of the [class@Gio.IOStream] separately will not close the + * underlying [class@Gio.Socket]. * * Since: 2.22 */