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

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

See merge request GNOME/glib!3662

gio/gdbusserver.c

@@ -63,35 +63,28 @@
    G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER)
 
 /**
- * SECTION:gdbusserver
+ * GDBusServer:
- * @short_description: Helper for accepting connections
- * @include: gio/gio.h
  *
- * #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
+ * Note that a minimal `GDBusServer` will accept connections from any
- * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver
+ * peer. In many use-cases it will be necessary to add a
- * that only accepts connections that have successfully authenticated
+ * [class@Gio.DBusAuthObserver] that only accepts connections that have
- * as the same user that is running the #GDBusServer. Since GLib 2.68 this can
+ * successfully authenticated as the same user that is running the
- * be achieved more simply by passing the
+ * `GDBusServer`. Since GLib 2.68 this can be achieved more simply by passing
- * %G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server.
+ * 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.
  *
  * Since: 2.26
  */

gio/gloadableicon.c

@@ -29,13 +29,10 @@
 
 
 /**
- * SECTION:gloadableicon
+ * GLoadableIcon:
- * @short_description: Loadable Icons
- * @include: gio/gio.h
- * @see_also: #GIcon, #GThemedIcon
  * 
- * Extends the #GIcon interface and adds the ability to 
+ * `GLoadableIcon` extends the [iface@Gio.Icon] interface and adds the ability
- * load icons from streams.
+ * to load icons from streams.
  **/
 
 static void          g_loadable_icon_real_load_async  (GLoadableIcon        *icon,

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

gio/gmemoryinputstream.c

@@ -32,16 +32,13 @@
 
 
 /**
- * SECTION:gmemoryinputstream
+ * GMemoryInputStream:
- * @short_description: Streaming input operations on memory chunks
- * @include: gio/gio.h
- * @see_also: #GMemoryOutputStream
  *
- * #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
+ * As of GLib 2.34, `GMemoryInputStream` implements
- * #GPollableInputStream.
+ * [iface@Gio.PollableInputStream].
  */
 
 struct _GMemoryInputStreamPrivate {

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;
 

gio/gmemoryoutputstream.c

@@ -35,16 +35,13 @@
 
 
 /**
- * SECTION:gmemoryoutputstream
+ * GMemoryOutputStream:
- * @short_description: Streaming output operations on memory chunks
- * @include: gio/gio.h
- * @see_also: #GMemoryInputStream
  *
- * #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
+ * As of GLib 2.34, `GMemoryOutputStream` trivially implements
- * #GPollableOutputStream: it always polls as ready.
+ * [iface@Gio.PollableOutputStream]: it always polls as ready.
  */
 
 #define MIN_ARRAY_SIZE  16

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;
 

gio/gnetworkmonitor.c

@@ -31,24 +31,14 @@
 #include "gtask.h"
 
 /**
- * SECTION:gnetworkmonitor
+ * GNetworkMonitor:
- * @title: GNetworkMonitor
- * @short_description: Network status monitor
- * @include: gio/gio.h
  *
- * #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
  */

gio/gnotification.c

@@ -28,63 +28,53 @@
 #include "gioenumtypes.h"
 
 /**
- * SECTION:gnotification
+ * GNotification:
- * @short_description: User Notifications (pop up messages)
- * @include: gio/gio.h
  *
- * #GNotification is a mechanism for creating a notification to be shown
+ * `GNotification` is a mechanism for creating a notification to be shown
- * to the user -- typically as a pop-up notification presented by the
+ * 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
+ * not running, applications using `GNotification` should be able to be
- * started as a D-Bus service, using #GApplication.
+ * 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]
+ * [Desktop Entry]
- *   Name=Test Application
+ * Name=Test Application
- *   Comment=Description of what Test Application does
+ * Comment=Description of what Test Application does
- *   Exec=gnome-test-application
+ * Exec=gnome-test-application
- *   Icon=org.gnome.TestApplication
+ * Icon=org.gnome.TestApplication
- *   Terminal=false
+ * Terminal=false
- *   Type=Application
+ * Type=Application
- *   Categories=GNOME;GTK;TestApplication Category;
+ * Categories=GNOME;GTK;TestApplication Category;
- *   StartupNotify=true
+ * StartupNotify=true
- *   DBusActivatable=true
+ * DBusActivatable=true
- *   X-GNOME-UsesNotifications=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().
+ * A notification can be sent with [method@Gio.Application.send_notification].
- *
- * Since: 2.40
- **/
-
-/**
- * GNotification:
- *
- * This structure type is private and should only be accessed using the
- * public APIs.
  *
  * Since: 2.40
  **/

gio/gpermission.c

@@ -31,13 +31,9 @@
 
 
 /**
- * SECTION:gpermission
+ * GPermission:
- * @title: GPermission
- * @short_description: An object representing the permission
- *     to perform a certain action
- * @include: gio/gio.h
  *
- * 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
+ * As an example, a `GPermission` might represent the ability for the
- * user to write to a #GSettings object.  This #GPermission object could
+ * user to write to a [class@Gio.Settings] object.  This `GPermission` object
- * then be used to decide if it is appropriate to show a "Click here to
+ * 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
+ * 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;

gio/gpollableinputstream.c

@@ -27,19 +27,16 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gpollableinputstream
+ * GPollableInputStream:
- * @short_description: Interface for pollable input streams
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GPollableOutputStream, #GFileDescriptorBased
  *
- * #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
+ * Some classes may implement `GPollableInputStream` but have only certain
- * instances of that class be pollable. If g_pollable_input_stream_can_poll()
+ * instances of that class be pollable. If [method@Gio.PollableInputStream.can_poll]
- * returns %FALSE, then the behavior of other #GPollableInputStream methods is
+ * returns false, then the behavior of other `GPollableInputStream` methods is
  * undefined.
  *
  * Since: 2.28

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

gio/gpollableoutputstream.c

@@ -28,19 +28,16 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gpollableoutputstream
+ * GPollableOutputStream:
- * @short_description: Interface for pollable output streams
- * @include: gio/gio.h
- * @see_also: #GOutputStream, #GFileDescriptorBased, #GPollableInputStream
  *
- * #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
+ * Some classes may implement `GPollableOutputStream` but have only certain
- * instances of that class be pollable. If g_pollable_output_stream_can_poll()
+ * instances of that class be pollable. If [method@Gio.PollableOutputStream.can_poll]
- * returns %FALSE, then the behavior of other #GPollableOutputStream methods is
+ * returns false, then the behavior of other `GPollableOutputStream` methods is
  * undefined.
  *
  * Since: 2.28

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

gio/gpowerprofilemonitor.c

@@ -32,15 +32,12 @@
 #include "gtask.h"
 
 /**
- * SECTION:gpowerprofilemonitor
+ * GPowerProfileMonitor:
- * @title: GPowerProfileMonitor
- * @short_description: Power profile monitor
- * @include: gio/gio.h
  *
- * #GPowerProfileMonitor makes it possible for applications as well as OS components
+ * `GPowerProfileMonitor` makes it possible for applications as well as OS
- * to monitor system power profiles and act upon them. It currently only exports
+ * components to monitor system power profiles and act upon them. It currently
- * whether the system is in “Power Saver” mode (known as “Low Power” mode on
+ * only exports whether the system is in “Power Saver” mode (known as
- * some systems).
+ * “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
+ * Don’t forget to disconnect the [signal@GObject.Object::notify] signal for
- * signal, and unref the #GPowerProfileMonitor itself when exiting.
+ * [property@Gio.PowerProfileMonitor:power-saver-enabled], and unref the
- *
+ * `GPowerProfileMonitor` itself when exiting.
- * Since: 2.70
- */
-
-/**
- * GPowerProfileMonitor:
- *
- * #GPowerProfileMonitor monitors system power profile and notifies on
- * changes.
  *
  * Since: 2.70
  */

gio/gpropertyaction.c

@@ -28,17 +28,14 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gpropertyaction
+ * GPropertyAction:
- * @title: GPropertyAction
- * @short_description: A GAction reflecting a GObject property
- * @include: gio/gio.h
  *
- * A #GPropertyAction is a way to get a #GAction with a state value
+ * A `GPropertyAction` is a way to get a [iface@Gio.Action] with a state value
- * reflecting and controlling the value of a #GObject property.
+ * 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
+ * between). `GPropertyAction` does not have a separate state that is kept
- * in sync with the property value -- its state is the property value.
+ * in sync with the property value — its state is the property value.
  *
- * For example, it might be useful to create a #GAction corresponding to
+ * For example, it might be useful to create a [iface@Gio.Action] corresponding
- * the "visible-child-name" property of a #GtkStack so that the current
+ * to the `visible-child-name` property of a [class@Gtk.Stack] so that the
- * page can be switched from a menu.  The active radio indication in 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
+ * An anti-example would be binding the `active-id` property on a
- * #GtkComboBox.  This is because the state of the combobox itself is
+ * [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"
+ * Another anti-example would be to bind to the `visible-child-name`
- * property of a #GtkStack if this value is actually stored in
+ * property of a [class@Gtk.Stack] if this value is actually stored in
- * #GSettings.  In that case, the real source of the value is
+ * [class@Gio.Settings].  In that case, the real source of the value is
- * #GSettings.  If you want a #GAction to control a setting stored in
+ * [class@Gio.Settings].  If you want a [iface@Gio.Action] to control a setting
- * #GSettings, see g_settings_create_action() instead, and possibly
+ * stored in [class@Gio.Settings], see [method@Gio.Settings.create_action]
- * combine its use with g_settings_bind().
+ * 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);

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:

gio/gseekable.c

@@ -26,25 +26,22 @@
 
 
 /**
- * SECTION:gseekable
+ * GSeekable:
- * @short_description: Stream seeking interface
- * @include: gio/gio.h
- * @see_also: #GInputStream, #GOutputStream
  *
- * #GSeekable is implemented by streams (implementations of
+ * `GSeekable` is implemented by streams (implementations of
- * #GInputStream or #GOutputStream) that support seeking.
+ * [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
+ * `GSeekable` on fixed-sized streams is approximately the same as POSIX
- * lseek() on a block device (for example: attempting to seek past the
+ * [`lseek()`](man:lseek(2)) on a block device (for example: attempting to seek
- * end of the device is an error).  Fixed streams typically cannot be
+ * 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
+ * `GSeekable` on resizable streams is approximately the same as POSIX
- * lseek() on a normal file.  Seeking past the end and writing data will
+ * [`lseek()`](man:lseek(2)) on a normal file.  Seeking past the end and writing
- * usually cause the stream to resize by introducing zero bytes.
+ * data will usually cause the stream to resize by introducing zero bytes.
  **/
 
 typedef GSeekableIface GSeekableInterface;

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

gio/gsimpleasyncresult.c

@@ -33,83 +33,81 @@
 
 
 /**
- * SECTION:gsimpleasyncresult
+ * GSimpleAsyncResult:
- * @short_description: Simple asynchronous results implementation
- * @include: gio/gio.h
- * @see_also: #GAsyncResult, #GTask
  *
- * As of GLib 2.46, #GSimpleAsyncResult is deprecated in favor of
+ * As of GLib 2.46, `GSimpleAsyncResult` is deprecated in favor of
- * #GTask, which provides a simpler API.
+ * [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
+ * are handled by [iface@Gio.AsyncResult]’s interface. However, if implementing
- * new GIO module, for writing language bindings, or for complex
+ * 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().
+ * To create a new `GSimpleAsyncResult`, call [ctor@Gio.SimpleAsyncResult.new].
- * If the result needs to be created for a #GError, use
+ * If the result needs to be created for a `GError`, use
- * g_simple_async_result_new_from_error() or
+ * [ctor@Gio.SimpleAsyncResult.new_from_error] or
- * g_simple_async_result_new_take_error(). If a #GError is not available
+ * [ctor@Gio.SimpleAsyncResult.new_take_error]. If a `GError` is not available
- * (e.g. the asynchronous operation's doesn't take a #GError argument),
+ * (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()
+ * [ctor@Gio.SimpleAsyncResult.new_error] (or
- * if your application or binding requires passing a variable argument list
+ * [method@Gio.SimpleAsyncResult.set_error_va] if your application or binding
- * directly), and the error can then be propagated through the use of
+ * requires passing a variable argument list directly), and the error can then
- * g_simple_async_result_propagate_error().
+ * 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
+ * calling [method@Gio.SimpleAsyncResult.set_handle_cancellation] with a
- * #GSimpleAsyncResult for the operation and %FALSE. This is useful for
+ * `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,
+ * `GSimpleAsyncResult` can integrate into GLib’s event loop,
- * or it can use #GThreads.
+ * [type@GLib.MainLoop], or it can use [type@GLib.Thread]s.
- * g_simple_async_result_complete() will finish an I/O task directly
+ * [method@Gio.SimpleAsyncResult.complete] will finish an I/O task directly
- * from the point where it is called. g_simple_async_result_complete_in_idle()
+ * from the point where it is called.
- * will finish it from an idle handler in the 
+ * [method@Gio.SimpleAsyncResult.complete_in_idle] will finish it from an idle
- * [thread-default main context][g-main-context-push-thread-default]
+ * handler in the  thread-default main context (see
- * where the #GSimpleAsyncResult was created.
+ * [method@GLib.MainContext.push_thread_default]) where the `GSimpleAsyncResult`
- * g_simple_async_result_run_in_thread() will run the job in a
+ * was created. [method@Gio.SimpleAsyncResult.run_in_thread] will run the job in
- * separate thread and then use
+ * a separate thread and then use
- * g_simple_async_result_complete_in_idle() to deliver the result.
+ * [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(),
+ * [method@Gio.SimpleAsyncResult.set_op_res_gpointer],
- * g_simple_async_result_set_op_res_gboolean(), and
+ * [method@Gio.SimpleAsyncResult.set_op_res_gboolean], and
- * g_simple_async_result_set_op_res_gssize()
+ * [method@Gio.SimpleAsyncResult.set_op_res_gssize]
- * are provided, setting the operation's result to a gpointer, gboolean, or
+ * are provided, setting the operation's result to a `gpointer`, `gboolean`, or
- * gssize, respectively.
+ * `gssize`, respectively.
  *
  * Likewise, to get the result of an asynchronous function,
- * g_simple_async_result_get_op_res_gpointer(),
+ * [method@Gio.SimpleAsyncResult.get_op_res_gpointer],
- * g_simple_async_result_get_op_res_gboolean(), and
+ * [method@Gio.SimpleAsyncResult.get_op_res_gboolean], and
- * g_simple_async_result_get_op_res_gssize() are
+ * [method@Gio.SimpleAsyncResult.get_op_res_gssize] are
- * provided, getting the operation's result as a gpointer, gboolean, and
+ * provided, getting the operation’s result as a `gpointer`, `gboolean`, and
- * gssize, respectively.
+ * `gssize`, respectively.
  *
  * For the details of the requirements implementations must respect, see
- * #GAsyncResult.  A typical implementation of an asynchronous operation
+ * [iface@Gio.AsyncResult].  A typical implementation of an asynchronous
- * using GSimpleAsyncResult looks something like this:
+ * operation using `GSimpleAsyncResult` looks something like this:
  *
- * |[<!-- language="C" -->
+ * ```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

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;
 
 

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

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
+ * `GSimplePermission` is a trivial implementation of [class@Gio.Permission]
- * except for those defined by #GPermission.
+ * 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;

gio/gsocket.c

@@ -83,46 +83,44 @@
 #endif
 
 /**
- * SECTION:gsocket
+ * GSocket:
- * @short_description: Low-level socket object
- * @include: gio/gio.h
- * @see_also: #GInitable, [<gnetworking.h>][gio-gnetworking.h]
  *
- * 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,
+ * use it directly, but rather through classes like [class@Gio.SocketClient],
- * #GSocketService and #GSocketConnection. However there may be cases where
+ * [class@Gio.SocketService] and [class@Gio.SocketConnection]. However there may
- * direct use of #GSocket is useful.
+ * be cases where direct use of `GSocket` is useful.
  *
- * #GSocket implements the #GInitable interface, so if it is manually constructed
+ * `GSocket` implements the [iface@Gio.Initable] interface, so if it is manually
- * by e.g. g_object_new() you must call g_initable_init() and check the
+ * constructed by e.g. [ctor@GObject.Object.new] you must call
- * results before using the object. This is done automatically in
+ * [method@Gio.Initable.init] and check the results before using the object.
- * g_socket_new() and g_socket_new_from_fd(), so these functions can return
+ * This is done automatically in [ctor@Gio.Socket.new] and
- * %NULL.
+ * [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.
+ * 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(),
+ * To know when a call would successfully run you can call
- * or g_socket_condition_wait(). You can also use g_socket_create_source() and
+ * [method@Gio.Socket.condition_check], or [method@Gio.Socket.condition_wait].
- * attach it to a #GMainContext to get callbacks when I/O is possible.
+ * 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
+ * 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
+ * a `GSocket` concurrently from multiple threads, you must implement your own
  * locking.
  *
  * Since: 2.22

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
+ * `GSocketAddress` is the equivalent of
- * or one of its subtypes.
+ * [`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

gio/gsocketclient.c

@@ -64,23 +64,20 @@
 #define HAPPY_EYEBALLS_CONNECTION_ATTEMPT_TIMEOUT_MS 250
 
 /**
- * SECTION:gsocketclient
+ * GSocketClient:
- * @short_description: Helper for connecting to a network service
- * @include: gio/gio.h
- * @see_also: #GSocketConnection, #GSocketListener
  *
- * #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
+ * You create a `GSocketClient` object, set any options you want, and then
- * call a sync or async connect operation, which returns a #GSocketConnection
+ * call a sync or async connect operation, which returns a
- * subclass on success.
+ * [class@Gio.SocketConnection] subclass on success.
  *
- * The type of the #GSocketConnection object returned depends on the type of
+ * The type of the [class@Gio.SocketConnection] object returned depends on the
- * the underlying socket that is in use. For instance, for a TCP/IP connection
+ * type of the underlying socket that is in use. For instance, for a TCP/IP
- * it will be a #GTcpConnection.
+ * 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

gio/gsocketconnection.c

@@ -40,27 +40,24 @@
 
 
 /**
- * SECTION:gsocketconnection
+ * GSocketConnection:
- * @short_description: A socket connection
- * @include: gio/gio.h
- * @see_also: #GIOStream, #GSocketClient, #GSocketListener
  *
- * #GSocketConnection is a #GIOStream for a connected socket. They
+ * `GSocketConnection` is a [class@Gio.IOStream] for a connected socket. They
- * can be created either by #GSocketClient when connecting to a host,
+ * can be created either by [class@Gio.SocketClient] when connecting to a host,
- * or by #GSocketListener when accepting a new client.
+ * 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
+ * To close a `GSocketConnection`, use [method@Gio.IOStream.close]. Closing both
- * substreams of the #GIOStream separately will not close the underlying
+ * substreams of the [class@Gio.IOStream] separately will not close the
- * #GSocket.
+ * underlying [class@Gio.Socket].
  *
  * Since: 2.22
  */