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

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

See merge request GNOME/glib!3690

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",

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)

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.
+

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
+ * The `GDBusObject` type is the base type for D-Bus objects on both
- * using the following functions.
+ * 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;

gio/gremoteactiongroup.c

@@ -27,43 +27,33 @@
 #include "gaction.h"
 
 /**
- * SECTION:gremoteactiongroup
+ * GRemoteActionGroup:
- * @title: GRemoteActionGroup
- * @short_description: A GActionGroup that interacts with other processes
- * @include: gio/gio.h
  *
- * 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:
+ * methods on [iface@Gio.ActionGroup] used to activate actions:
- * g_action_group_activate_action() and
+ * [method@Gio.ActionGroup.activate_action] and
- * g_action_group_change_action_state(). These variants allow a
+ * [method@Gio.ActionGroup.change_action_state]. These variants allow a
- * "platform data" #GVariant to be specified: a dictionary providing
+ * ‘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
+ * Additionally, [method@Gio.DBusConnection.export_action_group] will check if
- * the exported #GActionGroup implements #GRemoteActionGroup and use the
+ * the exported [iface@Gio.ActionGroup] implements `GRemoteActionGroup` and use
- * `_full` variants of the calls if available.  This
+ * 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()

gio/gsettings.c

@@ -37,116 +37,115 @@
 #include "strinfo.c"
 
 /**
- * SECTION:gsettings
+ * GSettings:
- * @short_description: High-level API for application settings
- * @include: gio/gio.h
  *
- * 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
+ * [struct@GLib.HashTable] lookup.  Writing settings is also extremely fast in
- * of time to return to your application, but can be extremely expensive
+ * 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
+ * made during startup — for example, when setting the initial value
- * of preferences widgets.  The built-in g_settings_bind() functionality
+ * of preferences widgets.  The built-in [method@Gio.Settings.bind]
- * is careful not to write settings in response to notify signals as a
+ * functionality is careful not to write settings in response to notify signals
- * result of modifications that it makes to widgets.
+ * 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/".
+ * `/org/gtk/settings/file-chooser/` and `/ca/desrt/dconf-editor/`.
- * Paths should not start with "/apps/", "/desktop/" or "/system/" as
+ * 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
+ * values as [struct@GLib.Variant], and allows any [type@GLib.VariantType] for
- * are restricted to lowercase characters, numbers and '-'. Furthermore,
+ * keys. Key names are restricted to lowercase characters, numbers and `-`.
- * the names must begin with a lowercase character, must not end
+ * Furthermore, the names must begin with a lowercase character, must not end
- * with a '-', and must not contain consecutive dashes.
+ * 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 <schemalist> or <schema>
+ * `gettext-domain` attribute of the `<schemalist>` or `<schema>`
  * elements and the category that is specified in the `l10n` attribute of
- * the <default> element. The string which is translated includes all text in
+ * the `<default>` element. The string which is translated includes all text in
- * the <default> element, including any surrounding quotation marks.
+ * the `<default>` 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 <default> element — it is recommended to
+ * XML comment immediately above the `<default>` 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 <default> element to disambiguate multiple
+ * attribute can be set on the `<default>` element to disambiguate multiple
  * defaults which use the same string.
  *
  * For example:
- * |[
+ * ```xml
  *  <!-- Translators: A list of words which are not allowed to be typed, in
  *       GVariant serialization syntax.
  *       See: https://developer.gnome.org/glib/stable/gvariant-text.html -->
  *  <default l10n='messages' context='Banned words'>['bad', 'words']</default>
- * ]|
+ * ```
  *
  * Translations of default values must remain syntactically valid serialized
- * #GVariants (e.g. retaining any surrounding quotation marks) or runtime
+ * [struct@GLib.Variant]s (e.g. retaining any surrounding quotation marks) or
- * errors will occur.
+ * 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
+ * At runtime, schemas are identified by their ID (as specified in the
- * id attribute of the <schema> element). The convention for schema
+ * `id` attribute of the `<schema>` element). The convention for schema
- * ids is to use a dotted name, similar in style to a D-Bus bus name,
+ * 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
+ * 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
+ * and schema ID should match. For schemas which deal with settings not
- * associated with one named application, the id should not use
+ * associated with one named application, the ID should not use
- * StudlyCaps, e.g. "org.gnome.font-rendering".
+ * StudlyCaps, e.g. `org.gnome.font-rendering`.
  *
- * In addition to #GVariant types, keys can have types that have
+ * In addition to [struct@GLib.Variant] types, keys can have types that have
- * enumerated types. These can be described by a <choice>,
+ * enumerated types. These can be described by a `<choice>`,
- * <enum> or <flags> element, as seen in the
+ * `<enum>` or `<flags>` element, as seen in the
- * [example][schema-enumerated]. The underlying type of such a key
+ * second example below. The underlying type of such a key
- * is string, but you can use g_settings_get_enum(), g_settings_set_enum(),
+ * is string, but you can use [method@Gio.Settings.get_enum],
- * g_settings_get_flags(), g_settings_set_flags() access the numeric values
+ * [method@Gio.Settings.set_enum], [method@Gio.Settings.get_flags],
- * corresponding to the string value of enum and flags keys.
+ * [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
  * <schemalist>
  *   <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
  *
@@ -169,10 +168,10 @@
  *
  *   </schema>
  * </schemalist>
- * ]|
+ * ```
  *
  * An example for ranges, choices and enumerated types:
- * |[
+ * ```xml
  * <schemalist>
  *
  *   <enum id="org.gtk.Test.myenum">
@@ -215,7 +214,7 @@
  *     </key>
  *   </schema>
  * </schemalist>
- * ]|
+ * ```
  *
  * ## 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
+ * [`glib-compile-schemas`](glib-compile-schemas.html) reads so-called ‘vendor
- * override' files. These are keyfiles in the same directory as the XML
+ * override’ files. These are keyfiles in the same directory as the XML
- * schema sources which can override default values. The schema id serves
+ * 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:
+ * 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
+ * A very convenient feature of GSettings lets you bind [class@GObject.Object]
- * directly to settings, using g_settings_bind(). Once a GObject property
+ * properties directly to settings, using [method@Gio.Settings.bind]. Once a
- * has been bound to a setting, changes on either side are automatically
+ * [class@GObject.Object] property has been bound to a setting, changes on
- * propagated to the other side. GSettings handles details like mapping
+ * either side are automatically propagated to the other side. GSettings handles
- * between GObject and GVariant types, and preventing infinite cycles.
+ * 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
+ * If this ‘magic’ gets in the way, it can be suppressed with the
- * %G_SETTINGS_BIND_NO_SENSITIVITY flag.
+ * `G_SETTINGS_BIND_NO_SENSITIVITY` flag.
  *
- * ## Relocatable schemas # {#gsettings-relocatable}
+ * ## Relocatable schemas
  *
  * A relocatable schema is one with no `path` attribute specified on its
- * <schema> element. By using g_settings_new_with_path(), a #GSettings object
+ * `<schema>` element. By using [ctor@Gio.Settings.new_with_path], a `GSettings`
- * can be instantiated for a relocatable schema, assigning a path to the
+ * 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
+ * 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 <child> elements in the parent schema, e.g.:
+ * they can be specified as `<child>` elements in the parent schema, e.g.:
- * |[
+ * ```xml
  * <schema id="org.foo.MyApp" path="/org/foo/MyApp/">
  *   <child name="main" schema="org.foo.MyApp.Window"/>
  * </schema>
- * ]|
+ * ```
  *
- * ## 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 <summary> and
+ * GSettings will use gettext to look up translations for the `<summary>` and
- * <description> elements, and also any <default> elements which have a `l10n`
+ * `<description>` elements, and also any `<default>` elements which have a
- * attribute set. Translations must not be included in the `.gschema.xml` file
+ * `l10n` attribute set. Translations must not be included in the `.gschema.xml`
- * by the build system, for example by using intltool XML rules with a
+ * 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 <enum> element in the
+ * schema, it can either be defined manually using an `<enum>` 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... */

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
+ * GSettingsBackend:
- * @title: GSettingsBackend
- * @short_description: Interface for settings backend implementations
- * @include: gio/gsettingsbackend.h
- * @see_also: #GSettings, #GIOExtensionPoint
  *
- * 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
+ * an alternative storage backend for [class@Gio.Settings], you need to
- * the #GSettingsBackend interface and then make it implement the
+ * implement the `GSettingsBackend` interface and then make it implement the
- * extension point %G_SETTINGS_BACKEND_EXTENSION_POINT_NAME.
+ * 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.
+ * Some of the `GSettingsBackend` functions accept or return a
- * These trees always have strings as keys and #GVariant as values.
+ * [struct@GLib.Tree]. These trees always have strings as keys and
- * g_settings_backend_create_tree() is a convenience function to create
+ * [struct@GLib.Variant] as values.
- * suitable trees.
  *
- * 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`.
  **/
 

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;
 

gio/gsettingsschema.c

@@ -38,12 +38,9 @@
 #endif
 
 /**
- * SECTION:gsettingsschema
+ * GSettingsSchema:
- * @short_description: Introspecting and controlling the loading
- *     of GSettings schemas
- * @include: gio/gio.h
  *
- * 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
+ * [struct@Gio.SettingsSchemaSource] provides a mechanism for dealing with this
- * allowing the creation of a new 'schema source' from which schemas can
+ * 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:
  *
- * |[<!-- language="C" -->
+ * ```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:
  *
- * |[<!-- language="C" -->
+ * ```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;

gio/gsimpleproxyresolver.c

@@ -33,19 +33,16 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gsimpleproxyresolver
+ * GSimpleProxyResolver:
- * @short_description: Simple proxy resolver implementation
- * @include: gio/gio.h
- * @see_also: g_socket_client_set_proxy_resolver()
  *
- * #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
  */

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;

gio/gsocketaddressenumerator.c

@@ -25,23 +25,22 @@
 #include "gtask.h"
 
 /**
- * SECTION:gsocketaddressenumerator
+ * GSocketAddressEnumerator:
- * @short_description: Enumerator for socket addresses
- * @include: gio/gio.h
  *
- * #GSocketAddressEnumerator is an enumerator type for #GSocketAddress
+ * `GSocketAddressEnumerator` is an enumerator type for
- * instances. It is returned by enumeration functions such as
+ * [class@Gio.SocketAddress] instances. It is returned by enumeration functions
- * g_socket_connectable_enumerate(), which returns a #GSocketAddressEnumerator
+ * such as [method@Gio.SocketConnectable.enumerate], which returns a
- * to list each #GSocketAddress which could be used to connect to that
+ * `GSocketAddressEnumerator` to list each [class@Gio.SocketAddress] which could
- * #GSocketConnectable.
+ * 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
+ * [method@Gio.SocketAddressEnumerator.next_async] and
- * g_socket_address_enumerator_next_finish() should be used where possible.
+ * [method@Gio.SocketAddressEnumerator.next_finish] should be used where
+ * possible.
  *
- * Each #GSocketAddressEnumerator can only be enumerated once. Once
+ * Each `GSocketAddressEnumerator` can only be enumerated once. Once
- * g_socket_address_enumerator_next() has returned %NULL, further
+ * [method@Gio.SocketAddressEnumerator.next] has returned `NULL`, further
- * enumeration with that #GSocketAddressEnumerator is not possible, and it can
+ * enumeration with that `GSocketAddressEnumerator` is not possible, and it can
  * be unreffed.
  */
 

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

gio/gsocketlistener.c

@@ -42,26 +42,23 @@
 
 
 /**
- * SECTION:gsocketlistener
+ * GSocketListener:
- * @title: GSocketListener
- * @short_description: Helper for accepting network client connections
- * @include: gio/gio.h
- * @see_also: #GThreadedSocketService, #GSocketService.
  *
- * 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()
+ * Add addresses and ports to listen on using
- * and g_socket_listener_add_inet_port(). These will be listened on until
+ * [method@Gio.SocketListener.add_address] and
- * g_socket_listener_close() is called. Dropping your final reference to the
+ * [method@Gio.SocketListener.add_inet_port]. These will be listened on until
- * #GSocketListener will not cause g_socket_listener_close() to be called
+ * [method@Gio.SocketListener.close] is called. Dropping your final reference to
- * implicitly, as some references to the #GSocketListener may be held
+ * 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
+ * If you want to implement a network server, also look at
- * and #GThreadedSocketService which are subclasses of #GSocketListener
+ * [class@Gio.SocketService] and [class@Gio.ThreadedSocketService] which are
- * that make this even easier.
+ * subclasses of `GSocketListener` that make this even easier.
  *
  * Since: 2.22
  */

gio/gsocketservice.c

@@ -23,37 +23,33 @@
  */
 
 /**
- * SECTION:gsocketservice
+ * GSocketService:
- * @title: GSocketService
- * @short_description: Make it easy to implement a network service
- * @include: gio/gio.h
- * @see_also: #GThreadedSocketService, #GSocketListener.
  *
- * 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
+ * `GSocketService`. The first is to create the service using
- * g_socket_service_new() and to connect to the #GSocketService::incoming
+ * [ctor@Gio.SocketService.new] and to connect to the
- * signal. The second is to subclass #GSocketService and override the
+ * [signal@Gio.SocketService::incoming] signal. The second is to subclass
- * default signal handler implementation.
+ * `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]
+ * thread-default context (see
- * of the thread it is created in, and is not
+ * [method@GLib.MainContext.push_thread_default_context]) of the thread it is
- * threadsafe in general. However, the calls to start and stop the
+ * created in, and is not threadsafe in general. However, the calls to start and
- * service are thread-safe so these can be used from threads that
+ * stop the service are thread-safe so these can be used from threads that
  * handle incoming clients.
  *
  * Since: 2.22

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

gio/gtlscertificate.c

@@ -29,25 +29,13 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gtlscertificate
+ * GTlsCertificate:
- * @title: GTlsCertificate
- * @short_description: TLS certificate
- * @include: gio/gio.h
- * @see_also: #GTlsConnection
  *
  * 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).
+ * [iface@Gio.TlsServerConnection]).
- *
- * Since: 2.28
- */
-
-/**
- * GTlsCertificate:
- *
- * Abstract base class for TLS certificate types.
  *
  * Since: 2.28
  */

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
+ * `GTlsClientConnection` is the client-side subclass of
- * type.
+ * [class@Gio.TlsConnection], representing a client-side TLS connection.
  *
  * Since: 2.28
  */

gio/gtlsdatabase.c

@@ -33,27 +33,17 @@
 #include "gtlsinteraction.h"
 
 /**
- * SECTION:gtlsdatabase
+ * GTlsDatabase:
- * @short_description: TLS database type
- * @include: gio/gio.h
  *
- * #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.
+ * `GTlsDatabase`. It is used internally by [class@Gio.TlsConnection].
- *
- * Since: 2.30
- */
-
-/**
- * GTlsDatabase:
- *
- * Abstract base class for the backend-specific database types.
  *
  * Since: 2.30
  */

gio/gtlsserverconnection.c

@@ -30,12 +30,10 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gtlsserverconnection
+ * GTlsServerConnection:
- * @short_description: TLS server-side connection
- * @include: gio/gio.h
  *
- * #GTlsServerConnection is the server-side subclass of #GTlsConnection,
+ * `GTlsServerConnection` is the server-side subclass of
- * representing a server-side TLS connection.
+ * [class@Gio.TlsConnection], representing a server-side TLS connection.
  *
  * Since: 2.28
  */

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

gio/gunixconnection.c

@@ -31,19 +31,15 @@
 #endif
 
 /**
- * SECTION:gunixconnection
+ * GUnixConnection:
- * @title: GUnixConnection
- * @short_description: A UNIX domain GSocketConnection
- * @include: gio/gunixconnection.h
- * @see_also: #GSocketConnection.
  *
- * 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, `<gio/gunixconnection.h>` 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,

gio/gunixcredentialsmessage.c

@@ -16,31 +16,29 @@
  */
 
 /**
- * SECTION:gunixcredentialsmessage
+ * GUnixCredentialsMessage:
- * @title: GUnixCredentialsMessage
- * @short_description: A GSocketControlMessage containing credentials
- * @include: gio/gunixcredentialsmessage.h
- * @see_also: #GUnixConnection, #GSocketControlMessage
  *
- * This #GSocketControlMessage contains a #GCredentials instance.  It
+ * This [class@Gio.SocketControlMessage] contains a [class@Gio.Credentials]
- * may be sent using g_socket_send_message() and received using
+ * instance.  It may be sent using [method@Gio.Socket.send_message] and received
- * g_socket_receive_message() over UNIX sockets (ie: sockets in the
+ * using [method@Gio.Socket.receive_message] over UNIX sockets (ie: sockets in
- * %G_SOCKET_FAMILY_UNIX family).
+ * 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
+ * [method@Gio.UnixConnection.send_credentials] and
- * g_unix_connection_receive_credentials(). To receive credentials of
+ * [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, `<gio/gunixcredentialsmessage.h>` 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"

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;

gio/gunixinputstream.c

@@ -39,14 +39,11 @@
 
 
 /**
- * SECTION:gunixinputstream
+ * GUnixInputStream:
- * @short_description: Streaming input operations for UNIX file descriptors
- * @include: gio/gunixinputstream.h
- * @see_also: #GInputStream
  *
- * #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.)
  *

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;

gio/gunixoutputstream.c

@@ -41,14 +41,11 @@
 
 
 /**
- * SECTION:gunixoutputstream
+ * GUnixOutputStream:
- * @short_description: Streaming output operations for UNIX file descriptors
- * @include: gio/gunixoutputstream.h
- * @see_also: #GOutputStream
  *
- * #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.)
  *

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;

gio/gunixsocketaddress.c

@@ -35,22 +35,21 @@
 #endif
 
 /**
- * SECTION:gunixsocketaddress
+ * GUnixSocketAddress:
- * @short_description: UNIX GSocketAddress
- * @include: gio/gunixsocketaddress.h
  *
- * 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
+ * systems, function calls may return `G_IO_ERROR_NOT_SUPPORTED`
- * errors. You can use g_unix_socket_address_abstract_names_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,

gio/gvolume.c

@@ -32,51 +32,49 @@
 
 
 /**
- * SECTION:gvolume
+ * GVolume:
- * @short_description: Volume management
- * @include: gio/gio.h
  * 
- * The #GVolume interface represents user-visible objects that can be
+ * The `GVolume` interface represents user-visible objects that can be
- * mounted. Note, when porting from GnomeVFS, #GVolume is the moral
+ * mounted. Note, when [porting from GnomeVFS](migrating-gnome-vfs.html),
- * equivalent of #GnomeVFSDrive.
+ * `GVolume` is the moral equivalent of `GnomeVFSDrive`.
  *
- * Mounting a #GVolume instance is an asynchronous operation. For more
+ * Mounting a `GVolume` instance is an asynchronous operation. For more
- * information about asynchronous operations, see #GAsyncResult and
+ * information about asynchronous operations, see [class@Gio.AsyncResult] and
- * #GTask. To mount a #GVolume, first call g_volume_mount() with (at
+ * [class@Gio.Task]. To mount a `GVolume`, first call [method@Gio.Volume.mount]
- * least) the #GVolume instance, optionally a #GMountOperation object
+ * with (at least) the `GVolume` instance, optionally a
- * and a #GAsyncReadyCallback.
+ * [class@Gio.MountOperation] object and a [type@Gio.AsyncReadyCallback].
  *
- * Typically, one will only want to pass %NULL for the
+ * Typically, one will only want to pass `NULL` for the
- * #GMountOperation if automounting all volumes when a desktop session
+ * [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
+ * 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
+ * [method@Gio.Volume.mount_finish] with the `GVolume` instance and the
- * #GAsyncResult data to see if the operation was completed
+ * [class@Gio.AsyncResult] data to see if the operation was completed
- * successfully.  If an @error is present when g_volume_mount_finish()
+ * successfully.  If a [type@GLib.Error] is present when
- * is called, then it will be filled with any error information.
+ * [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 command line). For this purpose, GIO
- * allows to obtain an 'identifier' for the volume. There can be
+ * 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.
+ * `G_VOLUME_IDENTIFIER_KIND_UUID`, `G_VOLUME_IDENTIFIER_KIND_LABEL`, etc.
- * Use g_volume_get_identifier() to obtain an identifier for a volume.
+ * 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
- * Note that %G_VOLUME_IDENTIFIER_KIND_HAL_UDI will only be available
+ * when the GVFS hal volume monitor is in use. Other volume monitors
- * 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`
- * 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

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.

gio/gvolumemonitor.c

@@ -32,19 +32,16 @@
 
 
 /**
- * SECTION:gvolumemonitor
+ * GVolumeMonitor:
- * @short_description: Volume Monitor
- * @include: gio/gio.h
- * @see_also: #GFileMonitor
  * 
- * #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.
  *
- * #GVolumeMonitor is not
+ * `GVolumeMonitor` is not
- * [thread-default-context aware][g-main-context-push-thread-default],
+ * thread-default-context aware (see
- * and so should not be used other than from the main thread, with no
+ * [method@GLib.MainContext.push_thread_default]), and so should not be used
- * thread-default-context active.
+ * 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.

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

gio/gwin32inputstream.c

@@ -36,12 +36,9 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gwin32inputstream
+ * GWin32InputStream:
- * @short_description: Streaming input operations for Windows file handles
- * @include: gio/gwin32inputstream.h
- * @see_also: #GInputStream
  *
- * #GWin32InputStream implements #GInputStream for reading from a
+ * `GWin32InputStream` implements [class@Gio.InputStream] for reading from a
  * Windows file handle.
  *
  * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO

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;

gio/gwin32outputstream.c

@@ -37,12 +37,9 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gwin32outputstream
+ * GWin32OutputStream:
- * @short_description: Streaming output operations for Windows file handles
- * @include: gio/gwin32outputstream.h
- * @see_also: #GOutputStream
  *
- * #GWin32OutputStream implements #GOutputStream for writing to a
+ * `GWin32OutputStream` implements [class@Gio.OutputStream] for writing to a
  * Windows file handle.
  *
  * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO

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;

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
+ * GWin32RegistryKey:
- * @title: GWin32RegistryKey
- * @short_description: W32 registry access helper
- * @include: gio/win32/gwin32registrykey.h
  *
- * #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
+ * `GWin32RegistryKey` implements the [iface@Gio.Initable] interface, so if it
- * constructed by e.g. g_object_new() you must call g_initable_init() and check
+ * is manually constructed by e.g. [ctor@GObject.Object.new] you must call
- * the results before using the object. This is done automatically
+ * [method@Gio.Initable.init] and check the results before using the object.
- * in g_win32_registry_key_new() and g_win32_registry_key_get_child(), so these
+ * This is done automatically in [ctor@Gio.Win32RegistryKey.new] and
- * functions can return %NULL.
+ * [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
+ * All functions operate in the current user’s context (it is not possible to
- * access registry tree of a different user).
+ * access the registry tree of a different user).
  *
- * Key paths must use '\\' as a separator, '/' is not supported. Key names
+ * Key paths must use `\\` as a separator, `/` is not supported. Key names
- * must not include '\\', because it's used as a separator. Value names
+ * must not include `\\`, because it’s used as a separator. Value names
- * can include '\\'.
+ * can include `\\`.
  *
  * Key and value names are not case sensitive.
  *
- * Full key name (excluding the pre-defined ancestor's name) can't exceed
+ * A 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
+ * 255 UTF-16 characters, give or take. A value name can’t exceed 16383 UTF-16
  * characters. Tree depth is limited to 512 levels.
  **/
 

gio/gzlibcompressor.c

@@ -43,21 +43,14 @@ enum {
 };
 
 /**
- * SECTION:gzlibcompressor
+ * GZlibCompressor:
- * @short_description: Zlib compressor
- * @include: gio/gio.h
  *
- * #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;

gio/gzlibdecompressor.c

@@ -42,11 +42,9 @@ enum {
 };
 
 /**
- * SECTION:gzlibdecompressor
+ * GZlibDecompressor:
- * @short_description: Zlib decompressor
- * @include: gio/gio.h
  *
- * #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;

glib/gchecksum.c

@@ -33,25 +33,26 @@
 
 
 /**
- * SECTION:checksum
+ * GChecksum:
- * @title: Data Checksums
- * @short_description: computes the checksum for data
  *
- * 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
+ * To create a new `GChecksum`, use [ctor@GLib.Checksum.new]. To free
- * structure, by calling g_checksum_update() as long as there's data
+ * a `GChecksum`, use [method@GLib.Checksum.free].
- * 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.
  *
- * 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)

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