From ac7cbb146edfdf8772e9ead79ae8b135e884cf2c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:21:03 +0000 Subject: [PATCH 01/21] docs: Move the gtls SECTION Move it to a separate Markdown page. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/gio/gio.toml.in | 1 + docs/reference/gio/meson.build | 1 + docs/reference/gio/tls-overview.md | 37 +++++++++++++++++++++++ gio/gtlsbackend.c | 47 ------------------------------ 4 files changed, 39 insertions(+), 47 deletions(-) create mode 100644 docs/reference/gio/tls-overview.md diff --git a/docs/reference/gio/gio.toml.in b/docs/reference/gio/gio.toml.in index d62bbd15e..5e6386055 100644 --- a/docs/reference/gio/gio.toml.in +++ b/docs/reference/gio/gio.toml.in @@ -42,6 +42,7 @@ urlmap_file = "urlmap.js" content_files = [ "overview.md", "file-attributes.md", + "tls-overview.md", "migrating-gdbus.md", "migrating-gconf.md", diff --git a/docs/reference/gio/meson.build b/docs/reference/gio/meson.build index 38cdc6a06..f3164fae5 100644 --- a/docs/reference/gio/meson.build +++ b/docs/reference/gio/meson.build @@ -230,6 +230,7 @@ expand_content_files = [ 'migrating-gdbus.md', 'migrating-gnome-vfs.md', 'overview.md', + 'tls-overview.md', ] gio_toml = configure_file(input: 'gio.toml.in', output: 'gio.toml', configuration: toml_conf) diff --git a/docs/reference/gio/tls-overview.md b/docs/reference/gio/tls-overview.md new file mode 100644 index 000000000..453c57ed0 --- /dev/null +++ b/docs/reference/gio/tls-overview.md @@ -0,0 +1,37 @@ +Title: TLS Overview +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2010 Dan Winship +SPDX-FileCopyrightText: 2015 Collabora, Ltd. + +# TLS Overview + +[class@Gio.TlsConnection] and related classes provide TLS (Transport Layer +Security, previously known as SSL, Secure Sockets Layer) support for GIO-based +network streams. + +[iface@Gio.DtlsConnection] and related classes provide DTLS (Datagram TLS) +support for GIO-based network sockets, using the [iface@Gio.DatagramBased] +interface. The TLS and DTLS APIs are almost identical, except TLS is +stream-based and DTLS is datagram-based. They share certificate and backend +infrastructure. + +In the simplest case, for a client TLS connection, you can just set the +[property@Gio.SocketClient:tls] flag on a [class@Gio.SocketClient], and then any +connections created by that client will have TLS negotiated automatically, using +appropriate default settings, and rejecting any invalid or self-signed +certificates (unless you change that default by setting the +[property@Gio.SocketClient:tls-validation-flags] property). The returned object +will be a [class@Gio.TcpWrapperConnection], which wraps the underlying +[iface@Gio.TlsClientConnection]. + +For greater control, you can create your own [iface@Gio.TlsClientConnection], +wrapping a [class@Gio.SocketConnection] (or an arbitrary [class@Gio.IOStream] +with pollable input and output streams) and then connect to its signals, +such as [signal@Gio.TlsConnection::accept-certificate], before starting the +handshake. + +Server-side TLS is similar, using [iface@Gio.TlsServerConnection]. At the +moment, there is no support for automatically wrapping server-side +connections in the way [class@Gio.SocketClient] does for client-side +connections. + diff --git a/gio/gtlsbackend.c b/gio/gtlsbackend.c index 39c5ef241..43bdbd46c 100644 --- a/gio/gtlsbackend.c +++ b/gio/gtlsbackend.c @@ -28,53 +28,6 @@ #include "gioenumtypes.h" #include "giomodule-priv.h" -/** - * SECTION:gtls - * @title: TLS Overview - * @short_description: TLS (aka SSL) support for GSocketConnection - * @include: gio/gio.h - * - * #GTlsConnection and related classes provide TLS (Transport Layer - * Security, previously known as SSL, Secure Sockets Layer) support for - * gio-based network streams. - * - * #GDtlsConnection and related classes provide DTLS (Datagram TLS) support for - * GIO-based network sockets, using the #GDatagramBased interface. The TLS and - * DTLS APIs are almost identical, except TLS is stream-based and DTLS is - * datagram-based. They share certificate and backend infrastructure. - * - * In the simplest case, for a client TLS connection, you can just set the - * #GSocketClient:tls flag on a #GSocketClient, and then any - * connections created by that client will have TLS negotiated - * automatically, using appropriate default settings, and rejecting - * any invalid or self-signed certificates (unless you change that - * default by setting the #GSocketClient:tls-validation-flags - * property). The returned object will be a #GTcpWrapperConnection, - * which wraps the underlying #GTlsClientConnection. - * - * For greater control, you can create your own #GTlsClientConnection, - * wrapping a #GSocketConnection (or an arbitrary #GIOStream with - * pollable input and output streams) and then connect to its signals, - * such as #GTlsConnection::accept-certificate, before starting the - * handshake. - * - * Server-side TLS is similar, using #GTlsServerConnection. At the - * moment, there is no support for automatically wrapping server-side - * connections in the way #GSocketClient does for client-side - * connections. - */ - -/** - * SECTION:gtlsbackend - * @title: GTlsBackend - * @short_description: TLS backend implementation - * @include: gio/gio.h - * - * TLS (Transport Layer Security, aka SSL) and DTLS backend. - * - * Since: 2.28 - */ - /** * GTlsBackend: * From bfa5d993052ba55ad8c60c4bb0d4933803a725e7 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:21:25 +0000 Subject: [PATCH 02/21] docs: Move the GDBusObject SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gdbusobject.c | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/gio/gdbusobject.c b/gio/gdbusobject.c index 5cd425e17..ab670d20c 100644 --- a/gio/gdbusobject.c +++ b/gio/gdbusobject.c @@ -28,22 +28,13 @@ #include "glibintl.h" -/** - * SECTION:gdbusobject - * @short_description: Base type for D-Bus objects - * @include: gio/gio.h - * - * The #GDBusObject type is the base type for D-Bus objects on both - * the service side (see #GDBusObjectSkeleton) and the client side - * (see #GDBusObjectProxy). It is essentially just a container of - * interfaces. - */ - /** * GDBusObject: * - * #GDBusObject is an opaque data structure and can only be accessed - * using the following functions. + * The `GDBusObject` type is the base type for D-Bus objects on both + * the service side (see [class@Gio.DBusObjectSkeleton]) and the client side + * (see [class@Gio.DBusObjectProxy]). It is essentially just a container of + * interfaces. */ typedef GDBusObjectIface GDBusObjectInterface; From 8c3e0aa406e48ba8348cfcac8d0f850020ed011d Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:21:51 +0000 Subject: [PATCH 03/21] docs: Move the GRemoteActionGroup SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gremoteactiongroup.c | 30 ++++++++++-------------------- 1 file changed, 10 insertions(+), 20 deletions(-) diff --git a/gio/gremoteactiongroup.c b/gio/gremoteactiongroup.c index 81971d042..079f6fc54 100644 --- a/gio/gremoteactiongroup.c +++ b/gio/gremoteactiongroup.c @@ -27,43 +27,33 @@ #include "gaction.h" /** - * SECTION:gremoteactiongroup - * @title: GRemoteActionGroup - * @short_description: A GActionGroup that interacts with other processes - * @include: gio/gio.h + * GRemoteActionGroup: * - * The GRemoteActionGroup interface is implemented by #GActionGroup + * The `GRemoteActionGroup` interface is implemented by [iface@Gio.ActionGroup] * instances that either transmit action invocations to other processes * or receive action invocations in the local process from other * processes. * * The interface has `_full` variants of the two - * methods on #GActionGroup used to activate actions: - * g_action_group_activate_action() and - * g_action_group_change_action_state(). These variants allow a - * "platform data" #GVariant to be specified: a dictionary providing + * methods on [iface@Gio.ActionGroup] used to activate actions: + * [method@Gio.ActionGroup.activate_action] and + * [method@Gio.ActionGroup.change_action_state]. These variants allow a + * ‘platform data’ [struct@GLib.Variant] to be specified: a dictionary providing * context for the action invocation (for example: timestamps, startup * notification IDs, etc). * - * #GDBusActionGroup implements #GRemoteActionGroup. This provides a + * [class@Gio.DBusActionGroup] implements `GRemoteActionGroup`. This provides a * mechanism to send platform data for action invocations over D-Bus. * - * Additionally, g_dbus_connection_export_action_group() will check if - * the exported #GActionGroup implements #GRemoteActionGroup and use the - * `_full` variants of the calls if available. This + * Additionally, [method@Gio.DBusConnection.export_action_group] will check if + * the exported [iface@Gio.ActionGroup] implements `GRemoteActionGroup` and use + * the `_full` variants of the calls if available. This * provides a mechanism by which to receive platform data for action * invocations that arrive by way of D-Bus. * * Since: 2.32 **/ -/** - * GRemoteActionGroup: - * - * #GRemoteActionGroup is an opaque data structure and can only be accessed - * using the following functions. - **/ - /** * GRemoteActionGroupInterface: * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full() From c16c639729ff5da0467c934c1a474feb0aec999b Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:22:47 +0000 Subject: [PATCH 04/21] docs: Move the GSettings SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsettings.c | 193 ++++++++++++++++++++--------------------- gio/gsettingsbackend.c | 25 +++--- gio/gsettingsbackend.h | 5 -- gio/gsettingsschema.c | 42 ++++----- 4 files changed, 119 insertions(+), 146 deletions(-) diff --git a/gio/gsettings.c b/gio/gsettings.c index a2c3dd0e4..bd36d7829 100644 --- a/gio/gsettings.c +++ b/gio/gsettings.c @@ -37,116 +37,115 @@ #include "strinfo.c" /** - * SECTION:gsettings - * @short_description: High-level API for application settings - * @include: gio/gio.h + * GSettings: * - * The #GSettings class provides a convenient API for storing and retrieving + * The `GSettings` class provides a convenient API for storing and retrieving * application settings. * * Reads and writes can be considered to be non-blocking. Reading - * settings with #GSettings is typically extremely fast: on + * settings with `GSettings` is typically extremely fast: on * approximately the same order of magnitude (but slower than) a - * #GHashTable lookup. Writing settings is also extremely fast in terms - * of time to return to your application, but can be extremely expensive + * [struct@GLib.HashTable] lookup. Writing settings is also extremely fast in + * terms of time to return to your application, but can be extremely expensive * for other threads and other processes. Many settings backends * (including dconf) have lazy initialisation which means in the common * case of the user using their computer without modifying any settings - * a lot of work can be avoided. For dconf, the D-Bus service doesn't + * a lot of work can be avoided. For dconf, the D-Bus service doesn’t * even need to be started in this case. For this reason, you should - * only ever modify #GSettings keys in response to explicit user action. + * only ever modify `GSettings` keys in response to explicit user action. * Particular care should be paid to ensure that modifications are not - * made during startup -- for example, when setting the initial value - * of preferences widgets. The built-in g_settings_bind() functionality - * is careful not to write settings in response to notify signals as a - * result of modifications that it makes to widgets. + * made during startup — for example, when setting the initial value + * of preferences widgets. The built-in [method@Gio.Settings.bind] + * functionality is careful not to write settings in response to notify signals + * as a result of modifications that it makes to widgets. * - * When creating a GSettings instance, you have to specify a schema + * When creating a `GSettings` instance, you have to specify a schema * that describes the keys in your settings and their types and default * values, as well as some other information. * * Normally, a schema has a fixed path that determines where the settings * are stored in the conceptual global tree of settings. However, schemas - * can also be '[relocatable][gsettings-relocatable]', i.e. not equipped with + * can also be ‘[relocatable](#relocatable-schemas)’, i.e. not equipped with * a fixed path. This is - * useful e.g. when the schema describes an 'account', and you want to be + * useful e.g. when the schema describes an ‘account’, and you want to be * able to store a arbitrary number of accounts. * - * Paths must start with and end with a forward slash character ('/') + * Paths must start with and end with a forward slash character (`/`) * and must not contain two sequential slash characters. Paths should * be chosen based on a domain name associated with the program or * library to which the settings belong. Examples of paths are - * "/org/gtk/settings/file-chooser/" and "/ca/desrt/dconf-editor/". - * Paths should not start with "/apps/", "/desktop/" or "/system/" as + * `/org/gtk/settings/file-chooser/` and `/ca/desrt/dconf-editor/`. + * Paths should not start with `/apps/`, `/desktop/` or `/system/` as * they often did in GConf. * * Unlike other configuration systems (like GConf), GSettings does not * restrict keys to basic types like strings and numbers. GSettings stores - * values as #GVariant, and allows any #GVariantType for keys. Key names - * are restricted to lowercase characters, numbers and '-'. Furthermore, - * the names must begin with a lowercase character, must not end - * with a '-', and must not contain consecutive dashes. + * values as [struct@GLib.Variant], and allows any [type@GLib.VariantType] for + * keys. Key names are restricted to lowercase characters, numbers and `-`. + * Furthermore, the names must begin with a lowercase character, must not end + * with a `-`, and must not contain consecutive dashes. * * Similar to GConf, the default values in GSettings schemas can be * localized, but the localized values are stored in gettext catalogs * and looked up with the domain that is specified in the - * `gettext-domain` attribute of the or + * `gettext-domain` attribute of the `` or `` * elements and the category that is specified in the `l10n` attribute of - * the element. The string which is translated includes all text in - * the element, including any surrounding quotation marks. + * the `` element. The string which is translated includes all text in + * the `` element, including any surrounding quotation marks. * * The `l10n` attribute must be set to `messages` or `time`, and sets the * [locale category for * translation](https://www.gnu.org/software/gettext/manual/html_node/Aspects.html#index-locale-categories-1). * The `messages` category should be used by default; use `time` for * translatable date or time formats. A translation comment can be added as an - * XML comment immediately above the element — it is recommended to + * XML comment immediately above the `` element — it is recommended to * add these comments to aid translators understand the meaning and * implications of the default value. An optional translation `context` - * attribute can be set on the element to disambiguate multiple + * attribute can be set on the `` element to disambiguate multiple * defaults which use the same string. * * For example: - * |[ + * ```xml * * ['bad', 'words'] - * ]| + * ``` * * Translations of default values must remain syntactically valid serialized - * #GVariants (e.g. retaining any surrounding quotation marks) or runtime - * errors will occur. + * [struct@GLib.Variant]s (e.g. retaining any surrounding quotation marks) or + * runtime errors will occur. * * GSettings uses schemas in a compact binary form that is created - * by the [glib-compile-schemas][glib-compile-schemas] + * by the [`glib-compile-schemas`](glib-compile-schemas.html) * utility. The input is a schema description in an XML format. * * A DTD for the gschema XML format can be found here: * [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd) * - * The [glib-compile-schemas][glib-compile-schemas] tool expects schema + * The [`glib-compile-schemas`](glib-compile-schemas.html) tool expects schema * files to have the extension `.gschema.xml`. * - * At runtime, schemas are identified by their id (as specified in the - * id attribute of the element). The convention for schema - * ids is to use a dotted name, similar in style to a D-Bus bus name, - * e.g. "org.gnome.SessionManager". In particular, if the settings are + * At runtime, schemas are identified by their ID (as specified in the + * `id` attribute of the `` element). The convention for schema + * IDs is to use a dotted name, similar in style to a D-Bus bus name, + * e.g. `org.gnome.SessionManager`. In particular, if the settings are * for a specific service that owns a D-Bus bus name, the D-Bus bus name - * and schema id should match. For schemas which deal with settings not - * associated with one named application, the id should not use - * StudlyCaps, e.g. "org.gnome.font-rendering". + * and schema ID should match. For schemas which deal with settings not + * associated with one named application, the ID should not use + * StudlyCaps, e.g. `org.gnome.font-rendering`. * - * In addition to #GVariant types, keys can have types that have - * enumerated types. These can be described by a , - * or element, as seen in the - * [example][schema-enumerated]. The underlying type of such a key - * is string, but you can use g_settings_get_enum(), g_settings_set_enum(), - * g_settings_get_flags(), g_settings_set_flags() access the numeric values - * corresponding to the string value of enum and flags keys. + * In addition to [struct@GLib.Variant] types, keys can have types that have + * enumerated types. These can be described by a ``, + * `` or `` element, as seen in the + * second example below. The underlying type of such a key + * is string, but you can use [method@Gio.Settings.get_enum], + * [method@Gio.Settings.set_enum], [method@Gio.Settings.get_flags], + * [method@Gio.Settings.set_flags] access the numeric values corresponding to + * the string value of enum and flags keys. * * An example for default value: - * |[ + * ```xml * * * @@ -169,10 +168,10 @@ * * * - * ]| + * ``` * * An example for ranges, choices and enumerated types: - * |[ + * ```xml * * * @@ -215,7 +214,7 @@ * * * - * ]| + * ``` * * ## Vendor overrides * @@ -223,41 +222,42 @@ * an application. Sometimes, it is necessary for a vendor or distributor * to adjust these defaults. Since patching the XML source for the schema * is inconvenient and error-prone, - * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor - * override' files. These are keyfiles in the same directory as the XML - * schema sources which can override default values. The schema id serves + * [`glib-compile-schemas`](glib-compile-schemas.html) reads so-called ‘vendor + * override’ files. These are keyfiles in the same directory as the XML + * schema sources which can override default values. The schema ID serves * as the group name in the key file, and the values are expected in - * serialized GVariant form, as in the following example: - * |[ - * [org.gtk.Example] - * key1='string' - * key2=1.5 - * ]| + * serialized [struct@GLib.Variant] form, as in the following example: + * ``` + * [org.gtk.Example] + * key1='string' + * key2=1.5 + * ``` * - * glib-compile-schemas expects schema files to have the extension + * `glib-compile-schemas` expects schema files to have the extension * `.gschema.override`. * * ## Binding * - * A very convenient feature of GSettings lets you bind #GObject properties - * directly to settings, using g_settings_bind(). Once a GObject property - * has been bound to a setting, changes on either side are automatically - * propagated to the other side. GSettings handles details like mapping - * between GObject and GVariant types, and preventing infinite cycles. + * A very convenient feature of GSettings lets you bind [class@GObject.Object] + * properties directly to settings, using [method@Gio.Settings.bind]. Once a + * [class@GObject.Object] property has been bound to a setting, changes on + * either side are automatically propagated to the other side. GSettings handles + * details like mapping between [class@GObject.Object] and [struct@GLib.Variant] + * types, and preventing infinite cycles. * * This makes it very easy to hook up a preferences dialog to the * underlying settings. To make this even more convenient, GSettings - * looks for a boolean property with the name "sensitivity" and + * looks for a boolean property with the name `sensitivity` and * automatically binds it to the writability of the bound setting. - * If this 'magic' gets in the way, it can be suppressed with the - * %G_SETTINGS_BIND_NO_SENSITIVITY flag. + * If this ‘magic’ gets in the way, it can be suppressed with the + * `G_SETTINGS_BIND_NO_SENSITIVITY` flag. * - * ## Relocatable schemas # {#gsettings-relocatable} + * ## Relocatable schemas * * A relocatable schema is one with no `path` attribute specified on its - * element. By using g_settings_new_with_path(), a #GSettings object - * can be instantiated for a relocatable schema, assigning a path to the - * instance. Paths passed to g_settings_new_with_path() will typically be + * `` element. By using [ctor@Gio.Settings.new_with_path], a `GSettings` + * object can be instantiated for a relocatable schema, assigning a path to the + * instance. Paths passed to [ctor@Gio.Settings.new_with_path] will typically be * constructed dynamically from a constant prefix plus some form of instance * identifier; but they must still be valid GSettings paths. Paths could also * be constant and used with a globally installed schema originating from a @@ -268,59 +268,59 @@ * `org.foo.MyApp.Window`, it could be instantiated for paths * `/org/foo/MyApp/main/`, `/org/foo/MyApp/document-1/`, * `/org/foo/MyApp/document-2/`, etc. If any of the paths are well-known - * they can be specified as elements in the parent schema, e.g.: - * |[ + * they can be specified as `` elements in the parent schema, e.g.: + * ```xml * * * - * ]| + * ``` * - * ## Build system integration # {#gsettings-build-system} + * ## Build system integration * * GSettings comes with autotools integration to simplify compiling and * installing schemas. To add GSettings support to an application, add the * following to your `configure.ac`: - * |[ + * ``` * GLIB_GSETTINGS - * ]| + * ``` * * In the appropriate `Makefile.am`, use the following snippet to compile and * install the named schema: - * |[ + * ``` * gsettings_SCHEMAS = org.foo.MyApp.gschema.xml * EXTRA_DIST = $(gsettings_SCHEMAS) * * @GSETTINGS_RULES@ - * ]| + * ``` * * No changes are needed to the build system to mark a schema XML file for * translation. Assuming it sets the `gettext-domain` attribute, a schema may * be marked for translation by adding it to `POTFILES.in`, assuming gettext * 0.19 is in use (the preferred method for translation): - * |[ + * ``` * data/org.foo.MyApp.gschema.xml - * ]| + * ``` * * Alternatively, if intltool 0.50.1 is in use: - * |[ + * ``` * [type: gettext/gsettings]data/org.foo.MyApp.gschema.xml - * ]| + * ``` * - * GSettings will use gettext to look up translations for the and - * elements, and also any elements which have a `l10n` - * attribute set. Translations must not be included in the `.gschema.xml` file - * by the build system, for example by using intltool XML rules with a + * GSettings will use gettext to look up translations for the `` and + * `` elements, and also any `` elements which have a + * `l10n` attribute set. Translations must not be included in the `.gschema.xml` + * file by the build system, for example by using intltool XML rules with a * `.gschema.xml.in` template. * * If an enumerated type defined in a C header file is to be used in a GSettings - * schema, it can either be defined manually using an element in the + * schema, it can either be defined manually using an `` element in the * schema XML, or it can be extracted automatically from the C header. This * approach is preferred, as it ensures the two representations are always * synchronised. To do so, add the following to the relevant `Makefile.am`: - * |[ + * ``` * gsettings_ENUM_NAMESPACE = org.foo.MyApp * gsettings_ENUM_FILES = my-app-enums.h my-app-misc.h - * ]| + * ``` * * `gsettings_ENUM_NAMESPACE` specifies the schema namespace for the enum files, * which are specified in `gsettings_ENUM_FILES`. This will generate a @@ -330,13 +330,6 @@ * `EXTRA_DIST`. */ -/** - * GSettings: - * - * #GSettings is an opaque data structure and can only be accessed - * using the following functions. - **/ - struct _GSettingsPrivate { /* where the signals go... */ diff --git a/gio/gsettingsbackend.c b/gio/gsettingsbackend.c index bc9400875..d11d1fd97 100644 --- a/gio/gsettingsbackend.c +++ b/gio/gsettingsbackend.c @@ -52,17 +52,13 @@ G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GSettingsBackend, g_settings_backend, G_TYP static gboolean g_settings_has_backend; /** - * SECTION:gsettingsbackend - * @title: GSettingsBackend - * @short_description: Interface for settings backend implementations - * @include: gio/gsettingsbackend.h - * @see_also: #GSettings, #GIOExtensionPoint + * GSettingsBackend: * - * The #GSettingsBackend interface defines a generic interface for + * The `GSettingsBackend` interface defines a generic interface for * non-strictly-typed data that is stored in a hierarchy. To implement - * an alternative storage backend for #GSettings, you need to implement - * the #GSettingsBackend interface and then make it implement the - * extension point %G_SETTINGS_BACKEND_EXTENSION_POINT_NAME. + * an alternative storage backend for [class@Gio.Settings], you need to + * implement the `GSettingsBackend` interface and then make it implement the + * extension point `G_SETTINGS_BACKEND_EXTENSION_POINT_NAME`. * * The interface defines methods for reading and writing values, a * method for determining if writing of certain values will fail @@ -72,15 +68,14 @@ static gboolean g_settings_has_backend; * implementations must carefully adhere to the expectations of * callers that are documented on each of the interface methods. * - * Some of the #GSettingsBackend functions accept or return a #GTree. - * These trees always have strings as keys and #GVariant as values. - * g_settings_backend_create_tree() is a convenience function to create - * suitable trees. + * Some of the `GSettingsBackend` functions accept or return a + * [struct@GLib.Tree]. These trees always have strings as keys and + * [struct@GLib.Variant] as values. * - * The #GSettingsBackend API is exported to allow third-party + * The `GSettingsBackend` API is exported to allow third-party * implementations, but does not carry the same stability guarantees * as the public GIO API. For this reason, you have to define the - * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including + * C preprocessor symbol `G_SETTINGS_ENABLE_BACKEND` before including * `gio/gsettingsbackend.h`. **/ diff --git a/gio/gsettingsbackend.h b/gio/gsettingsbackend.h index f579bf66f..2649605dd 100644 --- a/gio/gsettingsbackend.h +++ b/gio/gsettingsbackend.h @@ -53,11 +53,6 @@ G_BEGIN_DECLS **/ #define G_SETTINGS_BACKEND_EXTENSION_POINT_NAME "gsettings-backend" -/** - * GSettingsBackend: - * - * An implementation of a settings storage repository. - **/ typedef struct _GSettingsBackendPrivate GSettingsBackendPrivate; typedef struct _GSettingsBackendClass GSettingsBackendClass; diff --git a/gio/gsettingsschema.c b/gio/gsettingsschema.c index 2a2da65fd..b1918657d 100644 --- a/gio/gsettingsschema.c +++ b/gio/gsettingsschema.c @@ -38,12 +38,9 @@ #endif /** - * SECTION:gsettingsschema - * @short_description: Introspecting and controlling the loading - * of GSettings schemas - * @include: gio/gio.h + * GSettingsSchema: * - * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a + * The [struct@Gio.SettingsSchemaSource] and `GSettingsSchema` APIs provide a * mechanism for advanced control over the loading of schemas and a * mechanism for introspecting their content. * @@ -53,20 +50,20 @@ * the schema along with itself and it won't be installed into the * standard system directories for schemas. * - * #GSettingsSchemaSource provides a mechanism for dealing with this by - * allowing the creation of a new 'schema source' from which schemas can + * [struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this + * by allowing the creation of a new ‘schema source’ from which schemas can * be acquired. This schema source can then become part of the metadata * associated with the plugin and queried whenever the plugin requires * access to some settings. * * Consider the following example: * - * |[ + * ```c * typedef struct * { - * ... + * … * GSettingsSchemaSource *schema_source; - * ... + * … * } Plugin; * * Plugin * @@ -74,18 +71,18 @@ * { * Plugin *plugin; * - * ... + * … * * plugin->schema_source = * g_settings_schema_source_new_from_directory (dir, * g_settings_schema_source_get_default (), FALSE, NULL); * - * ... + * … * * return plugin; * } * - * ... + * … * * GSettings * * plugin_get_settings (Plugin *plugin, @@ -101,12 +98,12 @@ * * if (schema == NULL) * { - * ... disable the plugin or abort, etc ... + * … disable the plugin or abort, etc … * } * * return g_settings_new_full (schema, NULL, NULL); * } - * ]| + * ``` * * The code above shows how hooks should be added to the code that * initialises (or enables) the plugin to create the schema source and @@ -118,19 +115,19 @@ * ships a gschemas.compiled file as part of itself, and then simply do * the following: * - * |[ + * ```c * { * GSettings *settings; * gint some_value; * * settings = plugin_get_settings (self, NULL); * some_value = g_settings_get_int (settings, "some-value"); - * ... + * … * } - * ]| + * ``` * * It's also possible that the plugin system expects the schema source - * files (ie: .gschema.xml files) instead of a gschemas.compiled file. + * files (ie: `.gschema.xml` files) instead of a `gschemas.compiled` file. * In that case, the plugin loading system must compile the schemas for * itself before attempting to create the settings source. * @@ -144,13 +141,6 @@ * using the following functions. **/ -/** - * GSettingsSchema: - * - * This is an opaque structure type. You may not access it directly. - * - * Since: 2.32 - **/ struct _GSettingsSchema { GSettingsSchemaSource *source; From 832bf0f90c10546e54161a8edbf89d02a15bf782 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:23:10 +0000 Subject: [PATCH 05/21] docs: Move the GSimpleProxyResolver SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall --- gio/gsimpleproxyresolver.c | 11 ++++------- gio/gsimpleproxyresolver.h | 5 ----- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/gio/gsimpleproxyresolver.c b/gio/gsimpleproxyresolver.c index d0480a814..5ec998525 100644 --- a/gio/gsimpleproxyresolver.c +++ b/gio/gsimpleproxyresolver.c @@ -33,19 +33,16 @@ #include "glibintl.h" /** - * SECTION:gsimpleproxyresolver - * @short_description: Simple proxy resolver implementation - * @include: gio/gio.h - * @see_also: g_socket_client_set_proxy_resolver() + * GSimpleProxyResolver: * - * #GSimpleProxyResolver is a simple #GProxyResolver implementation + * `GSimpleProxyResolver` is a simple [iface@Gio.ProxyResolver] implementation * that handles a single default proxy, multiple URI-scheme-specific * proxies, and a list of hosts that proxies should not be used for. * - * #GSimpleProxyResolver is never the default proxy resolver, but it + * `GSimpleProxyResolver` is never the default proxy resolver, but it * can be used as the base class for another proxy resolver * implementation, or it can be created and used manually, such as - * with g_socket_client_set_proxy_resolver(). + * with [method@Gio.SocketClient.set_proxy_resolver]. * * Since: 2.36 */ diff --git a/gio/gsimpleproxyresolver.h b/gio/gsimpleproxyresolver.h index 2e5f4b2a8..113b49118 100644 --- a/gio/gsimpleproxyresolver.h +++ b/gio/gsimpleproxyresolver.h @@ -36,11 +36,6 @@ G_BEGIN_DECLS #define G_IS_SIMPLE_PROXY_RESOLVER_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SIMPLE_PROXY_RESOLVER)) #define G_SIMPLE_PROXY_RESOLVER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SIMPLE_PROXY_RESOLVER, GSimpleProxyResolverClass)) -/** - * GSimpleProxyResolver: - * - * A #GProxyResolver implementation for using a fixed set of proxies. - **/ typedef struct _GSimpleProxyResolver GSimpleProxyResolver; typedef struct _GSimpleProxyResolverPrivate GSimpleProxyResolverPrivate; typedef struct _GSimpleProxyResolverClass GSimpleProxyResolverClass; From 1c346808333fe187783fb7314728f1aa0dc16d0b Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:23:37 +0000 Subject: [PATCH 06/21] docs: Move the GSocketAddressEnumerator SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsocketaddressenumerator.c | 25 ++++++++++++------------- gio/gsocketaddressenumerator.h | 6 ------ 2 files changed, 12 insertions(+), 19 deletions(-) diff --git a/gio/gsocketaddressenumerator.c b/gio/gsocketaddressenumerator.c index 5a0e937a2..8b99d50c3 100644 --- a/gio/gsocketaddressenumerator.c +++ b/gio/gsocketaddressenumerator.c @@ -25,23 +25,22 @@ #include "gtask.h" /** - * SECTION:gsocketaddressenumerator - * @short_description: Enumerator for socket addresses - * @include: gio/gio.h + * GSocketAddressEnumerator: * - * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress - * instances. It is returned by enumeration functions such as - * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator - * to list each #GSocketAddress which could be used to connect to that - * #GSocketConnectable. + * `GSocketAddressEnumerator` is an enumerator type for + * [class@Gio.SocketAddress] instances. It is returned by enumeration functions + * such as [method@Gio.SocketConnectable.enumerate], which returns a + * `GSocketAddressEnumerator` to list each [class@Gio.SocketAddress] which could + * be used to connect to that [iface@Gio.SocketConnectable]. * * Enumeration is typically a blocking operation, so the asynchronous methods - * g_socket_address_enumerator_next_async() and - * g_socket_address_enumerator_next_finish() should be used where possible. + * [method@Gio.SocketAddressEnumerator.next_async] and + * [method@Gio.SocketAddressEnumerator.next_finish] should be used where + * possible. * - * Each #GSocketAddressEnumerator can only be enumerated once. Once - * g_socket_address_enumerator_next() has returned %NULL, further - * enumeration with that #GSocketAddressEnumerator is not possible, and it can + * Each `GSocketAddressEnumerator` can only be enumerated once. Once + * [method@Gio.SocketAddressEnumerator.next] has returned `NULL`, further + * enumeration with that `GSocketAddressEnumerator` is not possible, and it can * be unreffed. */ diff --git a/gio/gsocketaddressenumerator.h b/gio/gsocketaddressenumerator.h index ceee6a3f9..b3ff71c67 100644 --- a/gio/gsocketaddressenumerator.h +++ b/gio/gsocketaddressenumerator.h @@ -36,12 +36,6 @@ G_BEGIN_DECLS #define G_IS_SOCKET_ADDRESS_ENUMERATOR_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_SOCKET_ADDRESS_ENUMERATOR)) #define G_SOCKET_ADDRESS_ENUMERATOR_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_SOCKET_ADDRESS_ENUMERATOR, GSocketAddressEnumeratorClass)) -/** - * GSocketAddressEnumerator: - * - * Enumerator type for objects that contain or generate - * #GSocketAddress instances. - */ typedef struct _GSocketAddressEnumeratorClass GSocketAddressEnumeratorClass; struct _GSocketAddressEnumerator From bf5c0cc2baf61b12899c2897105da07cea35e1a1 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:23:54 +0000 Subject: [PATCH 07/21] docs: Move the GSocketListener SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsocketlistener.c | 25 +++++++++++-------------- 1 file changed, 11 insertions(+), 14 deletions(-) diff --git a/gio/gsocketlistener.c b/gio/gsocketlistener.c index 392f9ecd6..842140b75 100644 --- a/gio/gsocketlistener.c +++ b/gio/gsocketlistener.c @@ -42,26 +42,23 @@ /** - * SECTION:gsocketlistener - * @title: GSocketListener - * @short_description: Helper for accepting network client connections - * @include: gio/gio.h - * @see_also: #GThreadedSocketService, #GSocketService. + * GSocketListener: * - * A #GSocketListener is an object that keeps track of a set + * A `GSocketListener` is an object that keeps track of a set * of server sockets and helps you accept sockets from any of the * socket, either sync or async. * - * Add addresses and ports to listen on using g_socket_listener_add_address() - * and g_socket_listener_add_inet_port(). These will be listened on until - * g_socket_listener_close() is called. Dropping your final reference to the - * #GSocketListener will not cause g_socket_listener_close() to be called - * implicitly, as some references to the #GSocketListener may be held + * Add addresses and ports to listen on using + * [method@Gio.SocketListener.add_address] and + * [method@Gio.SocketListener.add_inet_port]. These will be listened on until + * [method@Gio.SocketListener.close] is called. Dropping your final reference to + * the `GSocketListener` will not cause [method@Gio.SocketListener.close] to be + * called implicitly, as some references to the `GSocketListener` may be held * internally. * - * If you want to implement a network server, also look at #GSocketService - * and #GThreadedSocketService which are subclasses of #GSocketListener - * that make this even easier. + * If you want to implement a network server, also look at + * [class@Gio.SocketService] and [class@Gio.ThreadedSocketService] which are + * subclasses of `GSocketListener` that make this even easier. * * Since: 2.22 */ From 45a815ae6d9b106c717d053be79632c86ee18241 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:24:14 +0000 Subject: [PATCH 08/21] docs: Move the GSocketService SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gsocketservice.c | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/gio/gsocketservice.c b/gio/gsocketservice.c index 42e18d0a1..ad6e4783d 100644 --- a/gio/gsocketservice.c +++ b/gio/gsocketservice.c @@ -23,37 +23,33 @@ */ /** - * SECTION:gsocketservice - * @title: GSocketService - * @short_description: Make it easy to implement a network service - * @include: gio/gio.h - * @see_also: #GThreadedSocketService, #GSocketListener. + * GSocketService: * - * A #GSocketService is an object that represents a service that + * A `GSocketService` is an object that represents a service that * is provided to the network or over local sockets. When a new - * connection is made to the service the #GSocketService::incoming + * connection is made to the service the [signal@Gio.SocketService::incoming] * signal is emitted. * - * A #GSocketService is a subclass of #GSocketListener and you need + * A `GSocketService` is a subclass of [class@Gio.SocketListener] and you need * to add the addresses you want to accept connections on with the - * #GSocketListener APIs. + * [class@Gio.SocketListener] APIs. * * There are two options for implementing a network service based on - * #GSocketService. The first is to create the service using - * g_socket_service_new() and to connect to the #GSocketService::incoming - * signal. The second is to subclass #GSocketService and override the - * default signal handler implementation. + * `GSocketService`. The first is to create the service using + * [ctor@Gio.SocketService.new] and to connect to the + * [signal@Gio.SocketService::incoming] signal. The second is to subclass + * `GSocketService` and override the default signal handler implementation. * * In either case, the handler must immediately return, or else it * will block additional incoming connections from being serviced. * If you are interested in writing connection handlers that contain - * blocking code then see #GThreadedSocketService. + * blocking code then see [class@Gio.ThreadedSocketService]. * * The socket service runs on the main loop of the - * [thread-default context][g-main-context-push-thread-default-context] - * of the thread it is created in, and is not - * threadsafe in general. However, the calls to start and stop the - * service are thread-safe so these can be used from threads that + * thread-default context (see + * [method@GLib.MainContext.push_thread_default_context]) of the thread it is + * created in, and is not threadsafe in general. However, the calls to start and + * stop the service are thread-safe so these can be used from threads that * handle incoming clients. * * Since: 2.22 From a463a295221fe1d8ea2e50d05116822fb418bf88 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:24:34 +0000 Subject: [PATCH 09/21] docs: Move the GTlsCertificate SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtlscertificate.c | 16 ++-------------- 1 file changed, 2 insertions(+), 14 deletions(-) diff --git a/gio/gtlscertificate.c b/gio/gtlscertificate.c index 4862bc99a..e95436d3c 100644 --- a/gio/gtlscertificate.c +++ b/gio/gtlscertificate.c @@ -29,25 +29,13 @@ #include "glibintl.h" /** - * SECTION:gtlscertificate - * @title: GTlsCertificate - * @short_description: TLS certificate - * @include: gio/gio.h - * @see_also: #GTlsConnection + * GTlsCertificate: * * A certificate used for TLS authentication and encryption. * This can represent either a certificate only (eg, the certificate * received by a client from a server), or the combination of * a certificate and a private key (which is needed when acting as a - * #GTlsServerConnection). - * - * Since: 2.28 - */ - -/** - * GTlsCertificate: - * - * Abstract base class for TLS certificate types. + * [iface@Gio.TlsServerConnection]). * * Since: 2.28 */ From 15ae12628de69a456b1edabc34e668be433fab7d Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:25:41 +0000 Subject: [PATCH 10/21] docs: Move the GTls*Connection SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtlsclientconnection.c | 13 ++----------- gio/gtlsserverconnection.c | 8 +++----- gio/gtlsserverconnection.h | 8 -------- 3 files changed, 5 insertions(+), 24 deletions(-) diff --git a/gio/gtlsclientconnection.c b/gio/gtlsclientconnection.c index d64106e51..b2b0155fd 100644 --- a/gio/gtlsclientconnection.c +++ b/gio/gtlsclientconnection.c @@ -30,20 +30,11 @@ #include "gtlscertificate.h" #include "glibintl.h" -/** - * SECTION:gtlsclientconnection - * @short_description: TLS client-side connection - * @include: gio/gio.h - * - * #GTlsClientConnection is the client-side subclass of - * #GTlsConnection, representing a client-side TLS connection. - */ - /** * GTlsClientConnection: * - * Abstract base class for the backend-specific client connection - * type. + * `GTlsClientConnection` is the client-side subclass of + * [class@Gio.TlsConnection], representing a client-side TLS connection. * * Since: 2.28 */ diff --git a/gio/gtlsserverconnection.c b/gio/gtlsserverconnection.c index dc9db62bb..10757fde3 100644 --- a/gio/gtlsserverconnection.c +++ b/gio/gtlsserverconnection.c @@ -30,12 +30,10 @@ #include "glibintl.h" /** - * SECTION:gtlsserverconnection - * @short_description: TLS server-side connection - * @include: gio/gio.h + * GTlsServerConnection: * - * #GTlsServerConnection is the server-side subclass of #GTlsConnection, - * representing a server-side TLS connection. + * `GTlsServerConnection` is the server-side subclass of + * [class@Gio.TlsConnection], representing a server-side TLS connection. * * Since: 2.28 */ diff --git a/gio/gtlsserverconnection.h b/gio/gtlsserverconnection.h index f84c25b86..7c4e2832d 100644 --- a/gio/gtlsserverconnection.h +++ b/gio/gtlsserverconnection.h @@ -34,14 +34,6 @@ G_BEGIN_DECLS #define G_IS_TLS_SERVER_CONNECTION(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), G_TYPE_TLS_SERVER_CONNECTION)) #define G_TLS_SERVER_CONNECTION_GET_INTERFACE(inst) (G_TYPE_INSTANCE_GET_INTERFACE ((inst), G_TYPE_TLS_SERVER_CONNECTION, GTlsServerConnectionInterface)) -/** - * GTlsServerConnection: - * - * TLS server-side connection. This is the server-side implementation - * of a #GTlsConnection. - * - * Since: 2.28 - */ typedef struct _GTlsServerConnectionInterface GTlsServerConnectionInterface; /** From 78411d0975c11061ba896f9e4634e0005829273e Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:26:02 +0000 Subject: [PATCH 11/21] docs: Move the GTlsDatabase SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gtlsdatabase.c | 18 ++++-------------- 1 file changed, 4 insertions(+), 14 deletions(-) diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c index 4966aadd0..d55d0fe90 100644 --- a/gio/gtlsdatabase.c +++ b/gio/gtlsdatabase.c @@ -33,27 +33,17 @@ #include "gtlsinteraction.h" /** - * SECTION:gtlsdatabase - * @short_description: TLS database type - * @include: gio/gio.h + * GTlsDatabase: * - * #GTlsDatabase is used to look up certificates and other information + * `GTlsDatabase` is used to look up certificates and other information * from a certificate or key store. It is an abstract base class which * TLS library specific subtypes override. * - * A #GTlsDatabase may be accessed from multiple threads by the TLS backend. + * A `GTlsDatabase` may be accessed from multiple threads by the TLS backend. * All implementations are required to be fully thread-safe. * * Most common client applications will not directly interact with - * #GTlsDatabase. It is used internally by #GTlsConnection. - * - * Since: 2.30 - */ - -/** - * GTlsDatabase: - * - * Abstract base class for the backend-specific database types. + * `GTlsDatabase`. It is used internally by [class@Gio.TlsConnection]. * * Since: 2.30 */ From 2be7859f107f7132882659e1fae49e6de7b49d77 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:26:25 +0000 Subject: [PATCH 12/21] docs: Move the GUnixConnection SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gunixconnection.c | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/gio/gunixconnection.c b/gio/gunixconnection.c index 936736638..94a92e3c4 100644 --- a/gio/gunixconnection.c +++ b/gio/gunixconnection.c @@ -31,19 +31,15 @@ #endif /** - * SECTION:gunixconnection - * @title: GUnixConnection - * @short_description: A UNIX domain GSocketConnection - * @include: gio/gunixconnection.h - * @see_also: #GSocketConnection. + * GUnixConnection: * - * This is the subclass of #GSocketConnection that is created + * This is the subclass of [class@Gio.SocketConnection] that is created * for UNIX domain sockets. * * It contains functions to do some of the UNIX socket specific * functionality like passing file descriptors. * - * Since GLib 2.72, #GUnixConnection is available on all platforms. It requires + * Since GLib 2.72, `GUnixConnection` is available on all platforms. It requires * underlying system support (such as Windows 10 with `AF_UNIX`) at run time. * * Before GLib 2.72, `` belonged to the UNIX-specific GIO @@ -53,13 +49,6 @@ * Since: 2.22 */ -/** - * GUnixConnection: - * - * #GUnixConnection is an opaque data structure and can only be accessed - * using the following functions. - **/ - G_DEFINE_TYPE_WITH_CODE (GUnixConnection, g_unix_connection, G_TYPE_SOCKET_CONNECTION, g_socket_connection_factory_register_type (g_define_type_id, From 68d3f6e53a2dc6c5eeb7e80b90f012e99589f8f2 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:26:43 +0000 Subject: [PATCH 13/21] docs: Move the GUnixCredentialsMessage SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gunixcredentialsmessage.c | 24 +++++++++++------------- gio/gunixcredentialsmessage.h | 8 -------- 2 files changed, 11 insertions(+), 21 deletions(-) diff --git a/gio/gunixcredentialsmessage.c b/gio/gunixcredentialsmessage.c index 212c4b0e0..6440c3ba4 100644 --- a/gio/gunixcredentialsmessage.c +++ b/gio/gunixcredentialsmessage.c @@ -16,31 +16,29 @@ */ /** - * SECTION:gunixcredentialsmessage - * @title: GUnixCredentialsMessage - * @short_description: A GSocketControlMessage containing credentials - * @include: gio/gunixcredentialsmessage.h - * @see_also: #GUnixConnection, #GSocketControlMessage + * GUnixCredentialsMessage: * - * This #GSocketControlMessage contains a #GCredentials instance. It - * may be sent using g_socket_send_message() and received using - * g_socket_receive_message() over UNIX sockets (ie: sockets in the - * %G_SOCKET_FAMILY_UNIX family). + * This [class@Gio.SocketControlMessage] contains a [class@Gio.Credentials] + * instance. It may be sent using [method@Gio.Socket.send_message] and received + * using [method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in + * the `G_SOCKET_FAMILY_UNIX` family). * * For an easier way to send and receive credentials over * stream-oriented UNIX sockets, see - * g_unix_connection_send_credentials() and - * g_unix_connection_receive_credentials(). To receive credentials of + * [method@Gio.UnixConnection.send_credentials] and + * [method@Gio.UnixConnection.receive_credentials]. To receive credentials of * a foreign process connected to a socket, use - * g_socket_get_credentials(). + * [method@Gio.Socket.get_credentials]. * - * Since GLib 2.72, #GUnixCredentialMessage is available on all platforms. It + * Since GLib 2.72, `GUnixCredentialMessage` is available on all platforms. It * requires underlying system support (such as Windows 10 with `AF_UNIX`) at run * time. * * Before GLib 2.72, `` belonged to the UNIX-specific * GIO interfaces, thus you had to use the `gio-unix-2.0.pc` pkg-config file * when using it. This is no longer necessary since GLib 2.72. + * + * Since: 2.26 */ #include "config.h" diff --git a/gio/gunixcredentialsmessage.h b/gio/gunixcredentialsmessage.h index cd42d254e..8f63bd253 100644 --- a/gio/gunixcredentialsmessage.h +++ b/gio/gunixcredentialsmessage.h @@ -58,14 +58,6 @@ struct _GUnixCredentialsMessageClass void (*_g_reserved2) (void); }; -/** - * GUnixCredentialsMessage: - * - * The #GUnixCredentialsMessage structure contains only private data - * and should only be accessed using the provided API. - * - * Since: 2.26 - */ struct _GUnixCredentialsMessage { GSocketControlMessage parent_instance; From 1390713af966a81ec7ba987ddaa8da7ad656776c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:27:11 +0000 Subject: [PATCH 14/21] docs: Move the GUnix*Stream SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gunixinputstream.c | 9 +++------ gio/gunixinputstream.h | 5 ----- gio/gunixoutputstream.c | 9 +++------ gio/gunixoutputstream.h | 5 ----- 4 files changed, 6 insertions(+), 22 deletions(-) diff --git a/gio/gunixinputstream.c b/gio/gunixinputstream.c index 2180ce8dc..4ae672d2e 100644 --- a/gio/gunixinputstream.c +++ b/gio/gunixinputstream.c @@ -39,14 +39,11 @@ /** - * SECTION:gunixinputstream - * @short_description: Streaming input operations for UNIX file descriptors - * @include: gio/gunixinputstream.h - * @see_also: #GInputStream + * GUnixInputStream: * - * #GUnixInputStream implements #GInputStream for reading from a UNIX + * `GUnixInputStream` implements [class@Gio.InputStream] for reading from a UNIX * file descriptor, including asynchronous operations. (If the file - * descriptor refers to a socket or pipe, this will use poll() to do + * descriptor refers to a socket or pipe, this will use `poll()` to do * asynchronous I/O. If it refers to a regular file, it will fall back * to doing asynchronous I/O in another thread.) * diff --git a/gio/gunixinputstream.h b/gio/gunixinputstream.h index 78b2cbb9a..0c2af4f03 100644 --- a/gio/gunixinputstream.h +++ b/gio/gunixinputstream.h @@ -34,11 +34,6 @@ G_BEGIN_DECLS #define G_IS_UNIX_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_UNIX_INPUT_STREAM)) #define G_UNIX_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_UNIX_INPUT_STREAM, GUnixInputStreamClass)) -/** - * GUnixInputStream: - * - * Implements #GInputStream for reading from selectable unix file descriptors - **/ typedef struct _GUnixInputStream GUnixInputStream; typedef struct _GUnixInputStreamClass GUnixInputStreamClass; typedef struct _GUnixInputStreamPrivate GUnixInputStreamPrivate; diff --git a/gio/gunixoutputstream.c b/gio/gunixoutputstream.c index 8a71c315c..0e48c9693 100644 --- a/gio/gunixoutputstream.c +++ b/gio/gunixoutputstream.c @@ -41,14 +41,11 @@ /** - * SECTION:gunixoutputstream - * @short_description: Streaming output operations for UNIX file descriptors - * @include: gio/gunixoutputstream.h - * @see_also: #GOutputStream + * GUnixOutputStream: * - * #GUnixOutputStream implements #GOutputStream for writing to a UNIX + * `GUnixOutputStream` implements [class@Gio.OutputStream] for writing to a UNIX * file descriptor, including asynchronous operations. (If the file - * descriptor refers to a socket or pipe, this will use poll() to do + * descriptor refers to a socket or pipe, this will use `poll()` to do * asynchronous I/O. If it refers to a regular file, it will fall back * to doing asynchronous I/O in another thread.) * diff --git a/gio/gunixoutputstream.h b/gio/gunixoutputstream.h index 37aa22584..55e33f68f 100644 --- a/gio/gunixoutputstream.h +++ b/gio/gunixoutputstream.h @@ -34,11 +34,6 @@ G_BEGIN_DECLS #define G_IS_UNIX_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_UNIX_OUTPUT_STREAM)) #define G_UNIX_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_UNIX_OUTPUT_STREAM, GUnixOutputStreamClass)) -/** - * GUnixOutputStream: - * - * Implements #GOutputStream for outputting to selectable unix file descriptors - **/ typedef struct _GUnixOutputStream GUnixOutputStream; typedef struct _GUnixOutputStreamClass GUnixOutputStreamClass; typedef struct _GUnixOutputStreamPrivate GUnixOutputStreamPrivate; From 830db4e3c0cdb3fb02acc050dad3df309e7aef1d Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:27:32 +0000 Subject: [PATCH 15/21] docs: Move the GUnixSocketAddress SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gunixsocketaddress.c | 20 ++++++-------------- 1 file changed, 6 insertions(+), 14 deletions(-) diff --git a/gio/gunixsocketaddress.c b/gio/gunixsocketaddress.c index 3ccb2cbf1..3640f1f90 100644 --- a/gio/gunixsocketaddress.c +++ b/gio/gunixsocketaddress.c @@ -35,22 +35,21 @@ #endif /** - * SECTION:gunixsocketaddress - * @short_description: UNIX GSocketAddress - * @include: gio/gunixsocketaddress.h + * GUnixSocketAddress: * - * Support for UNIX-domain (also known as local) sockets. + * Support for UNIX-domain (also known as local) sockets, corresponding to + * `struct sockaddr_un`. * * UNIX domain sockets are generally visible in the filesystem. * However, some systems support abstract socket names which are not * visible in the filesystem and not affected by the filesystem * permissions, visibility, etc. Currently this is only supported * under Linux. If you attempt to use abstract sockets on other - * systems, function calls may return %G_IO_ERROR_NOT_SUPPORTED - * errors. You can use g_unix_socket_address_abstract_names_supported() + * systems, function calls may return `G_IO_ERROR_NOT_SUPPORTED` + * errors. You can use [func@Gio.UnixSocketAddress.abstract_names_supported] * to see if abstract names are supported. * - * Since GLib 2.72, #GUnixSocketAddress is available on all platforms. It + * Since GLib 2.72, `GUnixSocketAddress` is available on all platforms. It * requires underlying system support (such as Windows 10 with `AF_UNIX`) at * run time. * @@ -59,13 +58,6 @@ * when using it. This is no longer necessary since GLib 2.72. */ -/** - * GUnixSocketAddress: - * - * A UNIX-domain (local) socket address, corresponding to a - * struct sockaddr_un. - */ - enum { PROP_0, From ed247401bf7d9240f3c08fb97767d0aa1a4ad10a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:27:57 +0000 Subject: [PATCH 16/21] docs: Move the GVolume SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gvolume.c | 60 +++++++++++++++++++++++++-------------------------- gio/gvolume.h | 4 ++-- 2 files changed, 31 insertions(+), 33 deletions(-) diff --git a/gio/gvolume.c b/gio/gvolume.c index 5a204969a..f10fe55e6 100644 --- a/gio/gvolume.c +++ b/gio/gvolume.c @@ -32,51 +32,49 @@ /** - * SECTION:gvolume - * @short_description: Volume management - * @include: gio/gio.h + * GVolume: * - * The #GVolume interface represents user-visible objects that can be - * mounted. Note, when porting from GnomeVFS, #GVolume is the moral - * equivalent of #GnomeVFSDrive. + * The `GVolume` interface represents user-visible objects that can be + * mounted. Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), + * `GVolume` is the moral equivalent of `GnomeVFSDrive`. * - * Mounting a #GVolume instance is an asynchronous operation. For more - * information about asynchronous operations, see #GAsyncResult and - * #GTask. To mount a #GVolume, first call g_volume_mount() with (at - * least) the #GVolume instance, optionally a #GMountOperation object - * and a #GAsyncReadyCallback. + * Mounting a `GVolume` instance is an asynchronous operation. For more + * information about asynchronous operations, see [class@Gio.AsyncResult] and + * [class@Gio.Task]. To mount a `GVolume`, first call [method@Gio.Volume.mount] + * with (at least) the `GVolume` instance, optionally a + * [class@Gio.MountOperation] object and a [type@Gio.AsyncReadyCallback]. * - * Typically, one will only want to pass %NULL for the - * #GMountOperation if automounting all volumes when a desktop session - * starts since it's not desirable to put up a lot of dialogs asking + * Typically, one will only want to pass `NULL` for the + * [class@Gio.MountOperation] if automounting all volumes when a desktop session + * starts since it’s not desirable to put up a lot of dialogs asking * for credentials. * * The callback will be fired when the operation has resolved (either - * with success or failure), and a #GAsyncResult instance will be + * with success or failure), and a [class@Gio.AsyncResult] instance will be * passed to the callback. That callback should then call - * g_volume_mount_finish() with the #GVolume instance and the - * #GAsyncResult data to see if the operation was completed - * successfully. If an @error is present when g_volume_mount_finish() - * is called, then it will be filled with any error information. + * [method@Gio.Volume.mount_finish] with the `GVolume` instance and the + * [class@Gio.AsyncResult] data to see if the operation was completed + * successfully. If a [type@GLib.Error] is present when + * [method@Gio.Volume.mount_finish] is called, then it will be filled with any + * error information. * - * ## Volume Identifiers # {#volume-identifier} + * ## Volume Identifiers * * It is sometimes necessary to directly access the underlying * operating system object behind a volume (e.g. for passing a volume - * to an application via the commandline). For this purpose, GIO - * allows to obtain an 'identifier' for the volume. There can be + * to an application via the command line). For this purpose, GIO + * allows to obtain an ‘identifier’ for the volume. There can be * different kinds of identifiers, such as Hal UDIs, filesystem labels, * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined * strings as names for the different kinds of identifiers: - * %G_VOLUME_IDENTIFIER_KIND_UUID, %G_VOLUME_IDENTIFIER_KIND_LABEL, etc. - * Use g_volume_get_identifier() to obtain an identifier for a volume. + * `G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc. + * Use [method@Gio.Volume.get_identifier] to obtain an identifier for a volume. * - * - * Note that %G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available - * when the gvfs hal volume monitor is in use. Other volume monitors - * will generally be able to provide the %G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE + * Note that `G_VOLUME_IDENTIFIER_KIND_HAL_UDI` will only be available + * when the GVFS hal volume monitor is in use. Other volume monitors + * will generally be able to provide the `G_VOLUME_IDENTIFIER_KIND_UNIX_DEVICE` * identifier, which can be used to obtain a hal device by means of - * libhal_manager_find_device_string_match(). + * `libhal_manager_find_device_string_match()`. */ typedef GVolumeIface GVolumeInterface; @@ -563,7 +561,7 @@ g_volume_eject_with_operation_finish (GVolume *volume, * @kind: the kind of identifier to return * * Gets the identifier of the given kind for @volume. - * See the [introduction][volume-identifier] for more + * See the [introduction](#volume-identifiers) for more * information about volume identifiers. * * Returns: (nullable) (transfer full): a newly allocated string containing the @@ -591,7 +589,7 @@ g_volume_get_identifier (GVolume *volume, * g_volume_enumerate_identifiers: * @volume: a #GVolume * - * Gets the kinds of [identifiers][volume-identifier] that @volume has. + * Gets the kinds of [identifiers](#volume-identifiers) that @volume has. * Use g_volume_get_identifier() to obtain the identifiers themselves. * * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array diff --git a/gio/gvolume.h b/gio/gvolume.h index 2d6e14eff..7b5a81a0c 100644 --- a/gio/gvolume.h +++ b/gio/gvolume.h @@ -109,10 +109,10 @@ G_BEGIN_DECLS * @mount_finish: Finishes a mount operation. * @eject: Ejects a given #GVolume. * @eject_finish: Finishes an eject operation. - * @get_identifier: Returns the [identifier][volume-identifier] of the given kind, or %NULL if + * @get_identifier: Returns the [identifier](#volume-identifiers) of the given kind, or %NULL if * the #GVolume doesn't have one. * @enumerate_identifiers: Returns an array strings listing the kinds - * of [identifiers][volume-identifier] which the #GVolume has. + * of [identifiers](#volume-identifiers) which the #GVolume has. * @should_automount: Returns %TRUE if the #GVolume should be automatically mounted. * @get_activation_root: Returns the activation root for the #GVolume if it is known in advance or %NULL if * it is not known. From 7df150eaac6a9af1cd4e401fd7ab6a175f5f05cd Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:28:16 +0000 Subject: [PATCH 17/21] docs: Move the GVolumeMonitor SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gvolumemonitor.c | 17 +++++++---------- gio/gvolumemonitor.h | 5 ----- 2 files changed, 7 insertions(+), 15 deletions(-) diff --git a/gio/gvolumemonitor.c b/gio/gvolumemonitor.c index cc4f3e49c..ed7288bde 100644 --- a/gio/gvolumemonitor.c +++ b/gio/gvolumemonitor.c @@ -32,19 +32,16 @@ /** - * SECTION:gvolumemonitor - * @short_description: Volume Monitor - * @include: gio/gio.h - * @see_also: #GFileMonitor + * GVolumeMonitor: * - * #GVolumeMonitor is for listing the user interesting devices and volumes + * `GVolumeMonitor` is for listing the user interesting devices and volumes * on the computer. In other words, what a file selector or file manager - * would show in a sidebar. + * would show in a sidebar. * - * #GVolumeMonitor is not - * [thread-default-context aware][g-main-context-push-thread-default], - * and so should not be used other than from the main thread, with no - * thread-default-context active. + * `GVolumeMonitor` is not + * thread-default-context aware (see + * [method@GLib.MainContext.push_thread_default]), and so should not be used + * other than from the main thread, with no thread-default-context active. * * In order to receive updates about volumes and mounts monitored through GVFS, * a main loop must be running. diff --git a/gio/gvolumemonitor.h b/gio/gvolumemonitor.h index 11bd3319b..7ef917a7b 100644 --- a/gio/gvolumemonitor.h +++ b/gio/gvolumemonitor.h @@ -49,11 +49,6 @@ G_BEGIN_DECLS */ #define G_VOLUME_MONITOR_EXTENSION_POINT_NAME "gio-volume-monitor" -/** - * GVolumeMonitor: - * - * A Volume Monitor that watches for volume events. - **/ typedef struct _GVolumeMonitorClass GVolumeMonitorClass; struct _GVolumeMonitor From 754047849c8e9569362d39f5247506a6a84ee33a Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:28:37 +0000 Subject: [PATCH 18/21] docs: Move the GWin32*Stream SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gwin32inputstream.c | 7 ++----- gio/gwin32inputstream.h | 5 ----- gio/gwin32outputstream.c | 7 ++----- gio/gwin32outputstream.h | 5 ----- 4 files changed, 4 insertions(+), 20 deletions(-) diff --git a/gio/gwin32inputstream.c b/gio/gwin32inputstream.c index 685d6f295..233f6ed1f 100644 --- a/gio/gwin32inputstream.c +++ b/gio/gwin32inputstream.c @@ -36,12 +36,9 @@ #include "glibintl.h" /** - * SECTION:gwin32inputstream - * @short_description: Streaming input operations for Windows file handles - * @include: gio/gwin32inputstream.h - * @see_also: #GInputStream + * GWin32InputStream: * - * #GWin32InputStream implements #GInputStream for reading from a + * `GWin32InputStream` implements [class@Gio.InputStream] for reading from a * Windows file handle. * * Note that `` belongs to the Windows-specific GIO diff --git a/gio/gwin32inputstream.h b/gio/gwin32inputstream.h index 8dde9e803..53c7d78cf 100644 --- a/gio/gwin32inputstream.h +++ b/gio/gwin32inputstream.h @@ -35,11 +35,6 @@ G_BEGIN_DECLS #define G_IS_WIN32_INPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_WIN32_INPUT_STREAM)) #define G_WIN32_INPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_WIN32_INPUT_STREAM, GWin32InputStreamClass)) -/** - * GWin32InputStream: - * - * Implements #GInputStream for reading from selectable Windows file handles - **/ typedef struct _GWin32InputStream GWin32InputStream; typedef struct _GWin32InputStreamClass GWin32InputStreamClass; typedef struct _GWin32InputStreamPrivate GWin32InputStreamPrivate; diff --git a/gio/gwin32outputstream.c b/gio/gwin32outputstream.c index b88f05c82..b3ad407de 100644 --- a/gio/gwin32outputstream.c +++ b/gio/gwin32outputstream.c @@ -37,12 +37,9 @@ #include "glibintl.h" /** - * SECTION:gwin32outputstream - * @short_description: Streaming output operations for Windows file handles - * @include: gio/gwin32outputstream.h - * @see_also: #GOutputStream + * GWin32OutputStream: * - * #GWin32OutputStream implements #GOutputStream for writing to a + * `GWin32OutputStream` implements [class@Gio.OutputStream] for writing to a * Windows file handle. * * Note that `` belongs to the Windows-specific GIO diff --git a/gio/gwin32outputstream.h b/gio/gwin32outputstream.h index d64fdc176..35942ca88 100644 --- a/gio/gwin32outputstream.h +++ b/gio/gwin32outputstream.h @@ -35,11 +35,6 @@ G_BEGIN_DECLS #define G_IS_WIN32_OUTPUT_STREAM_CLASS(k) (G_TYPE_CHECK_CLASS_TYPE ((k), G_TYPE_WIN32_OUTPUT_STREAM)) #define G_WIN32_OUTPUT_STREAM_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), G_TYPE_WIN32_OUTPUT_STREAM, GWin32OutputStreamClass)) -/** - * GWin32OutputStream: - * - * Implements #GOutputStream for outputting to Windows file handles - **/ typedef struct _GWin32OutputStream GWin32OutputStream; typedef struct _GWin32OutputStreamClass GWin32OutputStreamClass; typedef struct _GWin32OutputStreamPrivate GWin32OutputStreamPrivate; From 38c480971927b1e47bc720c33cb992fd26a29665 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:29:00 +0000 Subject: [PATCH 19/21] docs: Move the GWin32RegistryKey SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gwin32registrykey.c | 34 ++++++++++++++++------------------ 1 file changed, 16 insertions(+), 18 deletions(-) diff --git a/gio/gwin32registrykey.c b/gio/gwin32registrykey.c index ed9e854ef..73c47b155 100644 --- a/gio/gwin32registrykey.c +++ b/gio/gwin32registrykey.c @@ -347,23 +347,21 @@ G_DEFINE_BOXED_TYPE (GWin32RegistryValueIter, g_win32_registry_value_iter, g_win32_registry_value_iter_free) /** - * SECTION:gwin32registrykey - * @title: GWin32RegistryKey - * @short_description: W32 registry access helper - * @include: gio/win32/gwin32registrykey.h + * GWin32RegistryKey: * - * #GWin32RegistryKey represents a single Windows Registry key. + * `GWin32RegistryKey` represents a single Windows Registry key. * - * #GWin32RegistryKey is used by a number of helper functions that read + * `GWin32RegistryKey` is used by a number of helper functions that read * Windows Registry. All keys are opened with read-only access, and at * the moment there is no API for writing into registry keys or creating * new ones. * - * #GWin32RegistryKey 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_win32_registry_key_new() and g_win32_registry_key_get_child(), so these - * functions can return %NULL. + * `GWin32RegistryKey` 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.Win32RegistryKey.new] and + * [method@Gio.Win32RegistryKey.get_child], so these functions can return + * `NULL`. * * To increase efficiency, a UTF-16 variant is available for all functions * that deal with key or value names in the registry. Use these to perform @@ -372,17 +370,17 @@ G_DEFINE_BOXED_TYPE (GWin32RegistryValueIter, g_win32_registry_value_iter, * of UTF-16 functions avoids the overhead of converting names to UTF-8 and * back. * - * All functions operate in current user's context (it is not possible to - * access registry tree of a different user). + * All functions operate in the current user’s context (it is not possible to + * access the registry tree of a different user). * - * Key paths must use '\\' as a separator, '/' is not supported. Key names - * must not include '\\', because it's used as a separator. Value names - * can include '\\'. + * Key paths must use `\\` as a separator, `/` is not supported. Key names + * must not include `\\`, because it’s used as a separator. Value names + * can include `\\`. * * Key and value names are not case sensitive. * - * Full key name (excluding the pre-defined ancestor's name) can't exceed - * 255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16 + * A full key name (excluding the pre-defined ancestor’s name) can’t exceed + * 255 UTF-16 characters, give or take. A value name can’t exceed 16383 UTF-16 * characters. Tree depth is limited to 512 levels. **/ From 9e95163a3cc88cb7756fbcaccd1605cbeb3d75c0 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:29:26 +0000 Subject: [PATCH 20/21] docs: Move the GZlib*Compressor SECTIONs Move them to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- gio/gzlibcompressor.c | 11 ++--------- gio/gzlibdecompressor.c | 11 ++--------- 2 files changed, 4 insertions(+), 18 deletions(-) diff --git a/gio/gzlibcompressor.c b/gio/gzlibcompressor.c index a1c018a01..80084b135 100644 --- a/gio/gzlibcompressor.c +++ b/gio/gzlibcompressor.c @@ -43,21 +43,14 @@ enum { }; /** - * SECTION:gzlibcompressor - * @short_description: Zlib compressor - * @include: gio/gio.h + * GZlibCompressor: * - * #GZlibCompressor is an implementation of #GConverter that + * `GZlibCompressor` is an implementation of [iface@Gio.Converter] that * compresses data using zlib. */ static void g_zlib_compressor_iface_init (GConverterIface *iface); -/** - * GZlibCompressor: - * - * Zlib decompression - */ struct _GZlibCompressor { GObject parent_instance; diff --git a/gio/gzlibdecompressor.c b/gio/gzlibdecompressor.c index f7045093e..1e24a74dc 100644 --- a/gio/gzlibdecompressor.c +++ b/gio/gzlibdecompressor.c @@ -42,11 +42,9 @@ enum { }; /** - * SECTION:gzlibdecompressor - * @short_description: Zlib decompressor - * @include: gio/gio.h + * GZlibDecompressor: * - * #GZlibDecompressor is an implementation of #GConverter that + * `GZlibDecompressor` is an implementation of [iface@Gio.Converter] that * decompresses data compressed with zlib. */ @@ -58,11 +56,6 @@ typedef struct { GFileInfo *file_info; } HeaderData; -/** - * GZlibDecompressor: - * - * Zlib decompression - */ struct _GZlibDecompressor { GObject parent_instance; From 0fe15f9b9b2c15a4f164652801a1ef707767b726 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Thu, 2 Nov 2023 16:30:02 +0000 Subject: [PATCH 21/21] docs: Move the GChecksum SECTION Move it to the struct docs. Signed-off-by: Philip Withnall Helps: #3037 --- glib/gchecksum.c | 27 ++++++++++++++------------- glib/gchecksum.h | 10 ---------- 2 files changed, 14 insertions(+), 23 deletions(-) diff --git a/glib/gchecksum.c b/glib/gchecksum.c index fea7803cd..28de99d68 100644 --- a/glib/gchecksum.c +++ b/glib/gchecksum.c @@ -33,25 +33,26 @@ /** - * SECTION:checksum - * @title: Data Checksums - * @short_description: computes the checksum for data + * GChecksum: * - * GLib provides a generic API for computing checksums (or "digests") + * GLib provides a generic API for computing checksums (or ‘digests’) * for a sequence of arbitrary bytes, using various hashing algorithms * like MD5, SHA-1 and SHA-256. Checksums are commonly used in various * environments and specifications. * - * GLib supports incremental checksums using the GChecksum data - * structure, by calling g_checksum_update() as long as there's data - * available and then using g_checksum_get_string() or - * g_checksum_get_digest() to compute the checksum and return it either - * as a string in hexadecimal form, or as a raw sequence of bytes. To - * compute the checksum for binary blobs and NUL-terminated strings in - * one go, use the convenience functions g_compute_checksum_for_data() - * and g_compute_checksum_for_string(), respectively. + * To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free + * a `GChecksum`, use [method@GLib.Checksum.free]. * - * Support for checksums has been added in GLib 2.16 + * GLib supports incremental checksums using the `GChecksum` data + * structure, by calling [method@GLib.Checksum.update] as long as there’s data + * available and then using [method@GLib.Checksum.get_string] or + * [method@GLib.Checksum.get_digest] to compute the checksum and return it + * either as a string in hexadecimal form, or as a raw sequence of bytes. To + * compute the checksum for binary blobs and nul-terminated strings in + * one go, use the convenience functions [func@GLib.compute_checksum_for_data] + * and [func@GLib.compute_checksum_for_string], respectively. + * + * Since: 2.16 **/ #define IS_VALID_TYPE(type) ((type) >= G_CHECKSUM_MD5 && (type) <= G_CHECKSUM_SHA384) diff --git a/glib/gchecksum.h b/glib/gchecksum.h index e5c54e7c7..3dd84fd84 100644 --- a/glib/gchecksum.h +++ b/glib/gchecksum.h @@ -54,16 +54,6 @@ typedef enum { G_CHECKSUM_SHA384 } GChecksumType; -/** - * GChecksum: - * - * An opaque structure representing a checksumming operation. - * - * To create a new GChecksum, use g_checksum_new(). To free - * a GChecksum, use g_checksum_free(). - * - * Since: 2.16 - */ typedef struct _GChecksum GChecksum; GLIB_AVAILABLE_IN_ALL