Update glib annotations from git master

4 files changed, 4993 insertions, 5312 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index d19178b2..d3f9c581 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -219,6 +219,62 @@
 
 
 /**
+ * GApplication::handle-local-options:
+ * @application: the application
+ * @options: the options dictionary
+ *
+ * The ::handle-local-options signal is emitted on the local instance
+ * after the parsing of the commandline options has occurred.
+ *
+ * You can add options to be recognised during commandline option
+ * parsing using g_application_add_main_option_entries() and
+ * g_application_add_option_group().
+ *
+ * Signal handlers can inspect @options (along with values pointed to
+ * from the @arg_data of an installed #GOptionEntrys) in order to
+ * decide to perform certain actions, including direct local handling
+ * (which may be useful for options like --version).
+ *
+ * If the options have been "handled" then a non-negative value should
+ * be returned.   In this case, the return value is the exit status: 0
+ * for success and a positive value for failure.  -1 means to continue
+ * normal processing.
+ *
+ * In the event that the application is marked
+ * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
+ * send the @option dictionary to the primary instance where it can be
+ * read with g_application_command_line_get_options().  The signal
+ * handler can modify the dictionary before returning, and the
+ * modified dictionary will be sent.
+ *
+ * In the event that %G_APPLICATION_HANDLES_COMMAND_LINE is not set,
+ * "normal processing" will treat the remaining uncollected command
+ * line arguments as filenames or URIs.  If there are no arguments,
+ * the application is activated by g_application_activate().  One or
+ * more arguments results in a call to g_application_open().
+ *
+ * If you want to handle the local commandline arguments for yourself
+ * by converting them to calls to g_application_open() or
+ * g_action_group_activate_action() then you must be sure to register
+ * the application first.  You should probably not call
+ * g_application_activate() for yourself, however: just return -1 and
+ * allow the default handler to do it for you.  This will ensure that
+ * the <literal>--gapplication-service</literal> switch works properly
+ * (ie: no activation in that case).
+ *
+ * Note that this signal is emitted from the default implementation of
+ * local_command_line().  If you override that function and don't
+ * chain up then this signal will never be emitted.
+ *
+ * You can override local_command_line() if you need more powerful
+ * capabilities than what is provided here, but this should not
+ * normally be required.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * GApplication::open:
  * @application: the application
  * @files: (array length=n_files) (element-type GFile): an array of #GFiles
@@ -297,8 +353,8 @@
 /**
  * GApplicationCommandLineClass:
  *
- * The <structname>GApplicationCommandLineClass</structname> structure
- * contains private data only
+ * The #GApplicationCommandLineClass-struct
+ * contains private data only.
  *
  * Since: 2.28
  */
@@ -324,16 +380,14 @@
  *
  * Note that disconnecting from this signal (or any signal) in a
  * multi-threaded program is prone to race conditions. For instance
- * it is possible that a signal handler may be invoked even
- * <emphasis>after</emphasis> a call to
- * g_signal_handler_disconnect() for that handler has already
- * returned.
+ * it is possible that a signal handler may be invoked even after
+ * a call to g_signal_handler_disconnect() for that handler has
+ * already returned.
  *
- * There is also a problem when cancellation happen
- * right before connecting to the signal. If this happens the
- * signal will unexpectedly not be emitted, and checking before
- * connecting to the signal leaves a race condition where this is
- * still happening.
+ * There is also a problem when cancellation happens right before
+ * connecting to the signal. If this happens the signal will
+ * unexpectedly not be emitted, and checking before connecting to
+ * the signal leaves a race condition where this is still happening.
  *
  * In order to make it safe and easy to connect handlers there
  * are two helper functions: g_cancellable_connect() and
@@ -341,13 +395,14 @@
  * like this.
  *
  * An example of how to us this:
- * |[
- *     /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
+ * |[<!-- language="C" -->
+ *     /&ast; Make sure we don't do unnecessary work if already cancelled &ast;/
  *     if (g_cancellable_set_error_if_cancelled (cancellable, error))
  *       return;
  *
- *     /<!-- -->* Set up all the data needed to be able to
- *      * handle cancellation of the operation *<!-- -->/
+ *     /&ast; Set up all the data needed to be able to
+ *      &ast; handle cancellation of the operation
+ *      &ast;/
  *     my_data = my_data_new (...);
  *
  *     id = 0;
@@ -356,12 +411,13 @@
  *     			      G_CALLBACK (cancelled_handler)
  *     			      data, NULL);
  *
- *     /<!-- -->* cancellable operation here... *<!-- -->/
+ *     /&ast; cancellable operation here... &ast;/
  *
  *     g_cancellable_disconnect (cancellable, id);
  *
- *     /<!-- -->* cancelled_handler is never called after this, it
- *      * is now safe to free the data *<!-- -->/
+ *     /&ast; cancelled_handler is never called after this,
+ *      &ast; it is now safe to free the data
+ *      &ast;/
  *     my_data_free (my_data);
  * ]|
  *
@@ -421,7 +477,7 @@
 /**
  * GDBusAuthObserver::allow-mechanism:
  * @observer: The #GDBusAuthObserver emitting the signal.
- * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
+ * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
  *
  * Emitted to check if @mechanism is allowed to be used.
  *
@@ -466,29 +522,23 @@
 
 /**
  * GDBusConnection::closed:
- * @connection: The #GDBusConnection emitting the signal.
+ * @connection: the #GDBusConnection emitting the signal
  * @remote_peer_vanished: %TRUE if @connection is closed because the
- * remote peer closed its end of the connection.
- * @error: (allow-none): A #GError with more details about the event or %NULL.
+ *     remote peer closed its end of the connection
+ * @error: (allow-none): a #GError with more details about the event or %NULL
  *
  * Emitted when the connection is closed.
  *
  * The cause of this event can be
- * <itemizedlist>
- * <listitem><para>
- *    If g_dbus_connection_close() is called. In this case
- *    @remote_peer_vanished is set to %FALSE and @error is %NULL.
- * </para></listitem>
- * <listitem><para>
- *    If the remote peer closes the connection. In this case
- *    @remote_peer_vanished is set to %TRUE and @error is set.
- * </para></listitem>
- * <listitem><para>
- *    If the remote peer sends invalid or malformed data. In this
- *    case @remote_peer_vanished is set to %FALSE and @error
- *    is set.
- * </para></listitem>
- * </itemizedlist>
+ *
+ * - If g_dbus_connection_close() is called. In this case
+ *   @remote_peer_vanished is set to %FALSE and @error is %NULL.
+ *
+ * - If the remote peer closes the connection. In this case
+ *   @remote_peer_vanished is set to %TRUE and @error is set.
+ *
+ * - If the remote peer sends invalid or malformed data. In this
+ *   case @remote_peer_vanished is set to %FALSE and @error is set.
  *
  * Upon receiving this signal, you should give up your reference to
  * @connection. You are guaranteed that this signal is emitted only
@@ -540,11 +590,11 @@
  * GDBusConnection:exit-on-close:
  *
  * A boolean specifying whether the process will be terminated (by
- * calling <literal>raise(SIGTERM)</literal>) if the connection
- * is closed by the remote peer.
+ * calling `raise(SIGTERM)`) if the connection is closed by the
+ * remote peer.
  *
- * Note that #GDBusConnection objects returned by g_bus_get_finish() and
- * g_bus_get_sync() will (usually) have this property set to %TRUE.
+ * Note that #GDBusConnection objects returned by g_bus_get_finish()
+ * and g_bus_get_sync() will (usually) have this property set to %TRUE.
  *
  * Since: 2.26
  */
@@ -635,11 +685,11 @@
  *
  * Note that this signal is emitted in a thread dedicated to
  * handling the method call so handlers are allowed to perform
- * blocking IO. This means that it is appropriate to call
- * e.g. <ulink
- * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync">polkit_authority_check_authorization_sync()</ulink>
- * with the <ulink
- * url="http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS">POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION</ulink> flag set.
+ * blocking IO. This means that it is appropriate to call e.g.
+ * [polkit_authority_check_authorization_sync()](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#polkit-authority-check-authorization-sync)
+ * with the
+ * [POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION](http://hal.freedesktop.org/docs/polkit/PolkitAuthority.html#POLKIT-CHECK-AUTHORIZATION-FLAGS-ALLOW-USER-INTERACTION:CAPS)
+ * flag set.
  *
  * If %FALSE is returned then no further handlers are run and the
  * signal handler must take a reference to @invocation and finish
@@ -968,9 +1018,9 @@
  * Emitted when a method is invoked by a remote caller and used to
  * determine if the method call is authorized.
  *
- * This signal is like #GDBusInterfaceSkeleton<!-- -->'s
- * #GDBusInterfaceSkeleton::g-authorize-method signal, except that it is
- * for the enclosing object.
+ * This signal is like #GDBusInterfaceSkeleton's
+ * #GDBusInterfaceSkeleton::g-authorize-method signal,
+ * except that it is for the enclosing object.
  *
  * The default class handler just returns %TRUE.
  *
@@ -1004,8 +1054,8 @@
  * @invalidated_properties will always be empty.
  *
  * This signal corresponds to the
- * <literal>PropertiesChanged</literal> D-Bus signal on the
- * <literal>org.freedesktop.DBus.Properties</literal> interface.
+ * `PropertiesChanged` D-Bus signal on the
+ * `org.freedesktop.DBus.Properties` interface.
  *
  * Since: 2.26
  */
@@ -1076,27 +1126,23 @@
  * Ensure that interactions with this proxy conform to the given
  * interface. This is mainly to ensure that malformed data received
  * from the other peer is ignored. The given #GDBusInterfaceInfo is
- * said to be the <emphasis>expected interface</emphasis>.
+ * said to be the "expected interface".
  *
  * The checks performed are:
- * <itemizedlist>
- *   <listitem><para>
- *     When completing a method call, if the type signature of
- *     the reply message isn't what's expected, the reply is
- *     discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
- *   </para></listitem>
- *   <listitem><para>
- *     Received signals that have a type signature mismatch are dropped and
- *     a warning is logged via g_warning().
- *   </para></listitem>
- *   <listitem><para>
- *     Properties received via the initial <literal>GetAll()</literal> call
- *     or via the <literal>::PropertiesChanged</literal> signal (on the
- *     <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties">org.freedesktop.DBus.Properties</ulink> interface) or
- *     set using g_dbus_proxy_set_cached_property() with a type signature
- *     mismatch are ignored and a warning is logged via g_warning().
- *   </para></listitem>
- * </itemizedlist>
+ * - When completing a method call, if the type signature of
+ *   the reply message isn't what's expected, the reply is
+ *   discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
+ *
+ * - Received signals that have a type signature mismatch are dropped and
+ *   a warning is logged via g_warning().
+ *
+ * - Properties received via the initial `GetAll()` call or via the
+ *   `::PropertiesChanged` signal (on the
+ *   [org.freedesktop.DBus.Properties](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties)
+ *   interface) or set using g_dbus_proxy_set_cached_property()
+ *   with a type signature mismatch are ignored and a warning is
+ *   logged via g_warning().
+ *
  * Note that these checks are never done on methods, signals and
  * properties that are not referenced in the given
  * #GDBusInterfaceInfo, since extending a D-Bus interface on the
@@ -1493,15 +1539,15 @@
 /**
  * GInetSocketAddress:
  *
- * An IPv4 or IPv6 socket address, corresponding to a <type>struct
- * sockaddr_in</type> or <type>struct sockaddr_in6</type>.
+ * An IPv4 or IPv6 socket address, corresponding to a struct
+ * sockaddr_in or struct sockaddr_in6.
  */
 
 
 /**
  * GInetSocketAddress:flowinfo:
  *
- * The <literal>sin6_flowinfo</literal> field, for IPv6 addresses.
+ * The `sin6_flowinfo` field, for IPv6 addresses.
  *
  * Since: 2.32
  */
@@ -1510,7 +1556,7 @@
 /**
  * GInetSocketAddress:scope_id:
  *
- * The <literal>sin6_scope_id</literal> field, for IPv6 addresses.
+ * The `sin6_scope_id` field, for IPv6 addresses.
  *
  * Since: 2.32
  */
@@ -1870,10 +1916,9 @@
  * connected to a functioning router that has lost its own upstream
  * connectivity. Some hosts might only be accessible when a VPN is
  * active. Other hosts might only be accessible when the VPN is
- * <emphasis>not</emphasis> active. Thus, it is best to use
- * g_network_monitor_can_reach() or
- * g_network_monitor_can_reach_async() to test for reachability on a
- * host-by-host basis. (On the other hand, when the property is
+ * not active. Thus, it is best to use g_network_monitor_can_reach()
+ * or g_network_monitor_can_reach_async() to test for reachability
+ * on a host-by-host basis. (On the other hand, when the property is
  * %FALSE, the application can reasonably expect that no remote
  * hosts at all are reachable, and should indicate this to the user
  * in its UI.)
@@ -2097,7 +2142,7 @@
  * GSettings::change-event:
  * @settings: the object on which the signal was emitted
  * @keys: (array length=n_keys) (element-type GQuark) (allow-none):
- *        an array of #GQuark<!-- -->s for the changed keys, or %NULL
+ *        an array of #GQuarks for the changed keys, or %NULL
  * @n_keys: the length of the @keys array, or 0
  *
  * The "change-event" signal is emitted once per change event that
@@ -2304,13 +2349,12 @@
  *
  * If no handler is connected to this signal then the default
  * behaviour is to call g_simple_action_set_state() to set the state
- * to the requested value.  If you connect a signal handler then no
- * default action is taken.  If the state should change then you must
+ * to the requested value. If you connect a signal handler then no
+ * default action is taken. If the state should change then you must
  * call g_simple_action_set_state() from the handler.
  *
- * <example>
- * <title>Example 'change-state' handler</title>
- * <programlisting>
+ * An example of a 'change-state' handler:
+ * |[<!-- language="C" -->
  * static void
  * change_volume_state (GSimpleAction *action,
  *                      GVariant      *value,
@@ -2320,15 +2364,14 @@
  *
  *   requested = g_variant_get_int32 (value);
  *
- *   // Volume only goes from 0 to 10
+ *   /&ast; Volume only goes from 0 to 10 &ast;/
  *   if (0 <= requested && requested <= 10)
  *     g_simple_action_set_state (action, value);
  * }
- * </programlisting>
- * </example>
+ * ]|
  *
- * The handler need not set the state to the requested value.  It
- * could set it to any value at all, or take some other action.
+ * The handler need not set the state to the requested value.
+ * It could set it to any value at all, or take some other action.
  *
  * Since: 2.30
  */
@@ -2349,7 +2392,7 @@
 /**
  * GSimpleAction:name:
  *
- * The name of the action.  This is mostly meaningful for identifying
+ * The name of the action. This is mostly meaningful for identifying
  * the action once it has been added to a #GSimpleActionGroup.
  *
  * Since: 2.28
@@ -2401,10 +2444,8 @@
  * of the schemes set with g_simple_proxy_resolver_set_uri_proxy().
  *
  * Note that as a special case, if this URI starts with
- * "<literal>socks://</literal>", #GSimpleProxyResolver will treat
- * it as referring to all three of the <literal>socks5</literal>,
- * <literal>socks4a</literal>, and <literal>socks4</literal> proxy
- * types.
+ * "socks://", #GSimpleProxyResolver will treat it as referring
+ * to all three of the socks5, socks4a, and socks4 proxy types.
  */
 
 
@@ -2416,32 +2457,21 @@
  *
  * Entries can be in one of 4 formats:
  *
- * <itemizedlist>
- *   <listitem>
- *     A hostname, such as "<literal>example.com</literal>",
- *     "<literal>.example.com</literal>", or
- *     "<literal>*.example.com</literal>", any of which match
- *     "<literal>example.com</literal>" or any subdomain of it.
- *   </listitem>
- *   <listitem>
- *     An IPv4 or IPv6 address, such as
- *     "<literal>192.168.1.1</literal>", which matches only
- *     that address.
- *   </listitem>
- *   <listitem>
- *     A hostname or IP address followed by a port, such as
- *     "<literal>example.com:80</literal>", which matches whatever
- *     the hostname or IP address would match, but only for URLs
- *     with the (explicitly) indicated port. In the case of an IPv6
- *     address, the address part must appear in brackets:
- *     "<literal>[::1]:443</literal>"
- *   </listitem>
- *   <listitem>
- *     An IP address range, given by a base address and prefix length,
- *     such as "<literal>fe80::/10</literal>", which matches any
- *     address in that range.
- *   </listitem>
- * </itemizedlist>
+ * - A hostname, such as "example.com", ".example.com", or
+ *   "*.example.com", any of which match "example.com" or
+ *   any subdomain of it.
+ *
+ * - An IPv4 or IPv6 address, such as "192.168.1.1",
+ *   which matches only that address.
+ *
+ * - A hostname or IP address followed by a port, such as
+ *   "example.com:80", which matches whatever the hostname or IP
+ *   address would match, but only for URLs with the (explicitly)
+ *   indicated port. In the case of an IPv6 address, the address
+ *   part must appear in brackets: "[::1]:443"
+ *
+ * - An IP address range, given by a base address and prefix length,
+ *   such as "fe80::/10", which matches any address in that range.
  *
  * Note that when dealing with Unicode hostnames, the matching is
  * done against the ASCII form of the name.
@@ -2449,13 +2479,10 @@
  * Also note that hostname exclusions apply only to connections made
  * to hosts identified by name, and IP address exclusions apply only
  * to connections made to hosts identified by address. That is, if
- * <literal>example.com</literal> has an address of
- * <literal>192.168.1.1</literal>, and the :ignore-hosts list
- * contains only "<literal>192.168.1.1</literal>", then a connection
- * to "<literal>example.com</literal>" (eg, via a #GNetworkAddress)
- * will use the proxy, and a connection to
- * "<literal>192.168.1.1</literal>" (eg, via a #GInetSocketAddress)
- * will not.
+ * example.com has an address of 192.168.1.1, and the :ignore-hosts list
+ * contains only "192.168.1.1", then a connection to "example.com"
+ * (eg, via a #GNetworkAddress) will use the proxy, and a connection to
+ * "192.168.1.1" (eg, via a #GInetSocketAddress) will not.
  *
  * These rules match the "ignore-hosts"/"noproxy" rules most
  * commonly used by other applications.
@@ -2510,7 +2537,7 @@
 /**
  * GSocketAddress:
  *
- * A socket endpoint address, corresponding to <type>struct sockaddr</type>
+ * A socket endpoint address, corresponding to struct sockaddr
  * or one of its subtypes.
  */
 
@@ -2527,80 +2554,40 @@
  * information about a network connection in the UI. The meanings of
  * the different @event values are as follows:
  *
- * <variablelist>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_RESOLVING:</term>
- *     <listitem><para>
- *       @client is about to look up @connectable in DNS.
- *       @connection will be %NULL.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_RESOLVED:</term>
- *     <listitem><para>
- *       @client has successfully resolved @connectable in DNS.
- *       @connection will be %NULL.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_CONNECTING:</term>
- *     <listitem><para>
- *       @client is about to make a connection to a remote host;
- *       either a proxy server or the destination server itself.
- *       @connection is the #GSocketConnection, which is not yet
- *       connected.  Since GLib 2.40, you can access the remote
- *       address via g_socket_connection_get_remote_address().
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_CONNECTED:</term>
- *     <listitem><para>
- *       @client has successfully connected to a remote host.
- *       @connection is the connected #GSocketConnection.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
- *     <listitem><para>
- *       @client is about to negotiate with a proxy to get it to
- *       connect to @connectable. @connection is the
- *       #GSocketConnection to the proxy server.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
- *     <listitem><para>
- *       @client has negotiated a connection to @connectable through
- *       a proxy server. @connection is the stream returned from
- *       g_proxy_connect(), which may or may not be a
- *       #GSocketConnection.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
- *     <listitem><para>
- *       @client is about to begin a TLS handshake. @connection is a
- *       #GTlsClientConnection.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
- *     <listitem><para>
- *       @client has successfully completed the TLS handshake.
- *       @connection is a #GTlsClientConnection.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>%G_SOCKET_CLIENT_COMPLETE:</term>
- *     <listitem><para>
- *       @client has either successfully connected to @connectable
- *       (in which case @connection is the #GSocketConnection that
- *       it will be returning to the caller) or has failed (in which
- *       case @connection is %NULL and the client is about to return
- *       an error).
- *     </para></listitem>
- *   </varlistentry>
- * </variablelist>
+ * - %G_SOCKET_CLIENT_RESOLVING: @client is about to look up @connectable
+ *   in DNS. @connection will be %NULL.
+ *
+ * - %G_SOCKET_CLIENT_RESOLVED:  @client has successfully resolved
+ *   @connectable in DNS. @connection will be %NULL.
+ *
+ * - %G_SOCKET_CLIENT_CONNECTING: @client is about to make a connection
+ *   to a remote host; either a proxy server or the destination server
+ *   itself. @connection is the #GSocketConnection, which is not yet
+ *   connected.  Since GLib 2.40, you can access the remote
+ *   address via g_socket_connection_get_remote_address().
+ *
+ * - %G_SOCKET_CLIENT_CONNECTED: @client has successfully connected
+ *   to a remote host. @connection is the connected #GSocketConnection.
+ *
+ * - %G_SOCKET_CLIENT_PROXY_NEGOTIATING: @client is about to negotiate
+ *   with a proxy to get it to connect to @connectable. @connection is
+ *   the #GSocketConnection to the proxy server.
+ *
+ * - %G_SOCKET_CLIENT_PROXY_NEGOTIATED: @client has negotiated a
+ *   connection to @connectable through a proxy server. @connection is
+ *   the stream returned from g_proxy_connect(), which may or may not
+ *   be a #GSocketConnection.
+ *
+ * - %G_SOCKET_CLIENT_TLS_HANDSHAKING: @client is about to begin a TLS
+ *   handshake. @connection is a #GTlsClientConnection.
+ *
+ * - %G_SOCKET_CLIENT_TLS_HANDSHAKED: @client has successfully completed
+ *   the TLS handshake. @connection is a #GTlsClientConnection.
+ *
+ * - %G_SOCKET_CLIENT_COMPLETE: @client has either successfully connected
+ *   to @connectable (in which case @connection is the #GSocketConnection
+ *   that it will be returning to the caller) or has failed (in which
+ *   case @connection is %NULL and the client is about to return an error).
  *
  * Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
  * multiple times (or not at all) for a given connectable (in
@@ -2680,8 +2667,8 @@
  * g_task_set_return_on_cancel() for more details.
  *
  * Other than in that case, @task will be completed when the
- * #GTaskThreadFunc returns, <emphasis>not</emphasis> when it calls
- * a <literal>g_task_return_</literal> function.
+ * #GTaskThreadFunc returns, not when it calls a
+ * `g_task_return_` function.
  *
  * Since: 2.36
  */
@@ -2729,7 +2716,7 @@
  *
  * For example, if the icon name was "gnome-dev-cdrom-audio", the array
  * would become
- * |[
+ * |[<!-- language="C" -->
  * {
  *   "gnome-dev-cdrom-audio",
  *   "gnome-dev-cdrom",
@@ -2820,7 +2807,7 @@
  * but cannot be read.
  *
  * PKCS#8 format is supported since 2.32; earlier releases only
- * support PKCS#1. You can use the <literal>openssl rsa</literal>
+ * support PKCS#1. You can use the `openssl rsa`
  * tool to convert PKCS#8 keys to PKCS#1.
  *
  * Since: 2.28
@@ -2831,14 +2818,14 @@
  * GTlsCertificate:private-key-pem:
  *
  * The PEM (ASCII) encoded representation of the certificate's
- * private key in either PKCS#1 format ("<literal>BEGIN RSA PRIVATE
- * KEY</literal>") or unencrypted PKCS#8 format ("<literal>BEGIN
- * PRIVATE KEY</literal>"). This property (or the
+ * private key in either PKCS#1 format ("`BEGIN RSA PRIVATE
+ * KEY`") or unencrypted PKCS#8 format ("`BEGIN
+ * PRIVATE KEY`"). This property (or the
  * #GTlsCertificate:private-key property) can be set when
  * constructing a key (eg, from a file), but cannot be read.
  *
  * PKCS#8 format is supported since 2.32; earlier releases only
- * support PKCS#1. You can use the <literal>openssl rsa</literal>
+ * support PKCS#1. You can use the `openssl rsa`
  * tool to convert PKCS#8 keys to PKCS#1.
  *
  * Since: 2.28
@@ -3234,7 +3221,7 @@
  * GUnixSocketAddress:
  *
  * A UNIX-domain (local) socket address, corresponding to a
- * <type>struct sockaddr_un</type>.
+ * struct sockaddr_un.
  */
 
 
@@ -3514,7 +3501,7 @@
  * of an extension point has a name, and a priority. Use
  * g_io_extension_point_implement() to implement an extension point.
  *
- *  |[
+ *  |[<!-- language="C" -->
  *  GIOExtensionPoint *ep;
  *
  *  /&ast; Register an extension point &ast;/
@@ -3522,7 +3509,7 @@
  *  g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
  *  ]|
  *
- *  |[
+ *  |[<!-- language="C" -->
  *  /&ast; Implement an extension point &ast;/
  *  G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
  *  g_io_extension_point_implement ("my-extension-point",
@@ -3543,10 +3530,10 @@
  *  You are expected to run this command after installing a
  *  GIO module.
  *
- *  The <envar>GIO_EXTRA_MODULES</envar> environment variable can be
- *  used to specify additional directories to automatically load modules
+ *  The `GIO_EXTRA_MODULES` environment variable can be used to
+ *  specify additional directories to automatically load modules
  *  from. This environment variable has the same syntax as the
- *  <envar>PATH</envar>. If two modules have the same base name in different
+ *  `PATH`. If two modules have the same base name in different
  *  directories, then the latter one will be ignored. If additional
  *  directories are specified GIO will load modules from the built-in
  *  directory last.
@@ -3633,7 +3620,7 @@
  * with actions.  'Internal' APIs (ie: ones meant only to be accessed by
  * the action group implementation) are found on subclasses.  This is
  * why you will find - for example - g_action_group_get_action_enabled()
- * but not an equivalent <function>set()</function> call.
+ * but not an equivalent set() call.
  *
  * Signals are emitted on the action group in response to state changes
  * on individual actions.
@@ -3694,15 +3681,13 @@
  * As of GLib 2.20, URIs will always be converted to POSIX paths
  * (using g_file_get_path()) when using g_app_info_launch() even if
  * the application requested an URI and not a POSIX path. For example
- * for an desktop-file based application with Exec key <literal>totem
- * &percnt;U</literal> and a single URI,
- * <literal>sftp://foo/file.avi</literal>, then
- * <literal>/home/user/.gvfs/sftp on foo/file.avi</literal> will be
- * passed. This will only work if a set of suitable GIO extensions
- * (such as gvfs 2.26 compiled with FUSE support), is available and
- * operational; if this is not the case, the URI will be passed
- * unmodified to the application. Some URIs, such as
- * <literal>mailto:</literal>, of course cannot be mapped to a POSIX
+ * for an desktop-file based application with Exec key `totem
+ * &percnt;U` and a single URI, `sftp://foo/file.avi`, then
+ * `/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will
+ * only work if a set of suitable GIO extensions (such as gvfs 2.26
+ * compiled with FUSE support), is available and operational; if this
+ * is not the case, the URI will be passed unmodified to the application.
+ * Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX
  * path (in gvfs there's no FUSE mount for it); such URIs will be
  * passed unmodified to the application.
  *
@@ -3715,29 +3700,29 @@
  * equal to the result of g_file_get_uri(). The following snippet
  * illustrates this:
  *
- * <programlisting>
+ * |[
  * GFile *f;
  * char *uri;
  *
  * file = g_file_new_for_commandline_arg (uri_from_commandline);
  *
  * uri = g_file_get_uri (file);
- * strcmp (uri, uri_from_commandline) == 0; // FALSE
+ * strcmp (uri, uri_from_commandline) == 0;
  * g_free (uri);
  *
  * if (g_file_has_uri_scheme (file, "cdda"))
  *   {
- *     // do something special with uri
+ *     /&ast; do something special with uri &ast;/
  *   }
  * g_object_unref (file);
- * </programlisting>
+ * ]|
  *
- * This code will work when both <literal>cdda://sr0/Track
- * 1.wav</literal> and <literal>/home/user/.gvfs/cdda on sr0/Track
- * 1.wav</literal> is passed to the application. It should be noted
- * that it's generally not safe for applications to rely on the format
- * of a particular URIs. Different launcher applications (e.g. file
- * managers) may have different ideas of what a given URI means.
+ * This code will work when both `cdda://sr0/Track 1.wav` and
+ * `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the
+ * application. It should be noted that it's generally not safe
+ * for applications to rely on the format of a particular URIs.
+ * Different launcher applications (e.g. file managers) may have
+ * different ideas of what a given URI means.
  */
 
 
@@ -3780,41 +3765,40 @@
  * this class outside of a higher level framework.
  *
  * GApplication provides convenient life cycle management by maintaining
- * a <firstterm>use count</firstterm> for the primary application instance.
- * The use count can be changed using g_application_hold() and
- * g_application_release(). If it drops to zero, the application exits.
- * Higher-level classes such as #GtkApplication employ the use count to
- * ensure that the application stays alive as long as it has any opened
- * windows.
+ * a "use count" for the primary application instance. The use count can
+ * be changed using g_application_hold() and g_application_release(). If
+ * it drops to zero, the application exits. Higher-level classes such as
+ * #GtkApplication employ the use count to ensure that the application
+ * stays alive as long as it has any opened windows.
  *
  * Another feature that GApplication (optionally) provides is process
- * uniqueness.  Applications can make use of this functionality by
- * providing a unique application ID.  If given, only one application
- * with this ID can be running at a time per session.  The session
+ * uniqueness. Applications can make use of this functionality by
+ * providing a unique application ID. If given, only one application
+ * with this ID can be running at a time per session. The session
  * concept is platform-dependent, but corresponds roughly to a graphical
- * desktop login.  When your application is launched again, its
+ * desktop login. When your application is launched again, its
  * arguments are passed through platform communication to the already
- * running program.  The already running instance of the program is
- * called the <firstterm>primary instance</firstterm>; for non-unique
- * applications this is the always the current instance.
- * On Linux, the D-Bus session bus is used for communication.
+ * running program. The already running instance of the program is
+ * called the "primary instance"; for non-unique applications this is
+ * the always the current instance. On Linux, the D-Bus session bus
+ * is used for communication.
  *
  * The use of #GApplication differs from some other commonly-used
- * uniqueness libraries (such as libunique) in important ways.  The
- * application is not expected to manually register itself and check if
- * it is the primary instance.  Instead, the <code>main()</code>
- * function of a #GApplication should do very little more than
- * instantiating the application instance, possibly connecting signal
- * handlers, then calling g_application_run().  All checks for
- * uniqueness are done internally.  If the application is the primary
- * instance then the startup signal is emitted and the mainloop runs.
- * If the application is not the primary instance then a signal is sent
- * to the primary instance and g_application_run() promptly returns.
- * See the code examples below.
+ * uniqueness libraries (such as libunique) in important ways. The
+ * application is not expected to manually register itself and check
+ * if it is the primary instance. Instead, the main() function of a
+ * #GApplication should do very little more than instantiating the
+ * application instance, possibly connecting signal handlers, then
+ * calling g_application_run(). All checks for uniqueness are done
+ * internally. If the application is the primary instance then the
+ * startup signal is emitted and the mainloop runs. If the application
+ * is not the primary instance then a signal is sent to the primary
+ * instance and g_application_run() promptly returns. See the code
+ * examples below.
  *
  * If used, the expected form of an application identifier is very close
  * to that of of a
- * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface">DBus bus name</ulink>.
+ * [DBus bus name](http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface).
  * Examples include: "com.example.MyApp", "org.example.internal-apps.Calculator".
  * For details on valid application identifiers, see g_application_id_is_valid().
  *
@@ -3841,23 +3825,26 @@
  * for remote access to exported #GMenuModels.
  *
  * There is a number of different entry points into a GApplication:
- * <itemizedlist>
- * <listitem>via 'Activate' (i.e. just starting the application)</listitem>
- * <listitem>via 'Open' (i.e. opening some files)</listitem>
- * <listitem>by handling a command-line</listitem>
- * <listitem>via activating an action</listitem>
- * </itemizedlist>
+ *
+ * - via 'Activate' (i.e. just starting the application)
+ *
+ * - via 'Open' (i.e. opening some files)
+ *
+ * - by handling a command-line
+ *
+ * - via activating an action
+ *
  * The #GApplication::startup signal lets you handle the application
  * initialization for all of these in a single place.
  *
- * Regardless of which of these entry points is used to start the application,
- * GApplication passes some <firstterm id="platform-data">platform
- * data</firstterm> from the launching instance to the primary instance,
- * in the form of a #GVariant dictionary mapping strings to variants.
- * To use platform data, override the @before_emit or @after_emit virtual
- * functions in your #GApplication subclass. When dealing with
- * #GApplicationCommandLine objects, the platform data is directly
- * available via g_application_command_line_get_cwd(),
+ * Regardless of which of these entry points is used to start the
+ * application, GApplication passes some "platform data from the
+ * launching instance to the primary instance, in the form of a
+ * #GVariant dictionary mapping strings to variants. To use platform
+ * data, override the @before_emit or @after_emit virtual functions
+ * in your #GApplication subclass. When dealing with
+ * #GApplicationCommandLine objects, the platform data is
+ * directly available via g_application_command_line_get_cwd(),
  * g_application_command_line_get_environ() and
  * g_application_command_line_get_platform_data().
  *
@@ -3892,14 +3879,6 @@
  * </programlisting>
  * </example>
  *
- * <example id="gapplication-example-menu"><title>A GApplication with menus</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-menu.c">
- *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
- *
  * <example id="gapplication-example-dbushooks"><title>Using extra D-Bus hooks with a GApplication</title>
  * <programlisting>
  * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-dbushooks.c">
@@ -3940,64 +3919,136 @@
  *
  * The main use for #GApplicationCommandLine (and the
  * #GApplication::command-line signal) is 'Emacs server' like use cases:
- * You can set the <envar>EDITOR</envar> environment variable to have
- * e.g. git use your favourite editor to edit commit messages, and if you
- * already have an instance of the editor running, the editing will happen
+ * You can set the `EDITOR` environment variable to have e.g. git use
+ * your favourite editor to edit commit messages, and if you already
+ * have an instance of the editor running, the editing will happen
  * in the running instance, instead of opening a new one. An important
  * aspect of this use case is that the process that gets started by git
  * does not return until the editing is done.
  *
- * <example id="gapplication-example-cmdline"><title>Handling commandline arguments with GApplication</title>
- * <para>
- * A simple example where the commandline is completely handled
- * in the #GApplication::command-line handler. The launching instance exits
- * once the signal handler in the primary instance has returned, and the
- * return value of the signal handler becomes the exit status of the launching
- * instance.
- * </para>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
- *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * Normally, the commandline is completely handled in the
+ * #GApplication::command-line handler. The launching instance exits
+ * once the signal handler in the primary instance has returned, and
+ * the return value of the signal handler becomes the exit status
+ * of the launching instance.
+ * |[<!-- language="C" -->
+ * static int
+ * command_line (GApplication            *application,
+ *               GApplicationCommandLine *cmdline)
+ * {
+ *   gchar **argv;
+ *   gint argc;
+ *   gint i;
  *
- * <example id="gapplication-example-cmdline2"><title>Split commandline handling</title>
- * <para>
- * An example of split commandline handling. Options that start with
- * <literal>--local-</literal> are handled locally, all other options are
- * passed to the #GApplication::command-line handler which runs in the primary
+ *   argv = g_application_command_line_get_arguments (cmdline, &argc);
+ *
+ *   g_application_command_line_print (cmdline,
+ *                                     "This text is written back\n"
+ *                                     "to stdout of the caller\n");
+ *
+ *   for (i = 0; i < argc; i++)
+ *     g_print ("argument %d: %s\n", i, argv[i]);
+ *
+ *   g_strfreev (argv);
+ *
+ *   return 0;
+ * }
+ * ]|
+ * The complete example can be found here:
+ * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c)
+ *
+ * In more complicated cases, the handling of the comandline can be
+ * split between the launcher and the primary instance.
+ * |[<!-- language="C" -->
+ * static gboolean
+ *  test_local_cmdline (GApplication   *application,
+ *                      gchar        ***arguments,
+ *                      gint           *exit_status)
+ * {
+ *   gint i, j;
+ *   gchar **argv;
+ *
+ *   argv = *arguments;
+ *
+ *   i = 1;
+ *   while (argv[i])
+ *     {
+ *       if (g_str_has_prefix (argv[i], "--local-"))
+ *         {
+ *           g_print ("handling argument %s locally\n", argv[i]);
+ *           g_free (argv[i]);
+ *           for (j = i; argv[j]; j++)
+ *             argv[j] = argv[j + 1];
+ *         }
+ *       else
+ *         {
+ *           g_print ("not handling argument %s locally\n", argv[i]);
+ *           i++;
+ *         }
+ *     }
+ *
+ *   *exit_status = 0;
+ *
+ *   return FALSE;
+ * }
+ *
+ * static void
+ * test_application_class_init (TestApplicationClass *class)
+ * {
+ *   G_APPLICATION_CLASS (class)->local_command_line = test_local_cmdline;
+ *
+ *   ...
+ * }
+ * ]|
+ * In this example of split commandline handling, options that start
+ * with `--local-` are handled locally, all other options are passed
+ * to the #GApplication::command-line handler which runs in the primary
  * instance.
- * </para>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
- *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
  *
- * <example id="gapplication-example-cmdline3"><title>Deferred commandline handling</title>
- * <para>
- * An example of deferred commandline handling. Here, the commandline is
- * not completely handled before the #GApplication::command-line handler
- * returns. Instead, we keep a reference to the GApplicationCommandLine
- * object and handle it later(in this example, in an idle). Note that it
- * is necessary to hold the application until you are done with the
- * commandline.
- * </para>
- * <para>
- * This example also shows how to use #GOptionContext for parsing the
- * commandline arguments. Note that it is necessary to disable the
- * built-in help-handling of #GOptionContext, since it calls exit()
- * after printing help, which is not what you want to happen in
- * the primary instance.
- * </para>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
- *   <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * The complete example can be found here:
+ * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c)
+ *
+ * If handling the commandline requires a lot of work, it may
+ * be better to defer it.
+ * |[<!-- language="C" -->
+ * static gboolean
+ * my_cmdline_handler (gpointer data)
+ * {
+ *   GApplicationCommandLine *cmdline = data;
+ *
+ *   /&ast; do the heavy lifting in an idle &ast;/
+ *
+ *   g_application_command_line_set_exit_status (cmdline, 0);
+ *   g_object_unref (cmdline); /&ast; this releases the application &ast;/
+ *
+ *   return G_SOURCE_REMOVE;
+ * }
+ *
+ * static int
+ * command_line (GApplication            *application,
+ *               GApplicationCommandLine *cmdline)
+ * {
+ *   /&ast; keep the application running until we are done with this commandline &ast;/
+ *   g_application_hold (application);
+ *
+ *   g_object_set_data_full (G_OBJECT (cmdline),
+ *                           "application", application,
+ *                           (GDestroyNotify)g_application_release);
+ *
+ *   g_object_ref (cmdline);
+ *   g_idle_add (my_cmdline_handler, cmdline);
+ *
+ *   return 0;
+ * }
+ * ]|
+ * In this example the commandline is not completely handled before
+ * the #GApplication::command-line handler returns. Instead, we keep
+ * a reference to the #GApplicationCommandLine object and handle it
+ * later (in this example, in an idle). Note that it is necessary to
+ * hold the application until you are done with the commandline.
+ *
+ * The complete example can be found here:
+ * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
  */
 
 
@@ -4022,7 +4073,7 @@
  *
  * A typical implementation might look something like this:
  *
- * |[
+ * |[<!-- language="C" -->
  * enum {
  *    NOT_INITIALIZED,
  *    INITIALIZING,
@@ -4141,7 +4192,7 @@
  * however, the "_finish()" function may be called at most once.
  *
  * Example of a typical asynchronous operation flow:
- * |[
+ * |[<!-- language="C" -->
  * void _theoretical_frobnitz_async (Theoretical         *t,
  *                                   GCancellable        *c,
  *                                   GAsyncReadyCallback  cb,
@@ -4165,20 +4216,20 @@
  *   else
  *     g_printf ("Uh oh!\n");
  *
- *   /<!-- -->* ... *<!-- -->/
+ *   ...
  *
  * }
  *
  * int main (int argc, void *argv[])
  * {
- *    /<!-- -->* ... *<!-- -->/
+ *    ...
  *
  *    _theoretical_frobnitz_async (theoretical_data,
  *                                 NULL,
  *                                 frobnitz_result_func,
  *                                 NULL);
  *
- *    /<!-- -->* ... *<!-- -->/
+ *    ...
  * }
  * ]|
  *
@@ -4186,15 +4237,15 @@
  * always called, even in the case of a cancelled operation. On cancellation
  * the result is a %G_IO_ERROR_CANCELLED error.
  *
- * <para id="io-priority"><indexterm><primary>I/O
- * priority</primary></indexterm> Many I/O-related asynchronous
- * operations have a priority parameter, which is used in certain
- * cases to determine the order in which operations are executed. They
- * are <emphasis>not</emphasis> used to determine system-wide I/O
- * scheduling. Priorities are integers, with lower numbers indicating
+ * ## I/O Priority # {#io-priority}
+ *
+ * Many I/O-related asynchronous operations have a priority parameter,
+ * which is used in certain cases to determine the order in which
+ * operations are executed. They are not used to determine system-wide
+ * I/O scheduling. Priorities are integers, with lower numbers indicating
  * higher priority. It is recommended to choose priorities between
- * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT as a
- * default. </para>
+ * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
+ * as a default.
  */
 
 
@@ -4284,7 +4335,9 @@
  * @include: gio/gio.h
  *
  * A content type is a platform specific string that defines the type
- * of a file. On UNIX it is a <ulink url="http://www.wikipedia.org/wiki/Internet_media_type">mime type</ulink> like "text/plain" or "image/png".
+ * of a file. On UNIX it is a
+ * [mime type](http://www.wikipedia.org/wiki/Internet_media_type)
+ * like "text/plain" or "image/png".
  * On Win32 it is an extension string like ".doc", ".txt" or a perceived
  * string like "audio". Such strings can be looked up in the registry at
  * HKEY_CLASSES_ROOT.
@@ -4355,21 +4408,19 @@
  * #GUnixCredentialsMessage, g_unix_connection_send_credentials() and
  * g_unix_connection_receive_credentials() for details.
  *
- * On Linux, the native credential type is a <type>struct ucred</type>
- * - see the
- * <citerefentry><refentrytitle>unix</refentrytitle><manvolnum>7</manvolnum></citerefentry>
- * man page for details. This corresponds to
+ * On Linux, the native credential type is a struct ucred - see the
+ * unix(7) man page for details. This corresponds to
  * %G_CREDENTIALS_TYPE_LINUX_UCRED.
  *
  * On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native
- * credential type is a <type>struct cmsgcred</type>. This corresponds
+ * credential type is a struct cmsgcred. This corresponds
  * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.
  *
- * On OpenBSD, the native credential type is a <type>struct sockpeercred</type>.
+ * On OpenBSD, the native credential type is a struct sockpeercred.
  * This corresponds to %G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.
  *
  * On Solaris (including OpenSolaris and its derivatives), the native
- * credential type is a <type>ucred_t</type>. This corresponds to
+ * credential type is a ucred_t. This corresponds to
  * %G_CREDENTIALS_TYPE_SOLARIS_UCRED.
  */
 
@@ -4474,14 +4525,10 @@
  * an D-Bus client, it is often easier to use the g_bus_own_name(),
  * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
  *
- * As an exception to the usual GLib rule that a particular object must not be
- * used by two threads at the same time, #GDBusConnection's methods may be
- * called from any thread<footnote>
- * <para>
- *   This is so that g_bus_get() and g_bus_get_sync() can safely return the
- *   same #GDBusConnection when called from any thread.
- * </para>
- * </footnote>.
+ * As an exception to the usual GLib rule that a particular object must not
+ * be used by two threads at the same time, #GDBusConnection's methods may be
+ * called from any thread. This is so that g_bus_get() and g_bus_get_sync()
+ * can safely return the same #GDBusConnection when called from any thread.
  *
  * Most of the ways to obtain a #GDBusConnection automatically initialize it
  * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
@@ -4533,8 +4580,8 @@
  * automatically map from D-Bus errors to #GError and back. This
  * is typically done in the function returning the #GQuark for the
  * error domain:
- * <example id="error-registration"><title>Error Registration</title><programlisting>
- * /<!-- -->* foo-bar-error.h: *<!-- -->/
+ * |[<!-- language="C" -->
+ * /&ast; foo-bar-error.h: &ast;/
  *
  * #define FOO_BAR_ERROR (foo_bar_error_quark ())
  * GQuark foo_bar_error_quark (void);
@@ -4544,10 +4591,10 @@
  *   FOO_BAR_ERROR_FAILED,
  *   FOO_BAR_ERROR_ANOTHER_ERROR,
  *   FOO_BAR_ERROR_SOME_THIRD_ERROR,
- *   FOO_BAR_N_ERRORS /<!-- -->*< skip >*<!-- -->/
+ *   FOO_BAR_N_ERRORS /&ast;< skip >&ast;/
  * } FooBarError;
  *
- * /<!-- -->* foo-bar-error.c: *<!-- -->/
+ * /&ast; foo-bar-error.c: &ast;/
  *
  * static const GDBusErrorEntry foo_bar_error_entries[] =
  * {
@@ -4556,7 +4603,7 @@
  *   {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
  * };
  *
- * /<!-- -->* Ensure that every error code has an associated D-Bus error name *<!-- -->/
+ * /&ast; Ensure that every error code has an associated D-Bus error name &ast;/
  * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) == FOO_BAR_N_ERRORS);
  *
  * GQuark
@@ -4569,15 +4616,15 @@
  *                                       G_N_ELEMENTS (foo_bar_error_entries));
  *   return (GQuark) quark_volatile;
  * }
- * </programlisting></example>
+ * ]|
  * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
- * other peers will see the D-Bus error name <literal>org.project.Foo.Bar.Error.AnotherError</literal>.
+ * other peers will see the D-Bus error name org.project.Foo.Bar.Error.AnotherError.
  *
  * If the other peer is using GDBus, and has registered the association with
  * g_dbus_error_register_error_domain() in advance (e.g. by invoking the %FOO_BAR_ERROR quark
  * generation itself in the previous example) the peer will see also %FOO_BAR_ERROR_ANOTHER_ERROR instead
  * of %G_IO_ERROR_DBUS_ERROR. Note that GDBus clients can still recover
- * <literal>org.project.Foo.Bar.Error.AnotherError</literal> using g_dbus_error_get_remote_error().
+ * org.project.Foo.Bar.Error.AnotherError using g_dbus_error_get_remote_error().
  *
  * Note that errors in the %G_DBUS_ERROR error domain is intended only
  * for returning errors from a remote message bus process. Errors
@@ -4617,7 +4664,7 @@
  * used when registering objects with g_dbus_connection_register_object().
  *
  * The format of D-Bus introspection XML is specified in the
- * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</ulink>.
+ * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format)
  */
 
 
@@ -4701,8 +4748,8 @@
  * @include: gio/gio.h
  *
  * The #GDBusObjectManager type is the base type for service- and
- * client-side implementations of the standardized <ulink
- * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
+ * client-side implementations of the standardized
+ * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
  * interface.
  *
  * See #GDBusObjectManagerClient for the client-side implementation
@@ -4717,8 +4764,8 @@
  *
  * #GDBusObjectManagerClient is used to create, monitor and delete object
  * proxies for remote objects exported by a #GDBusObjectManagerServer (or any
- * code implementing the <ulink
- * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
+ * code implementing the
+ * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
  * interface).
  *
  * Once an instance of this type has been created, you can connect to
@@ -4758,18 +4805,17 @@
  * is set to the new name owner (this includes emission of the
  * #GObject::notify signal).  Furthermore, you are guaranteed that
  * #GDBusObjectManagerClient:name-owner will alternate between a name owner
- * (e.g. <literal>:1.42</literal>) and %NULL even in the case where
+ * (e.g. `:1.42`) and %NULL even in the case where
  * the name of interest is atomically replaced
  *
  * Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy
  * instances. All signals (including the
- * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
- * signal) delivered to #GDBusProxy instances are guaranteed to
- * originate from the name owner. This guarantee along with the
- * behavior described above, means that certain race conditions
- * including the <emphasis><quote>half the proxy is from the old owner
- * and the other half is from the new owner</quote></emphasis> problem
- * cannot happen.
+ * org.freedesktop.DBus.Properties::PropertiesChanged signal)
+ * delivered to #GDBusProxy instances are guaranteed to originate
+ * from the name owner. This guarantee along with the behavior
+ * described above, means that certain race conditions including the
+ * "half the proxy is from the old owner and the other half is from
+ * the new owner" problem cannot happen.
  *
  * To avoid having the application connect to signals on the returned
  * #GDBusObjectProxy and #GDBusProxy objects, the
@@ -4800,8 +4846,8 @@
  * @include: gio/gio.h
  *
  * #GDBusObjectManagerServer is used to export #GDBusObject instances using
- * the standardized <ulink
- * url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager">org.freedesktop.DBus.ObjectManager</ulink>
+ * the standardized
+ * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
  * interface. For example, remote D-Bus clients can get all objects
  * and properties in a single call. Additionally, any change in the
  * object hierarchy is broadcast using signals. This means that D-Bus
@@ -4876,8 +4922,7 @@
  * subclass #GDBusProxy, and have more natural properties and signals
  * in your derived class. See <xref linkend="gdbus-example-gdbus-codegen"/>
  * for how this can easily be done using the
- * <command><link linkend="gdbus-codegen">gdbus-codegen</link></command>
- * tool.
+ * <link linkend="gdbus-codegen">gdbus-codegen</link> tool.
  *
  * A #GDBusProxy instance can be used from multiple threads but note
  * that all signals (e.g. #GDBusProxy::g-signal, #GDBusProxy::g-properties-changed
@@ -4926,9 +4971,9 @@
  * #GDesktopAppInfo is an implementation of #GAppInfo based on
  * desktop files.
  *
- * Note that <filename>&lt;gio/gdesktopappinfo.h&gt;</filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gdesktopappinfo.h&gt;` belongs to the UNIX-specific
+ * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+ * file when using it.
  */
 
 
@@ -5071,14 +5116,15 @@
  * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
  * </simplelist>
  *
- * <para id="gfile-etag"><indexterm><primary>entity tag</primary></indexterm>
+ * ## Entity Tags # {#gfile-etag}
+ *
  * One notable feature of #GFiles are entity tags, or "etags" for
  * short. Entity tags are somewhat like a more abstract version of the
- * traditional mtime, and can be used to quickly determine if the file has
- * been modified from the version on the file system. See the HTTP 1.1
- * <ulink url="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html">specification</ulink>
+ * traditional mtime, and can be used to quickly determine if the file
+ * has been modified from the version on the file system. See the
+ * HTTP 1.1
+ * [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html)
  * for HTTP Etag headers, which are a very similar concept.
- * </para>
  */
 
 
@@ -5261,8 +5307,8 @@
  * "xattr::". Keys for the "xattr-sys" namespace are constructed by
  * concatenating "xattr-sys::" with the extended attribute name. All extended
  * attribute values are returned as hex-encoded strings in which bytes outside
- * the ASCII range are encoded as hexadecimal escape sequences of the form
- * \x<replaceable>nn</replaceable>.
+ * the ASCII range are encoded as escape sequences of the form \x`nn`
+ * where `nn` is a 2-digit hexadecimal number.
  */
 
 
@@ -5275,9 +5321,9 @@
  * #GFileDescriptorBased is implemented by streams (implementations of
  * #GInputStream or #GOutputStream) that are based on file descriptors.
  *
- * Note that <filename>&lt;gio/gfiledescriptorbased.h&gt;</filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gfiledescriptorbased.h&gt;` belongs to the UNIX-specific
+ * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+ * file when using it.
  *
  * Since: 2.24
  */
@@ -5288,7 +5334,7 @@
  * @short_description: Enumerated Files Routines
  * @include: gio/gio.h
  *
- * #GFileEnumerator allows you to operate on a set of #GFile<!-- -->s,
+ * #GFileEnumerator allows you to operate on a set of #GFiles,
  * returning a #GFileInfo structure for each file enumerated (e.g.
  * g_file_enumerate_children() will return a #GFileEnumerator for each
  * of the children within a directory).
@@ -5296,7 +5342,7 @@
  * To get the next file's information from a #GFileEnumerator, use
  * g_file_enumerator_next_file() or its asynchronous version,
  * g_file_enumerator_next_files_async(). Note that the asynchronous
- * version will return a list of #GFileInfo<!---->s, whereas the
+ * version will return a list of #GFileInfos, whereas the
  * synchronous will only return the next file in the enumerator.
  *
  * The ordering of returned files is unspecified for non-Unix
@@ -5640,10 +5686,8 @@
  * @short_description: I/O Scheduler
  * @include: gio/gio.h
  *
- * <note><para>
- *   As of GLib 2.36, the <literal>g_io_scheduler</literal> methods
- *   are deprecated in favor of #GThreadPool and #GTask.
- * </para></note>
+ * As of GLib 2.36, #GIOScheduler is deprecated in favor of
+ * #GThreadPool and #GTask.
  *
  * Schedules asynchronous I/O operations. #GIOScheduler integrates
  * into the main event loop (#GMainLoop) and uses threads.
@@ -5782,33 +5826,30 @@
  * As an example, consider the visible portions of the menu in
  * <xref linkend="menu-example"/>.
  *
- * <figure id="menu-example">
- *   <title>An example menu</title>
- *   <graphic fileref="menu-example.png" format="PNG"></graphic>
- * </figure>
+ * ## An example menu # {#menu-example}
+ *
+ * ![](menu-example.png)
  *
  * There are 8 "menus" visible in the screenshot: one menubar, two
  * submenus and 5 sections:
- * <itemizedlist>
- * <listitem>the toplevel menubar (containing 4 items)</listitem>
- * <listitem>the View submenu (containing 3 sections)</listitem>
- * <listitem>the first section of the View submenu (containing 2 items)</listitem>
- * <listitem>the second section of the View submenu (containing 1 item)</listitem>
- * <listitem>the final section of the View submenu (containing 1 item)</listitem>
- * <listitem>the Highlight Mode submenu (containing 2 sections)</listitem>
- * <listitem>the Sources section (containing 2 items)</listitem>
- * <listitem>the Markup section (containing 2 items)</listitem>
- * </itemizedlist>
+ *
+ * - the toplevel menubar (containing 4 items)
+ * - the View submenu (containing 3 sections)
+ * - the first section of the View submenu (containing 2 items)
+ * - the second section of the View submenu (containing 1 item)
+ * - the final section of the View submenu (containing 1 item)
+ * - the Highlight Mode submenu (containing 2 sections)
+ * - the Sources section (containing 2 items)
+ * - the Markup section (containing 2 items)
  *
  * <xref linkend="menu-model"/> illustrates the conceptual connection between
  * these 8 menus. Each large block in the figure represents a menu and the
  * smaller blocks within the large block represent items in that menu. Some
  * items contain references to other menus.
  *
- * <figure id="menu-model">
- *   <title>A menu model</title>
- *   <graphic fileref="menu-model.png" format="PNG"></graphic>
- * </figure>
+ * ## A menu example # {#menu-model}
+ *
+ * ![](menu-model.png)
  *
  * Notice that the separators visible in <xref linkend="menu-example"/>
  * appear nowhere in <xref linkend="menu-model"/>. This is because
@@ -5852,48 +5893,37 @@
  * While a wide variety of stateful actions is possible, the following
  * is the minimum that is expected to be supported by all users of exported
  * menu information:
- * <itemizedlist>
- * <listitem>an action with no parameter type and no state</listitem>
- * <listitem>an action with no parameter type and boolean state</listitem>
- * <listitem>an action with string parameter type and string state</listitem>
- * </itemizedlist>
+ * - an action with no parameter type and no state
+ * - an action with no parameter type and boolean state
+ * - an action with string parameter type and string state
+ *
+ * ## Stateless
  *
- * <formalpara><title>Stateless</title>
- * <para>
  * A stateless action typically corresponds to an ordinary menu item.
- * </para>
- * <para>
+ *
  * Selecting such a menu item will activate the action (with no parameter).
- * </para>
- * </formalpara>
  *
- * <formalpara><title>Boolean State</title>
- * <para>
+ * ## Boolean State
+ *
  * An action with a boolean state will most typically be used with a "toggle"
  * or "switch" menu item. The state can be set directly, but activating the
  * action (with no parameter) results in the state being toggled.
- * </para>
- * <para>
+ *
  * Selecting a toggle menu item will activate the action. The menu item should
  * be rendered as "checked" when the state is true.
- * </para>
- * </formalpara>
  *
- * <formalpara><title>String Parameter and State</title>
- * <para>
+ * ## String Parameter and State
+ *
  * Actions with string parameters and state will most typically be used to
  * represent an enumerated choice over the items available for a group of
  * radio menu items. Activating the action with a string parameter is
  * equivalent to setting that parameter as the state.
- * </para>
- * <para>
+ *
  * Radio menu items, in addition to being associated with the action, will
  * have a target value. Selecting that menu item will result in activation
  * of the action with the target value as the parameter. The menu item should
  * be rendered as "selected" when the state of the action is equal to the
  * target value of the menu item.
- * </para>
- * </formalpara>
  */
 
 
@@ -5968,7 +5998,7 @@
  * @short_description: System networking includes
  * @include: gio/gnetworking.h
  *
- * The <literal>gnetworking.h</literal> header can be included to get
+ * The `&lt;gio/gnetworking.h&gt;` header can be included to get
  * various low-level networking-related system headers, automatically
  * taking care of certain portability issues for you.
  *
@@ -5981,11 +6011,10 @@
  * want your code to work under both UNIX and Windows, you will need
  * to take these differences into account.
  *
- * Also, under glibc, certain non-portable functions are only visible
- * in the headers if you define <literal>_GNU_SOURCE</literal> before
- * including them. Note that this symbol must be defined before
- * including <emphasis>any</emphasis> headers, or it may not take
- * effect.
+ * Also, under GNU libc, certain non-portable functions are only visible
+ * in the headers if you define %_GNU_SOURCE before including them. Note
+ * that this symbol must be defined before including any headers, or it
+ * may not take effect.
  */
 
 
@@ -6240,10 +6269,10 @@
  * or receive action invocations in the local process from other
  * processes.
  *
- * The interface has <literal>_full</literal> variants of the two
+ * 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
+ * g_action_group_change_action_state(). These variants allow a
  * "platform data" #GVariant to be specified: a dictionary providing
  * context for the action invocation (for example: timestamps, startup
  * notification IDs, etc).
@@ -6253,7 +6282,7 @@
  *
  * Additionally, g_dbus_connection_export_action_group() will check if
  * the exported #GActionGroup implements #GRemoteActionGroup and use the
- * <literal>_full</literal> variants of the calls if available.  This
+ * `_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.
  *
@@ -6282,9 +6311,10 @@
  * @short_description: Resource framework
  * @include: gio/gio.h
  *
- * Applications and libraries often contain binary or textual data that is really part of the
- * application, rather than user data. For instance #GtkBuilder .ui files, splashscreen images,
- * GMenu markup xml, CSS files, icons, etc. These are often shipped as files in <filename>$datadir/appname</filename>, or
+ * Applications and libraries often contain binary or textual data that is
+ * really part of the application, rather than user data. For instance
+ * #GtkBuilder .ui files, splashscreen images, GMenu markup xml, CSS files,
+ * icons, etc. These are often shipped as files in `$datadir/appname`, or
  * manually included as literal strings in the code.
  *
  * The #GResource API and the <link linkend="glib-compile-resources">glib-compile-resources</link> program
@@ -6300,18 +6330,19 @@
  * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
  *
  * Resource files can also be marked to be preprocessed, by setting the value of the
- * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options.
+ * `preprocess` attribute to a comma-separated list of preprocessing options.
  * The only options currently supported are:
  *
- * <literal>xml-stripblanks</literal> which will use <command>xmllint</command> to strip
- * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar>
- * environment variable must be set to the full path to the xmllint executable, or xmllint
- * must be in the PATH; otherwise the preprocessing step is skipped.
+ * `xml-stripblanks` which will use the xmllint command
+ * to strip ignorable whitespace from the xml file. For this to work,
+ * the `XMLLINT` environment variable must be set to the full path to
+ * the xmllint executable, or xmllint must be in the `PATH`; otherwise
+ * the preprocessing step is skipped.
  *
- * <literal>to-pixdata</literal> which will use <command>gdk-pixbuf-pixdata</command> to convert
+ * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert
  * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
  * the resource file, rather than an (uncompressed) copy if it. For this, the gdk-pixbuf-pixdata
- * program must be in the PATH, or the <envar>GDK_PIXBUF_PIXDATA</envar> environment variable must be
+ * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be
  * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
  * abort.
  *
@@ -6319,8 +6350,8 @@
  * which takes an xml file that describes the bundle, and a set of files that the xml references. These
  * are combined into a binary resource bundle.
  *
- * <example id="resource-example"><title>Example resource description</title>
- * <programlisting><![CDATA[
+ * An example resource description:
+ * |[
  * <?xml version="1.0" encoding="UTF-8"?>
  * <gresources>
  *   <gresource prefix="/org/gtk/Example">
@@ -6329,14 +6360,14 @@
  *     <file preprocess="xml-stripblanks">menumarkup.xml</file>
  *   </gresource>
  * </gresources>
- * ]]></programlisting></example>
+ * ]|
  *
  * This will create a resource bundle with the following files:
- * <programlisting><![CDATA[
+ * |[
  * /org/gtk/Example/data/splashscreen.png
  * /org/gtk/Example/dialog.ui
  * /org/gtk/Example/menumarkup.xml
- * ]]></programlisting>
+ * ]|
  *
  * Note that all resources in the process share the same namespace, so use java-style
  * path prefixes (like in the above example) to avoid conflicts.
@@ -6441,40 +6472,40 @@
  * 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
- * <tag class="attribute">gettext-domain</tag> attribute of the
- * <tag class="starttag">schemalist</tag> or <tag class="starttag">schema</tag>
- * elements and the category that is specified in the l10n attribute of the
- * <tag class="starttag">key</tag> element.
+ * gettext-domain attribute of the &lt;schemalist&gt; or &lt;schema&gt;
+ * elements and the category that is specified in the l10n attribute of
+ * the &lt;key&gt; element.
  *
  * GSettings uses schemas in a compact binary form that is created
  * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
- * utility. The input is a schema description in an XML format that can be
- * described by the following DTD:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/gschema.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
- *
- * glib-compile-schemas expects schema files to have the extension <filename>.gschema.xml</filename>
- *
- * At runtime, schemas are identified by their id (as specified
- * in the <tag class="attribute">id</tag> attribute of the
- * <tag class="starttag">schema</tag> 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".
- *
- * In addition to #GVariant types, keys can have types that have enumerated
- * types. These can be described by a <tag class="starttag">choice</tag>,
- * <tag class="starttag">enum</tag> or <tag class="starttag">flags</tag> element, see
+ * 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://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
+ *
+ * The <link linkend="glib-compile-schemas">glib-compile-schemas</link>
+ * 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 &lt;schema&gt; 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".
+ *
+ * In addition to #GVariant types, keys can have types that have
+ * enumerated types. These can be described by a &lt;choice&gt;,
+ * &lt;enum&gt; or &lt;flags&gt; element, see
  * <xref linkend="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.
  *
- * <example id="schema-default-values"><title>Default values</title>
- * <programlisting><![CDATA[
+ * An example for default value:
+ * |[
  * <schemalist>
  *   <schema id="org.gtk.Test" path="/org/gtk/Test/" gettext-domain="test">
  *
@@ -6492,10 +6523,10 @@
  *
  *   </schema>
  * </schemalist>
- * ]]></programlisting></example>
+ * ]|
  *
- * <example id="schema-enumerated"><title>Ranges, choices and enumerated types</title>
- * <programlisting><![CDATA[
+ * An example for ranges, choices and enumerated types:
+ * |[
  * <schemalist>
  *
  *   <enum id="org.gtk.Test.myenum">
@@ -6538,51 +6569,42 @@
  *     </key>
  *   </schema>
  * </schemalist>
- * ]]></programlisting></example>
- *
- * <refsect2>
- *   <title>Vendor overrides</title>
- *   <para>
- *     Default values are defined in the schemas that get installed by
- *     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,
- *     <link linkend="glib-compile-schemas">glib-compile-schemas</link> 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:
- *     <informalexample><programlisting>
+ * ]|
+ *
+ * ## Vendor overrides
+ *
+ * Default values are defined in the schemas that get installed by
+ * 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,
+ * <link linkend="glib-compile-schemas">glib-compile-schemas</link> 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
- *     </programlisting></informalexample>
- *   </para>
- *   <para>
- *     glib-compile-schemas expects schema files to have the extension
- *     <filename>.gschema.override</filename>
- *   </para>
- * </refsect2>
- *
- * <refsect2>
- *   <title>Binding</title>
- *   <para>
- *     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.
- *   </para>
- *   <para>
- *     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
- *     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.
- *   </para>
- * </refsect2>
+ * ]|
+ *
+ * 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.
+ *
+ * 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
+ * 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.
  */
 
 
@@ -6612,13 +6634,11 @@
  * g_settings_backend_create_tree() is a convenience function to create
  * suitable trees.
  *
- * <note><para>
- * 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
- * <filename>gio/gsettingsbackend.h</filename>
- * </para></note>
+ * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
+ * `gio/gsettingsbackend.h`.
  */
 
 
@@ -6646,7 +6666,7 @@
  *
  * Consider the following example:
  *
- * |[
+ * |[<!-- language="C" -->
  * typedef struct
  * {
  *    ...
@@ -6703,7 +6723,7 @@
  * ships a gschemas.compiled file as part of itself, and then simply do
  * the following:
  *
- * |[
+ * |[<!-- language="C" -->
  * {
  *   GSettings *settings;
  *   gint some_value;
@@ -6752,16 +6772,14 @@
  * SECTION:gsimpleasyncresult
  * @short_description: Simple asynchronous results implementation
  * @include: gio/gio.h
- * @see_also: #GAsyncResult
+ * @see_also: #GAsyncResult, #GTask
  *
- * <note><para>
- *   As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
- *   #GTask, which provides a simpler API.
- * </para></note>
+ * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of
+ * #GTask, which provides a simpler API.
  *
  * #GSimpleAsyncResult implements #GAsyncResult.
  *
- * GSimpleAsyncResult handles #GAsyncReadyCallback<!-- -->s, error
+ * GSimpleAsyncResult handles #GAsyncReadyCallbacks, error
  * reporting, operation cancellation and the final state of an operation,
  * completely transparent to the application. Results can be returned
  * as a pointer e.g. for functions that return data that is collected
@@ -6799,7 +6817,7 @@
  * cause a leak if cancelled before being run).
  *
  * GSimpleAsyncResult can integrate into GLib's event loop, #GMainLoop,
- * or it can use #GThread<!-- -->s.
+ * or it can use #GThreads.
  * g_simple_async_result_complete() will finish an I/O task directly
  * from the point where it is called. g_simple_async_result_complete_in_idle()
  * will finish it from an idle handler in the <link
@@ -6826,7 +6844,7 @@
  * #GAsyncResult.  A typical implementation of an asynchronous operation
  * using GSimpleAsyncResult looks something like this:
  *
- * |[
+ * |[<!-- language="C" -->
  * static void
  * baked_cb (Cake    *cake,
  *           gpointer user_data)
@@ -6998,7 +7016,7 @@
  * reasons. For instance, on Windows a socket is always seen as writable
  * until a write returns %G_IO_ERROR_WOULD_BLOCK.
  *
- * #GSocket<!-- -->s can be either connection oriented or datagram based.
+ * #GSockets can be either connection oriented or datagram based.
  * For connection oriented types you must first establish a connection by
  * either connecting to an address or accepting a connection from another
  * address. For connectionless socket types the target/source address is
@@ -7022,10 +7040,9 @@
  *     for socket communication
  * @include: gio/gio.h
  *
- * #GSocketAddress is the equivalent of <type>struct sockaddr</type>
- * in the BSD sockets API. This is an abstract class; use
- * #GInetSocketAddress for internet sockets, or #GUnixSocketAddress
- * for UNIX domain sockets.
+ * #GSocketAddress is the equivalent of struct sockaddr in the BSD
+ * sockets API. This is an abstract class; use #GInetSocketAddress
+ * for internet sockets, or #GUnixSocketAddress for UNIX domain sockets.
  */
 
 
@@ -7064,7 +7081,7 @@
  * to try out each socket address in turn until one succeeds, as shown
  * in the sample code below.
  *
- * |[
+ * |[<!-- language="C" -->
  * MyConnectionType *
  * connect_to_host (const char    *hostname,
  *                  guint16        port,
@@ -7081,10 +7098,10 @@
  *   enumerator = g_socket_connectable_enumerate (addr);
  *   g_object_unref (addr);
  *
- *   /<!-- -->* Try each sockaddr until we succeed. Record the first
- *    * connection error, but not any further ones (since they'll probably
- *    * be basically the same as the first).
- *    *<!-- -->/
+ *   /&ast; Try each sockaddr until we succeed. Record the first
+ *    &ast; connection error, but not any further ones (since they'll probably
+ *    &ast; be basically the same as the first).
+ *    &ast;/
  *   while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
  *     {
  *       conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
@@ -7096,18 +7113,18 @@
  *     {
  *       if (conn_error)
  *         {
- *           /<!-- -->* We couldn't connect to the first address, but we succeeded
- *            * in connecting to a later address.
- *            *<!-- -->/
+ *           /&ast; We couldn't connect to the first address, but we succeeded
+ *            &ast; in connecting to a later address.
+ *            &ast;/
  *           g_error_free (conn_error);
  *         }
  *       return conn;
  *     }
  *   else if (error)
  *     {
- *       /<!-- -->* Either the initial lookup failed, or else the caller
- *        * cancelled us.
- *        *<!-- -->/
+ *       /&ast; Either the initial lookup failed, or else the caller
+ *        &ast; cancelled us.
+ *        &ast;/
  *       if (conn_error)
  *         g_error_free (conn_error);
  *       return NULL;
@@ -7248,7 +7265,7 @@
  * then connect to whatever host was pointed to by that record.
  *
  * You can use g_resolver_lookup_service() or
- * g_resolver_lookup_service_async() to find the #GSrvTarget<!-- -->s
+ * g_resolver_lookup_service_async() to find the #GSrvTargets
  * for a given service. However, if you are simply planning to connect
  * to the remote service, you can use #GNetworkService's
  * #GSocketConnectable interface and not need to worry about
@@ -7278,16 +7295,15 @@
  * comprehensive API for asynchronous I/O, such
  * g_output_stream_splice_async().  This makes GSubprocess
  * significantly more powerful and flexible than equivalent APIs in
- * some other languages such as the <literal>subprocess.py</literal>
+ * some other languages such as the `subprocess.py`
  * included with Python.  For example, using #GSubprocess one could
  * create two child processes, reading standard output from the first,
  * processing it, and writing to the input stream of the second, all
  * without blocking the main loop.
  *
  * A powerful g_subprocess_communicate() API is provided similar to the
- * <literal>communicate()</literal> method of
- * <literal>subprocess.py</literal>.  This enables very easy interaction
- * with a subprocess that has been opened with pipes.
+ * `communicate()` method of `subprocess.py`. This enables very easy
+ * interaction with a subprocess that has been opened with pipes.
  *
  * #GSubprocess defaults to tight control over the file descriptors open
  * in the child process, avoiding dangling-fd issues that are caused by
@@ -7349,29 +7365,27 @@
  * @include: gio/gio.h
  * @see_also: #GAsyncResult
  *
- * <para>
- *   A #GTask represents and manages a cancellable "task".
- * </para>
- * <refsect2>
- *   <title>Asynchronous operations</title>
- *   <para>
- *     The most common usage of #GTask is as a #GAsyncResult, to
- *     manage data during an asynchronous operation. You call
- *     g_task_new() in the "start" method, followed by
- *     g_task_set_task_data() and the like if you need to keep some
- *     additional data associated with the task, and then pass the
- *     task object around through your asynchronous operation.
- *     Eventually, you will call a method such as
- *     g_task_return_pointer() or g_task_return_error(), which will
- *     save the value you give it and then invoke the task's callback
- *     function (waiting until the next iteration of the main
- *     loop first, if necessary). The caller will pass the #GTask back
- *     to the operation's finish function (as a #GAsyncResult), and
- *     you can use g_task_propagate_pointer() or the like to extract
- *     the return value.
- *   </para>
- *   <example id="gtask-async"><title>GTask as a GAsyncResult</title>
- *   <programlisting>
+ * A #GTask represents and manages a cancellable "task".
+ *
+ * ## Asynchronous operations
+ *
+ * The most common usage of #GTask is as a #GAsyncResult, to
+ * manage data during an asynchronous operation. You call
+ * g_task_new() in the "start" method, followed by
+ * g_task_set_task_data() and the like if you need to keep some
+ * additional data associated with the task, and then pass the
+ * task object around through your asynchronous operation.
+ * Eventually, you will call a method such as
+ * g_task_return_pointer() or g_task_return_error(), which will
+ * save the value you give it and then invoke the task's callback
+ * function (waiting until the next iteration of the main
+ * loop first, if necessary). The caller will pass the #GTask back
+ * to the operation's finish function (as a #GAsyncResult), and
+ * you can use g_task_propagate_pointer() or the like to extract
+ * the return value.
+ *
+ * Here is an example for using GTask as a GAsyncResult:
+ * |[<!-- language="C" -->
  *     typedef struct {
  *       CakeFrostingType frosting;
  *       char *message;
@@ -7463,25 +7477,23 @@
  *
  *       return g_task_propagate_pointer (G_TASK (result), error);
  *     }
- *   </programlisting>
- *   </example>
- * </refsect2>
- * <refsect2>
- *   <title>Chained asynchronous operations</title>
- *   <para>
- *     #GTask also tries to simplify asynchronous operations that
- *     internally chain together several smaller asynchronous
- *     operations. g_task_get_cancellable(), g_task_get_context(), and
- *     g_task_get_priority() allow you to get back the task's
- *     #GCancellable, #GMainContext, and <link
- *     linkend="io-priority">I/O priority</link> when starting a new
- *     subtask, so you don't have to keep track of them yourself.
- *     g_task_attach_source() simplifies the case of waiting for a
- *     source to fire (automatically using the correct #GMainContext
- *     and priority).
- *   </para>
- *   <example id="gtask-chained"><title>Chained asynchronous operations</title>
- *   <programlisting>
+ * ]|
+ *
+ * ## Chained asynchronous operations
+ *
+ * #GTask also tries to simplify asynchronous operations that
+ * internally chain together several smaller asynchronous
+ * operations. g_task_get_cancellable(), g_task_get_context(), and
+ * g_task_get_priority() allow you to get back the task's
+ * #GCancellable, #GMainContext, and <link
+ * linkend="io-priority">I/O priority</link> when starting a new
+ * subtask, so you don't have to keep track of them yourself.
+ * g_task_attach_source() simplifies the case of waiting for a
+ * source to fire (automatically using the correct #GMainContext
+ * and priority).
+ *
+ * Here is an example for chained asynchronous operations:
+ *   |[<!-- language="C" -->
  *     typedef struct {
  *       Cake *cake;
  *       CakeFrostingType frosting;
@@ -7606,19 +7618,17 @@
  *
  *       return g_task_propagate_pointer (G_TASK (result), error);
  *     }
- *   </programlisting>
- *   </example>
- * </refsect2>
- * <refsect2>
- *   <title>Asynchronous operations from synchronous ones</title>
- *   <para>
- *     You can use g_task_run_in_thread() to turn a synchronous
- *     operation into an asynchronous one, by running it in a thread
- *     which will then dispatch the result back to the caller's
- *     #GMainContext when it completes.
- *   </para>
- *   <example id="gtask-run-in-thread"><title>g_task_run_in_thread()</title>
- *   <programlisting>
+ * ]|
+ *
+ * ## Asynchronous operations from synchronous ones
+ *
+ * You can use g_task_run_in_thread() to turn a synchronous
+ * operation into an asynchronous one, by running it in a thread
+ * which will then dispatch the result back to the caller's
+ * #GMainContext when it completes.
+ *
+ * Running a task in a thread:
+ *   |[<!-- language="C" -->
  *     typedef struct {
  *       guint radius;
  *       CakeFlavor flavor;
@@ -7685,26 +7695,24 @@
  *
  *       return g_task_propagate_pointer (G_TASK (result), error);
  *     }
- *   </programlisting>
- *   </example>
- * </refsect2>
- * <refsect2>
- *   <title>Adding cancellability to uncancellable tasks</title>
- *   <para>
- *     Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
- *     can be used to turn an uncancellable operation into a
- *     cancellable one. If you call g_task_set_return_on_cancel(),
- *     passing %TRUE, then if the task's #GCancellable is cancelled,
- *     it will return control back to the caller immediately, while
- *     allowing the task thread to continue running in the background
- *     (and simply discarding its result when it finally does finish).
- *     Provided that the task thread is careful about how it uses
- *     locks and other externally-visible resources, this allows you
- *     to make "GLib-friendly" asynchronous and cancellable
- *     synchronous variants of blocking APIs.
- *   </para>
- *   <example id="gtask-cancellable"><title>g_task_set_return_on_cancel()</title>
- *   <programlisting>
+ * ]|
+ *
+ * ## Adding cancellability to uncancellable tasks
+ *
+ * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
+ * can be used to turn an uncancellable operation into a
+ * cancellable one. If you call g_task_set_return_on_cancel(),
+ * passing %TRUE, then if the task's #GCancellable is cancelled,
+ * it will return control back to the caller immediately, while
+ * allowing the task thread to continue running in the background
+ * (and simply discarding its result when it finally does finish).
+ * Provided that the task thread is careful about how it uses
+ * locks and other externally-visible resources, this allows you
+ * to make "GLib-friendly" asynchronous and cancellable
+ * synchronous variants of blocking APIs.
+ *
+ * Cancelling a task:
+ *   |[<!-- language="C" -->
  *     static void
  *     bake_cake_thread (GTask         *task,
  *                       gpointer       source_object,
@@ -7793,81 +7801,63 @@
  *       g_object_unref (task);
  *       return cake;
  *     }
- *   </programlisting>
- *   </example>
- * </refsect2>
- * <refsect2>
- *   <title>Porting from <literal>GSimpleAsyncResult</literal></title>
- *   <para>
- *     #GTask's API attempts to be simpler than #GSimpleAsyncResult's
- *     in several ways:
- *   </para>
- *   <itemizedlist>
- *     <listitem><para>
- *       You can save task-specific data with g_task_set_task_data(), and
- *       retrieve it later with g_task_get_task_data(). This replaces the
- *       abuse of g_simple_async_result_set_op_res_gpointer() for the same
- *       purpose with #GSimpleAsyncResult.
- *     </para></listitem>
- *     <listitem><para>
- *       In addition to the task data, #GTask also keeps track of the
- *       <link linkend="io-priority">priority</link>, #GCancellable, and
- *       #GMainContext associated with the task, so tasks that consist of
- *       a chain of simpler asynchronous operations will have easy access
- *       to those values when starting each sub-task.
- *     </para></listitem>
- *     <listitem><para>
- *       g_task_return_error_if_cancelled() provides simplified
- *       handling for cancellation. In addition, cancellation
- *       overrides any other #GTask return value by default, like
- *       #GSimpleAsyncResult does when
- *       g_simple_async_result_set_check_cancellable() is called.
- *       (You can use g_task_set_check_cancellable() to turn off that
- *       behavior.) On the other hand, g_task_run_in_thread()
- *       guarantees that it will always run your
- *       <literal>task_func</literal>, even if the task's #GCancellable
- *       is already cancelled before the task gets a chance to run;
- *       you can start your <literal>task_func</literal> with a
- *       g_task_return_error_if_cancelled() check if you need the
- *       old behavior.
- *     </para></listitem>
- *     <listitem><para>
- *       The "return" methods (eg, g_task_return_pointer())
- *       automatically cause the task to be "completed" as well, and
- *       there is no need to worry about the "complete" vs "complete
- *       in idle" distinction. (#GTask automatically figures out
- *       whether the task's callback can be invoked directly, or
- *       if it needs to be sent to another #GMainContext, or delayed
- *       until the next iteration of the current #GMainContext.)
- *     </para></listitem>
- *     <listitem><para>
- *       The "finish" functions for #GTask-based operations are generally
- *       much simpler than #GSimpleAsyncResult ones, normally consisting
- *       of only a single call to g_task_propagate_pointer() or the like.
- *       Since g_task_propagate_pointer() "steals" the return value from
- *       the #GTask, it is not necessary to juggle pointers around to
- *       prevent it from being freed twice.
- *     </para></listitem>
- *     <listitem><para>
- *       With #GSimpleAsyncResult, it was common to call
- *       g_simple_async_result_propagate_error() from the
- *       <literal>_finish()</literal> wrapper function, and have
- *       virtual method implementations only deal with successful
- *       returns. This behavior is deprecated, because it makes it
- *       difficult for a subclass to chain to a parent class's async
- *       methods. Instead, the wrapper function should just be a
- *       simple wrapper, and the virtual method should call an
- *       appropriate <literal>g_task_propagate_</literal> function.
- *       Note that wrapper methods can now use
- *       g_async_result_legacy_propagate_error() to do old-style
- *       #GSimpleAsyncResult error-returning behavior, and
- *       g_async_result_is_tagged() to check if a result is tagged as
- *       having come from the <literal>_async()</literal> wrapper
- *       function (for "short-circuit" results, such as when passing
- *       0 to g_input_stream_read_async()).
- *     </para></listitem>
- *   </itemizedlist>
- * </refsect2>
+ * ]|
+ *
+ * ## Porting from GSimpleAsyncResult
+ *
+ * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
+ * in several ways:
+ * - You can save task-specific data with g_task_set_task_data(), and
+ *   retrieve it later with g_task_get_task_data(). This replaces the
+ *   abuse of g_simple_async_result_set_op_res_gpointer() for the same
+ *   purpose with #GSimpleAsyncResult.
+ * - In addition to the task data, #GTask also keeps track of the
+ *   <link linkend="io-priority">priority</link>, #GCancellable, and
+ *   #GMainContext associated with the task, so tasks that consist of
+ *   a chain of simpler asynchronous operations will have easy access
+ *   to those values when starting each sub-task.
+ * - g_task_return_error_if_cancelled() provides simplified
+ *   handling for cancellation. In addition, cancellation
+ *   overrides any other #GTask return value by default, like
+ *   #GSimpleAsyncResult does when
+ *   g_simple_async_result_set_check_cancellable() is called.
+ *   (You can use g_task_set_check_cancellable() to turn off that
+ *   behavior.) On the other hand, g_task_run_in_thread()
+ *   guarantees that it will always run your
+ *   `task_func`, even if the task's #GCancellable
+ *   is already cancelled before the task gets a chance to run;
+ *   you can start your `task_func` with a
+ *   g_task_return_error_if_cancelled() check if you need the
+ *   old behavior.
+ * - The "return" methods (eg, g_task_return_pointer())
+ *   automatically cause the task to be "completed" as well, and
+ *   there is no need to worry about the "complete" vs "complete
+ *   in idle" distinction. (#GTask automatically figures out
+ *   whether the task's callback can be invoked directly, or
+ *   if it needs to be sent to another #GMainContext, or delayed
+ *   until the next iteration of the current #GMainContext.)
+ * - The "finish" functions for #GTask-based operations are generally
+ *   much simpler than #GSimpleAsyncResult ones, normally consisting
+ *   of only a single call to g_task_propagate_pointer() or the like.
+ *   Since g_task_propagate_pointer() "steals" the return value from
+ *   the #GTask, it is not necessary to juggle pointers around to
+ *   prevent it from being freed twice.
+ * - With #GSimpleAsyncResult, it was common to call
+ *   g_simple_async_result_propagate_error() from the
+ *   `_finish()` wrapper function, and have
+ *   virtual method implementations only deal with successful
+ *   returns. This behavior is deprecated, because it makes it
+ *   difficult for a subclass to chain to a parent class's async
+ *   methods. Instead, the wrapper function should just be a
+ *   simple wrapper, and the virtual method should call an
+ *   appropriate `g_task_propagate_` function.
+ *   Note that wrapper methods can now use
+ *   g_async_result_legacy_propagate_error() to do old-style
+ *   #GSimpleAsyncResult error-returning behavior, and
+ *   g_async_result_is_tagged() to check if a result is tagged as
+ *   having come from the `_async()` wrapper
+ *   function (for "short-circuit" results, such as when passing
+ *   0 to g_input_stream_read_async()).
  */
 
 
@@ -7911,88 +7901,75 @@
  * A helper class for testing code which uses D-Bus without touching the user's
  * session bus.
  *
- * Note that #GTestDBus modifies the user’s environment, calling setenv(). This
- * is not thread-safe, so all #GTestDBus calls should be completed before
+ * Note that #GTestDBus modifies the user’s environment, calling setenv().
+ * This is not thread-safe, so all #GTestDBus calls should be completed before
  * threads are spawned, or should have appropriate locking to ensure no access
  * conflicts to environment variables shared between #GTestDBus and other
  * threads.
  *
- * <refsect2 id="gio-D-Bus-Test-Scaffolding">
- *   <title>Creating unit tests using GTestDBus</title>
- *   <para>
- *     Testing of D-Bus services can be tricky because normally we only ever run
- *     D-Bus services over an existing instance of the D-Bus daemon thus we
- *     usually don't activate D-Bus services that are not yet installed into the
- *     target system. The #GTestDBus object makes this easier for us by taking care
- *     of the lower level tasks such as running a private D-Bus daemon and looking
- *     up uninstalled services in customizable locations, typically in your source code tree.
- *   </para>
- *   <para>
- *     The first thing you will need is a separate service description file for the
- *     D-Bus daemon. Typically a <filename>services</filename> subdirectory of
- *     your <filename>tests</filename> directory
- *     is a good place to put this file.
- *   </para>
- *   <para>
- *     The service file should list your service along with an absolute path to the
- *     uninstalled service executable in your source tree. Using autotools we would
- *     achieve this by adding a file such as <filename>my-server.service.in</filename>
- *     in the services
- *     directory and have it processed by configure.
- *     <informalexample><programlisting>
+ * ## Creating unit tests using GTestDBus
+ *
+ * Testing of D-Bus services can be tricky because normally we only ever run
+ * D-Bus services over an existing instance of the D-Bus daemon thus we
+ * usually don't activate D-Bus services that are not yet installed into the
+ * target system. The #GTestDBus object makes this easier for us by taking care
+ * of the lower level tasks such as running a private D-Bus daemon and looking
+ * up uninstalled services in customizable locations, typically in your source
+ * code tree.
+ *
+ * The first thing you will need is a separate service description file for the
+ * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
+ * is a good place to put this file.
+ *
+ * The service file should list your service along with an absolute path to the
+ * uninstalled service executable in your source tree. Using autotools we would
+ * achieve this by adding a file such as `my-server.service.in` in the services
+ * directory and have it processed by configure.
+ * |[
  *     [D-BUS Service]
  *     Name=org.gtk.GDBus.Examples.ObjectManager
  *     Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
- *     </programlisting></informalexample>
- *     You will also need to indicate this service directory in your test
- *     fixtures, so you will need to pass the path while compiling your
- *     test cases. Typically this is done with autotools with an added
- *     preprocessor flag specified to compile your tests such as:
- *     <informalexample><programlisting>
+ * ]|
+ * You will also need to indicate this service directory in your test
+ * fixtures, so you will need to pass the path while compiling your
+ * test cases. Typically this is done with autotools with an added
+ * preprocessor flag specified to compile your tests such as:
+ * |[
  *     -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
- *     </programlisting></informalexample>
- *   </para>
- *   <para>
+ * ]|
  *     Once you have a service definition file which is local to your source tree,
- *     you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
- *     <example id="gdbus-test-fixture">
- *       <title>Test Fixture for D-Bus services</title>
- *       <programlisting>
- *         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-test-fixture.c">
- *           <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- *         </xi:include>
- *       </programlisting>
- *     </example>
- *   </para>
- *   <para>
- *     Note that these examples only deal with isolating the D-Bus aspect of your
- *     service. To successfully run isolated unit tests on your service you may need
- *     some additional modifications to your test case fixture. For example; if your
- *     service uses GSettings and installs a schema then it is important that your test service
- *     not load the schema in the ordinary installed location (chances are that your service
- *     and schema files are not yet installed, or worse; there is an older version of the
- *     schema file sitting in the install location).
- *   </para>
- *   <para>
- *     Most of the time we can work around these obstacles using the environment. Since the
- *     environment is inherited by the D-Bus daemon created by #GTestDBus and then in turn
- *     inherited by any services the D-Bus daemon activates, using the setup routine for your
- *     fixture is a practical place to help sandbox your runtime environment. For the rather
- *     typical GSettings case we can work around this by setting <envar>GSETTINGS_SCHEMA_DIR</envar> to the
- *     in tree directory holding your schemas in the above fixture_setup() routine.
- *   </para>
- *   <para>
- *     The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
- *     by compiling the schemas locally as a step before running test cases, an autotools setup might
- *     do the following in the directory holding schemas:
- *     <informalexample><programlisting>
+ * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
+ *
+ * An example of a test fixture for D-Bus services can be found
+ * here:
+ * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c)
+ *
+ * Note that these examples only deal with isolating the D-Bus aspect of your
+ * service. To successfully run isolated unit tests on your service you may need
+ * some additional modifications to your test case fixture. For example; if your
+ * service uses GSettings and installs a schema then it is important that your test service
+ * not load the schema in the ordinary installed location (chances are that your service
+ * and schema files are not yet installed, or worse; there is an older version of the
+ * schema file sitting in the install location).
+ *
+ * Most of the time we can work around these obstacles using the
+ * environment. Since the environment is inherited by the D-Bus daemon
+ * created by #GTestDBus and then in turn inherited by any services the
+ * D-Bus daemon activates, using the setup routine for your fixture is
+ * a practical place to help sandbox your runtime environment. For the
+ * rather typical GSettings case we can work around this by setting
+ * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
+ * in the above fixture_setup() routine.
+ *
+ * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
+ * by compiling the schemas locally as a step before running test cases, an autotools setup might
+ * do the following in the directory holding schemas:
+ * |[
  *     all-am:
  *             $(GLIB_COMPILE_SCHEMAS) .
  *
  *     CLEANFILES += gschemas.compiled
- *     </programlisting></informalexample>
- *   </para>
- * </refsect2>
+ * ]|
  */
 
 
@@ -8210,9 +8187,9 @@
  * It contains functions to do some of the UNIX socket specific
  * functionality like passing file descriptors.
  *
- * Note that <filename>&lt;gio/gunixconnection.h&gt;</filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gunixconnection.h&gt;` belongs to the UNIX-specific
+ * GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
+ * pkg-config file when using it.
  *
  * Since: 2.22
  */
@@ -8253,9 +8230,9 @@
  * the %G_SOCKET_ADDRESS_UNIX family by using g_socket_send_message()
  * and received using g_socket_receive_message().
  *
- * Note that <filename>&lt;gio/gunixfdlist.h&gt;</filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gunixfdlist.h&gt;` belongs to the UNIX-specific GIO
+ * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+ * file when using it.
  */
 
 
@@ -8276,9 +8253,9 @@
  * stream-oriented UNIX sockets, see g_unix_connection_send_fd() and
  * g_unix_connection_receive_fd().
  *
- * Note that <filename>&lt;gio/gunixfdmessage.h&gt;</filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gunixfdmessage.h&gt;` belongs to the UNIX-specific GIO
+ * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+ * file when using it.
  */
 
 
@@ -8294,9 +8271,9 @@
  * asynchronous I/O. If it refers to a regular file, it will fall back
  * to doing asynchronous I/O in another thread.)
  *
- * Note that <filename>&lt;gio/gunixinputstream.h&gt;</filename> belongs
- * to the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gunixinputstream.h&gt;` belongs to the UNIX-specific GIO
+ * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+ * file when using it.
  */
 
 
@@ -8307,9 +8284,9 @@
  *
  * Routines for managing mounted UNIX mount points and paths.
  *
- * Note that <filename>&lt;gio/gunixmounts.h&gt;</filename> belongs to the
- * UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gunixmounts.h&gt;` belongs to the UNIX-specific GIO
+ * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
+ * file when using it.
  */
 
 
@@ -8325,9 +8302,9 @@
  * asynchronous I/O. If it refers to a regular file, it will fall back
  * to doing asynchronous I/O in another thread.)
  *
- * Note that <filename>&lt;gio/gunixoutputstream.h&gt;</filename> belongs
- * to the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gunixoutputstream.h&gt;` belongs to the UNIX-specific GIO
+ * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
+ * when using it.
  */
 
 
@@ -8347,9 +8324,9 @@
  * errors. You can use g_unix_socket_address_abstract_names_supported()
  * to see if abstract names are supported.
  *
- * Note that <filename>&lt;gio/gunixsocketaddress.h&gt;</filename> belongs to
- * the UNIX-specific GIO interfaces, thus you have to use the
- * <filename>gio-unix-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gunixsocketaddress.h&gt;` belongs to the UNIX-specific GIO
+ * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
+ * when using it.
  */
 
 
@@ -8390,18 +8367,18 @@
  * successfully.  If an @error is present when g_volume_mount_finish()
  * is called, then it will be filled with any error information.
  *
- * <para id="volume-identifier">
+ * ## Volume Identifiers # {#volume-identifier}
+ *
  * 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
  * different kinds of identifiers, such as Hal UDIs, filesystem labels,
- * traditional Unix devices (e.g. <filename>/dev/sda2</filename>),
- * uuids. GIO uses predefind strings as names for the different kinds
- * of identifiers: #G_VOLUME_IDENTIFIER_KIND_HAL_UDI,
- * #G_VOLUME_IDENTIFIER_KIND_LABEL, etc. Use g_volume_get_identifier()
- * to obtain an identifier for a volume.
- * </para>
+ * traditional Unix devices (e.g. `/dev/sda2`), UUIDs. GIO uses predefined
+ * strings as names for the different kinds of identifiers:
+ * #G_VOLUME_IDENTIFIER_KIND_HAL_UDI, #G_VOLUME_IDENTIFIER_KIND_LABEL, etc.
+ * Use g_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
@@ -8437,9 +8414,9 @@
  * #GWin32InputStream implements #GInputStream for reading from a
  * Windows file handle.
  *
- * Note that <filename>&lt;gio/gwin32inputstream.h&gt;</filename> belongs
- * to the Windows-specific GIO interfaces, thus you have to use the
- * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gwin32inputstream.h&gt;` belongs to the Windows-specific GIO
+ * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
+ * when using it.
  */
 
 
@@ -8452,9 +8429,9 @@
  * #GWin32OutputStream implements #GOutputStream for writing to a
  * Windows file handle.
  *
- * Note that <filename>&lt;gio/gwin32outputstream.h&gt;</filename> belongs
- * to the Windows-specific GIO interfaces, thus you have to use the
- * <filename>gio-windows-2.0.pc</filename> pkg-config file when using it.
+ * Note that `&lt;gio/gwin32outputstream.h&gt;` belongs to the Windows-specific GIO
+ * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
+ * when using it.
  */
 
 
@@ -10433,9 +10410,7 @@
  *
  * Each action is constructed as per one #GActionEntry.
  *
- * <example>
- * <title>Using g_action_map_add_action_entries()</title>
- * <programlisting>
+ * |[<!-- language="C" -->
  * static void
  * activate_quit (GSimpleAction *simple,
  *                GVariant      *parameter,
@@ -10466,8 +10441,7 @@
  *
  *   return G_ACTION_GROUP (group);
  * }
- * </programlisting>
- * </example>
+ * ]|
  *
  * Since: 2.32
  */
@@ -10622,8 +10596,8 @@
  * Creates a new #GAppInfo from the given information.
  *
  * Note that for @commandline, the quoting rules of the Exec key of the
- * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">freedesktop.org Desktop
- * Entry Specification</ulink> are applied. For example, if the @commandline contains
+ * [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
+ * are applied. For example, if the @commandline contains
  * percent-encoded URIs, the percent-character must be doubled in order to prevent it from
  * being swallowed by Exec key unquoting. See the specification for exact quoting rules.
  *
@@ -10638,8 +10612,8 @@
  * Tries to delete a #GAppInfo.
  *
  * On some platforms, there may be a difference between user-defined
- * #GAppInfo<!-- -->s which can be deleted, and system-wide ones which
- * cannot. See g_app_info_can_delete().
+ * #GAppInfos which can be deleted, and system-wide ones which cannot.
+ * See g_app_info_can_delete().
  *
  * Returns: %TRUE if @appinfo has been deleted
  * Since: 2.20
@@ -10661,7 +10635,7 @@
  * @appinfo1: the first #GAppInfo.
  * @appinfo2: the second #GAppInfo.
  *
- * Checks if two #GAppInfo<!-- -->s are equal.
+ * Checks if two #GAppInfos are equal.
  *
  * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
  */
@@ -10674,13 +10648,12 @@
  * on this system.
  *
  * For desktop files, this includes applications that have
- * <literal>NoDisplay=true</literal> set or are excluded from
- * display by means of <literal>OnlyShowIn</literal> or
- * <literal>NotShowIn</literal>. See g_app_info_should_show().
+ * `NoDisplay=true` set or are excluded from display by means
+ * of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show().
  * The returned list does not include applications which have
- * the <literal>Hidden</literal> key set.
+ * the `Hidden` key set.
  *
- * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfo<!---->s.
+ * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos.
  */
 
 
@@ -10881,17 +10854,16 @@
  * g_app_info_launch_uris() instead.
  *
  * The launched application inherits the environment of the launching
- * process, but it can be modified with g_app_launch_context_setenv() and
- * g_app_launch_context_unsetenv().
+ * process, but it can be modified with g_app_launch_context_setenv()
+ * and g_app_launch_context_unsetenv().
  *
- * On UNIX, this function sets the <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>
+ * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE`
  * environment variable with the path of the launched desktop file and
- * <envar>GIO_LAUNCHED_DESKTOP_FILE_PID</envar> to the process
- * id of the launched process. This can be used to ignore
- * <envar>GIO_LAUNCHED_DESKTOP_FILE</envar>, should it be inherited
- * by further processes. The <envar>DISPLAY</envar> and
- * <envar>DESKTOP_STARTUP_ID</envar> environment variables are also
- * set, based on information provided in @launch_context.
+ * `GIO_LAUNCHED_DESKTOP_FILE_PID` to the process id of the launched
+ * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
+ * should it be inherited by further processes. The `DISPLAY` and
+ * `DESKTOP_STARTUP_ID` environment variables are also set, based
+ * on information provided in @launch_context.
  *
  * Returns: %TRUE on successful launch, %FALSE otherwise.
  */
@@ -11056,7 +11028,7 @@
  *
  * Gets the display string for the @context. This is used to ensure new
  * applications are started on the same display as the launching
- * application, by setting the <envar>DISPLAY</envar> environment variable.
+ * application, by setting the `DISPLAY` environment variable.
  *
  * Returns: a display string for the display.
  */
@@ -11069,7 +11041,7 @@
  * Gets the complete environment variable list to be passed to
  * the child process when @context is used to launch an application.
  * This is a %NULL-terminated array of strings, where each string has
- * the form <literal>KEY=VALUE</literal>.
+ * the form `KEY=VALUE`.
  *
  * Returns: (array zero-terminated=1) (transfer full): the
  *     child's environment
@@ -11084,12 +11056,10 @@
  * @files: (element-type GFile): a #GList of of #GFile objects
  *
  * Initiates startup notification for the application and returns the
- * <envar>DESKTOP_STARTUP_ID</envar> for the launched operation,
- * if supported.
+ * `DESKTOP_STARTUP_ID` for the launched operation, if supported.
  *
- * Startup notification IDs are defined in the <ulink
- * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt">
- * FreeDesktop.Org Startup Notifications standard</ulink>.
+ * Startup notification IDs are defined in the
+ * [FreeDesktop.Org Startup Notifications standard](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt").
  *
  * Returns: a startup notification ID for the application, or %NULL if
  *     not supported.
@@ -11157,6 +11127,95 @@
 
 
 /**
+ * g_application_add_main_option_entries:
+ * @application: a #GApplication
+ * @entries: a %NULL-terminated list of #GOptionEntrys
+ *
+ * Adds main option entries to be handled by @application.
+ *
+ * This function is comparable to g_option_context_add_main_entries().
+ *
+ * After the commandline arguments are parsed, the
+ * #GApplication::handle-local-options signal will be emitted.  At this
+ * point, the application can inspect the values pointed to by @arg_data
+ * in the given #GOptionEntrys.
+ *
+ * Unlike #GOptionContext, #GApplication supports giving a %NULL
+ * @arg_data for a non-callback #GOptionEntry.  This results in the
+ * argument in question being packed into a #GVariantDict which is also
+ * passed to #GApplication::handle-local-options, where it can be
+ * inspected and modified.  If %G_APPLICATION_HANDLES_COMMAND_LINE is
+ * set, then the resulting dictionary is sent to the primary instance,
+ * where g_application_command_line_get_options_dict() will return it.
+ * This "packing" is done according to the type of the argument --
+ * booleans for normal flags, strings for strings, bytestrings for
+ * filenames, etc.  The packing only occurs if the flag is given (ie: we
+ * do not pack a "false" #GVariant in the case that a flag is missing).
+ *
+ * In general, it is recommended that all commandline arguments are
+ * parsed locally.  The options dictionary should then be used to
+ * transmit the result of the parsing to the primary instance, where
+ * g_variant_dict_lookup() can be used.  For local options, it is
+ * possible to either use @arg_data in the usual way, or to consult (and
+ * potentially remove) the option from the options dictionary.
+ *
+ * This function is new in GLib 2.40.  Before then, the only real choice
+ * was to send all of the commandline arguments (options and all) to the
+ * primary instance for handling.  #GApplication ignored them completely
+ * on the local side.  Calling this function "opts in" to the new
+ * behaviour, and in particular, means that unrecognised options will be
+ * treated as errors.  Unrecognised options have never been ignored when
+ * %G_APPLICATION_HANDLES_COMMAND_LINE is unset.
+ *
+ * If #GApplication::handle-local-options needs to see the list of
+ * filenames, then the use of %G_OPTION_REMAINING is recommended.  If
+ * @arg_data is %NULL then %G_OPTION_REMAINING can be used as a key into
+ * the options dictionary.  If you do use %G_OPTION_REMAINING then you
+ * need to handle these arguments for yourself because once they are
+ * consumed, they will no longer be visible to the default handling
+ * (which treats them as filenames to be opened).
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_application_add_option_group:
+ * @application: the #GApplication
+ * @group: a #GOptionGroup
+ *
+ * Adds a #GOptionGroup to the commandline handling of @application.
+ *
+ * This function is comparable to g_option_context_add_group().
+ *
+ * Unlike g_application_add_main_option_entries(), this function does
+ * not deal with %NULL @arg_data and never transmits options to the
+ * primary instance.
+ *
+ * The reason for that is because, by the time the options arrive at the
+ * primary instance, it is typically too late to do anything with them.
+ * Taking the GTK option group as an example: GTK will already have been
+ * initialised by the time the #GApplication::command-line handler runs.
+ * In the case that this is not the first-running instance of the
+ * application, the existing instance may already have been running for
+ * a very long time.
+ *
+ * This means that the options from #GOptionGroup are only really usable
+ * in the case that the instance of the application being run is the
+ * first instance.  Passing options like <literal>--display=</literal>
+ * or <literal>--gdk-debug=</literal> on future runs will have no effect
+ * on the existing primary instance.
+ *
+ * Calling this function will cause the options in the supplied option
+ * group to be parsed, but it does not cause you to be "opted in" to the
+ * new functionality whereby unrecognised options are rejected even if
+ * %G_APPLICATION_HANDLES_COMMAND_LINE was given.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * g_application_command_line_create_file_for_arg:
  * @cmdline: a #GApplicationCommandLine
  * @arg: an argument from @cmdline
@@ -11264,6 +11323,25 @@
 
 
 /**
+ * g_application_command_line_get_options_dict:
+ * @cmdline: a #GApplicationCommandLine
+ *
+ * Gets the options there were passed to g_application_command_line().
+ *
+ * If you did not override local_command_line() then these are the same
+ * options that were parsed according to the #GOptionEntrys added to the
+ * application with g_application_add_main_option_entries() and possibly
+ * modified from your GApplication::handle-local-options handler.
+ *
+ * If no options were sent then an empty dictionary is returned so that
+ * you don't need to check for %NULL.
+ *
+ * Returns: (transfer none): a #GVariantDict with the options
+ * Since: 2.40
+ */
+
+
+/**
  * g_application_command_line_get_platform_data:
  * @cmdline: #GApplicationCommandLine
  *
@@ -11548,13 +11626,20 @@
  *
  * For convenience, the restrictions on application identifiers are
  * reproduced here:
- * <itemizedlist>
- *   <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
- *   <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
- *   <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
- *   <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
- *   <listitem>Application identifiers must not exceed 255 characters.</listitem>
- * </itemizedlist>
+ *
+ * - Application identifiers must contain only the ASCII characters
+ *   "[A-Z][a-z][0-9]_-." and must not begin with a digit.
+ *
+ * - Application identifiers must contain at least one '.' (period)
+ *   character (and thus at least three elements).
+ *
+ * - Application identifiers must not begin or end with a '.' (period)
+ *   character.
+ *
+ * - Application identifiers must not contain consecutive '.' (period)
+ *   characters.
+ *
+ * - Application identifiers must not exceed 255 characters.
  *
  * Returns: %TRUE if @application_id is valid
  */
@@ -11711,49 +11796,28 @@
  * g_win32_get_command_line() is called internally (for proper support
  * of Unicode commandline arguments).
  *
- * First, the local_command_line() virtual function is invoked.
- * This function always runs on the local instance. It gets passed a pointer
- * to a %NULL-terminated copy of the command line and is expected to
- * remove the arguments that it handled (shifting up remaining
- * arguments). See <xref linkend="gapplication-example-cmdline2"/> for
- * an example of parsing @argv manually. Alternatively, you may use the
- * #GOptionContext API, but you must use g_option_context_parse_strv()
- * in order to avoid memory leaks and encoding mismatches.
- *
- * The last argument to local_command_line() is a pointer to the @status
- * variable which can used to set the exit status that is returned from
- * g_application_run().
- *
- * If local_command_line() returns %TRUE, the command line is expected
- * to be completely handled, including possibly registering as the primary
- * instance, calling g_application_activate() or g_application_open(), etc.
- *
- * If local_command_line() returns %FALSE then the application is registered
- * and the #GApplication::command-line signal is emitted in the primary
- * instance (which may or may not be this instance). The signal handler
- * gets passed a #GApplicationCommandLine object that (among other things)
- * contains the remaining commandline arguments that have not been handled
- * by local_command_line().
- *
- * If the application has the %G_APPLICATION_HANDLES_COMMAND_LINE
- * flag set then the default implementation of local_command_line()
- * always returns %FALSE immediately, resulting in the commandline
- * always being handled in the primary instance.
- *
- * Otherwise, the default implementation of local_command_line() tries
- * to do a couple of things that are probably reasonable for most
- * applications.  First, g_application_register() is called to attempt
- * to register the application.  If that works, then the command line
- * arguments are inspected.  If no commandline arguments are given, then
- * g_application_activate() is called.  If commandline arguments are
- * given and the %G_APPLICATION_HANDLES_OPEN flag is set then they
- * are assumed to be filenames and g_application_open() is called.
- *
- * If you need to handle commandline arguments that are not filenames,
- * and you don't mind commandline handling to happen in the primary
- * instance, you should set %G_APPLICATION_HANDLES_COMMAND_LINE and
- * process the commandline arguments in your #GApplication::command-line
- * signal handler, either manually or using the #GOptionContext API.
+ * #GApplication will attempt to parse the commandline arguments.  You
+ * can add commandline flags to the list of recognised options by way of
+ * g_application_add_main_option_entries().  After this, the
+ * #GApplication::handle-local-options signal is emitted, from which the
+ * application can inspect the values of its #GOptionEntrys.
+ *
+ * #GApplication::handle-local-options is a good place to handle options
+ * such as <literal>--version</literal>, where an immediate reply from
+ * the local process is desired (instead of communicating with an
+ * already-running instance).  A #GApplication::handle-local-options
+ * handler can stop further processing by returning a non-negative
+ * value, which then becomes the exit status of the process.
+ *
+ * What happens next depends on the flags: if
+ * %G_APPLICATION_HANDLES_COMMAND_LINE was specified then the remaining
+ * commandline arguments are sent to the primary instance, where a
+ * #GApplication::command-line signal is emitted.  Otherwise, the
+ * remaining commandline arguments are assumed to be a list of files.
+ * If there are no files listed, the application is activated via the
+ * #GApplication::activate signal.  If there are one or more files, and
+ * %G_APPLICATION_HANDLES_OPEN was specified then the files are opened
+ * via the #GApplication::open signal.
  *
  * If you are interested in doing more complicated local handling of the
  * commandline then you should implement your own #GApplication subclass
@@ -12157,13 +12221,12 @@
  * g_simple_async_result_propagate_error(). Otherwise it returns
  * %FALSE.
  *
- * This can be used for legacy error handling in async
- * <literal>_finish ()</literal> wrapper functions that traditionally
- * handled #GSimpleAsyncResult error returns themselves rather than
- * calling into the virtual method. This should not be used in new
- * code; #GAsyncResult errors that are set by virtual methods should
- * also be extracted by virtual methods, to enable subclasses to chain
- * up correctly.
+ * This can be used for legacy error handling in async *_finish()
+ * wrapper functions that traditionally handled #GSimpleAsyncResult
+ * error returns themselves rather than calling into the virtual method.
+ * This should not be used in new code; #GAsyncResult errors that are
+ * set by virtual methods should also be extracted by virtual methods,
+ * to enable subclasses to chain up correctly.
  *
  * Returns: %TRUE if @error is has been filled in with an error from
  *   @res, %FALSE if not.
@@ -12411,10 +12474,10 @@
 
 /**
  * g_bus_get:
- * @bus_type: A #GBusType.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
+ * @bus_type: a #GBusType
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to @callback
  *
  * Asynchronously connects to the message bus specified by @bus_type.
  *
@@ -12430,8 +12493,9 @@
 
 /**
  * g_bus_get_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_bus_get().
- * @error: Return location for error or %NULL.
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ *     to g_bus_get()
+ * @error: return location for error or %NULL
  *
  * Finishes an operation started with g_bus_get().
  *
@@ -12444,16 +12508,17 @@
  * Note that the returned #GDBusConnection object will (usually) have
  * the #GDBusConnection:exit-on-close property set to %TRUE.
  *
- * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
+ *     Free with g_object_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_bus_get_sync:
- * @bus_type: A #GBusType.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @bus_type: a #GBusType
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously connects to the message bus specified by @bus_type.
  * Note that the returned object may shared with other callers,
@@ -12472,21 +12537,22 @@
  * Note that the returned #GDBusConnection object will (usually) have
  * the #GDBusConnection:exit-on-close property set to %TRUE.
  *
- * Returns: (transfer full): A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set.
+ *     Free with g_object_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_bus_own_name:
- * @bus_type: The type of bus to own a name on.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
- * @bus_acquired_handler: (allow-none): Handler to invoke when connected to the bus of type @bus_type or %NULL.
- * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL.
- * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
+ * @bus_type: the type of bus to own a name on
+ * @name: the well-known name to own
+ * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
+ * @bus_acquired_handler: (allow-none): handler to invoke when connected to the bus of type @bus_type or %NULL
+ * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
+ * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
+ * @user_data: user data to pass to handlers
+ * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
  *
  * Starts acquiring @name on the bus specified by @bus_type and calls
  * @name_acquired_handler and @name_lost_handler when the name is
@@ -12497,26 +12563,25 @@
  * You are guaranteed that one of the @name_acquired_handler and @name_lost_handler
  * callbacks will be invoked after calling this function - there are three
  * possible cases:
- * <itemizedlist>
- *   <listitem><para>
- *     @name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
- *   </para></listitem>
- *   <listitem><para>
- *     @bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
- *   </para></listitem>
- *   <listitem><para>
- *     @bus_acquired_handler then @name_acquired_handler (if the name was obtained).
- *   </para></listitem>
- * </itemizedlist>
+ *
+ * - @name_lost_handler with a %NULL connection (if a connection to the bus
+ *   can't be made).
+ *
+ * - @bus_acquired_handler then @name_lost_handler (if the name can't be
+ *   obtained)
+ *
+ * - @bus_acquired_handler then @name_acquired_handler (if the name was
+ *   obtained).
+ *
  * When you are done owning the name, just call g_bus_unown_name()
  * with the owner id this function returns.
  *
  * If the name is acquired or lost (for example another application
  * could acquire the name if you allow replacement or the application
- * currently owning the name exits), the handlers are also invoked. If the
- * #GDBusConnection that is used for attempting to own the name
- * closes, then @name_lost_handler is invoked since it is no
- * longer possible for other processes to access the process.
+ * currently owning the name exits), the handlers are also invoked.
+ * If the #GDBusConnection that is used for attempting to own the name
+ * closes, then @name_lost_handler is invoked since it is no longer
+ * possible for other processes to access the process.
  *
  * You cannot use g_bus_own_name() several times for the same name (unless
  * interleaved with calls to g_bus_unown_name()) - only the first call
@@ -12539,74 +12604,74 @@
  * Simply register objects to be exported in @bus_acquired_handler and
  * unregister the objects (if any) in @name_lost_handler.
  *
- * Returns: An identifier (never 0) that an be used with
- * g_bus_unown_name() to stop owning the name.
+ * Returns: an identifier (never 0) that an be used with
+ *     g_bus_unown_name() to stop owning the name.
  * Since: 2.26
  */
 
 
 /**
  * g_bus_own_name_on_connection:
- * @connection: A #GDBusConnection.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
- * @name_acquired_handler: (allow-none): Handler to invoke when @name is acquired or %NULL.
- * @name_lost_handler: (allow-none): Handler to invoke when @name is lost or %NULL.
- * @user_data: User data to pass to handlers.
- * @user_data_free_func: (allow-none): Function for freeing @user_data or %NULL.
+ * @connection: a #GDBusConnection
+ * @name: the well-known name to own
+ * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
+ * @name_acquired_handler: (allow-none): handler to invoke when @name is acquired or %NULL
+ * @name_lost_handler: (allow-none): handler to invoke when @name is lost or %NULL
+ * @user_data: user data to pass to handlers
+ * @user_data_free_func: (allow-none): function for freeing @user_data or %NULL
  *
  * Like g_bus_own_name() but takes a #GDBusConnection instead of a
  * #GBusType.
  *
- * Returns: An identifier (never 0) that an be used with
- * g_bus_unown_name() to stop owning the name.
+ * Returns: an identifier (never 0) that an be used with
+ *     g_bus_unown_name() to stop owning the name
  * Since: 2.26
  */
 
 
 /**
  * g_bus_own_name_on_connection_with_closures: (rename-to g_bus_own_name_on_connection)
- * @connection: A #GDBusConnection.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
+ * @connection: a #GDBusConnection
+ * @name: the well-known name to own
+ * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
  * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
- * acquired or %NULL.
- * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or
- * %NULL.
+ *     acquired or %NULL
+ * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost
+ *     or %NULL
  *
- * Version of g_bus_own_name_on_connection() using closures instead of callbacks for
- * easier binding in other languages.
+ * Version of g_bus_own_name_on_connection() using closures instead of
+ * callbacks for easier binding in other languages.
  *
- * Returns: An identifier (never 0) that an be used with
- * g_bus_unown_name() to stop owning the name.
+ * Returns: an identifier (never 0) that an be used with
+ *     g_bus_unown_name() to stop owning the name.
  * Since: 2.26
  */
 
 
 /**
  * g_bus_own_name_with_closures: (rename-to g_bus_own_name)
- * @bus_type: The type of bus to own a name on.
- * @name: The well-known name to own.
- * @flags: A set of flags from the #GBusNameOwnerFlags enumeration.
+ * @bus_type: the type of bus to own a name on
+ * @name: the well-known name to own
+ * @flags: a set of flags from the #GBusNameOwnerFlags enumeration
  * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to
- * the bus of type @bus_type or %NULL.
+ *     the bus of type @bus_type or %NULL
  * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is
- * acquired or %NULL.
+ *     acquired or %NULL
  * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or
- * %NULL.
+ *     %NULL
  *
  * Version of g_bus_own_name() using closures instead of callbacks for
  * easier binding in other languages.
  *
- * Returns: An identifier (never 0) that an be used with
- * g_bus_unown_name() to stop owning the name.
+ * Returns: an identifier (never 0) that an be used with
+ *     g_bus_unown_name() to stop owning the name.
  * Since: 2.26
  */
 
 
 /**
  * g_bus_unown_name:
- * @owner_id: An identifier obtained from g_bus_own_name()
+ * @owner_id: an identifier obtained from g_bus_own_name()
  *
  * Stops owning a name.
  *
@@ -13098,7 +13163,8 @@
  *
  * Gets the generic icon name for a content type.
  *
- * See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+ * See the
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
  * specification for more on the generic icon name.
  *
  * Returns: (allow-none): the registered generic icon name for the given @type,
@@ -13169,7 +13235,8 @@
  *
  * The types returned all have the form x-content/foo, e.g.
  * x-content/audio-cdda (for audio CDs) or x-content/image-dcf
- * (for a camera memory card). See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+ * (for a camera memory card). See the
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
  * specification for more on x-content types.
  *
  * This function is useful in the implementation of
@@ -13210,11 +13277,10 @@
  *
  * Gets a list of strings containing all the registered content types
  * known to the system. The list and its data should be freed using
- * <programlisting>
- * g_list_free_full (list, g_free);
- * </programlisting>
+ * g_list_free_full (list, g_free).
  *
- * Returns: (element-type utf8) (transfer full): #GList of the registered content types
+ * Returns: (element-type utf8) (transfer full): list of the registered
+ *     content types
  */
 
 
@@ -13859,8 +13925,8 @@
  * occurrence of any of the stop characters.
  *
  * In contrast to g_data_input_stream_read_until(), this function
- * does <emphasis>not</emphasis> consume the stop character. You have
- * to use g_data_input_stream_read_byte() to get it before calling
+ * does not consume the stop character. You have to use
+ * g_data_input_stream_read_byte() to get it before calling
  * g_data_input_stream_read_upto() again.
  *
  * Note that @stop_chars may contain '\0' if @stop_chars_len is
@@ -13890,8 +13956,8 @@
  * It is an error to have two outstanding calls to this function.
  *
  * In contrast to g_data_input_stream_read_until(), this function
- * does <emphasis>not</emphasis> consume the stop character. You have
- * to use g_data_input_stream_read_byte() to get it before calling
+ * does not consume the stop character. You have to use
+ * g_data_input_stream_read_byte() to get it before calling
  * g_data_input_stream_read_upto() again.
  *
  * Note that @stop_chars may contain '\0' if @stop_chars_len is
@@ -13915,9 +13981,9 @@
  * Finish an asynchronous call started by
  * g_data_input_stream_read_upto_async().
  *
- * Note that this function does <emphasis>not</emphasis> consume the
- * stop character. You have to use g_data_input_stream_read_byte() to
- * get it before calling g_data_input_stream_read_upto_async() again.
+ * Note that this function does not consume the stop character. You
+ * have to use g_data_input_stream_read_byte() to get it before calling
+ * g_data_input_stream_read_upto_async() again.
  *
  * Returns: (transfer full): a string with the data that was read
  *     before encountering any of the stop characters. Set @length to
@@ -14111,33 +14177,34 @@
 /**
  * g_dbus_address_escape_value:
  * @string: an unescaped string to be included in a D-Bus address
- *  as the value in a key-value pair
+ *     as the value in a key-value pair
  *
  * Escape @string so it can appear in a D-Bus address as the value
  * part of a key-value pair.
  *
- * For instance, if @string is <code>/run/bus-for-:0</code>,
- * this function would return <code>/run/bus-for-%3A0</code>,
+ * For instance, if @string is "/run/bus-for-:0",
+ * this function would return "/run/bus-for-%3A0",
  * which could be used in a D-Bus address like
- * <code>unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0</code>.
+ * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
  *
  * Returns: (transfer full): a copy of @string with all
- *  non-optionally-escaped bytes escaped
+ *     non-optionally-escaped bytes escaped
  * Since: 2.36
  */
 
 
 /**
  * g_dbus_address_get_for_bus_sync:
- * @bus_type: A #GBusType.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @bus_type: a #GBusType
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously looks up the D-Bus address for the well-known message
  * bus instance specified by @bus_type. This may involve using various
  * platform specific mechanisms.
  *
- * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
+ * Returns: a valid D-Bus address string for @bus_type or %NULL if
+ *     @error is set
  * Since: 2.26
  */
 
@@ -14261,7 +14328,7 @@
 /**
  * g_dbus_auth_observer_allow_mechanism:
  * @observer: A #GDBusAuthObserver.
- * @mechanism: The name of the mechanism, e.g. <literal>DBUS_COOKIE_SHA1</literal>.
+ * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
  *
  * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
  *
@@ -14295,11 +14362,11 @@
 
 /**
  * g_dbus_connection_add_filter:
- * @connection: A #GDBusConnection.
- * @filter_function: A filter function.
- * @user_data: User data to pass to @filter_function.
- * @user_data_free_func: Function to free @user_data with when filter
- * is removed or %NULL.
+ * @connection: a #GDBusConnection
+ * @filter_function: a filter function
+ * @user_data: user data to pass to @filter_function
+ * @user_data_free_func: function to free @user_data with when filter
+ *     is removed or %NULL
  *
  * Adds a message filter. Filters are handlers that are run on all
  * incoming and outgoing messages, prior to standard dispatch. Filters
@@ -14322,31 +14389,31 @@
  * message. Similary, if a filter consumes an outgoing message, the
  * message will not be sent to the other peer.
  *
- * Returns: A filter identifier that can be used with
- * g_dbus_connection_remove_filter().
+ * Returns: a filter identifier that can be used with
+ *     g_dbus_connection_remove_filter()
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_call:
- * @connection: A #GDBusConnection.
- * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
- *            @connection is not a message bus connection.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to invoke method on.
- * @method_name: The name of the method to invoke.
- * @parameters: (allow-none): A #GVariant tuple with parameters for the method
- *              or %NULL if not passing parameters.
- * @reply_type: (allow-none): The expected type of the reply, or %NULL.
- * @flags: Flags from the #GDBusCallFlags enumeration.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default
- *                timeout or %G_MAXINT for no timeout.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
- *            satisfied or %NULL if you don't care about the result of the
- *            method invocation.
- * @user_data: The data to pass to @callback.
+ * @connection: a #GDBusConnection
+ * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
+ *     @connection is not a message bus connection
+ * @object_path: path of remote object
+ * @interface_name: D-Bus interface to invoke method on
+ * @method_name: the name of the method to invoke
+ * @parameters: (allow-none): a #GVariant tuple with parameters for the method
+ *     or %NULL if not passing parameters
+ * @reply_type: (allow-none): the expected type of the reply, or %NULL
+ * @flags: flags from the #GDBusCallFlags enumeration
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ *     timeout or %G_MAXINT for no timeout
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
+ *     is satisfied or %NULL if you don't care about the result of the
+ *     method invocation
+ * @user_data: the data to pass to @callback
  *
  * Asynchronously invokes the @method_name method on the
  * @interface_name D-Bus interface on the remote object at
@@ -14364,7 +14431,7 @@
  *
  * If the @parameters #GVariant is floating, it is consumed. This allows
  * convenient 'inline' use of g_variant_new(), e.g.:
- * |[
+ * |[<!-- language="C" -->
  *  g_dbus_connection_call (connection,
  *                          "org.freedesktop.StringThings",
  *                          "/org/freedesktop/StringThings",
@@ -14397,34 +14464,34 @@
 
 /**
  * g_dbus_connection_call_finish:
- * @connection: A #GDBusConnection.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call().
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call()
+ * @error: return location for error or %NULL
  *
  * Finishes an operation started with g_dbus_connection_call().
  *
  * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * return values. Free with g_variant_unref().
+ *     return values. Free with g_variant_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_call_sync:
- * @connection: A #GDBusConnection.
- * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
- *            @connection is not a message bus connection.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to invoke method on.
- * @method_name: The name of the method to invoke.
- * @parameters: (allow-none): A #GVariant tuple with parameters for the method
- *              or %NULL if not passing parameters.
- * @reply_type: (allow-none): The expected type of the reply, or %NULL.
- * @flags: Flags from the #GDBusCallFlags enumeration.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default
- *                timeout or %G_MAXINT for no timeout.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
+ *     @connection is not a message bus connection
+ * @object_path: path of remote object
+ * @interface_name: D-Bus interface to invoke method on
+ * @method_name: the name of the method to invoke
+ * @parameters: (allow-none): a #GVariant tuple with parameters for the method
+ *     or %NULL if not passing parameters
+ * @reply_type: (allow-none): the expected type of the reply, or %NULL
+ * @flags: flags from the #GDBusCallFlags enumeration
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ *     timeout or %G_MAXINT for no timeout
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously invokes the @method_name method on the
  * @interface_name D-Bus interface on the remote object at
@@ -14443,7 +14510,7 @@
  *
  * If the @parameters #GVariant is floating, it is consumed.
  * This allows convenient 'inline' use of g_variant_new(), e.g.:
- * |[
+ * |[<!-- language="C" -->
  *  g_dbus_connection_call_sync (connection,
  *                               "org.freedesktop.StringThings",
  *                               "/org/freedesktop/StringThings",
@@ -14456,7 +14523,7 @@
  *                               G_DBUS_CALL_FLAGS_NONE,
  *                               -1,
  *                               NULL,
- *                               &amp;error);
+ *                               &error);
  * ]|
  *
  * The calling thread is blocked until a reply is received. See
@@ -14464,30 +14531,30 @@
  * this method.
  *
  * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * return values. Free with g_variant_unref().
+ *     return values. Free with g_variant_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_call_with_unix_fd_list:
- * @connection: A #GDBusConnection.
- * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
- *            @connection is not a message bus connection.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to invoke method on.
- * @method_name: The name of the method to invoke.
- * @parameters: (allow-none): A #GVariant tuple with parameters for the method
- *              or %NULL if not passing parameters.
- * @reply_type: (allow-none): The expected type of the reply, or %NULL.
- * @flags: Flags from the #GDBusCallFlags enumeration.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default
- *                timeout or %G_MAXINT for no timeout.
- * @fd_list: (allow-none): A #GUnixFDList or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
- *            satisfied or %NULL if you don't * care about the result of the
- *            method invocation.
+ * @connection: a #GDBusConnection
+ * @bus_name: (allow-none): a unique or well-known bus name or %NULL if
+ *     @connection is not a message bus connection
+ * @object_path: path of remote object
+ * @interface_name: D-Bus interface to invoke method on
+ * @method_name: the name of the method to invoke
+ * @parameters: (allow-none): a #GVariant tuple with parameters for the method
+ *     or %NULL if not passing parameters
+ * @reply_type: (allow-none): the expected type of the reply, or %NULL
+ * @flags: flags from the #GDBusCallFlags enumeration
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ *     timeout or %G_MAXINT for no timeout
+ * @fd_list: (allow-none): a #GUnixFDList or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
+ *     satisfied or %NULL if you don't * care about the result of the
+ *     method invocation
  * @user_data: The data to pass to @callback.
  *
  * Like g_dbus_connection_call() but also takes a #GUnixFDList object.
@@ -14500,55 +14567,56 @@
 
 /**
  * g_dbus_connection_call_with_unix_fd_list_finish:
- * @connection: A #GDBusConnection.
- * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_call_with_unix_fd_list().
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
+ *     g_dbus_connection_call_with_unix_fd_list()
+ * @error: return location for error or %NULL
  *
  * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
  *
  * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * return values. Free with g_variant_unref().
+ *     return values. Free with g_variant_unref().
  * Since: 2.30
  */
 
 
 /**
  * g_dbus_connection_call_with_unix_fd_list_sync:
- * @connection: A #GDBusConnection.
- * @bus_name: (allow-none): A unique or well-known bus name or %NULL if
- *            @connection is not a message bus connection.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to invoke method on.
- * @method_name: The name of the method to invoke.
- * @parameters: (allow-none): A #GVariant tuple with parameters for the method
- *              or %NULL if not passing parameters.
- * @reply_type: (allow-none): The expected type of the reply, or %NULL.
- * @flags: Flags from the #GDBusCallFlags enumeration.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default
- *                timeout or %G_MAXINT for no timeout.
- * @fd_list: (allow-none): A #GUnixFDList or %NULL.
- * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @bus_name: (allow-none): a unique or well-known bus name or %NULL
+ *     if @connection is not a message bus connection
+ * @object_path: path of remote object
+ * @interface_name: D-Bus interface to invoke method on
+ * @method_name: the name of the method to invoke
+ * @parameters: (allow-none): a #GVariant tuple with parameters for
+ *     the method or %NULL if not passing parameters
+ * @reply_type: (allow-none): the expected type of the reply, or %NULL
+ * @flags: flags from the #GDBusCallFlags enumeration
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ *     timeout or %G_MAXINT for no timeout
+ * @fd_list: (allow-none): a #GUnixFDList or %NULL
+ * @out_fd_list: (out) (allow-none): return location for a #GUnixFDList or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Like g_dbus_connection_call_sync() but also takes and returns #GUnixFDList objects.
  *
  * This method is only available on UNIX.
  *
  * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
- * return values. Free with g_variant_unref().
+ *     return values. Free with g_variant_unref().
  * Since: 2.30
  */
 
 
 /**
  * g_dbus_connection_close:
- * @connection: A #GDBusConnection.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
- *            satisfied or %NULL if you don't care about the result.
- * @user_data: The data to pass to @callback.
+ * @connection: a #GDBusConnection
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is
+ *     satisfied or %NULL if you don't care about the result
+ * @user_data: The data to pass to @callback
  *
  * Closes @connection. Note that this never causes the process to
  * exit (this might only happen if the other end of a shared message
@@ -14572,7 +14640,7 @@
  * linkend="g-main-context-push-thread-default">thread-default main
  * loop</link> of the thread you are calling this method from. You can
  * then call g_dbus_connection_close_finish() to get the result of the
- * operation.  See g_dbus_connection_close_sync() for the synchronous
+ * operation. See g_dbus_connection_close_sync() for the synchronous
  * version.
  *
  * Since: 2.26
@@ -14581,44 +14649,45 @@
 
 /**
  * g_dbus_connection_close_finish:
- * @connection: A #GDBusConnection.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_close().
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ *     to g_dbus_connection_close()
+ * @error: return location for error or %NULL
  *
  * Finishes an operation started with g_dbus_connection_close().
  *
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_close_sync:
- * @connection: A #GDBusConnection.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously closees @connection. The calling thread is blocked
  * until this is done. See g_dbus_connection_close() for the
  * asynchronous version of this method and more details about what it
  * does.
  *
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_emit_signal:
- * @connection: A #GDBusConnection.
- * @destination_bus_name: (allow-none): The unique bus name for the destination
- *                        for the signal or %NULL to emit to all listeners.
- * @object_path: Path of remote object.
- * @interface_name: D-Bus interface to emit a signal on.
- * @signal_name: The name of the signal to emit.
- * @parameters: (allow-none): A #GVariant tuple with parameters for the signal
- *              or %NULL if not passing parameters.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @destination_bus_name: (allow-none): the unique bus name for the destination
+ *     for the signal or %NULL to emit to all listeners
+ * @object_path: path of remote object
+ * @interface_name: D-Bus interface to emit a signal on
+ * @signal_name: the name of the signal to emit
+ * @parameters: (allow-none): a #GVariant tuple with parameters for the signal
+ *              or %NULL if not passing parameters
+ * @error: Return location for error or %NULL
  *
  * Emits a signal.
  *
@@ -14626,7 +14695,7 @@
  *
  * This can only fail if @parameters is not compatible with the D-Bus protocol.
  *
- * Returns: %TRUE unless @error is set.
+ * Returns: %TRUE unless @error is set
  * Since: 2.26
  */
 
@@ -14692,26 +14761,25 @@
 
 /**
  * g_dbus_connection_flush:
- * @connection: A #GDBusConnection.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
- *            satisfied or %NULL if you don't care about the result.
- * @user_data: The data to pass to @callback.
+ * @connection: a #GDBusConnection
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: (allow-none): a #GAsyncReadyCallback to call when the
+ *     request is satisfied or %NULL if you don't care about the result
+ * @user_data: The data to pass to @callback
  *
  * Asynchronously flushes @connection, that is, writes all queued
  * outgoing message to the transport and then flushes the transport
  * (using g_output_stream_flush_async()). This is useful in programs
- * that wants to emit a D-Bus signal and then exit
- * immediately. Without flushing the connection, there is no guarantee
- * that the message has been sent to the networking buffers in the OS
- * kernel.
+ * that wants to emit a D-Bus signal and then exit immediately. Without
+ * flushing the connection, there is no guaranteed that the message has
+ * been sent to the networking buffers in the OS kernel.
  *
  * This is an asynchronous method. When the operation is finished,
  * @callback will be invoked in the <link
  * linkend="g-main-context-push-thread-default">thread-default main
  * loop</link> of the thread you are calling this method from. You can
  * then call g_dbus_connection_flush_finish() to get the result of the
- * operation.  See g_dbus_connection_flush_sync() for the synchronous
+ * operation. See g_dbus_connection_flush_sync() for the synchronous
  * version.
  *
  * Since: 2.26
@@ -14720,74 +14788,75 @@
 
 /**
  * g_dbus_connection_flush_finish:
- * @connection: A #GDBusConnection.
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_flush().
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ *     to g_dbus_connection_flush()
+ * @error: return location for error or %NULL
  *
  * Finishes an operation started with g_dbus_connection_flush().
  *
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_flush_sync:
- * @connection: A #GDBusConnection.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously flushes @connection. The calling thread is blocked
  * until this is done. See g_dbus_connection_flush() for the
  * asynchronous version of this method and more details about what it
  * does.
  *
- * Returns: %TRUE if the operation succeeded, %FALSE if @error is set.
+ * Returns: %TRUE if the operation succeeded, %FALSE if @error is set
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_get_capabilities:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * Gets the capabilities negotiated with the remote peer
  *
- * Returns: Zero or more flags from the #GDBusCapabilityFlags enumeration.
+ * Returns: zero or more flags from the #GDBusCapabilityFlags enumeration
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_get_exit_on_close:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * Gets whether the process is terminated when @connection is
  * closed by the remote peer. See
  * #GDBusConnection:exit-on-close for more details.
  *
- * Returns: Whether the process is terminated when @connection is
- * closed by the remote peer.
+ * Returns: whether the process is terminated when @connection is
+ *     closed by the remote peer
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_get_guid:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * The GUID of the peer performing the role of server when
  * authenticating. See #GDBusConnection:guid for more details.
  *
  * Returns: The GUID. Do not free this string, it is owned by
- * @connection.
+ *     @connection.
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_get_last_serial:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * Retrieves the last serial number assigned to a #GDBusMessage on
  * the current thread. This includes messages sent via both low-level
@@ -14796,14 +14865,14 @@
  * g_dbus_connection_call() or g_dbus_proxy_call().
  *
  * Returns: the last used serial or zero when no message has been sent
- * within the current thread.
+ *     within the current thread
  * Since: 2.34
  */
 
 
 /**
  * g_dbus_connection_get_peer_credentials:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * Gets the credentials of the authenticated peer. This will always
  * return %NULL unless @connection acted as a server
@@ -14815,8 +14884,8 @@
  * each application is a client. So this method will always return
  * %NULL for message bus clients.
  *
- * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
- * this object, it is owned by @connection.
+ * Returns: (transfer none): a #GCredentials or %NULL if not available.
+ *     Do not free this object, it is owned by @connection.
  * Since: 2.26
  */
 
@@ -14838,39 +14907,39 @@
 
 /**
  * g_dbus_connection_get_unique_name:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * Gets the unique name of @connection as assigned by the message
  * bus. This can also be used to figure out if @connection is a
  * message bus connection.
  *
- * Returns: The unique name or %NULL if @connection is not a message
- * bus connection. Do not free this string, it is owned by
- * @connection.
+ * Returns: the unique name or %NULL if @connection is not a message
+ *     bus connection. Do not free this string, it is owned by
+ *     @connection.
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_is_closed:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * Gets whether @connection is closed.
  *
- * Returns: %TRUE if the connection is closed, %FALSE otherwise.
+ * Returns: %TRUE if the connection is closed, %FALSE otherwise
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_new:
- * @stream: A #GIOStream.
- * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
- * @flags: Flags describing how to make the connection.
- * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
+ * @stream: a #GIOStream
+ * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
+ * @flags: flags describing how to make the connection
+ * @observer: (allow-none): a #GDBusAuthObserver or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to @callback
  *
  * Asynchronously sets up a D-Bus connection for exchanging D-Bus messages
  * with the end represented by @stream.
@@ -14899,24 +14968,26 @@
 
 /**
  * g_dbus_connection_new_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
- * @error: Return location for error or %NULL.
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback
+ *     passed to g_dbus_connection_new().
+ * @error: return location for error or %NULL
  *
  * Finishes an operation started with g_dbus_connection_new().
  *
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: a #GDBusConnection or %NULL if @error is set. Free
+ *     with g_object_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_new_for_address:
- * @address: A D-Bus address.
- * @flags: Flags describing how to make the connection.
- * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
- * @user_data: The data to pass to @callback.
+ * @address: a D-Bus address
+ * @flags: flags describing how to make the connection
+ * @observer: (allow-none): a #GDBusAuthObserver or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: a #GAsyncReadyCallback to call when the request is satisfied
+ * @user_data: the data to pass to @callback
  *
  * Asynchronously connects and sets up a D-Bus client connection for
  * exchanging D-Bus messages with an endpoint specified by @address
@@ -14945,23 +15016,25 @@
 
 /**
  * g_dbus_connection_new_for_address_finish:
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_new().
- * @error: Return location for error or %NULL.
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed
+ *     to g_dbus_connection_new()
+ * @error: return location for error or %NULL
  *
  * Finishes an operation started with g_dbus_connection_new_for_address().
  *
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: a #GDBusConnection or %NULL if @error is set. Free with
+ *     g_object_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_new_for_address_sync:
- * @address: A D-Bus address.
- * @flags: Flags describing how to make the connection.
- * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @address: a D-Bus address
+ * @flags: flags describing how to make the connection
+ * @observer: (allow-none): a #GDBusAuthObserver or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously connects and sets up a D-Bus client connection for
  * exchanging D-Bus messages with an endpoint specified by @address
@@ -14979,19 +15052,20 @@
  * If @observer is not %NULL it may be used to control the
  * authentication process.
  *
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: a #GDBusConnection or %NULL if @error is set. Free with
+ *     g_object_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_new_sync:
- * @stream: A #GIOStream.
- * @guid: (allow-none): The GUID to use if a authenticating as a server or %NULL.
- * @flags: Flags describing how to make the connection.
- * @observer: (allow-none): A #GDBusAuthObserver or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @stream: a #GIOStream
+ * @guid: (allow-none): the GUID to use if a authenticating as a server or %NULL
+ * @flags: flags describing how to make the connection
+ * @observer: (allow-none): a #GDBusAuthObserver or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously sets up a D-Bus connection for exchanging D-Bus messages
  * with the end represented by @stream.
@@ -15009,20 +15083,20 @@
  * This is a synchronous failable constructor. See
  * g_dbus_connection_new() for the asynchronous version.
  *
- * Returns: A #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
+ * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref().
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_register_object:
- * @connection: A #GDBusConnection.
- * @object_path: The object path to register at.
- * @interface_info: Introspection data for the interface.
- * @vtable: (allow-none): A #GDBusInterfaceVTable to call into or %NULL.
- * @user_data: (allow-none): Data to pass to functions in @vtable.
- * @user_data_free_func: Function to call when the object path is unregistered.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @object_path: the object path to register at
+ * @interface_info: introspection data for the interface
+ * @vtable: (allow-none): a #GDBusInterfaceVTable to call into or %NULL
+ * @user_data: (allow-none): data to pass to functions in @vtable
+ * @user_data_free_func: function to call when the object path is unregistered
+ * @error: return location for error or %NULL
  *
  * Registers callbacks for exported objects at @object_path with the
  * D-Bus interface that is described in @interface_info.
@@ -15033,13 +15107,13 @@
  *
  * Note that all #GVariant values passed to functions in @vtable will match
  * the signature given in @interface_info - if a remote caller passes
- * incorrect values, the <literal>org.freedesktop.DBus.Error.InvalidArgs</literal>
+ * incorrect values, the `org.freedesktop.DBus.Error.InvalidArgs`
  * is returned to the remote caller.
  *
  * Additionally, if the remote caller attempts to invoke methods or
  * access properties not mentioned in @interface_info the
- * <literal>org.freedesktop.DBus.Error.UnknownMethod</literal> resp.
- * <literal>org.freedesktop.DBus.Error.InvalidArgs</literal> errors
+ * `org.freedesktop.DBus.Error.UnknownMethod` resp.
+ * `org.freedesktop.DBus.Error.InvalidArgs` errors
  * are returned to the caller.
  *
  * It is considered a programming error if the
@@ -15051,10 +15125,9 @@
  *
  * GDBus automatically implements the standard D-Bus interfaces
  * org.freedesktop.DBus.Properties, org.freedesktop.DBus.Introspectable
- * and org.freedesktop.Peer, so you don't have to implement those for
- * the objects you export. You <emphasis>can</emphasis> implement
- * org.freedesktop.DBus.Properties yourself, e.g. to handle getting
- * and setting of properties asynchronously.
+ * and org.freedesktop.Peer, so you don't have to implement those for the
+ * objects you export. You can implement org.freedesktop.DBus.Properties
+ * yourself, e.g. to handle getting and setting of properties asynchronously.
  *
  * Note that the reference count on @interface_info will be
  * incremented by 1 (unless allocated statically, e.g. if the
@@ -15064,22 +15137,23 @@
  * See <xref linkend="gdbus-server"/> for an example of how to use this method.
  *
  * Returns: 0 if @error is set, otherwise a registration id (never 0)
- * that can be used with g_dbus_connection_unregister_object() .
+ *     that can be used with g_dbus_connection_unregister_object()
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_register_subtree:
- * @connection: A #GDBusConnection.
- * @object_path: The object path to register the subtree at.
- * @vtable: A #GDBusSubtreeVTable to enumerate, introspect and dispatch nodes in the subtree.
- * @flags: Flags used to fine tune the behavior of the subtree.
- * @user_data: Data to pass to functions in @vtable.
- * @user_data_free_func: Function to call when the subtree is unregistered.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @object_path: the object path to register the subtree at
+ * @vtable: a #GDBusSubtreeVTable to enumerate, introspect and
+ *     dispatch nodes in the subtree
+ * @flags: flags used to fine tune the behavior of the subtree
+ * @user_data: data to pass to functions in @vtable
+ * @user_data_free_func: function to call when the subtree is unregistered
+ * @error: return location for error or %NULL
  *
- * Registers a whole subtree of <quote>dynamic</quote> objects.
+ * Registers a whole subtree of dynamic objects.
  *
  * The @enumerate and @introspection functions in @vtable are used to
  * convey, to remote callers, what nodes exist in the subtree rooted
@@ -15105,9 +15179,8 @@
  * g_dbus_connection_register_object()) in a subtree registered with
  * g_dbus_connection_register_subtree() - if so, the subtree handler
  * is tried as the last resort. One way to think about a subtree
- * handler is to consider it a <quote>fallback handler</quote>
- * for object paths not registered via g_dbus_connection_register_object()
- * or other bindings.
+ * handler is to consider it a fallback handler for object paths not
+ * registered via g_dbus_connection_register_object() or other bindings.
  *
  * Note that @vtable will be copied so you cannot change it after
  * registration.
@@ -15133,12 +15206,12 @@
 
 /**
  * g_dbus_connection_send_message:
- * @connection: A #GDBusConnection.
- * @message: A #GDBusMessage
- * @flags: Flags affecting how the message is sent.
- * @out_serial: (out) (allow-none): Return location for serial number assigned
- *              to @message when sending it or %NULL.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @message: a #GDBusMessage
+ * @flags: flags affecting how the message is sent
+ * @out_serial: (out) (allow-none): return location for serial number assigned
+ *     to @message when sending it or %NULL
+ * @error: Return location for error or %NULL
  *
  * Asynchronously sends @message to the peer represented by @connection.
  *
@@ -15161,24 +15234,24 @@
  * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
  *
  * Returns: %TRUE if the message was well-formed and queued for
- * transmission, %FALSE if @error is set.
+ *     transmission, %FALSE if @error is set
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_send_message_with_reply:
- * @connection: A #GDBusConnection.
- * @message: A #GDBusMessage.
- * @flags: Flags affecting how the message is sent.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default
- *                timeout or %G_MAXINT for no timeout.
- * @out_serial: (out) (allow-none): Return location for serial number assigned
- *              to @message when sending it or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is
- *            satisfied or %NULL if you don't care about the result.
- * @user_data: The data to pass to @callback.
+ * @connection: a #GDBusConnection
+ * @message: a #GDBusMessage
+ * @flags: flags affecting how the message is sent
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ *     timeout or %G_MAXINT for no timeout
+ * @out_serial: (out) (allow-none): return location for serial number assigned
+ *     to @message when sending it or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @callback: (allow-none): a #GAsyncReadyCallback to call when the request
+ *     is satisfied or %NULL if you don't care about the result
+ * @user_data: The data to pass to @callback
  *
  * Asynchronously sends @message to the peer represented by @connection.
  *
@@ -15214,8 +15287,9 @@
 /**
  * g_dbus_connection_send_message_with_reply_finish:
  * @connection: a #GDBusConnection
- * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback passed to g_dbus_connection_send_message_with_reply().
- * @error: Return location for error or %NULL.
+ * @res: a #GAsyncResult obtained from the #GAsyncReadyCallback passed to
+ *     g_dbus_connection_send_message_with_reply()
+ * @error: teturn location for error or %NULL
  *
  * Finishes an operation started with g_dbus_connection_send_message_with_reply().
  *
@@ -15228,22 +15302,22 @@
  * linkend="gdbus-unix-fd-client"/> for an example of how to use this
  * low-level API to send and receive UNIX file descriptors.
  *
- * Returns: (transfer full): A locked #GDBusMessage or %NULL if @error is set.
+ * Returns: (transfer full): a locked #GDBusMessage or %NULL if @error is set
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_send_message_with_reply_sync:
- * @connection: A #GDBusConnection.
- * @message: A #GDBusMessage.
- * @flags: Flags affecting how the message is sent.
- * @timeout_msec: The timeout in milliseconds, -1 to use the default
- *                timeout or %G_MAXINT for no timeout.
- * @out_serial: (out) (allow-none): Return location for serial number assigned
- *              to @message when sending it or %NULL.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
- * @error: Return location for error or %NULL.
+ * @connection: a #GDBusConnection
+ * @message: a #GDBusMessage
+ * @flags: flags affecting how the message is sent.
+ * @timeout_msec: the timeout in milliseconds, -1 to use the default
+ *     timeout or %G_MAXINT for no timeout
+ * @out_serial: (out) (allow-none): return location for serial number
+ *     assigned to @message when sending it or %NULL
+ * @cancellable: (allow-none): a #GCancellable or %NULL
+ * @error: return location for error or %NULL
  *
  * Synchronously sends @message to the peer represented by @connection
  * and blocks the calling thread until a reply is received or the
@@ -15274,16 +15348,17 @@
  * Note that @message must be unlocked, unless @flags contain the
  * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
  *
- * Returns: (transfer full): A locked #GDBusMessage that is the reply to @message or %NULL if @error is set.
+ * Returns: (transfer full): a locked #GDBusMessage that is the reply
+ *     to @message or %NULL if @error is set
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_set_exit_on_close:
- * @connection: A #GDBusConnection.
- * @exit_on_close: Whether the process should be terminated
- *     when @connection is closed by the remote peer.
+ * @connection: a #GDBusConnection
+ * @exit_on_close: whether the process should be terminated
+ *     when @connection is closed by the remote peer
  *
  * Sets whether the process should be terminated when @connection is
  * closed by the remote peer. See #GDBusConnection:exit-on-close for
@@ -15302,24 +15377,26 @@
 
 /**
  * g_dbus_connection_signal_subscribe:
- * @connection: A #GDBusConnection.
- * @sender: (allow-none): Sender name to match on (unique or well-known name)
- *                        or %NULL to listen from all senders.
+ * @connection: a #GDBusConnection
+ * @sender: (allow-none): sender name to match on (unique or well-known name)
+ *     or %NULL to listen from all senders
  * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to
- *                                match on all interfaces.
- * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals.
- * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths.
- * @arg0: (allow-none): Contents of first string argument to match on or %NULL
- *                      to match on all kinds of arguments.
- * @flags: Flags describing how to subscribe to the signal (currently unused).
- * @callback: Callback to invoke when there is a signal matching the requested data.
- * @user_data: User data to pass to @callback.
- * @user_data_free_func: (allow-none): Function to free @user_data with when
- *                       subscription is removed or %NULL.
+ *     match on all interfaces
+ * @member: (allow-none): D-Bus signal name to match on or %NULL to match on
+ *     all signals
+ * @object_path: (allow-none): object path to match on or %NULL to match on
+ *     all object paths
+ * @arg0: (allow-none): contents of first string argument to match on or %NULL
+ *     to match on all kinds of arguments
+ * @flags: flags describing how to subscribe to the signal (currently unused)
+ * @callback: callback to invoke when there is a signal matching the requested data
+ * @user_data: user data to pass to @callback
+ * @user_data_free_func: (allow-none): function to free @user_data with when
+ *     subscription is removed or %NULL
  *
  * Subscribes to signals on @connection and invokes @callback with a
- * whenever the signal is received. Note that @callback
- * will be invoked in the <link
+ * whenever the signal is received. Note that @callback will be invoked
+ * in the <link
  * linkend="g-main-context-push-thread-default">thread-default main
  * loop</link> of the thread you are calling this method from.
  *
@@ -15338,15 +15415,16 @@
  * interpreted as part of a namespace or path.  The first argument
  * of a signal is matched against that part as specified by D-Bus.
  *
- * Returns: A subscription identifier that can be used with g_dbus_connection_signal_unsubscribe().
+ * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_signal_unsubscribe:
- * @connection: A #GDBusConnection.
- * @subscription_id: A subscription id obtained from g_dbus_connection_signal_subscribe().
+ * @connection: a #GDBusConnection
+ * @subscription_id: a subscription id obtained from
+ *     g_dbus_connection_signal_subscribe()
  *
  * Unsubscribes from signals.
  *
@@ -15356,7 +15434,7 @@
 
 /**
  * g_dbus_connection_start_message_processing:
- * @connection: A #GDBusConnection.
+ * @connection: a #GDBusConnection
  *
  * If @connection was created with
  * %G_DBUS_CONNECTION_FLAGS_DELAY_MESSAGE_PROCESSING, this method
@@ -15401,24 +15479,26 @@
 
 /**
  * g_dbus_connection_unregister_object:
- * @connection: A #GDBusConnection.
- * @registration_id: A registration id obtained from g_dbus_connection_register_object().
+ * @connection: a #GDBusConnection
+ * @registration_id: a registration id obtained from
+ *     g_dbus_connection_register_object()
  *
  * Unregisters an object.
  *
- * Returns: %TRUE if the object was unregistered, %FALSE otherwise.
+ * Returns: %TRUE if the object was unregistered, %FALSE otherwise
  * Since: 2.26
  */
 
 
 /**
  * g_dbus_connection_unregister_subtree:
- * @connection: A #GDBusConnection.
- * @registration_id: A subtree registration id obtained from g_dbus_connection_register_subtree().
+ * @connection: a #GDBusConnection
+ * @registration_id: a subtree registration id obtained from
+ *     g_dbus_connection_register_subtree()
  *
  * Unregisters a subtree.
  *
- * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise.
+ * Returns: %TRUE if the subtree was unregistered, %FALSE otherwise
  * Since: 2.26
  */
 
@@ -15432,7 +15512,7 @@
  * D-Bus error name will be returned.
  *
  * Otherwise the a name of the form
- * <literal>org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE</literal>
+ * `org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE`
  * will be used. This allows other GDBus applications to map the error
  * on the wire back to a #GError using g_dbus_error_new_for_dbus_error().
  *
@@ -15446,16 +15526,17 @@
 
 /**
  * g_dbus_error_get_remote_error:
- * @error: A #GError.
+ * @error: a #GError
  *
  * Gets the D-Bus error name used for @error, if any.
  *
  * This function is guaranteed to return a D-Bus error name for all
- * #GError<!-- -->s returned from functions handling remote method
- * calls (e.g. g_dbus_connection_call_finish()) unless
+ * #GErrors returned from functions handling remote method calls
+ * (e.g. g_dbus_connection_call_finish()) unless
  * g_dbus_error_strip_remote_error() has been used on @error.
  *
- * Returns: An allocated string or %NULL if the D-Bus error name could not be found. Free with g_free().
+ * Returns: an allocated string or %NULL if the D-Bus error name
+ *     could not be found. Free with g_free().
  * Since: 2.26
  */
 
@@ -15517,7 +15598,7 @@
  * @dbus_error_name: A D-Bus error name.
  *
  * Creates an association to map between @dbus_error_name and
- * #GError<!-- -->s specified by @error_domain and @error_code.
+ * #GErrors specified by @error_domain and @error_code.
  *
  * This is typically done in the routine that returns the #GQuark for
  * an error domain.
@@ -15681,10 +15762,9 @@
  * #G_TYPE_BOXED derived-types) not in the table above.
  *
  * Note that if @gvalue is of type #G_TYPE_VARIANT and its value is
- * %NULL, the <emphasis>empty</emphasis> #GVariant instance (never
- * %NULL) for @type is returned (e.g. 0 for scalar types, the empty
- * string for string types, <literal>'/'</literal> for object path
- * types, the empty array for any array type and so on).
+ * %NULL, the empty #GVariant instance (never %NULL) for @type is
+ * returned (e.g. 0 for scalar types, the empty string for string types,
+ * '/' for object path types, the empty array for any array type and so on).
  *
  * See the g_dbus_gvariant_to_gvalue() function for how to convert a
  * #GVariant to a #GValue.
@@ -15739,17 +15819,16 @@
 
 /**
  * g_dbus_interface_get_object: (skip)
- * @interface_: An exported D-Bus interface.
+ * @interface_: An exported D-Bus interface
  *
  * Gets the #GDBusObject that @interface_ belongs to, if any.
  *
- * <warning>It is not safe to use the returned object if @interface_
- * or the returned object is being used from other threads. See
- * g_dbus_interface_dup_object() for a thread-safe
- * alternative.</warning>
+ * It is not safe to use the returned object if @interface_ or
+ * the returned object is being used from other threads. See
+ * g_dbus_interface_dup_object() for a thread-safe alternative.
  *
  * Returns: (transfer none): A #GDBusObject or %NULL. The returned
- * reference belongs to @interface_ and should not be freed.
+ *     reference belongs to @interface_ and should not be freed.
  * Since: 2.30
  */
 
@@ -15795,7 +15874,7 @@
  *
  * This function is typically used for generating introspection XML
  * documents at run-time for handling the
- * <literal>org.freedesktop.DBus.Introspectable.Introspect</literal>
+ * `org.freedesktop.DBus.Introspectable.Introspect`
  * method.
  *
  * Since: 2.26
@@ -15914,7 +15993,7 @@
  *
  * For example, an exported D-Bus interface may queue up property
  * changes and emit the
- * <literal>org.freedesktop.DBus.Properties::PropertiesChanged</literal>
+ * `org.freedesktop.DBus.Properties::Propert``
  * signal later (e.g. in an idle handler). This technique is useful
  * for collapsing multiple property changes into one.
  *
@@ -16540,7 +16619,7 @@
 
 
 /**
- * g_dbus_message_print:
+ * g_dbus_message_print: (type method-return)
  * @message: A #GDBusMessage.
  * @indent: Indentation level.
  *
@@ -16549,35 +16628,33 @@
  * The contents of the description has no ABI guarantees, the contents
  * and formatting is subject to change at any time. Typical output
  * looks something like this:
- * <programlisting>
- * Type&colon;    method-call
- * Flags&colon;   none
- * Version&colon; 0
- * Serial&colon;  4
- * Headers&colon;
+ * |[
+ * Flags:   none
+ * Version: 0
+ * Serial:  4
+ * Headers:
  *   path -> objectpath '/org/gtk/GDBus/TestObject'
  *   interface -> 'org.gtk.GDBus.TestInterface'
  *   member -> 'GimmeStdout'
  *   destination -> ':1.146'
- * Body&colon; ()
+ * Body: ()
  * UNIX File Descriptors:
  *   (none)
- * </programlisting>
+ * ]|
  * or
- * <programlisting>
- * Type&colon;    method-return
- * Flags&colon;   no-reply-expected
- * Version&colon; 0
- * Serial&colon;  477
- * Headers&colon;
+ * |[
+ * Flags:   no-reply-expected
+ * Version: 0
+ * Serial:  477
+ * Headers:
  *   reply-serial -> uint32 4
  *   destination -> ':1.159'
  *   sender -> ':1.146'
  *   num-unix-fds -> uint32 1
- * Body&colon; ()
- * UNIX File Descriptors&colon;
+ * Body: ()
+ * UNIX File Descriptors:
  *   fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
- * </programlisting>
+ * ]|
  *
  * Returns: A string that should be freed with g_free().
  * Since: 2.26
@@ -16996,12 +17073,11 @@
  * will be returned on the wire. In a nutshell, if the given error is
  * registered using g_dbus_error_register_error() the name given
  * during registration is used. Otherwise, a name of the form
- * <literal>org.gtk.GDBus.UnmappedGError.Quark...</literal> is
- * used. This provides transparent mapping of #GError between
- * applications using GDBus.
+ * `org.gtk.GDBus.UnmappedGError.Quark...` is used. This provides
+ * transparent mapping of #GError between applications using GDBus.
  *
  * If you are writing an application intended to be portable,
- * <emphasis>always</emphasis> register errors with g_dbus_error_register_error()
+ * always register errors with g_dbus_error_register_error()
  * or use g_dbus_method_invocation_return_dbus_error().
  *
  * This method will free @invocation, you cannot use it afterwards.
@@ -17111,7 +17187,7 @@
  * Appends an XML representation of @info (and its children) to @string_builder.
  *
  * This function is typically used for generating introspection XML documents at run-time for
- * handling the <literal>org.freedesktop.DBus.Introspectable.Introspect</literal> method.
+ * handling the `org.freedesktop.DBus.Introspectable.Introspect`  method.
  *
  * Since: 2.26
  */
@@ -17139,7 +17215,7 @@
  * Parses @xml_data and returns a #GDBusNodeInfo representing the data.
  *
  * The introspection XML must contain exactly one top-level
- * <tag class="starttag">node</tag> element.
+ * &lt;node&gt; element.
  *
  * Note that this routine is using a
  * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
@@ -17476,10 +17552,9 @@
  * @object: An object.
  *
  * Like g_dbus_object_manager_server_export() but appends a string of
- * the form <literal>_N</literal> (with N being a natural number) to
- * @object<!-- -->'s object path if an object with the given path
- * already exists. As such, the #GDBusObjectProxy:g-object-path property
- * of @object may be modified.
+ * the form _N (with N being a natural number) to @object's object path
+ * if an object with the given path already exists. As such, the
+ * #GDBusObjectProxy:g-object-path property of @object may be modified.
  *
  * Since: 2.30
  */
@@ -17706,7 +17781,7 @@
  *
  * If the @parameters #GVariant is floating, it is consumed. This allows
  * convenient 'inline' use of g_variant_new(), e.g.:
- * |[
+ * |[<!-- language="C" -->
  *  g_dbus_proxy_call (proxy,
  *                     "TwoStrings",
  *                     g_variant_new ("(ss)",
@@ -17716,7 +17791,7 @@
  *                     -1,
  *                     NULL,
  *                     (GAsyncReadyCallback) two_strings_done,
- *                     &amp;data);
+ *                     &data);
  * ]|
  *
  * If @proxy has an expected interface (see
@@ -17779,7 +17854,7 @@
  *
  * If the @parameters #GVariant is floating, it is consumed. This allows
  * convenient 'inline' use of g_variant_new(), e.g.:
- * |[
+ * |[<!-- language="C" -->
  *  g_dbus_proxy_call_sync (proxy,
  *                          "TwoStrings",
  *                          g_variant_new ("(ss)",
@@ -17788,7 +17863,7 @@
  *                          G_DBUS_CALL_FLAGS_NONE,
  *                          -1,
  *                          NULL,
- *                          &amp;error);
+ *                          &error);
  * ]|
  *
  * The calling thread is blocked until a reply is received. See
@@ -18154,7 +18229,7 @@
  *
  * If the @value #GVariant is floating, it is consumed. This allows
  * convenient 'inline' use of g_variant_new(), e.g.
- * |[
+ * |[<!-- language="C" -->
  *  g_dbus_proxy_set_cached_property (proxy,
  *                                    "SomeProperty",
  *                                    g_variant_new ("(si)",
@@ -18162,20 +18237,19 @@
  *                                                  42));
  * ]|
  *
- * Normally you will not need to use this method since @proxy is
- * tracking changes using the
- * <literal>org.freedesktop.DBus.Properties.PropertiesChanged</literal>
- * D-Bus signal. However, for performance reasons an object may decide
- * to not use this signal for some properties and instead use a
- * proprietary out-of-band mechanism to transmit changes.
+ * Normally you will not need to use this method since @proxy
+ * is tracking changes using the
+ * `org.freedesktop.DBus.Properties.PropertiesChanged`
+ * D-Bus signal. However, for performance reasons an object may
+ * decide to not use this signal for some properties and instead
+ * use a proprietary out-of-band mechanism to transmit changes.
  *
  * As a concrete example, consider an object with a property
- * <literal>ChatroomParticipants</literal> which is an array of
- * strings. Instead of transmitting the same (long) array every time
- * the property changes, it is more efficient to only transmit the
- * delta using e.g. signals <literal>ChatroomParticipantJoined(String
- * name)</literal> and <literal>ChatroomParticipantParted(String
- * name)</literal>.
+ * `ChatroomParticipants` which is an array of strings. Instead of
+ * transmitting the same (long) array every time the property changes,
+ * it is more efficient to only transmit the delta using e.g. signals
+ * `ChatroomParticipantJoined(String name)` and
+ * `ChatroomParticipantParted(String name)`.
  *
  * Since: 2.26
  */
@@ -18440,7 +18514,7 @@
  *
  * Checks if the application info should be shown in menus that list available
  * applications for a specific name of the desktop, based on the
- * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys.
+ * `OnlyShowIn` and `NotShowIn` keys.
  *
  * If @desktop_env is %NULL, then the name of the desktop set with
  * g_desktop_app_info_set_desktop_env() is used.
@@ -18449,7 +18523,7 @@
  * %NULL for @desktop_env) as well as additional checks.
  *
  * Returns: %TRUE if the @info should be shown in @desktop_env according to the
- * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE
+ * `OnlyShowIn` and `NotShowIn` keys, %FALSE
  * otherwise.
  * Since: 2.30
  */
@@ -18598,13 +18672,13 @@
  *
  * A desktop file id is the basename of the desktop file, including the
  * .desktop extension. GIO is looking for a desktop file with this name
- * in the <filename>applications</filename> subdirectories of the XDG data
- * directories (i.e. the directories specified in the
- * <envar>XDG_DATA_HOME</envar> and <envar>XDG_DATA_DIRS</envar> environment
- * variables). GIO also supports the prefix-to-subdirectory mapping that is
- * described in the <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Menu Spec</ulink>
+ * in the `applications` subdirectories of the XDG
+ * data directories (i.e. the directories specified in the `XDG_DATA_HOME`
+ * and `XDG_DATA_DIRS` environment variables). GIO also supports the
+ * prefix-to-subdirectory mapping that is described in the
+ * [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/)
  * (i.e. a desktop id of kde-foo.desktop will match
- * <filename>/usr/share/applications/kde/foo.desktop</filename>).
+ * `/usr/share/applications/kde/foo.desktop`).
  *
  * Returns: a new #GDesktopAppInfo, or %NULL if no desktop file with that id
  */
@@ -18657,20 +18731,19 @@
  * Sets the name of the desktop that the application is running in.
  * This is used by g_app_info_should_show() and
  * g_desktop_app_info_get_show_in() to evaluate the
- * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal>
+ * `OnlyShowIn` and `NotShowIn`
  * desktop entry fields.
  *
- * The <ulink url="http://standards.freedesktop.org/menu-spec/latest/">Desktop
- * Menu specification</ulink> recognizes the following:
- * <simplelist>
- *   <member>GNOME</member>
- *   <member>KDE</member>
- *   <member>ROX</member>
- *   <member>XFCE</member>
- *   <member>LXDE</member>
- *   <member>Unity</member>
- *   <member>Old</member>
- * </simplelist>
+ * The
+ * [Desktop Menu specification](http://standards.freedesktop.org/menu-spec/latest/)
+ * recognizes the following:
+ * - GNOME
+ * - KDE
+ * - ROX
+ * - XFCE
+ * - LXDE
+ * - Unity
+ * - Old
  *
  * Should be called only once; subsequent calls are ignored.
  */
@@ -19081,7 +19154,7 @@
  * @emblemed: a #GEmblemedIcon
  * @emblem: a #GEmblem
  *
- * Adds @emblem to the #GList of #GEmblem <!-- -->s.
+ * Adds @emblem to the #GList of #GEmblems.
  *
  * Since: 2.18
  */
@@ -19104,7 +19177,7 @@
  * Gets the list of emblems for the @icon.
  *
  * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
- *          #GEmblem <!-- -->s that is owned by @emblemed
+ *     #GEmblems that is owned by @emblemed
  * Since: 2.18
  */
 
@@ -19321,7 +19394,7 @@
  * @attributes: an attribute string to match.
  *
  * Creates a new file attribute matcher, which matches attributes
- * against a given string. #GFileAttributeMatcher<!-- -->s are reference
+ * against a given string. #GFileAttributeMatchers are reference
  * counted structures, and are created with a reference count of 1. If
  * the number of references falls to 0, the #GFileAttributeMatcher is
  * automatically destroyed.
@@ -19971,7 +20044,7 @@
  * inside loops with g_file_enumerator_next_file().
  *
  * This is a convenience method that's equivalent to:
- * |[
+ * |[<!-- language="C" -->
  *   gchar *name = g_file_info_get_name (info);
  *   GFile *child = g_file_get_child (g_file_enumerator_get_container (enumr),
  *                                    name);
@@ -20323,9 +20396,9 @@
  *
  * Gets the URI scheme for a #GFile.
  * RFC 3986 decodes the scheme as:
- * <programlisting>
+ * |[
  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
- * </programlisting>
+ * ]|
  * Common schemes include "file", "http", "ftp", etc.
  *
  * This call does no blocking I/O.
@@ -21514,9 +21587,9 @@
  *
  * Recursively measures the disk usage of @file.
  *
- * This is essentially an analog of the '<literal>du</literal>' command,
- * but it also reports the number of directories and non-directory files
- * encountered (including things like symbolic links).
+ * This is essentially an analog of the 'du' command, but it also
+ * reports the number of directories and non-directory files encountered
+ * (including things like symbolic links).
  *
  * By default, errors are only reported against the toplevel file
  * itself.  Errors found while recursing are silently ignored, unless
@@ -22618,10 +22691,10 @@
  * If @make_backup is %TRUE, this function will attempt to
  * make a backup of @file.
  *
- * <warning><para>No copy of @content will be made, so it must stay valid until
- * @callback is called. See g_file_replace_contents_bytes_async() for a #GBytes
- * version that will automatically hold a reference to the contents (without
- * copying) for the duration of the call.</para></warning>
+ * Note that no copy of @content will be made, so it must stay valid
+ * until @callback is called. See g_file_replace_contents_bytes_async()
+ * for a #GBytes version that will automatically hold a reference to the
+ * contents (without copying) for the duration of the call.
  */
 
 
@@ -23472,19 +23545,14 @@
  * The encoding of the returned string is proprietary to #GIcon except
  * in the following two cases
  *
- * <itemizedlist>
- * <listitem><para>
- *     If @icon is a #GFileIcon, the returned string is a native path
- *     (such as <literal>/path/to/my icon.png</literal>) without escaping
- *     if the #GFile for @icon is a native file.  If the file is not
- *     native, the returned string is the result of g_file_get_uri()
- *     (such as <literal>sftp://path/to/my&percnt;20icon.png</literal>).
- * </para></listitem>
- * <listitem><para>
- *    If @icon is a #GThemedIcon with exactly one name, the encoding is
- *    simply the name (such as <literal>network-server</literal>).
- * </para></listitem>
- * </itemizedlist>
+ * - If @icon is a #GFileIcon, the returned string is a native path
+ *   (such as `/path/to/my icon.png`) without escaping
+ *   if the #GFile for @icon is a native file.  If the file is not
+ *   native, the returned string is the result of g_file_get_uri()
+ *   (such as `sftp://path/to/my&percnt;20icon.png`).
+ *
+ * - If @icon is a #GThemedIcon with exactly one name, the encoding is
+ *    simply the name (such as `network-server`).
  *
  * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
  * be serialized. Use g_free() to free.
@@ -23833,7 +23901,7 @@
  * g_inet_socket_address_get_flowinfo:
  * @address: a %G_SOCKET_FAMILY_IPV6 #GInetSocketAddress
  *
- * Gets the <literal>sin6_flowinfo</literal> field from @address,
+ * Gets the `sin6_flowinfo` field from @address,
  * which must be an IPv6 address.
  *
  * Returns: the flowinfo field
@@ -23856,7 +23924,7 @@
  * g_inet_socket_address_get_scope_id:
  * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
  *
- * Gets the <literal>sin6_scope_id</literal> field from @address,
+ * Gets the `sin6_scope_id` field from @address,
  * which must be an IPv6 address.
  *
  * Returns: the scope id field
@@ -24447,8 +24515,8 @@
  * The list is sorted by priority, beginning with the highest priority.
  *
  * Returns: (element-type GIOExtension) (transfer none): a #GList of
- * #GIOExtension<!-- -->s. The list is owned by GIO and should not be
- * modified.
+ *     #GIOExtensions. The list is owned by GIO and should not be
+ *     modified.
  */
 
 
@@ -25172,7 +25240,7 @@
  * @size as 0 (allowing #GMemoryOutputStream to do the initial
  * allocation for itself).
  *
- * |[
+ * |[<!-- language="C" -->
  * /&ast; a stream that can grow &ast;/
  * stream = g_memory_output_stream_new (NULL, 0, realloc, free);
  *
@@ -25574,8 +25642,7 @@
  * second with the "Cut", "Copy" and "Paste" items.  The first and
  * second menus would then be added as submenus of the third.  In XML
  * format, this would look something like the following:
- *
- * <informalexample><programlisting><![CDATA[
+ * |[
  * <menu id='edit-menu'>
  *   <section>
  *     <item label='Undo'/>
@@ -25587,7 +25654,7 @@
  *     <item label='Paste'/>
  *   </section>
  * </menu>
- * ]]></programlisting></informalexample>
+ * ]|
  *
  * The following example is exactly equivalent.  It is more illustrative
  * of the exact relationship between the menus and items (keeping in
@@ -25595,8 +25662,7 @@
  * containing one).  The style of the second example is more verbose and
  * difficult to read (and therefore not recommended except for the
  * purpose of understanding what is really going on).
- *
- * <informalexample><programlisting><![CDATA[
+ * |[
  * <menu id='edit-menu'>
  *   <item>
  *     <link name='section'>
@@ -25612,7 +25678,7 @@
  *     </link>
  *   </item>
  * </menu>
- * ]]></programlisting></informalexample>
+ * ]|
  *
  * Returns: a new #GMenuItem
  * Since: 2.32
@@ -26418,7 +26484,8 @@
  * Tries to guess the type of content stored on @mount. Returns one or
  * more textual identifiers of well-known content types (typically
  * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
- * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+ * memory cards. See the
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
  * specification for more on x-content types.
  *
  * This is an asynchronous operation (see
@@ -26461,7 +26528,8 @@
  * Tries to guess the type of content stored on @mount. Returns one or
  * more textual identifiers of well-known content types (typically
  * prefixed with "x-content/"), e.g. x-content/image-dcf for camera
- * memory cards. See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink>
+ * memory cards. See the
+ * [shared-mime-info](http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec)
  * specification for more on x-content types.
  *
  * This is an synchronous operation and as such may block doing IO;
@@ -26489,10 +26557,10 @@
  * situation, a #GVolumeMonitor implementation would create two
  * #GVolume objects (for example, one for the camera functionality of
  * the device and one for a SD card reader on the device) with
- * activation URIs <literal>gphoto2://[usb:001,002]/store1/</literal>
- * and <literal>gphoto2://[usb:001,002]/store2/</literal>. When the
+ * activation URIs `gphoto2://[usb:001,002]/store1/`
+ * and `gphoto2://[usb:001,002]/store2/`. When the
  * underlying mount (with root
- * <literal>gphoto2://[usb:001,002]/</literal>) is mounted, said
+ * `gphoto2://[usb:001,002]/`) is mounted, said
  * #GVolumeMonitor implementation would create two #GMount objects
  * (each with their root matching the corresponding volume activation
  * root) that would shadow the original mount.
@@ -27670,10 +27738,10 @@
  * For the synchronous, blocking version of this function, see
  * g_output_stream_write().
  *
- * <warning><para>No copy of @buffer will be made, so it must stay valid until
- * @callback is called. See g_output_stream_write_bytes_async() for a #GBytes
- * version that will automatically hold a reference to the contents (without
- * copying) for the duration of the call.</para></warning>
+ * Note that no copy of @buffer will be made, so it must stay valid
+ * until @callback is called. See g_output_stream_write_bytes_async()
+ * for a #GBytes version that will automatically hold a reference to
+ * the contents (without copying) for the duration of the call.
  */
 
 
@@ -27689,13 +27757,12 @@
  * bindings or in other cases where the refcounted nature of #GBytes
  * is helpful over a bare pointer interface.
  *
- * However, note that this function <emphasis>may</emphasis> still
- * perform partial writes, just like g_output_stream_write().  If that
- * occurs, to continue writing, you will need to create a new #GBytes
- * containing just the remaining bytes, using
- * g_bytes_new_from_bytes().  Passing the same #GBytes instance
- * multiple times potentially can result in duplicated data in the
- * output stream.
+ * However, note that this function may still perform partial writes,
+ * just like g_output_stream_write().  If that occurs, to continue
+ * writing, you will need to create a new #GBytes containing just the
+ * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
+ * #GBytes instance multiple times potentially can result in duplicated
+ * data in the output stream.
  *
  * Returns: Number of bytes written, or -1 on error
  */
@@ -27714,13 +27781,12 @@
  * takes a #GBytes as input.  Due to the refcounted nature of #GBytes,
  * this allows the stream to avoid taking a copy of the data.
  *
- * However, note that this function <emphasis>may</emphasis> still
- * perform partial writes, just like g_output_stream_write_async().
- * If that occurs, to continue writing, you will need to create a new
- * #GBytes containing just the remaining bytes, using
- * g_bytes_new_from_bytes().  Passing the same #GBytes instance
- * multiple times potentially can result in duplicated data in the
- * output stream.
+ * However, note that this function may still perform partial writes,
+ * just like g_output_stream_write_async(). If that occurs, to continue
+ * writing, you will need to create a new #GBytes containing just the
+ * remaining bytes, using g_bytes_new_from_bytes(). Passing the same
+ * #GBytes instance multiple times potentially can result in duplicated
+ * data in the output stream.
  *
  * For the synchronous, blocking version of this function, see
  * g_output_stream_write_bytes().
@@ -28441,18 +28507,18 @@
  * @error: return location for a #GError, or %NULL
  *
  * Looks into the system proxy configuration to determine what proxy,
- * if any, to use to connect to @uri. The returned proxy URIs are of the
- * form <literal>&lt;protocol&gt;://[user[:password]@]host:port</literal>
- * or <literal>direct://</literal>, where &lt;protocol&gt; could be
- * http, rtsp, socks or other proxying protocol.
+ * if any, to use to connect to @uri. The returned proxy URIs are of
+ * the form `&lt;protocol&gt;://[user[:password]@]host:port` or
+ * `direct://`, where &lt;protocol&gt; could be http, rtsp, socks
+ * or other proxying protocol.
  *
  * If you don't know what network protocol is being used on the
- * socket, you should use <literal>none</literal> as the URI protocol.
+ * socket, you should use `none` as the URI protocol.
  * In this case, the resolver might still return a generic proxy type
  * (such as SOCKS), but would not return protocol-specific proxy types
  * (such as http).
  *
- * <literal>direct://</literal> is used when no proxy is needed.
+ * `direct://` is used when no proxy is needed.
  * Direct connection should not be attempted unless it is part of the
  * returned array of proxies.
  *
@@ -28813,9 +28879,8 @@
  * Synchronously performs a DNS SRV lookup for the given @service and
  * @protocol in the given @domain and returns an array of #GSrvTarget.
  * @domain may be an ASCII-only or UTF-8 hostname. Note also that the
- * @service and @protocol arguments <emphasis>do not</emphasis>
- * include the leading underscore that appears in the actual DNS
- * entry.
+ * @service and @protocol arguments do not include the leading underscore
+ * that appears in the actual DNS entry.
  *
  * On success, g_resolver_lookup_service() will return a #GList of
  * #GSrvTarget, sorted in order of preference. (That is, you should
@@ -29320,8 +29385,8 @@
  * g_settings_backend_get_default:
  *
  * Returns the default #GSettingsBackend. It is possible to override
- * the default by setting the <envar>GSETTINGS_BACKEND</envar>
- * environment variable to the name of a settings backend.
+ * the default by setting the `GSETTINGS_BACKEND` environment variable
+ * to the name of a settings backend.
  *
  * The user gets a reference to the backend.
  *
@@ -29505,8 +29570,7 @@
  *
  * When the @inverted argument is %TRUE, the binding inverts the
  * value as it passes from the setting to the object, i.e. @property
- * will be set to %TRUE if the key is <emphasis>not</emphasis>
- * writable.
+ * will be set to %TRUE if the key is not writable.
  *
  * Note that the lifecycle of the binding is tied to the object,
  * and that you can have only one binding per object property.
@@ -29594,14 +29658,14 @@
 /**
  * g_settings_get_child:
  * @settings: a #GSettings object
- * @name: the name of the 'child' schema
+ * @name: the name of the child schema
  *
- * Creates a 'child' settings object which has a base path of
- * <replaceable>base-path</replaceable>/@name, where
- * <replaceable>base-path</replaceable> is the base path of @settings.
+ * Creates a child settings object which has a base path of
+ * `base-path/@name`, where `base-path` is the base path of
+ * @settings.
  *
  * The schema for the child settings object must have been declared
- * in the schema of @settings using a <tag class="starttag">child</tag> element.
+ * in the schema of @settings using a &lt;child&gt; element.
  *
  * Returns: (transfer full): a 'child' settings object
  * Since: 2.26
@@ -30218,31 +30282,28 @@
  * This function will return a #GVariant that fully describes the range
  * of values that are valid for @key.
  *
- * The type of #GVariant returned is <literal>(sv)</literal>.  The
- * string describes the type of range restriction in effect.  The type
- * and meaning of the value contained in the variant depends on the
- * string.
+ * The type of #GVariant returned is `(sv)`. The string describes
+ * the type of range restriction in effect. The type and meaning of
+ * the value contained in the variant depends on the string.
  *
- * If the string is <literal>'type'</literal> then the variant contains
- * an empty array.  The element type of that empty array is the expected
- * type of value and all values of that type are valid.
+ * If the string is `'type'` then the variant contains an empty array.
+ * The element type of that empty array is the expected type of value
+ * and all values of that type are valid.
  *
- * If the string is <literal>'enum'</literal> then the variant contains
- * an array enumerating the possible values.  Each item in the array is
+ * If the string is `'enum'` then the variant contains an array
+ * enumerating the possible values. Each item in the array is
  * a possible valid value and no other values are valid.
  *
- * If the string is <literal>'flags'</literal> then the variant contains
- * an array.  Each item in the array is a value that may appear zero or
- * one times in an array to be used as the value for this key.  For
- * example, if the variant contained the array <literal>['x',
- * 'y']</literal> then the valid values for the key would be
- * <literal>[]</literal>, <literal>['x']</literal>,
- * <literal>['y']</literal>, <literal>['x', 'y']</literal> and
- * <literal>['y', 'x']</literal>.
+ * If the string is `'flags'` then the variant contains an array. Each
+ * item in the array is a value that may appear zero or one times in an
+ * array to be used as the value for this key. For example, if the
+ * variant contained the array `['x', 'y']` then the valid values for
+ * the key would be `[]`, `['x']`, `['y']`, `['x', 'y']` and
+ * `['y', 'x']`.
  *
- * Finally, if the string is <literal>'range'</literal> then the variant
- * contains a pair of like-typed values -- the minimum and maximum
- * permissible values for this key.
+ * Finally, if the string is `'range'` then the variant contains a pair
+ * of like-typed values -- the minimum and maximum permissible values
+ * for this key.
  *
  * This information should not be used by normal programs.  It is
  * considered to be a hint for introspection purposes.  Normal programs
@@ -30353,9 +30414,8 @@
  *
  * The returned source may actually consist of multiple schema sources
  * from different directories, depending on which directories were given
- * in <envar>XDG_DATA_DIRS</envar> and
- * <envar>GSETTINGS_SCHEMA_DIR</envar>.  For this reason, all lookups
- * performed against the default source should probably be done
+ * in `XDG_DATA_DIRS` and `GSETTINGS_SCHEMA_DIR`. For this reason, all
+ * lookups performed against the default source should probably be done
  * recursively.
  *
  * Returns: (transfer none): the default schema source
@@ -30423,16 +30483,15 @@
  * This function is not required for normal uses of #GSettings but it
  * may be useful to authors of plugin management systems.
  *
- * The directory should contain a file called
- * <filename>gschemas.compiled</filename> as produced by
- * <command>glib-compile-schemas</command>.
+ * The directory should contain a file called `gschemas.compiled` as
+ * produced by the
+ * <link linkend="glib-compile-schemas">glib-compile-schemas</link> tool.
  *
- * If @trusted is %TRUE then <filename>gschemas.compiled</filename> is
- * trusted not to be corrupted.  This assumption has a performance
- * advantage, but can result in crashes or inconsistent behaviour in the
- * case of a corrupted file.  Generally, you should set @trusted to
- * %TRUE for files installed by the system and to %FALSE for files in
- * the home directory.
+ * If @trusted is %TRUE then `gschemas.compiled` is trusted not to be
+ * corrupted. This assumption has a performance advantage, but can result
+ * in crashes or inconsistent behaviour in the case of a corrupted file.
+ * Generally, you should set @trusted to %TRUE for files installed by the
+ * system and to %FALSE for files in the home directory.
  *
  * If @parent is non-%NULL then there are two effects.
  *
@@ -30441,8 +30500,8 @@
  * source, the lookup will recurse to the parent.
  *
  * Second, any references to other schemas specified within this
- * source (ie: <literal>child</literal> or <literal>extends</literal>)
- * references may be resolved from the @parent.
+ * source (ie: `child` or `extends`) references may be resolved
+ * from the @parent.
  *
  * For this second reason, except in very unusual situations, the
  * @parent should probably be given as the default schema source, as
@@ -31220,9 +31279,9 @@
 /**
  * g_simple_proxy_resolver_new:
  * @default_proxy: (allow-none): the default proxy to use, eg
- *   "socks://192.168.1.1"
+ *     "socks://192.168.1.1"
  * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses
- *   to not use a proxy for.
+ *     to not use a proxy for.
  *
  * Creates a new #GSimpleProxyResolver. See
  * #GSimpleProxyResolver:default-proxy and
@@ -31243,10 +31302,9 @@
  * don't match #GSimpleProxyResolver:ignore-hosts or a proxy set
  * via g_simple_proxy_resolver_set_uri_proxy().
  *
- * If @default_proxy starts with "<literal>socks://</literal>",
+ * If @default_proxy starts with "socks://",
  * #GSimpleProxyResolver will treat it as referring to all three of
- * the <literal>socks5</literal>, <literal>socks4a</literal>, and
- * <literal>socks4</literal> proxy types.
+ * the socks5, socks4a, and socks4 proxy types.
  *
  * Since: 2.36
  */
@@ -31278,9 +31336,8 @@
  * #GSimpleProxyResolver:ignore-hosts) will be proxied via @proxy.
  *
  * As with #GSimpleProxyResolver:default-proxy, if @proxy starts with
- * "<literal>socks://</literal>", #GSimpleProxyResolver will treat it
- * as referring to all three of the <literal>socks5</literal>,
- * <literal>socks4a</literal>, and <literal>socks4</literal> proxy
+ * "socks://", #GSimpleProxyResolver will treat it
+ * as referring to all three of the socks5, socks4a, and socks4 proxy
  * types.
  *
  * Since: 2.36
@@ -31373,7 +31430,7 @@
  *
  * Gets the socket family type of @address.
  *
- * Returns: the socket family type of @address.
+ * Returns: the socket family type of @address
  * Since: 2.22
  */
 
@@ -31382,11 +31439,11 @@
  * g_socket_address_get_native_size:
  * @address: a #GSocketAddress
  *
- * Gets the size of @address's native <type>struct sockaddr</type>.
+ * Gets the size of @address's native struct sockaddr.
  * You can use this to allocate memory to pass to
  * g_socket_address_to_native().
  *
- * Returns: the size of the native <type>struct sockaddr</type> that
+ * Returns: the size of the native struct sockaddr that
  *     @address represents
  * Since: 2.22
  */
@@ -31394,14 +31451,14 @@
 
 /**
  * g_socket_address_new_from_native:
- * @native: a pointer to a <type>struct sockaddr</type>
+ * @native: a pointer to a struct sockaddr
  * @len: the size of the memory location pointed to by @native
  *
  * Creates a #GSocketAddress subclass corresponding to the native
- * <type>struct sockaddr</type> @native.
+ * struct sockaddr @native.
  *
- * Returns: a new #GSocketAddress if @native could successfully be converted,
- * otherwise %NULL.
+ * Returns: a new #GSocketAddress if @native could successfully
+ *     be converted, otherwise %NULL
  * Since: 2.22
  */
 
@@ -31410,17 +31467,16 @@
  * g_socket_address_to_native:
  * @address: a #GSocketAddress
  * @dest: a pointer to a memory location that will contain the native
- * <type>struct sockaddr</type>.
+ * struct sockaddr
  * @destlen: the size of @dest. Must be at least as large as
- * g_socket_address_get_native_size().
- * @error: #GError for error reporting, or %NULL to ignore.
+ *     g_socket_address_get_native_size()
+ * @error: #GError for error reporting, or %NULL to ignore
  *
- * Converts a #GSocketAddress to a native <type>struct
- * sockaddr</type>, which can be passed to low-level functions like
- * connect() or bind().
+ * Converts a #GSocketAddress to a native struct sockaddr, which can
+ * be passed to low-level functions like connect() or bind().
  *
- * If not enough space is available, a %G_IO_ERROR_NO_SPACE error is
- * returned. If the address type is not known on the system
+ * If not enough space is available, a %G_IO_ERROR_NO_SPACE error
+ * is returned. If the address type is not known on the system
  * then a %G_IO_ERROR_NOT_SUPPORTED error is returned.
  *
  * Returns: %TRUE if @dest was filled in, %FALSE on error
@@ -31445,12 +31501,12 @@
  * used to initiate connections, though this is not normally required.
  *
  * If @socket is a TCP socket, then @allow_reuse controls the setting
- * of the <literal>SO_REUSEADDR</literal> socket option; normally it
- * should be %TRUE for server sockets (sockets that you will
- * eventually call g_socket_accept() on), and %FALSE for client
- * sockets. (Failing to set this flag on a server socket may cause
- * g_socket_bind() to return %G_IO_ERROR_ADDRESS_IN_USE if the server
- * program is stopped and then immediately restarted.)
+ * of the `SO_REUSEADDR` socket option; normally it should be %TRUE for
+ * server sockets (sockets that you will eventually call
+ * g_socket_accept() on), and %FALSE for client sockets. (Failing to
+ * set this flag on a server socket may cause g_socket_bind() to return
+ * %G_IO_ERROR_ADDRESS_IN_USE if the server program is stopped and then
+ * immediately restarted.)
  *
  * If @socket is a UDP socket, then @allow_reuse determines whether or
  * not other UDP sockets can be bound to the same address at the same
@@ -32218,7 +32274,7 @@
  * @connectable: a #GSocketConnectable
  *
  * Creates a #GSocketAddressEnumerator for @connectable that will
- * return #GProxyAddress<!-- -->es for addresses that you must connect
+ * return #GProxyAddresses for addresses that you must connect
  * to via a proxy.
  *
  * If @connectable does not implement
@@ -32646,17 +32702,16 @@
 /**
  * g_socket_get_option:
  * @socket: a #GSocket
- * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>)
- * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
+ * @level: the "API level" of the option (eg, `SOL_SOCKET`)
+ * @optname: the "name" of the option (eg, `SO_BROADCAST`)
  * @value: (out): return location for the option value
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Gets the value of an integer-valued option on @socket, as with
- * <literal>getsockopt ()</literal>. (If you need to fetch a
- * non-integer-valued option, you will need to call
- * <literal>getsockopt ()</literal> directly.)
+ * getsockopt(). (If you need to fetch a  non-integer-valued option,
+ * you will need to call getsockopt() directly.)
  *
- * The <link linkend="gio-gnetworking.h"><literal>&lt;gio/gnetworking.h&gt;</literal></link>
+ * The <link linkend="gio-gnetworking.h">`&lt;gio/gnetworking.h&gt;`</link>
  * header pulls in system headers that will define most of the
  * standard/portable socket options. For unusual socket protocols or
  * platform-dependent options, you may need to include additional
@@ -32667,9 +32722,8 @@
  * g_socket_get_option() will handle the conversion internally.
  *
  * Returns: success or failure. On failure, @error will be set, and
- *   the system error value (<literal>errno</literal> or
- *   <literal>WSAGetLastError ()</literal>) will still be set to the
- *   result of the <literal>getsockopt ()</literal> call.
+ *   the system error value (`errno` or WSAGetLastError()) will still
+ *   be set to the result of the getsockopt() call.
  * Since: 2.36
  */
 
@@ -33336,7 +33390,7 @@
  * then @vectors is assumed to be terminated by a #GOutputVector with a
  * %NULL buffer pointer.) The #GOutputVector structs describe the buffers
  * that the sent data will be gathered from. Using multiple
- * #GOutputVector<!-- -->s is more memory-efficient than manually copying
+ * #GOutputVectors is more memory-efficient than manually copying
  * data from multiple sources into a single buffer, and more
  * network-efficient than making multiple calls to g_socket_send().
  *
@@ -33567,26 +33621,24 @@
 /**
  * g_socket_set_option:
  * @socket: a #GSocket
- * @level: the "API level" of the option (eg, <literal>SOL_SOCKET</literal>)
- * @optname: the "name" of the option (eg, <literal>SO_BROADCAST</literal>)
+ * @level: the "API level" of the option (eg, `SOL_SOCKET`)
+ * @optname: the "name" of the option (eg, `SO_BROADCAST`)
  * @value: the value to set the option to
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Sets the value of an integer-valued option on @socket, as with
- * <literal>setsockopt ()</literal>. (If you need to set a
- * non-integer-valued option, you will need to call
- * <literal>setsockopt ()</literal> directly.)
+ * setsockopt(). (If you need to set a non-integer-valued option,
+ * you will need to call setsockopt() directly.)
  *
- * The <link linkend="gio-gnetworking.h"><literal>&lt;gio/gnetworking.h&gt;</literal></link>
+ * The <link linkend="gio-gnetworking.h">`&lt;gio/gnetworking.h&gt;`</link>
  * header pulls in system headers that will define most of the
  * standard/portable socket options. For unusual socket protocols or
  * platform-dependent options, you may need to include additional
  * headers.
  *
  * Returns: success or failure. On failure, @error will be set, and
- *   the system error value (<literal>errno</literal> or
- *   <literal>WSAGetLastError ()</literal>) will still be set to the
- *   result of the <literal>setsockopt ()</literal> call.
+ *   the system error value (`errno` or WSAGetLastError()) will still
+ *   be set to the result of the setsockopt() call.
  * Since: 2.36
  */
 
@@ -33770,7 +33822,7 @@
  *
  * Creates a new #GSrvTarget with the given parameters.
  *
- * You should not need to use this; normally #GSrvTarget<!-- -->s are
+ * You should not need to use this; normally #GSrvTargets are
  * created by #GResolver.
  *
  * Returns: a new #GSrvTarget.
@@ -34619,8 +34671,7 @@
  * to wait for a #GSource to trigger. Attaches @source to @task's
  * #GMainContext with @task's <link
  * linkend="io-priority">priority</link>, and sets @source's callback
- * to @callback, with @task as the callback's
- * <literal>user_data</literal>.
+ * to @callback, with @task as the callback's `user_data`.
  *
  * This takes a reference on @task until @source is destroyed.
  *
@@ -34716,9 +34767,9 @@
  * g_task_get_task_data:
  * @task: a #GTask
  *
- * Gets @task's <literal>task_data</literal>.
+ * Gets @task's `task_data`.
  *
- * Returns: (transfer none): @task's <literal>task_data</literal>.
+ * Returns: (transfer none): @task's `task_data`.
  * Since: 2.36
  */
 
@@ -35022,7 +35073,7 @@
  * See #GTaskThreadFunc for more details about how @task_func is handled.
  *
  * Normally this is used with tasks created with a %NULL
- * <literal>callback</literal>, but note that even if the task does
+ * `callback`, but note that even if the task does
  * have a callback, it will not be invoked when @task_func returns.
  *
  * Since: 2.36
@@ -35296,10 +35347,8 @@
  *
  * Append a name to the list of icons from within @icon.
  *
- * <note><para>
  * Note that doing so invalidates the hash computed by prior calls
  * to g_icon_hash().
- * </para></note>
  */
 
 
@@ -35343,7 +35392,7 @@
  * that can be created by shortening @iconname at '-' characters.
  *
  * In the following example, @icon1 and @icon2 are equivalent:
- * |[
+ * |[<!-- language="C" -->
  * const char *names[] = {
  *   "gnome-dev-cdrom-audio",
  *   "gnome-dev-cdrom",
@@ -35366,10 +35415,8 @@
  *
  * Prepend a name to the list of icons from within @icon.
  *
- * <note><para>
  * Note that doing so invalidates the hash computed by prior calls
  * to g_icon_hash().
- * </para></note>
  *
  * Since: 2.18
  */
@@ -35503,7 +35550,7 @@
  * @file: file containing PEM-encoded certificates to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Creates one or more #GTlsCertificate<!-- -->s from the PEM-encoded
+ * Creates one or more #GTlsCertificates from the PEM-encoded
  * data in @file. If @file cannot be read or parsed, the function will
  * return %NULL and set @error. If @file does not contain any
  * PEM-encoded certificates, this will return an empty list and not
@@ -35970,16 +36017,16 @@
  *
  * %G_TLS_REHANDSHAKE_SAFELY means that the connection will allow a
  * rehandshake only if the other end of the connection supports the
- * TLS <literal>renegotiation_info</literal> extension. This is the
- * default behavior, but means that rehandshaking will not work
- * against older implementations that do not support that extension.
+ * TLS `renegotiation_info` extension. This is the default behavior,
+ * but means that rehandshaking will not work against older
+ * implementations that do not support that extension.
  *
  * %G_TLS_REHANDSHAKE_UNSAFELY means that the connection will allow
- * rehandshaking even without the
- * <literal>renegotiation_info</literal> extension. On the server side
- * in particular, this is not recommended, since it leaves the server
- * open to certain attacks. However, this mode is necessary if you
- * need to allow renegotiation with older client software.
+ * rehandshaking even without the `renegotiation_info` extension. On
+ * the server side in particular, this is not recommended, since it
+ * leaves the server open to certain attacks. However, this mode is
+ * necessary if you need to allow renegotiation with older client
+ * software.
  *
  * Since: 2.28
  */
@@ -37178,8 +37225,7 @@
 
 /**
  * g_unix_is_mount_path_system_internal:
- * @mount_path: a mount path, e.g. <filename>/media/disk</filename>
- *    or <filename>/usr</filename>
+ * @mount_path: a mount path, e.g. `/media/disk` or `/usr`
  *
  * Determines if @mount_path is considered an implementation of the
  * OS. This is primarily used for hiding mountable and mounted volumes
@@ -37697,7 +37743,7 @@
  * zero-padded buffer will be considered the name. (As above, if
  * @path_len is -1, then @path is assumed to be NUL-terminated.) In
  * this case, g_socket_address_get_native_size() will always return
- * the full size of a <literal>struct sockaddr_un</literal>, although
+ * the full size of a `struct sockaddr_un`, although
  * g_unix_socket_address_get_path_len() will still return just the
  * length of @path.
  *
@@ -37797,30 +37843,30 @@
 
 /**
  * g_volume_can_eject:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Checks if a volume can be ejected.
  *
- * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise.
+ * Returns: %TRUE if the @volume can be ejected. %FALSE otherwise
  */
 
 
 /**
  * g_volume_can_mount:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Checks if a volume can be mounted.
  *
- * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise.
+ * Returns: %TRUE if the @volume can be mounted. %FALSE otherwise
  */
 
 
 /**
  * g_volume_eject:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  * @flags: flags affecting the unmount if required for eject
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
  * @user_data: user data that gets passed to @callback
  *
  * Ejects a volume. This is an asynchronous operation, and is
@@ -37833,27 +37879,27 @@
 
 /**
  * g_volume_eject_finish:
- * @volume: pointer to a #GVolume.
- * @result: a #GAsyncResult.
+ * @volume: pointer to a #GVolume
+ * @result: a #GAsyncResult
  * @error: a #GError location to store an error, or %NULL to ignore
  *
  * Finishes ejecting a volume. If any errors occurred during the operation,
  * @error will be set to contain the errors and %FALSE will be returned.
  *
- * Returns: %TRUE, %FALSE if operation failed.
+ * Returns: %TRUE, %FALSE if operation failed
  * Deprecated: 2.22: Use g_volume_eject_with_operation_finish() instead.
  */
 
 
 /**
  * g_volume_eject_with_operation:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  * @flags: flags affecting the unmount if required for eject
  * @mount_operation: (allow-none): a #GMountOperation or %NULL to
- *     avoid user interaction.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
- * @user_data: user data passed to @callback.
+ *     avoid user interaction
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
+ * @user_data: user data passed to @callback
  *
  * Ejects a volume. This is an asynchronous operation, and is
  * finished by calling g_volume_eject_with_operation_finish() with the @volume
@@ -37865,15 +37911,14 @@
 
 /**
  * g_volume_eject_with_operation_finish:
- * @volume: a #GVolume.
- * @result: a #GAsyncResult.
- * @error: a #GError location to store the error occurring, or %NULL to
- *     ignore.
+ * @volume: a #GVolume
+ * @result: a #GAsyncResult
+ * @error: a #GError location to store the error occurring, or %NULL
  *
  * Finishes ejecting a volume. If any errors occurred during the operation,
  * @error will be set to contain the errors and %FALSE will be returned.
  *
- * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise.
+ * Returns: %TRUE if the volume was successfully ejected. %FALSE otherwise
  * Since: 2.22
  */
 
@@ -37902,23 +37947,20 @@
  * either be equal or a prefix of what this function returns. In
  * other words, in code
  *
- * <programlisting>
+ * |[<!-- language="C" -->
  *   GMount *mount;
  *   GFile *mount_root
  *   GFile *volume_activation_root;
  *
  *   mount = g_volume_get_mount (volume); /&ast; mounted, so never NULL &ast;/
  *   mount_root = g_mount_get_root (mount);
- *   volume_activation_root = g_volume_get_activation_root(volume); /&ast; assume not NULL &ast;/
- * </programlisting>
- *
+ *   volume_activation_root = g_volume_get_activation_root (volume); /&ast; assume not NULL &ast;/
+ * ]|
  * then the expression
- *
- * <programlisting>
+ * |[<!-- language="C" -->
  *   (g_file_has_prefix (volume_activation_root, mount_root) ||
  *       g_file_equal (volume_activation_root, mount_root))
- * </programlisting>
- *
+ * ]|
  * will always be %TRUE.
  *
  * Activation roots are typically used in #GVolumeMonitor
@@ -37926,26 +37968,26 @@
  * g_mount_is_shadowed() for more details.
  *
  * Returns: (transfer full): the activation root of @volume or %NULL. Use
- * g_object_unref() to free.
+ *     g_object_unref() to free.
  * Since: 2.18
  */
 
 
 /**
  * g_volume_get_drive:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Gets the drive for the @volume.
  *
- * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive.
- *     The returned object should be unreffed with g_object_unref()
- *     when no longer needed.
+ * Returns: (transfer full): a #GDrive or %NULL if @volume is not
+ *     associated with a drive. The returned object should be unreffed
+ *     with g_object_unref() when no longer needed.
  */
 
 
 /**
  * g_volume_get_icon:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Gets the icon for @volume.
  *
@@ -37965,14 +38007,14 @@
  * for more information about volume identifiers.
  *
  * Returns: a newly allocated string containing the
- *   requested identfier, or %NULL if the #GVolume
- *   doesn't have this kind of identifier
+ *     requested identfier, or %NULL if the #GVolume
+ *     doesn't have this kind of identifier
  */
 
 
 /**
  * g_volume_get_mount:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Gets the mount for the @volume.
  *
@@ -37984,29 +38026,29 @@
 
 /**
  * g_volume_get_name:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Gets the name of @volume.
  *
  * Returns: the name for the given @volume. The returned string should
- * be freed with g_free() when no longer needed.
+ *     be freed with g_free() when no longer needed.
  */
 
 
 /**
  * g_volume_get_sort_key:
- * @volume: A #GVolume.
+ * @volume: a #GVolume
  *
  * Gets the sort key for @volume, if any.
  *
- * Returns: Sorting key for @volume or %NULL if no such key is available.
+ * Returns: Sorting key for @volume or %NULL if no such key is available
  * Since: 2.32
  */
 
 
 /**
  * g_volume_get_symbolic_icon:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Gets the symbolic icon for @volume.
  *
@@ -38019,7 +38061,7 @@
 
 /**
  * g_volume_get_uuid:
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  *
  * Gets the UUID for the @volume. The reference is typically based on
  * the file system UUID for the volume in question and should be
@@ -38150,11 +38192,11 @@
 
 /**
  * g_volume_mount: (virtual mount_fn)
- * @volume: a #GVolume.
+ * @volume: a #GVolume
  * @flags: flags affecting the operation
- * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction.
- * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore.
- * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL.
+ * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL
  * @user_data: user data that gets passed to @callback
  *
  * Mounts a volume. This is an asynchronous operation, and is
@@ -38177,7 +38219,7 @@
  * function; there's no need to listen for the 'mount-added' signal on
  * #GVolumeMonitor.
  *
- * Returns: %TRUE, %FALSE if operation failed.
+ * Returns: %TRUE, %FALSE if operation failed
  */
 
 
@@ -38187,7 +38229,7 @@
  *
  * Returns whether the volume should be automatically mounted.
  *
- * Returns: %TRUE if the volume should be automatically mounted.
+ * Returns: %TRUE if the volume should be automatically mounted
  */
 
 
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index bb403b15..a68339e5 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -44,15 +44,14 @@
  * used as a context. This is mainly useful for short strings which
  * may need different translations, depending on the context in which
  * they are used.
- * |[
+ * |[<!-- language="C" -->
  * label1 = C_("Navigation", "Back");
  * label2 = C_("Body part", "Back");
  * ]|
  *
- * <note><para>If you are using the C_() macro, you need to make sure
- * that you pass <option>--keyword=C_:1c,2</option> to xgettext when
- * extracting messages. Note that this only works with GNU
- * gettext >= 0.15.</para></note>
+ * If you are using the C_() macro, you need to make sure that you pass
+ * `--keyword=C_:1c,2` to xgettext when extracting messages.
+ * Note that this only works with GNU gettext >= 0.15.
  *
  * Returns: the translated message
  * Since: 2.16
@@ -69,11 +68,11 @@
 /**
  * GArray:
  * @data: a pointer to the element data. The data may be moved as
- *        elements are added to the #GArray.
+ *     elements are added to the #GArray.
  * @len: the number of elements in the #GArray not including the
- *       possible terminating zero element.
+ *     possible terminating zero element.
  *
- * Contains the public fields of an <link linkend="glib-Arrays">Array</link>.
+ * Contains the public fields of a GArray.
  */
 
 
@@ -82,18 +81,17 @@
  *
  * The GAsyncQueue struct is an opaque data structure which represents
  * an asynchronous queue. It should only be accessed through the
- * <function>g_async_queue_*</function> functions.
+ * g_async_queue_* functions.
  */
 
 
 /**
  * GByteArray:
  * @data: a pointer to the element data. The data may be moved as
- *        elements are added to the #GByteArray.
- * @len: the number of elements in the #GByteArray.
+ *     elements are added to the #GByteArray
+ * @len: the number of elements in the #GByteArray
  *
- * The <structname>GByteArray</structname> struct allows access to the
- * public fields of a <structname>GByteArray</structname>.
+ * Contains the public fields of a GByteArray.
  */
 
 
@@ -174,11 +172,9 @@
  * another thread publishes the data, it can signal one of the waiting
  * threads to wake up to collect the data.
  *
- * <example>
- *  <title>
- *   Using GCond to block a thread until a condition is satisfied
- *  </title>
- *  <programlisting>
+ * Here is an example for using GCond to block a thread until a condition
+ * is satisfied:
+ * |[<!-- language="C" -->
  *   gpointer current_data = NULL;
  *   GMutex data_mutex;
  *   GCond data_cond;
@@ -206,21 +202,19 @@
  *
  *     return data;
  *   }
- *  </programlisting>
- * </example>
- *
+ * ]|
  * Whenever a thread calls pop_data() now, it will wait until
  * current_data is non-%NULL, i.e. until some other thread
  * has called push_data().
  *
  * The example shows that use of a condition variable must always be
  * paired with a mutex.  Without the use of a mutex, there would be a
- * race between the check of <varname>current_data</varname> by the
- * while loop in <function>pop_data</function> and waiting.
- * Specifically, another thread could set <varname>pop_data</varname>
- * after the check, and signal the cond (with nobody waiting on it)
- * before the first thread goes to sleep.  #GCond is specifically useful
- * for its ability to release the mutex and go to sleep atomically.
+ * race between the check of @current_data by the while loop in
+ * pop_data() and waiting. Specifically, another thread could set
+ * @current_data after the check, and signal the cond (with nobody
+ * waiting on it) before the first thread goes to sleep. #GCond is
+ * specifically useful for its ability to release the mutex and go
+ * to sleep atomically.
  *
  * It is also important to use the g_cond_wait() and g_cond_wait_until()
  * functions only inside a loop which checks for the condition to be
@@ -228,11 +222,10 @@
  * not be true even after it returns.
  *
  * If a #GCond is allocated in static storage then it can be used
- * without initialisation.  Otherwise, you should call g_cond_init() on
- * it and g_cond_clear() when done.
+ * without initialisation.  Otherwise, you should call g_cond_init()
+ * on it and g_cond_clear() when done.
  *
- * A #GCond should only be accessed via the <function>g_cond_</function>
- * functions.
+ * A #GCond should only be accessed via the g_cond_ functions.
  */
 
 
@@ -269,14 +262,16 @@
  * @year: the day of the day-month-year representation of the date
  *
  * Represents a day between January 1, Year 1 and a few thousand years in
- * the future. None of its members should be accessed directly. If the
- * <structname>GDate</structname> is obtained from g_date_new(), it will
- * be safe to mutate but invalid and thus not safe for calendrical
- * computations. If it's declared on the stack, it will contain garbage
- * so must be initialized with g_date_clear(). g_date_clear() makes the
- * date invalid but sane. An invalid date doesn't represent a day, it's
- * "empty." A date becomes valid after you set it to a Julian day or you
- * set a day, month, and year.
+ * the future. None of its members should be accessed directly.
+ *
+ * If the #GDate-struct is obtained from g_date_new(), it will be safe
+ * to mutate but invalid and thus not safe for calendrical computations.
+ *
+ * If it's declared on the stack, it will contain garbage so must be
+ * initialized with g_date_clear(). g_date_clear() makes the date invalid
+ * but sane. An invalid date doesn't represent a day, it's "empty." A date
+ * becomes valid after you set it to a Julian day or you set a day, month,
+ * and year.
  */
 
 
@@ -294,8 +289,8 @@
 /**
  * GDateDay:
  *
- * Integer representing a day of the month; between 1 and
- * 31. #G_DATE_BAD_DAY represents an invalid day of the month.
+ * Integer representing a day of the month; between 1 and 31.
+ * #G_DATE_BAD_DAY represents an invalid day of the month.
  */
 
 
@@ -593,7 +588,7 @@
  * and #gchar* respectively.
  *
  * g_direct_hash() is also the appropriate hash function for keys
- * of the form <literal>GINT_TO_POINTER (n)</literal> (or similar macros).
+ * of the form `GINT_TO_POINTER (n)` (or similar macros).
  *
  * <!-- FIXME: Need more here. --> A good hash functions should produce
  * hash values that are evenly distributed over a fairly large range.
@@ -607,7 +602,8 @@
  * a more secure hash function when using a GHashTable with keys
  * that originate in untrusted data (such as HTTP requests).
  * Using g_str_hash() in that situation might make your application
- * vulerable to <ulink url="https://lwn.net/Articles/474912/">Algorithmic Complexity Attacks</ulink>.
+ * vulerable to
+ * [Algorithmic Complexity Attacks](https://lwn.net/Articles/474912/).
  *
  * The key to choosing a good hash is unpredictability.  Even
  * cryptographic hashes are very easy to find collisions for when the
@@ -651,8 +647,7 @@
  * @destroy: the default @finalize_hook function of a #GHookList calls
  *     this member of the hook that is being finalized
  *
- * The <structname>GHook</structname> struct represents a single hook
- * function in a #GHookList.
+ * The #GHook struct represents a single hook function in a #GHookList.
  */
 
 
@@ -742,8 +737,7 @@
  *     The default behaviour is to call the hooks @destroy function
  * @dummy: unused
  *
- * The <structname>GHookList</structname> struct represents a
- * list of hook functions.
+ * The #GHookList struct represents a list of hook functions.
  */
 
 
@@ -923,9 +917,9 @@
  * Stuffs an integer into a pointer type.
  *
  * Remember, you may not store pointers in integers. This is not portable
- * in any way, shape or form. These macros <emphasis>only</emphasis> allow
- * storing integers in pointers, and only preserve 32 bits of the
- * integer; values outside the range of a 32-bit integer will be mangled.
+ * in any way, shape or form. These macros only allow storing integers in
+ * pointers, and only preserve 32 bits of the integer; values outside the
+ * range of a 32-bit integer will be mangled.
  */
 
 
@@ -983,24 +977,26 @@
 
 /**
  * GIOFlags:
- * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal>
- *                    (see the documentation of the UNIX open()
- *                    syscall).
+ * @G_IO_FLAG_APPEND: turns on append mode, corresponds to %O_APPEND
+ *     (see the documentation of the UNIX open() syscall)
  * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to
- *                      <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal>
- *                      (see the documentation of the UNIX open() syscall).
+ *     %O_NONBLOCK/%O_NDELAY (see the documentation of the UNIX open()
+ *     syscall)
  * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable.
- *                         This flag cannot be changed.
+ *     This flag cannot be changed.
  * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable.
- *                          This flag cannot be changed.
+ *     This flag cannot be changed.
+ * G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
+ *     that existed before the spelling was fixed in GLib 2.30. It is kept
+ *     here for compatibility reasons. Deprecated since 2.30
  * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
- *                         i.e. that g_io_channel_seek_position() can
- *                         be used on it.  This flag cannot be changed.
+ *     i.e. that g_io_channel_seek_position() can be used on it.
+ *     This flag cannot be changed.
  * @G_IO_FLAG_MASK: the mask that specifies all the valid flags.
  * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from
- *                      g_io_channel_get_flags().
+ *     g_io_channel_get_flags()
  * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify
- *                      with g_io_channel_set_flags().
+ *     with g_io_channel_set_flags()
  *
  * Specifies properties of a #GIOChannel. Some of the flags can only be
  * read with g_io_channel_get_flags(), but not changed with
@@ -1115,17 +1111,7 @@
  * @micro: the micro version to check for
  *
  * Checks the version of the GLib library that is being compiled
- * against.
- *
- * <example>
- * <title>Checking the version of the GLib library</title>
- * <programlisting>
- *   if (!GLIB_CHECK_VERSION (1, 2, 0))
- *     g_error ("GLib version 1.2.0 or above is needed");
- * </programlisting>
- * </example>
- *
- * See glib_check_version() for a runtime check.
+ * against. See glib_check_version() for a runtime check.
  *
  * Returns: %TRUE if the version of the GLib header files
  * is the same as or newer than the passed-in version.
@@ -1314,33 +1300,27 @@
  *
  * The #GMutex struct is an opaque data structure to represent a mutex
  * (mutual exclusion). It can be used to protect data against shared
- * access. Take for example the following function:
+ * access.
  *
- * <example>
- *  <title>A function which will not work in a threaded environment</title>
- *  <programlisting>
+ * Take for example the following function:
+ * |[<!-- language="C" -->
  *   int
  *   give_me_next_number (void)
  *   {
  *     static int current_number = 0;
  *
- *     /<!-- -->* now do a very complicated calculation to calculate the new
- *      * number, this might for example be a random number generator
- *      *<!-- -->/
+ *     /&ast; now do a very complicated calculation to calculate the new
+ *      &ast; number, this might for example be a random number generator
+ *      &ast;/
  *     current_number = calc_next_number (current_number);
  *
  *     return current_number;
  *   }
- *  </programlisting>
- * </example>
- *
+ * ]|
  * It is easy to see that this won't work in a multi-threaded
  * application. There current_number must be protected against shared
  * access. A #GMutex can be used as a solution to this problem:
- *
- * <example>
- *  <title>Using GMutex to protected a shared variable</title>
- *  <programlisting>
+ * |[<!-- language="C" -->
  *   int
  *   give_me_next_number (void)
  *   {
@@ -1348,15 +1328,13 @@
  *     static int current_number = 0;
  *     int ret_val;
  *
- *     g_mutex_lock (&amp;mutex);
+ *     g_mutex_lock (&mutex);
  *     ret_val = current_number = calc_next_number (current_number);
- *     g_mutex_unlock (&amp;mutex);
+ *     g_mutex_unlock (&mutex);
  *
  *     return ret_val;
  *   }
- *  </programlisting>
- * </example>
- *
+ * ]|
  * Notice that the #GMutex is not initialised to any particular value.
  * Its placement in static storage ensures that it will be initialised
  * to all-zeros, which is appropriate.
@@ -1364,8 +1342,7 @@
  * If a #GMutex is placed in other contexts (eg: embedded in a struct)
  * then it must be explicitly initialised using g_mutex_init().
  *
- * A #GMutex should only be accessed via <function>g_mutex_</function>
- * functions.
+ * A #GMutex should only be accessed via g_mutex_ functions.
  */
 
 
@@ -1446,9 +1423,9 @@
  * been stored in the pointer with GINT_TO_POINTER().
  *
  * Remember, you may not store pointers in integers. This is not portable
- * in any way, shape or form. These macros <emphasis>only</emphasis> allow
- * storing integers in pointers, and only preserve 32 bits of the
- * integer; values outside the range of a 32-bit integer will be mangled.
+ * in any way, shape or form. These macros only allow storing integers in
+ * pointers, and only preserve 32 bits of the integer; values outside the
+ * range of a 32-bit integer will be mangled.
  */
 
 
@@ -1473,9 +1450,8 @@
 /**
  * GPatternSpec:
  *
- * A <structname>GPatternSpec</structname> is the 'compiled' form of a
- * pattern. This structure is opaque and its fields cannot be accessed
- * directly.
+ * A GPatternSpec struct is the 'compiled' form of a pattern. This
+ * structure is opaque and its fields cannot be accessed directly.
  */
 
 
@@ -1498,15 +1474,15 @@
  * See G_PRIVATE_INIT() for a couple of examples.
  *
  * The #GPrivate structure should be considered opaque.  It should only
- * be accessed via the <function>g_private_</function> functions.
+ * be accessed via the g_private_ functions.
  */
 
 
 /**
  * GPtrArray:
  * @pdata: points to the array of pointers, which may be moved when the
- *         array grows.
- * @len: number of pointers in the array.
+ *     array grows
+ * @len: number of pointers in the array
  *
  * Contains the public fields of a pointer array.
  */
@@ -1534,9 +1510,8 @@
  * simultaneous read-only access (by holding the 'reader' lock via
  * g_rw_lock_reader_lock()).
  *
- * <example>
- *  <title>An array with access functions</title>
- *  <programlisting>
+ * Here is an example for an array with access functions:
+ * |[<!-- language="C" -->
  *   GRWLock lock;
  *   GPtrArray *array;
  *
@@ -1548,10 +1523,10 @@
  *     if (!array)
  *       return NULL;
  *
- *     g_rw_lock_reader_lock (&amp;lock);
- *     if (index &lt; array->len)
+ *     g_rw_lock_reader_lock (&lock);
+ *     if (index < array->len)
  *       retval = g_ptr_array_index (array, index);
- *     g_rw_lock_reader_unlock (&amp;lock);
+ *     g_rw_lock_reader_unlock (&lock);
  *
  *     return retval;
  *   }
@@ -1559,35 +1534,30 @@
  *   void
  *   my_array_set (guint index, gpointer data)
  *   {
- *     g_rw_lock_writer_lock (&amp;lock);
+ *     g_rw_lock_writer_lock (&lock);
  *
  *     if (!array)
- *       array = g_ptr_array_new (<!-- -->);
+ *       array = g_ptr_array_new ();
  *
  *     if (index >= array->len)
  *       g_ptr_array_set_size (array, index+1);
  *     g_ptr_array_index (array, index) = data;
  *
- *     g_rw_lock_writer_unlock (&amp;lock);
+ *     g_rw_lock_writer_unlock (&lock);
  *   }
- *  </programlisting>
- *  <para>
- *    This example shows an array which can be accessed by many readers
- *    (the <function>my_array_get()</function> function) simultaneously,
- *    whereas the writers (the <function>my_array_set()</function>
- *    function) will only be allowed once at a time and only if no readers
- *    currently access the array. This is because of the potentially
- *    dangerous resizing of the array. Using these functions is fully
- *    multi-thread safe now.
- *  </para>
- * </example>
+ *  ]|
+ * This example shows an array which can be accessed by many readers
+ * (the my_array_get() function) simultaneously, whereas the writers
+ * (the my_array_set() function) will only be allowed one at a time
+ * and only if no readers currently access the array. This is because
+ * of the potentially dangerous resizing of the array. Using these
+ * functions is fully multi-thread safe now.
  *
  * If a #GRWLock is allocated in static storage then it can be used
  * without initialisation.  Otherwise, you should call
  * g_rw_lock_init() on it and g_rw_lock_clear() when done.
  *
- * A GRWLock should only be accessed with the
- * <function>g_rw_lock_</function> functions.
+ * A GRWLock should only be accessed with the g_rw_lock_ functions.
  *
  * Since: 2.32
  */
@@ -1596,8 +1566,8 @@
 /**
  * GRand:
  *
- * The #GRand struct is an opaque data structure. It should only be
- * accessed through the <function>g_rand_*</function> functions.
+ * The GRand struct is an opaque data structure. It should only be
+ * accessed through the g_rand_* functions.
  */
 
 
@@ -1615,7 +1585,7 @@
  * g_rec_mutex_init() on it and g_rec_mutex_clear() when done.
  *
  * A GRecMutex should only be accessed with the
- * <function>g_rec_mutex_</function> functions.
+ * g_rec_mutex_ functions.
  *
  * Since: 2.32
  */
@@ -1809,11 +1779,9 @@
  * @identifier_2_string: specifies if identifiers are reported as strings
  *     (the default is %FALSE).
  * @char_2_token: specifies if characters are reported by setting
- *     <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default
- *     is %TRUE).
+ *     `token = ch` or as %G_TOKEN_CHAR (the default is %TRUE).
  * @symbol_2_token: specifies if symbols are reported by setting
- *     <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the
- *     default is %FALSE).
+ *     `token = v_symbol` or as %G_TOKEN_SYMBOL (the default is %FALSE).
  * @scope_0_fallback: specifies if a symbol is searched for in the
  *     default scope in addition to the current scope (the default is %FALSE).
  * @store_int64: use value.v_int64 rather than v_int
@@ -1873,8 +1841,7 @@
  * if @a comes before @b, and a positive value if @b comes before @a.
  *
  * Returns: zero if the iterators are equal, a negative value if @a
- *          comes before @b, and a positive value if @b comes before
- *          @a.
+ *     comes before @b, and a positive value if @b comes before @a.
  */
 
 
@@ -1891,7 +1858,7 @@
 /**
  * GStatBuf:
  *
- * A type corresponding to the appropriate struct type for the stat
+ * A type corresponding to the appropriate struct type for the stat()
  * system call, depending on the platform and/or compiler being used.
  *
  * See g_stat() for more information.
@@ -1950,9 +1917,9 @@
  * 'built' terminology that automake uses and are explicitly used to
  * distinguish between the 'srcdir' and 'builddir' being separate.  All
  * files in your project should either be dist (in the
- * <literal>DIST_EXTRA</literal> or <literal>dist_schema_DATA</literal>
+ * `DIST_EXTRA` or `dist_schema_DATA`
  * sense, in which case they will always be in the srcdir) or built (in
- * the <literal>BUILT_SOURCES</literal> sense, in which case they will
+ * the `BUILT_SOURCES` sense, in which case they will
  * always be in the builddir).
  *
  * Note: as a general rule of automake, files that are generated only as
@@ -1997,7 +1964,7 @@
  * GTestSubprocessFlags:
  * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child
  *     process will inherit the parent's stdin. Otherwise, the child's
- *     stdin is redirected to <filename>/dev/null</filename>.
+ *     stdin is redirected to `/dev/null`.
  * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child
  *     process will inherit the parent's stdout. Otherwise, the child's
  *     stdout will not be visible, but it will be captured to allow
@@ -2024,16 +1991,16 @@
 /**
  * GTestTrapFlags:
  * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to
- *     <filename>/dev/null</filename> so it cannot be observed on the
- *     console during test runs. The actual output is still captured
- *     though to allow later tests with g_test_trap_assert_stdout().
+ *     `/dev/null` so it cannot be observed on the console during test
+ *     runs. The actual output is still captured though to allow later
+ *     tests with g_test_trap_assert_stdout().
  * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to
- *     <filename>/dev/null</filename> so it cannot be observed on the
- *     console during test runs. The actual output is still captured
- *     though to allow later tests with g_test_trap_assert_stderr().
+ *     `/dev/null` so it cannot be observed on the console during test
+ *     runs. The actual output is still captured though to allow later
+ *     tests with g_test_trap_assert_stderr().
  * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the
  *     child process is shared with stdin of its parent process.
- *     It is redirected to <filename>/dev/null</filename> otherwise.
+ *     It is redirected to `/dev/null` otherwise.
  *
  * Test traps are guards around forked tests.
  * These flags determine what traps to set.
@@ -2049,7 +2016,7 @@
  *
  * The #GThread struct represents a running thread. This struct
  * is returned by g_thread_new() or g_thread_try_new(). You can
- * obtain the #GThread struct representing the current thead by
+ * obtain the #GThread struct representing the current thread by
  * calling g_thread_self().
  *
  * GThread is refcounted, see g_thread_ref() and g_thread_unref().
@@ -2098,21 +2065,22 @@
 /**
  * GTime:
  *
- * Simply a replacement for <type>time_t</type>. It has been deprecated
- * since it is <emphasis>not</emphasis> equivalent to <type>time_t</type>
- * on 64-bit platforms with a 64-bit <type>time_t</type>.
- * Unrelated to #GTimer.
+ * Simply a replacement for time_t. It has been deprecated
+ * since it is not equivalent to time_t on 64-bit platforms
+ * with a 64-bit time_t. Unrelated to #GTimer.
  *
- * Note that <type>GTime</type> is defined to always be a 32bit integer,
- * unlike <type>time_t</type> which may be 64bit on some systems.
- * Therefore, <type>GTime</type> will overflow in the year 2038, and
- * you cannot use the address of a <type>GTime</type> variable as argument
- * to the UNIX time() function. Instead, do the following:
- * |[
+ * Note that #GTime is defined to always be a 32-bit integer,
+ * unlike time_t which may be 64-bit on some systems. Therefore,
+ * #GTime will overflow in the year 2038, and you cannot use the
+ * address of a #GTime variable as argument to the UNIX time()
+ * function.
+ *
+ * Instead, do the following:
+ * |[<!-- language="C" -->
  * time_t ttime;
  * GTime gtime;
  *
- * time (&amp;ttime);
+ * time (&ttime);
  * gtime = (GTime)ttime;
  * ]|
  */
@@ -2124,8 +2092,8 @@
  * @tv_usec: microseconds
  *
  * Represents a precise time, with seconds and microseconds.
- * Similar to the <structname>struct timeval</structname> returned by
- * the gettimeofday() UNIX system call.
+ * Similar to the struct timeval returned by the gettimeofday()
+ * UNIX system call.
  *
  * GLib is attempting to unify around the use of 64bit integers to
  * represent microsecond-precision time. As such, this type will be
@@ -2203,11 +2171,11 @@
 /**
  * GTrashStack:
  * @next: pointer to the previous element of the stack,
- *     gets stored in the first <literal>sizeof (gpointer)</literal>
+ *     gets stored in the first `sizeof (gpointer)`
  *     bytes of the element
  *
  * Each piece of memory that is pushed onto the stack
- * is cast to a <structname>GTrashStack*</structname>.
+ * is cast to a GTrashStack*.
  */
 
 
@@ -2300,10 +2268,9 @@
 /**
  * GTree:
  *
- * The <structname>GTree</structname> struct is an opaque data
- * structure representing a <link
- * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>. It
- * should be accessed only by using the following functions.
+ * The GTree struct is an opaque data structure representing a <link
+ * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
+ * It should be accessed only by using the following functions.
  */
 
 
@@ -2645,6 +2612,105 @@
 
 
 /**
+ * GVariantDict: (skip)
+ *
+ * #GVariantDict is a mutable interface to #GVariant dictionaries.
+ *
+ * It can be used for doing a sequence of dictionary lookups in an
+ * efficient way on an existing #GVariant dictionary or it can be used
+ * to construct new dictionaries with a hashtable-like interface.  It
+ * can also be used for taking existing dictionaries and modifying them
+ * in order to create new ones.
+ *
+ * #GVariantDict can only be used with %G_VARIANT_TYPE_VARDICT
+ * dictionaries.
+ *
+ * It is possible to use #GVariantDict allocated on the stack or on the
+ * heap.  When using a stack-allocated #GVariantDict, you begin with a
+ * call to g_variant_dict_init() and free the resources with a call to
+ * g_variant_dict_clear().
+ *
+ * Heap-allocated #GVariantDict follows normal refcounting rules: you
+ * allocate it with g_variant_dict_new() and use g_variant_dict_ref()
+ * and g_variant_dict_unref().
+ *
+ * g_variant_dict_end() is used to convert the #GVariantDict back into a
+ * dictionary-type #GVariant.  When used with stack-allocated instances,
+ * this also implicitly frees all associated memory, but for
+ * heap-allocated instances, you must still call g_variant_dict_unref()
+ * afterwards.
+ *
+ * You will typically want to use a heap-allocated #GVariantDict when
+ * you expose it as part of an API.  For most other uses, the
+ * stack-allocated form will be more convenient.
+ *
+ * Consider the following two examples that do the same thing in each
+ * style: take an existing dictionary and look up the "count" uint32
+ * key, adding 1 to it if it is found, or returning an error if the
+ * key is not found.  Each returns the new dictionary as a floating
+ * #GVariant.
+ *
+ * <example>
+ *  <title>Using stack-allocated #GVariantDict</title>
+ *  <programlisting>
+ *   GVariant *
+ *   add_to_count (GVariant  *orig,
+ *                 GError   **error)
+ *   {
+ *     GVariantDict dict;
+ *     guint32 count;
+ *
+ *     g_variant_dict_init (&amp;dict, orig);
+ *     if (!g_variant_dict_lookup (&amp;dict, "count", "u", &amp;count))
+ *       {
+ *         g_set_error (...);
+ *         g_variant_dict_clear (&amp;dict);
+ *         return NULL;
+ *       }
+ *
+ *     g_variant_dict_insert (&amp;dict, "count", "u", count + 1);
+ *
+ *     return g_variant_dict_end (&amp;dict);
+ *   }
+ *  </programlisting>
+ * </example>
+ *
+ * <example>
+ *  <title>Using heap-allocated #GVariantDict</title>
+ *  <programlisting>
+ *   GVariant *
+ *   add_to_count (GVariant  *orig,
+ *                 GError   **error)
+ *   {
+ *     GVariantDict *dict;
+ *     GVariant *result;
+ *     guint32 count;
+ *
+ *     dict = g_variant_dict_new (orig);
+ *
+ *     if (g_variant_dict_lookup (dict, "count", "u", &amp;count))
+ *       {
+ *         g_variant_dict_insert (dict, "count", "u", count + 1);
+ *         result = g_variant_dict_end (dict);
+ *       }
+ *     else
+ *       {
+ *         g_set_error (...);
+ *         result = NULL;
+ *       }
+ *
+ *     g_variant_dict_unref (dict);
+ *
+ *     return result;
+ *   }
+ *  </programlisting>
+ * </example>
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * GVariantIter: (skip)
  *
  * #GVariantIter is an opaque data structure and can only be accessed
@@ -2685,10 +2751,10 @@
  * on systems with 64bit IEEE-compatible doubles.
  *
  * The typical usage would be something like:
- * |[
+ * |[<!-- language="C" -->
  *   char buf[G_ASCII_DTOSTR_BUF_SIZE];
  *
- *   fprintf (out, "value=&percnt;s\n", g_ascii_dtostr (buf, sizeof (buf), value));
+ *   fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
  * ]|
  */
 
@@ -2711,7 +2777,7 @@
  * G_BEGIN_DECLS:
  *
  * Used (along with #G_END_DECLS) to bracket header files. If the
- * compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
+ * compiler in use is a C++ compiler, adds extern "C"
  * around the header.
  */
 
@@ -2736,19 +2802,17 @@
 /**
  * G_CONST_RETURN:
  *
- * If <literal>G_DISABLE_CONST_RETURNS</literal> is defined, this macro expands
- * to nothing. By default, the macro expands to <literal>const</literal>.
- * The macro should be used in place of <literal>const</literal> for
- * functions that return a value that should not be modified. The
- * purpose of this macro is to allow us to turn on <literal>const</literal>
- * for returned constant strings by default, while allowing programmers
- * who find that annoying to turn it off. This macro should only be used
- * for return values and for <emphasis>out</emphasis> parameters, it doesn't
- * make sense for <emphasis>in</emphasis> parameters.
+ * If %G_DISABLE_CONST_RETURNS is defined, this macro expands
+ * to nothing. By default, the macro expands to const. The macro
+ * can be used in place of const for functions that return a value
+ * that should not be modified. The purpose of this macro is to allow
+ * us to turn on const for returned constant strings by default, while
+ * allowing programmers who find that annoying to turn it off. This macro
+ * should only be used for return values and for "out" parameters, it
+ * doesn't make sense for "in" parameters.
  *
  * Deprecated: 2.30: API providers should replace all existing uses with
- *     <literal>const</literal> and API consumers should adjust their code
- *     accordingly
+ * const and API consumers should adjust their code accordingly
  */
 
 
@@ -2818,9 +2882,10 @@
  *
  * A convenience macro which defines a function returning the
  * #GQuark for the name @QN. The function will be named
- * @q_n<!-- -->_quark().
- * Note that the quark name will be stringified automatically in the
- * macro, so you shouldn't use double quotes.
+ * @q_n_quark().
+ *
+ * Note that the quark name will be stringified automatically
+ * in the macro, so you shouldn't use double quotes.
  *
  * Since: 2.34
  */
@@ -2843,8 +2908,8 @@
  * @f: the name of the function that this function was deprecated for
  *
  * This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark
- * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it is
- * meant to be portable across different compilers and must be placed
+ * functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it
+ * is meant to be portable across different compilers and must be placed
  * before the function declaration.
  *
  * Since: 2.32
@@ -2878,7 +2943,7 @@
  * G_END_DECLS:
  *
  * Used (along with #G_BEGIN_DECLS) to bracket header files. If the
- * compiler in use is a C++ compiler, adds <literal>extern "C"</literal>
+ * compiler in use is a C++ compiler, adds extern "C"
  * around the header.
  */
 
@@ -2900,10 +2965,10 @@
  * include the percent-sign, such that you can add precision and length
  * modifiers between percent-sign and conversion specifier.
  *
- * |[
+ * |[<!-- language="C" -->
  * gint16 in;
  * gint32 out;
- * sscanf ("42", "%" G_GINT16_FORMAT, &amp;in)
+ * sscanf ("42", "%" G_GINT16_FORMAT, &in)
  * out = in * 1000;
  * g_print ("%" G_GINT32_FORMAT, out);
  * ]|
@@ -2920,7 +2985,7 @@
  * and conversion specifier and append a conversion specifier.
  *
  * The following example prints "0x7b";
- * |[
+ * |[<!-- language="C" -->
  * gint16 value = 123;
  * g_print ("%#" G_GINT16_MODIFIER "x", value);
  * ]|
@@ -2963,14 +3028,12 @@
  * This is the platform dependent conversion specifier for scanning
  * and printing values of type #gint64. See also #G_GINT16_FORMAT.
  *
- * <note><para>
- * Some platforms do not support scanning and printing 64 bit integers,
- * even though the types are supported. On such platforms #G_GINT64_FORMAT
- * is not defined. Note that scanf() may not support 64 bit integers, even
- * if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
+ * Some platforms do not support scanning and printing 64-bit integers,
+ * even though the types are supported. On such platforms %G_GINT64_FORMAT
+ * is not defined. Note that scanf() may not support 64-bit integers, even
+ * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
  * is not recommended for parsing anyway; consider using g_ascii_strtoull()
  * instead.
- * </para></note>
  */
 
 
@@ -2981,11 +3044,9 @@
  * for scanning and printing values of type #gint64 or #guint64.
  * It is a string literal.
  *
- * <note><para>
- * Some platforms do not support printing 64 bit integers, even
- * though the types are supported. On such platforms #G_GINT64_MODIFIER
+ * Some platforms do not support printing 64-bit integers, even
+ * though the types are supported. On such platforms %G_GINT64_MODIFIER
  * is not defined.
- * </para></note>
  *
  * Since: 2.4
  */
@@ -3016,10 +3077,10 @@
  * G_GNUC_ALLOC_SIZE:
  * @x: the index of the argument specifying the allocation size
  *
- * Expands to the GNU C <literal>alloc_size</literal> function attribute
- * if the compiler is a new enough <command>gcc</command>. This attribute
- * tells the compiler that the function returns a pointer to memory of a
- * size that is specified by the @x<!-- -->th function parameter.
+ * Expands to the GNU C alloc_size function attribute if the compiler
+ * is a new enough gcc. This attribute tells the compiler that the
+ * function returns a pointer to memory of a size that is specified
+ * by the @xth function parameter.
  *
  * Place the attribute after the function declaration, just before the
  * semicolon.
@@ -3035,10 +3096,10 @@
  * @x: the index of the argument specifying one factor of the allocation size
  * @y: the index of the argument specifying the second factor of the allocation size
  *
- * Expands to the GNU C <literal>alloc_size</literal> function attribute
- * if the compiler is a new enough <command>gcc</command>. This attribute
- * tells the compiler that the function returns a pointer to memory of a
- * size that is specified by the product of two function parameters.
+ * Expands to the GNU C alloc_size function attribute if the compiler is a
+ * new enough gcc. This attribute tells the compiler that the function returns
+ * a pointer to memory of a size that is specified by the product of two
+ * function parameters.
  *
  * Place the attribute after the function declaration, just before the
  * semicolon.
@@ -3052,16 +3113,15 @@
 /**
  * G_GNUC_BEGIN_IGNORE_DEPRECATIONS:
  *
- * Tells <command>gcc</command> (if it is a new enough version) to
- * temporarily stop emitting warnings when functions marked with
- * %G_GNUC_DEPRECATED or %G_GNUC_DEPRECATED_FOR are called. This is
- * useful for when you have one deprecated function calling another
- * one, or when you still have regression tests for deprecated
- * functions.
+ * Tells gcc (if it is a new enough version) to temporarily stop emitting
+ * warnings when functions marked with %G_GNUC_DEPRECATED or
+ * %G_GNUC_DEPRECATED_FOR are called. This is useful for when you have
+ * one deprecated function calling another one, or when you still have
+ * regression tests for deprecated functions.
  *
  * Use %G_GNUC_END_IGNORE_DEPRECATIONS to begin warning again. (If you
- * are not compiling with <literal>-Wdeprecated-declarations</literal>
- * then neither macro has any effect.)
+ * are not compiling with `-Wdeprecated-declarations` then neither macro
+ * has any effect.)
  *
  * This macro can be used either inside or outside of a function body,
  * but must appear on a line by itself.
@@ -3073,33 +3133,29 @@
 /**
  * G_GNUC_CONST:
  *
- * Expands to the GNU C <literal>const</literal> function attribute if
- * the compiler is <command>gcc</command>. Declaring a function as const
- * enables better optimization of calls to the function. A const function
- * doesn't examine any values except its parameters, and has no effects
- * except its return value.
+ * Expands to the GNU C const function attribute if the compiler is gcc.
+ * Declaring a function as const enables better optimization of calls to
+ * the function. A const function doesn't examine any values except its
+ * parameters, and has no effects except its return value.
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
  * See the GNU C documentation for more details.
  *
- * <note><para>
  * A function that has pointer arguments and examines the data pointed to
- * must <emphasis>not</emphasis> be declared const. Likewise, a function
- * that calls a non-const function usually must not be const. It doesn't
- * make sense for a const function to return void.
- * </para></note>
+ * must not be declared const. Likewise, a function that calls a non-const
+ * function usually must not be const. It doesn't make sense for a const
+ * function to return void.
  */
 
 
 /**
  * G_GNUC_DEPRECATED:
  *
- * Expands to the GNU C <literal>deprecated</literal> attribute if the
- * compiler is <command>gcc</command>. It can be used to mark typedefs,
- * variables and functions as deprecated. When called with the
- * <option>-Wdeprecated-declarations</option> option, the compiler will
- * generate warnings when deprecated interfaces are used.
+ * Expands to the GNU C deprecated attribute if the compiler is gcc.
+ * It can be used to mark typedefs, variables and functions as deprecated.
+ * When called with the `-Wdeprecated-declarations` option,
+ * gcc will generate warnings when deprecated interfaces are used.
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
@@ -3115,8 +3171,8 @@
  *     such as the name of a function
  *
  * Like %G_GNUC_DEPRECATED, but names the intended replacement for the
- * deprecated symbol if the version of <command>gcc</command> in use is
- * new enough to support custom deprecation messages.
+ * deprecated symbol if the version of gcc in use is new enough to support
+ * custom deprecation messages.
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
@@ -3134,8 +3190,8 @@
  * G_GNUC_END_IGNORE_DEPRECATIONS:
  *
  * Undoes the effect of %G_GNUC_BEGIN_IGNORE_DEPRECATIONS, telling
- * <command>gcc</command> to begin outputting warnings again
- * (assuming those warnings had been enabled to begin with).
+ * gcc to begin outputting warnings again (assuming those warnings
+ * had been enabled to begin with).
  *
  * This macro can be used either inside or outside of a function body,
  * but must appear on a line by itself.
@@ -3147,10 +3203,9 @@
 /**
  * G_GNUC_EXTENSION:
  *
- * Expands to <literal>__extension__</literal> when <command>gcc</command>
- * is used as the compiler. This simply tells <command>gcc</command> not
- * to warn about the following non-standard code when compiling with the
- * <option>-pedantic</option> option.
+ * Expands to __extension__ when gcc is used as the compiler. This simply
+ * tells gcc not to warn about the following non-standard code when compiling
+ * with the `-pedantic` option.
  */
 
 
@@ -3158,21 +3213,20 @@
  * G_GNUC_FORMAT:
  * @arg_idx: the index of the argument
  *
- * Expands to the GNU C <literal>format_arg</literal> function attribute
- * if the compiler is <command>gcc</command>. This function attribute
- * specifies that a function takes a format string for a printf(),
- * scanf(), strftime() or strfmon() style function and modifies it,
- * so that the result can be passed to a printf(), scanf(), strftime()
- * or strfmon() style function (with the remaining arguments to the
- * format function the same as they would have been for the unmodified
- * string).
+ * Expands to the GNU C format_arg function attribute if the compiler
+ * is gcc. This function attribute specifies that a function takes a
+ * format string for a printf(), scanf(), strftime() or strfmon() style
+ * function and modifies it, so that the result can be passed to a printf(),
+ * scanf(), strftime() or strfmon() style function (with the remaining
+ * arguments to the format function the same as they would have been
+ * for the unmodified string).
  *
  * Place the attribute after the function declaration, just before the
  * semicolon.
  *
  * See the GNU C documentation for more details.
  *
- * |[
+ * |[<!-- language="C" -->
  * gchar *g_dgettext (gchar *domain_name, gchar *msgid) G_GNUC_FORMAT (2);
  * ]|
  */
@@ -3181,11 +3235,10 @@
 /**
  * G_GNUC_FUNCTION:
  *
- * Expands to "" on all modern compilers, and to
- * <literal>__FUNCTION__</literal> on <command>gcc</command> version 2.x.
- * Don't use it.
+ * Expands to "" on all modern compilers, and to  __FUNCTION__ on gcc
+ * version 2.x. Don't use it.
  *
- * Deprecated: 2.16: Use #G_STRFUNC instead
+ * Deprecated: 2.16: Use G_STRFUNC() instead
  */
 
 
@@ -3199,14 +3252,14 @@
  * details.
  *
  * When using a compiler that supports the GNU C hidden visibility attribute,
- * this macro expands to <literal>__attribute__((visibility("hidden")))</literal>.
- * When using the Sun Studio compiler, it expands to <literal>__hidden</literal>.
+ * this macro expands to __attribute__((visibility("hidden"))).
+ * When using the Sun Studio compiler, it expands to __hidden.
  *
  * Note that for portability, the attribute should be placed before the
  * function declaration. While GCC allows the macro after the declaration,
  * Sun Studio does not.
  *
- * |[
+ * |[<!-- language="C" -->
  * G_GNUC_INTERNAL
  * void _g_log_fallback_handler (const gchar    *log_domain,
  *                               GLogLevelFlags  log_level,
@@ -3221,12 +3274,11 @@
 /**
  * G_GNUC_MALLOC:
  *
- * Expands to the GNU C <literal>malloc</literal> function attribute if the
- * compiler is <command>gcc</command>. Declaring a function as malloc enables
- * better optimization of the function. A function can have the malloc
- * attribute if it returns a pointer which is guaranteed to not alias with
- * any other pointer when the function returns (in practice, this means newly
- * allocated memory).
+ * Expands to the GNU C malloc function attribute if the compiler is gcc.
+ * Declaring a function as malloc enables better optimization of the function.
+ * A function can have the malloc attribute if it returns a pointer which is
+ * guaranteed to not alias with any other pointer when the function returns
+ * (in practice, this means newly allocated memory).
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
@@ -3239,10 +3291,10 @@
 /**
  * G_GNUC_MAY_ALIAS:
  *
- * Expands to the GNU C <literal>may_alias</literal> type attribute
- * if the compiler is <command>gcc</command>. Types with this attribute
- * will not be subjected to type-based alias analysis, but are assumed
- * to alias with any other type, just like char.
+ * Expands to the GNU C may_alias type attribute if the compiler is gcc.
+ * Types with this attribute will not be subjected to type-based alias
+ * analysis, but are assumed to alias with any other type, just like char.
+ *
  * See the GNU C documentation for details.
  *
  * Since: 2.14
@@ -3252,10 +3304,9 @@
 /**
  * G_GNUC_NORETURN:
  *
- * Expands to the GNU C <literal>noreturn</literal> function attribute
- * if the compiler is <command>gcc</command>. It is used for declaring
- * functions which never return. It enables optimization of the function,
- * and avoids possible compiler warnings.
+ * Expands to the GNU C noreturn function attribute if the compiler is gcc.
+ * It is used for declaring functions which never return. It enables
+ * optimization of the function, and avoids possible compiler warnings.
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
@@ -3266,10 +3317,10 @@
 /**
  * G_GNUC_NO_INSTRUMENT:
  *
- * Expands to the GNU C <literal>no_instrument_function</literal> function
- * attribute if the compiler is <command>gcc</command>. Functions with this
- * attribute will not be instrumented for profiling, when the compiler is
- * called with the <option>-finstrument-functions</option> option.
+ * Expands to the GNU C no_instrument_function function attribute if the
+ * compiler is gcc. Functions with this attribute will not be instrumented
+ * for profiling, when the compiler is called with the
+ * `-finstrument-functions` option.
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
@@ -3280,9 +3331,8 @@
 /**
  * G_GNUC_NULL_TERMINATED:
  *
- * Expands to the GNU C <literal>sentinel</literal> function attribute
- * if the compiler is <command>gcc</command>, or "" if it isn't. This
- * function attribute only applies to variadic functions and instructs
+ * Expands to the GNU C sentinel function attribute if the compiler is gcc.
+ * This function attribute only applies to variadic functions and instructs
  * the compiler to check that the argument list is terminated with an
  * explicit %NULL.
  *
@@ -3297,11 +3347,10 @@
 /**
  * G_GNUC_PRETTY_FUNCTION:
  *
- * Expands to "" on all modern compilers, and to
- * <literal>__PRETTY_FUNCTION__</literal> on <command>gcc</command>
- * version 2.x. Don't use it.
+ * Expands to "" on all modern compilers, and to __PRETTY_FUNCTION__
+ * on gcc version 2.x. Don't use it.
  *
- * Deprecated: 2.16: Use #G_STRFUNC instead
+ * Deprecated: 2.16: Use G_STRFUNC() instead
  */
 
 
@@ -3311,18 +3360,17 @@
  *     format string (The arguments are numbered from 1)
  * @arg_idx: the index of the first of the format arguments
  *
- * Expands to the GNU C <literal>format</literal> function attribute
- * if the compiler is <command>gcc</command>. This is used for declaring
- * functions which take a variable number of arguments, with the same
- * syntax as printf(). It allows the compiler to type-check the arguments
- * passed to the function.
+ * Expands to the GNU C format function attribute if the compiler is gcc.
+ * This is used for declaring functions which take a variable number of
+ * arguments, with the same syntax as printf(). It allows the compiler
+ * to type-check the arguments passed to the function.
  *
  * Place the attribute after the function declaration, just before the
  * semicolon.
  *
  * See the GNU C documentation for more details.
  *
- * |[
+ * |[<!-- language="C" -->
  * gint g_snprintf (gchar  *string,
  *                  gulong       n,
  *                  gchar const *format,
@@ -3334,11 +3382,11 @@
 /**
  * G_GNUC_PURE:
  *
- * Expands to the GNU C <literal>pure</literal> function attribute if the
- * compiler is <command>gcc</command>. Declaring a function as pure enables
- * better optimization of calls to the function. A pure function has no
- * effects except its return value and the return value depends only on
- * the parameters and/or global variables.
+ * Expands to the GNU C pure function attribute if the compiler is gcc.
+ * Declaring a function as pure enables better optimization of calls to
+ * the function. A pure function has no effects except its return value
+ * and the return value depends only on the parameters and/or global
+ * variables.
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
@@ -3352,27 +3400,27 @@
  *     the format string (The arguments are numbered from 1)
  * @arg_idx: the index of the first of the format arguments
  *
- * Expands to the GNU C <literal>format</literal> function attribute
- * if the compiler is <command>gcc</command>. This is used for declaring
- * functions which take a variable number of arguments, with the same
- * syntax as scanf(). It allows the compiler to type-check the arguments
- * passed to the function. See the GNU C documentation for details.
+ * Expands to the GNU C format function attribute if the compiler is gcc.
+ * This is used for declaring functions which take a variable number of
+ * arguments, with the same syntax as scanf(). It allows the compiler
+ * to type-check the arguments passed to the function.
+ *
+ * See the GNU C documentation for details.
  */
 
 
 /**
  * G_GNUC_UNUSED:
  *
- * Expands to the GNU C <literal>unused</literal> function attribute if
- * the compiler is <command>gcc</command>. It is used for declaring
- * functions and arguments which may never be used. It avoids possible compiler
- * warnings.
+ * Expands to the GNU C unused function attribute if the compiler is gcc.
+ * It is used for declaring functions and arguments which may never be used.
+ * It avoids possible compiler warnings.
  *
  * For functions, place the attribute after the declaration, just before the
  * semicolon. For arguments, place the attribute at the beginning of the
  * argument declaration.
  *
- * |[
+ * |[<!-- language="C" -->
  * void my_unused_function (G_GNUC_UNUSED gint unused_argument,
  *                          gint other_argument) G_GNUC_UNUSED;
  * ]|
@@ -3384,10 +3432,9 @@
 /**
  * G_GNUC_WARN_UNUSED_RESULT:
  *
- * Expands to the GNU C <literal>warn_unused_result</literal> function
- * attribute if the compiler is <command>gcc</command>, or "" if it isn't.
- * This function attribute makes the compiler emit a warning if the result
- * of a function call is ignored.
+ * Expands to the GNU C warn_unused_result function attribute if the compiler
+ * is gcc. This function attribute makes the compiler emit a warning if the
+ * result of a function call is ignored.
  *
  * Place the attribute after the declaration, just before the semicolon.
  *
@@ -3495,14 +3542,12 @@
  * This is the platform dependent conversion specifier for scanning
  * and printing values of type #guint64. See also #G_GINT16_FORMAT.
  *
- * <note><para>
- * Some platforms do not support scanning and printing 64 bit integers,
- * even though the types are supported. On such platforms #G_GUINT64_FORMAT
- * is not defined.  Note that scanf() may not support 64 bit integers, even
- * if #G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
+ * Some platforms do not support scanning and printing 64-bit integers,
+ * even though the types are supported. On such platforms %G_GUINT64_FORMAT
+ * is not defined.  Note that scanf() may not support 64-bit integers, even
+ * if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
  * is not recommended for parsing anyway; consider using g_ascii_strtoull()
  * instead.
- * </para></note>
  */
 
 
@@ -3520,7 +3565,7 @@
  * G_HOOK:
  * @hook: a pointer
  *
- * Casts a pointer to a <literal>GHook*</literal>.
+ * Casts a pointer to a `GHook*`.
  */
 
 
@@ -3548,7 +3593,7 @@
  *
  * The position of the first bit which is not reserved for internal
  * use be the #GHook implementation, i.e.
- * <literal>1 &lt;&lt; G_HOOK_FLAG_USER_SHIFT</literal> is the first
+ * `1 &lt;&lt; G_HOOK_FLAG_USER_SHIFT` is the first
  * bit which can be used for application-defined flags.
  */
 
@@ -3603,7 +3648,7 @@
  *
  * This macro is used to export function prototypes so they can be linked
  * with an external version when no inlining is performed. The file which
- * implements the functions should define <literal>G_IMPLEMENTS_INLINES</literal>
+ * implements the functions should define %G_IMPLEMENTS_INLINES
  * before including the headers which contain %G_INLINE_FUNC declarations.
  * Since inlining is very compiler-dependent using these macros correctly
  * is very difficult. Their use is strongly discouraged.
@@ -3624,17 +3669,6 @@
 
 
 /**
- * G_IO_FLAG_IS_WRITEABLE:
- *
- * This is a misspelled version of G_IO_FLAG_IS_WRITABLE that existed
- * before the spelling was fixed in GLib 2.30.  It is kept here for
- * compatibility reasons.
- *
- * Deprecated: 2.30: Use G_IO_FLAG_IS_WRITABLE instead.
- */
-
-
-/**
  * G_IS_DIR_SEPARATOR:
  * @c: a character
  *
@@ -3650,8 +3684,8 @@
  * G_KEY_FILE_DESKTOP_GROUP:
  *
  * The name of the main group of a desktop entry file, as defined in the
- * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
- * Entry Specification</ulink>. Consult the specification for more
+ * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec).
+ * Consult the specification for more
  * details about the meanings of the keys below.
  *
  * Since: 2.14
@@ -3684,7 +3718,7 @@
  *
  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * giving the command line to execute. It is only valid for desktop
- * entries with the <literal>Application</literal> type.
+ * entries with the `Application` type.
  *
  * Since: 2.14
  */
@@ -3778,7 +3812,7 @@
  *
  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * containing the working directory to run the program in. It is only
- * valid for desktop entries with the <literal>Application</literal> type.
+ * valid for desktop entries with the `Application` type.
  *
  * Since: 2.14
  */
@@ -3788,9 +3822,8 @@
  * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY:
  *
  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
- * stating whether the application supports the <ulink
- * url="http://www.freedesktop.org/Standards/startup-notification-spec">Startup
- * Notification Protocol Specification</ulink>.
+ * stating whether the application supports the
+ * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec).
  *
  * Since: 2.14
  */
@@ -3814,7 +3847,7 @@
  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
  * stating whether the program should be run in a terminal window.
  * It is only valid for desktop entries with the
- * <literal>Application</literal> type.
+ * `Application` type.
  *
  * Since: 2.14
  */
@@ -3826,7 +3859,7 @@
  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * giving the file name of a binary on disk used to determine if the
  * program is actually installed. It is only valid for desktop entries
- * with the <literal>Application</literal> type.
+ * with the `Application` type.
  *
  * Since: 2.14
  */
@@ -3850,7 +3883,7 @@
  *
  * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * giving the URL to access. It is only valid for desktop entries
- * with the <literal>Link</literal> type.
+ * with the `Link` type.
  *
  * Since: 2.14
  */
@@ -3914,7 +3947,7 @@
  * Hints the compiler that the expression is likely to evaluate to
  * a true value. The compiler may use this information for optimizations.
  *
- * |[
+ * |[<!-- language="C" -->
  * if (G_LIKELY (random () != 1))
  *   g_print ("not one");
  * ]|
@@ -3959,19 +3992,17 @@
  * G_LOCK_DEFINE:
  * @name: the name of the lock
  *
- * The <literal>G_LOCK_*</literal> macros provide a convenient interface to #GMutex.
+ * The #G_LOCK_ macros provide a convenient interface to #GMutex.
  * #G_LOCK_DEFINE defines a lock. It can appear in any place where
  * variable definitions may appear in programs, i.e. in the first block
  * of a function or outside of functions. The @name parameter will be
  * mangled to get the name of the #GMutex. This means that you
  * can use names of existing variables as the parameter - e.g. the name
  * of the variable you intend to protect with the lock. Look at our
- * <function>give_me_next_number()</function> example using the
- * <literal>G_LOCK_*</literal> macros:
+ * give_me_next_number() example using the #G_LOCK macros:
  *
- * <example>
- *  <title>Using the <literal>G_LOCK_*</literal> convenience macros</title>
- *  <programlisting>
+ * Here is an example for using the #G_LOCK convenience macros:
+ * |[<!-- language="C" -->
  *   G_LOCK_DEFINE (current_number);
  *
  *   int
@@ -3986,8 +4017,7 @@
  *
  *     return ret_val;
  *   }
- *  </programlisting>
- * </example>
+ * ]|
  */
 
 
@@ -4195,7 +4225,7 @@
  * The minimum positive value which can be held in a #gdouble.
  *
  * If you are interested in the smallest value which can be held
- * in a #gdouble, use -G_MAXDOUBLE.
+ * in a #gdouble, use -%G_MAXDOUBLE.
  */
 
 
@@ -4205,7 +4235,7 @@
  * The minimum positive value which can be held in a #gfloat.
  *
  * If you are interested in the smallest value which can be held
- * in a #gfloat, use -G_MAXFLOAT.
+ * in a #gfloat, use -%G_MAXFLOAT.
  */
 
 
@@ -4296,7 +4326,7 @@
  *
  * A #GOnce must be initialized with this macro before it can be used.
  *
- * |[
+ * |[<!-- language="C" -->
  *   GOnce my_once = G_ONCE_INIT;
  * ]|
  *
@@ -4326,10 +4356,10 @@
  * @identifier2: an identifier
  *
  * Yields a new preprocessor pasted identifier
- * <code>identifier1identifier2</code> from its expanded
+ * @identifier1identifier2 from its expanded
  * arguments @identifier1 and @identifier2. For example,
  * the following code:
- * |[
+ * |[<!-- language="C" -->
  * #define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller)
  * const gchar *name = GET (traveller, name);
  * const gchar *quest = GET (traveller, quest);
@@ -4337,7 +4367,7 @@
  * ]|
  *
  * is transformed by the preprocessor into:
- * |[
+ * |[<!-- language="C" -->
  * const gchar *name = traveller_get_name (traveller);
  * const gchar *quest = traveller_get_quest (traveller);
  * GdkColor *favourite = traveller_get_favourite_colour (traveller);
@@ -4395,10 +4425,10 @@
  * be properly initialised by default (ie: to all zeros).  See the
  * examples below.
  *
- * |[
+ * |[<!-- language="C" -->
  * static GPrivate name_key = G_PRIVATE_INIT (g_free);
  *
- * // return value should not be freed
+ * /&ast; return value should not be freed &ast;/
  * const gchar *
  * get_local_name (void)
  * {
@@ -4412,7 +4442,7 @@
  * }
  *
  *
- * static GPrivate count_key;   // no free function
+ * static GPrivate count_key;   /&ast; no free function &ast;/
  *
  * gint
  * get_local_count (void)
@@ -4467,18 +4497,14 @@
  * G_STATIC_ASSERT:
  * @expr: a constant expression
  *
- * The G_STATIC_ASSERT macro lets the programmer check
+ * The G_STATIC_ASSERT() macro lets the programmer check
  * a condition at compile time, the condition needs to
  * be compile time computable. The macro can be used in
- * any place where a <literal>typedef</literal> is valid.
+ * any place where a typedef is valid.
  *
- * <note><para>
- * A <literal>typedef</literal> is generally allowed in
- * exactly the same places that a variable declaration is
- * allowed. For this reason, you should not use
- * <literal>G_STATIC_ASSERT</literal> in the middle of
- * blocks of code.
- * </para></note>
+ * A typedef is generally allowed in exactly the same places that
+ * a variable declaration is allowed. For this reason, you should
+ * not use G_STATIC_ASSERT() in the middle of blocks of code.
  *
  * The macro should only be used once per source code line.
  *
@@ -4490,17 +4516,16 @@
  * G_STATIC_ASSERT_EXPR:
  * @expr: a constant expression
  *
- * The G_STATIC_ASSERT_EXPR macro lets the programmer check
+ * The G_STATIC_ASSERT_EXPR() macro lets the programmer check
  * a condition at compile time. The condition needs to be
  * compile time computable.
  *
- * Unlike <literal>G_STATIC_ASSERT</literal>, this macro
- * evaluates to an expression and, as such, can be used in
- * the middle of other expressions. Its value should be
- * ignored. This can be accomplished by placing it as
- * the first argument of a comma expression.
+ * Unlike G_STATIC_ASSERT(), this macro evaluates to an expression
+ * and, as such, can be used in the middle of other expressions.
+ * Its value should be ignored. This can be accomplished by placing
+ * it as the first argument of a comma expression.
  *
- * |[
+ * |[<!-- language="C" -->
  * #define ADD_ONE_TO_INT(x) \
  *   (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
  * ]|
@@ -4541,14 +4566,14 @@
  * Accepts a macro or a string and converts it into a string after
  * preprocessor argument expansion. For example, the following code:
  *
- * |[
+ * |[<!-- language="C" -->
  * #define AGE 27
  * const gchar *greeting = G_STRINGIFY (AGE) " today!";
  * ]|
  *
  * is transformed by the preprocessor into (code equivalent to):
  *
- * |[
+ * |[<!-- language="C" -->
  * const gchar *greeting = "27 today!";
  * ]|
  */
@@ -4587,8 +4612,8 @@
 
 /**
  * G_STRUCT_OFFSET:
- * @struct_type: a structure type, e.g. <structname>GtkWidget</structname>
- * @member: a field in the structure, e.g. <structfield>window</structfield>
+ * @struct_type: a structure type, e.g. #GtkWidget
+ * @member: a field in the structure, e.g. @window
  *
  * Returns the offset, in bytes, of a member of a struct.
  *
@@ -4641,7 +4666,7 @@
  * Hints the compiler that the expression is unlikely to evaluate to
  * a true value. The compiler may use this information for optimizations.
  *
- * |[
+ * |[<!-- language="C" -->
  * if (G_UNLIKELY (random () == 1))
  *   g_print ("a random one");
  * ]|
@@ -4679,15 +4704,14 @@
 
 /**
  * G_VA_COPY:
- * @ap1: the <type>va_list</type> variable to place a copy of @ap2 in
- * @ap2: a <type>va_list</type>
+ * @ap1: the va_list variable to place a copy of @ap2 in
+ * @ap2: a va_list
  *
- * Portable way to copy <type>va_list</type> variables.
+ * Portable way to copy va_list variables.
  *
- * In order to use this function, you must include
- * <filename>string.h</filename> yourself, because this macro may
- * use memmove() and GLib does not include <filename>string.h</filename>
- * for you.
+ * In order to use this function, you must include string.h yourself,
+ * because this macro may use memmove() and GLib does not include
+ * string.h for you.
  */
 
 
@@ -4696,8 +4720,8 @@
  * @static: empty or "static"
  * @dll_name: the name of the (pointer to the) char array where
  *     the DLL name will be stored. If this is used, you must also
- *     include <filename>windows.h</filename>. If you need a more
- *     complex DLL entry point function, you cannot use this
+ *     include `windows.h`. If you need a more complex DLL entry
+ *     point function, you cannot use this
  *
  * On Windows, this macro defines a DllMain() function that stores
  * the actual DLL name that the code being compiled will be included in.
@@ -4774,7 +4798,7 @@
  * be directly used, e.g. in string array initializers. To get the
  * translated string, you should call g_dpgettext2() at runtime.
  *
- * |[
+ * |[<!-- language="C" -->
  * {
  *   static const char *messages[] = {
  *     NC_("some context", "some very meaningful message"),
@@ -4783,19 +4807,18 @@
  *   const char *string;
  *   ...
  *   string
- *     = index &gt; 1 ? g_dpgettext2 (NULL, "some context", "a default message")
- *                    : g_dpgettext2 (NULL, "some context", messages[index]);
+ *     = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
+ *                 : g_dpgettext2 (NULL, "some context", messages[index]);
  *
  *   fputs (string);
  *   ...
  * }
  * ]|
  *
- * <note><para>If you are using the NC_() macro, you need to make sure
- * that you pass <option>--keyword=NC_:1c,2</option> to xgettext when
- * extracting messages. Note that this only works with GNU gettext >= 0.15.
- * Intltool has support for the NC_() macro since version 0.40.1.
- * </para></note>
+ * If you are using the NC_() macro, you need to make sure that you pass
+ * `--keyword=NC_:1c,2` to xgettext when extracting messages.
+ * Note that this only works with GNU gettext >= 0.15. Intltool has support
+ * for the NC_() macro since version 0.40.1.
  *
  * Since: 2.18
  */
@@ -4816,7 +4839,7 @@
  * where the translated strings can't be directly used, e.g. in string
  * array initializers. To get the translated string, call gettext()
  * at runtime.
- * |[
+ * |[<!-- language="C" -->
  * {
  *   static const char *messages[] = {
  *     N_("some very meaningful message"),
@@ -4855,11 +4878,11 @@
  * See the C_() macro for a different way to mark up translatable strings
  * with context.
  *
- * <note><para>If you are using the Q_() macro, you need to make sure
- * that you pass <option>--keyword=Q_</option> to xgettext when extracting
- * messages. If you are using GNU gettext >= 0.15, you can also use
- * <option>--keyword=Q_:1g</option> to let xgettext split the context
- * string off into a msgctxt line in the po file.</para></note>
+ * If you are using the Q_() macro, you need to make sure that you pass
+ * `--keyword=Q_` to xgettext when extracting messages.
+ * If you are using GNU gettext >= 0.15, you can also use
+ * `--keyword=Q_:1g` to let xgettext split the context
+ * string off into a msgctxt line in the po file.
  *
  * Returns: the translated message
  * Since: 2.4
@@ -4870,7 +4893,7 @@
  * SECTION:arrays
  * @title: Arrays
  * @short_description: arrays of arbitrary elements which grow
- *                     automatically as elements are added
+ *     automatically as elements are added
  *
  * Arrays are similar to standard C arrays, except that they grow
  * automatically as elements are added.
@@ -4891,23 +4914,22 @@
  *
  * To free an array, use g_array_free().
  *
- * <example>
- *  <title>Using a #GArray to store #gint values</title>
- *  <programlisting>
+ * Here is an example that stores integers in a #GArray:
+ * |[<!-- language="C" -->
  *   GArray *garray;
  *   gint i;
- *   /<!-- -->* We create a new array to store gint values.
- *      We don't want it zero-terminated or cleared to 0's. *<!-- -->/
+ *   /&ast; We create a new array to store gint values.
+ *    &ast; We don't want it zero-terminated or cleared to 0's.
+ *    &ast;/
  *   garray = g_array_new (FALSE, FALSE, sizeof (gint));
- *   for (i = 0; i &lt; 10000; i++)
+ *   for (i = 0; i < 10000; i++)
  *     g_array_append_val (garray, i);
- *   for (i = 0; i &lt; 10000; i++)
+ *   for (i = 0; i < 10000; i++)
  *     if (g_array_index (garray, gint, i) != i)
- *       g_print ("ERROR: got &percnt;d instead of &percnt;d\n",
+ *       g_print ("ERROR: got %d instead of %d\n",
  *                g_array_index (garray, gint, i), i);
  *   g_array_free (garray, TRUE);
- *  </programlisting>
- * </example>
+ * ]|
  */
 
 
@@ -4926,17 +4948,16 @@
  *
  * To free a #GByteArray, use g_byte_array_free().
  *
- * <example>
- *  <title>Using a #GByteArray</title>
- *  <programlisting>
+ * An example for using a #GByteArray:
+ * |[<!-- language="C" -->
  *   GByteArray *gbarray;
  *   gint i;
  *
- *   gbarray = g_byte_array_new (<!-- -->);
- *   for (i = 0; i &lt; 10000; i++)
+ *   gbarray = g_byte_array_new ();
+ *   for (i = 0; i < 10000; i++)
  *     g_byte_array_append (gbarray, (guint8*) "abcd", 4);
  *
- *   for (i = 0; i &lt; 10000; i++)
+ *   for (i = 0; i < 10000; i++)
  *     {
  *       g_assert (gbarray->data[4*i] == 'a');
  *       g_assert (gbarray->data[4*i+1] == 'b');
@@ -4945,8 +4966,7 @@
  *     }
  *
  *   g_byte_array_free (gbarray, TRUE);
- *  </programlisting>
- * </example>
+ * ]|
  *
  * See #GBytes if you are interested in an immutable object representing a
  * sequence of bytes.
@@ -4957,16 +4977,16 @@
  * SECTION:arrays_pointer
  * @title: Pointer Arrays
  * @short_description: arrays of pointers to any type of data, which
- *                     grow automatically as new elements are added
+ *     grow automatically as new elements are added
  *
  * Pointer Arrays are similar to Arrays but are used only for storing
  * pointers.
  *
- * <note><para>If you remove elements from the array, elements at the
- * end of the array are moved into the space previously occupied by the
- * removed element. This means that you should not rely on the index of
- * particular elements remaining the same. You should also be careful
- * when deleting elements while iterating over the array.</para></note>
+ * If you remove elements from the array, elements at the end of the
+ * array are moved into the space previously occupied by the removed
+ * element. This means that you should not rely on the index of particular
+ * elements remaining the same. You should also be careful when deleting
+ * elements while iterating over the array.
  *
  * To create a pointer array, use g_ptr_array_new().
  *
@@ -4981,24 +5001,22 @@
  *
  * To free a pointer array, use g_ptr_array_free().
  *
- * <example>
- *  <title>Using a #GPtrArray</title>
- *  <programlisting>
- *   GPtrArray *gparray;
+ * An example using a #GPtrArray:
+ * |[<!-- language="C" -->
+ *   GPtrArray *array;
  *   gchar *string1 = "one", *string2 = "two", *string3 = "three";
  *
- *   gparray = g_ptr_array_new (<!-- -->);
- *   g_ptr_array_add (gparray, (gpointer) string1);
- *   g_ptr_array_add (gparray, (gpointer) string2);
- *   g_ptr_array_add (gparray, (gpointer) string3);
+ *   gparray = g_ptr_array_new ();
+ *   g_ptr_array_add (array, (gpointer) string1);
+ *   g_ptr_array_add (array, (gpointer) string2);
+ *   g_ptr_array_add (array, (gpointer) string3);
  *
- *   if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
- *     g_print ("ERROR: got &percnt;p instead of &percnt;p\n",
- *              g_ptr_array_index (gparray, 0), string1);
+ *   if (g_ptr_array_index (array, 0) != (gpointer) string1)
+ *     g_print ("ERROR: got %p instead of %p\n",
+ *              g_ptr_array_index (array, 0), string1);
  *
- *   g_ptr_array_free (gparray, TRUE);
- *  </programlisting>
- * </example>
+ *   g_ptr_array_free (array, TRUE);
+ * ]|
  */
 
 
@@ -5089,8 +5107,7 @@
  * fall outside of simple reference counting patterns are prone to
  * subtle bugs and occasionally undefined behaviour.  It is also worth
  * noting that since all of these operations require global
- * synchronisation of the entire machine, they can be quite slow.  In
- * the case of performing multiple atomic operations it can often be
+ * synchronisation of the entire machine, they can be quite slow.  In * the case of performing multiple atomic operations it can often be
  * faster to simply acquire a mutex lock around the critical area,
  * perform the operations normally and then release the lock.
  */
@@ -5103,9 +5120,11 @@
  *
  * Base64 is an encoding that allows a sequence of arbitrary bytes to be
  * encoded as a sequence of printable ASCII characters. For the definition
- * of Base64, see <ulink url="http://www.ietf.org/rfc/rfc1421.txt">RFC
- * 1421</ulink> or <ulink url="http://www.ietf.org/rfc/rfc2045.txt">RFC
- * 2045</ulink>. Base64 is most commonly used as a MIME transfer encoding
+ * of Base64, see
+ * [RFC 1421](http://www.ietf.org/rfc/rfc1421.txt)
+ * or
+ * [RFC 2045](http://www.ietf.org/rfc/rfc2045.txt).
+ * Base64 is most commonly used as a MIME transfer encoding
  * for email.
  *
  * GLib supports incremental encoding using g_base64_encode_step() and
@@ -5128,26 +5147,27 @@
  * like its MIME type, the application that is registering the bookmark and
  * the icon that should be used to represent the bookmark. The data is stored
  * using the
- * <ulink url="http://www.gnome.org/~ebassi/bookmark-spec">Desktop Bookmark
- * Specification</ulink>.
+ * [Desktop Bookmark Specification](http://www.gnome.org/~ebassi/bookmark-spec).
  *
- * The syntax of the bookmark files is described in detail inside the Desktop
- * Bookmark Specification, here is a quick summary: bookmark files use a
- * sub-class of the <ulink url="">XML Bookmark Exchange Language</ulink>
+ * The syntax of the bookmark files is described in detail inside the
+ * Desktop Bookmark Specification, here is a quick summary: bookmark
+ * files use a sub-class of the XML Bookmark Exchange Language
  * specification, consisting of valid UTF-8 encoded XML, under the
- * <literal>xbel</literal> root element; each bookmark is stored inside a
- * <literal>bookmark</literal> element, using its URI: no relative paths can
- * be used inside a bookmark file. The bookmark may have a user defined title
- * and description, to be used instead of the URI. Under the
- * <literal>metadata</literal> element, with its <literal>owner</literal>
- * attribute set to <literal>http://freedesktop.org</literal>, is stored the
- * meta-data about a resource pointed by its URI. The meta-data consists of
- * the resource's MIME type; the applications that have registered a bookmark;
- * the groups to which a bookmark belongs to; a visibility flag, used to set
- * the bookmark as "private" to the applications and groups that has it
- * registered; the URI and MIME type of an icon, to be used when displaying
- * the bookmark inside a GUI.
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../glib/tests/bookmarks.xbel"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
+ * &lt;xbel&gt; root element; each bookmark is stored inside a
+ * &lt;bookmark&gt; element, using its URI: no relative paths can
+ * be used inside a bookmark file. The bookmark may have a user defined
+ * title and description, to be used instead of the URI. Under the
+ * &lt;metadata&gt; element, with its owner attribute set to
+ * `http://freedesktop.org`, is stored the meta-data about a resource
+ * pointed by its URI. The meta-data consists of the resource's MIME
+ * type; the applications that have registered a bookmark; the groups
+ * to which a bookmark belongs to; a visibility flag, used to set the
+ * bookmark as "private" to the applications and groups that has it
+ * registered; the URI and MIME type of an icon, to be used when
+ * displaying the bookmark inside a GUI.
+ *
+ * Here is an example of a bookmark file:
+ * [bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel)
  *
  * A bookmark file might contain more than one bookmark; each bookmark
  * is accessed through its URI.
@@ -5227,120 +5247,100 @@
  * @title: Character Set Conversion
  * @short_description: convert strings between different character sets
  *
- * The g_convert() family of function wraps the functionality of iconv(). In
- * addition to pure character set conversions, GLib has functions to deal
- * with the extra complications of encodings for file names.
- *
- * <refsect2 id="file-name-encodings">
- * <title>File Name Encodings</title>
- * <para>
- * Historically, Unix has not had a defined encoding for file
- * names:  a file name is valid as long as it does not have path
- * separators in it ("/").  However, displaying file names may
- * require conversion:  from the character set in which they were
- * created, to the character set in which the application
- * operates.  Consider the Spanish file name
- * "<filename>Presentaci&oacute;n.sxi</filename>".  If the
- * application which created it uses ISO-8859-1 for its encoding,
- * </para>
- * <programlisting id="filename-iso8859-1">
+ * The g_convert() family of function wraps the functionality of iconv().
+ * In addition to pure character set conversions, GLib has functions to
+ * deal with the extra complications of encodings for file names.
+ *
+ * ## File Name Encodings
+ *
+ * Historically, UNIX has not had a defined encoding for file names:
+ * a file name is valid as long as it does not have path separators
+ * in it ("/"). However, displaying file names may require conversion:
+ * from the character set in which they were created, to the character
+ * set in which the application operates. Consider the Spanish file name
+ * "Presentaci&oacute;n.sxi". If the application which created it uses
+ * ISO-8859-1 for its encoding,
+ * <programlisting>
  * Character:  P  r  e  s  e  n  t  a  c  i  &oacute;  n  .  s  x  i
  * Hex code:   50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
  * </programlisting>
- * <para>
  * However, if the application use UTF-8, the actual file name on
  * disk would look like this:
- * </para>
  * <programlisting id="filename-utf-8">
  * Character:  P  r  e  s  e  n  t  a  c  i  &oacute;     n  .  s  x  i
  * Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
  * </programlisting>
- * <para>
- * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+
- * that use Glib do the same thing.  If you get a file name from
- * the file system, for example, from readdir(3) or from g_dir_read_name(),
- * and you wish to display the file name to the user, you
- * <emphasis>will</emphasis> need to convert it into UTF-8.  The
- * opposite case is when the user types the name of a file he
- * wishes to save:  the toolkit will give you that string in
- * UTF-8 encoding, and you will need to convert it to the
- * character set used for file names before you can create the
- * file with open(2) or fopen(3).
- * </para>
- * <para>
+ * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
+ * Glib do the same thing. If you get a file name from the file system,
+ * for example, from readdir() or from g_dir_read_name(), and you wish
+ * to display the file name to the user, you  will need to convert it
+ * into UTF-8. The opposite case is when the user types the name of a
+ * file he wishes to save: the toolkit will give you that string in
+ * UTF-8 encoding, and you will need to convert it to the character
+ * set used for file names before you can create the file with open()
+ * or fopen().
+ *
  * By default, Glib assumes that file names on disk are in UTF-8
- * encoding.  This is a valid assumption for file systems which
- * were created relatively recently:  most applications use UTF-8
+ * encoding. This is a valid assumption for file systems which
+ * were created relatively recently: most applications use UTF-8
  * encoding for their strings, and that is also what they use for
- * the file names they create.  However, older file systems may
+ * the file names they create. However, older file systems may
  * still contain file names created in "older" encodings, such as
  * ISO-8859-1. In this case, for compatibility reasons, you may
  * want to instruct Glib to use that particular encoding for file
- * names rather than UTF-8.  You can do this by specifying the
+ * names rather than UTF-8. You can do this by specifying the
  * encoding for file names in the <link
- * linkend="G_FILENAME_ENCODING"><envar>G_FILENAME_ENCODING</envar></link>
- * environment variable.  For example, if your installation uses
- * ISO-8859-1 for file names, you can put this in your
- * <filename>~/.profile</filename>:
- * </para>
+ * linkend="G_FILENAME_ENCODING">`G_FILENAME_ENCODING`</link>
+ * environment variable. For example, if your installation uses
+ * ISO-8859-1 for file names, you can put this in your `~/.profile`
  * <programlisting>
  * export G_FILENAME_ENCODING=ISO-8859-1
  * </programlisting>
- * <para>
  * Glib provides the functions g_filename_to_utf8() and
- * g_filename_from_utf8() to perform the necessary conversions. These
- * functions convert file names from the encoding specified in
- * <envar>G_FILENAME_ENCODING</envar> to UTF-8 and vice-versa.
+ * g_filename_from_utf8() to perform the necessary conversions.
+ * These functions convert file names from the encoding specified
+ * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa.
  * <xref linkend="file-name-encodings-diagram"/> illustrates how
  * these functions are used to convert between UTF-8 and the
  * encoding for file names in the file system.
- * </para>
- * <figure id="file-name-encodings-diagram">
- * <title>Conversion between File Name Encodings</title>
- * <graphic fileref="file-name-encodings.png" format="PNG"/>
- * </figure>
- * <refsect3 id="file-name-encodings-checklist">
- * <title>Checklist for Application Writers</title>
- * <para>
+ *
+ * ## Conversion between file name encodings # {#file-name-encodings-diagram)
+ *
+ * ![](file-name-encodings.png)
+ *
+ * ## Checklist for Application Writers
+ *
  * This section is a practical summary of the detailed
- * description above.  You can use this as a checklist of
+ *  
  * things to do to make sure your applications process file
  * name encodings correctly.
- * </para>
- * <orderedlist>
- * <listitem><para>
- * If you get a file name from the file system from a function
- * such as readdir(3) or gtk_file_chooser_get_filename(),
- * you do not need to do any conversion to pass that
- * file name to functions like open(2), rename(2), or
- * fopen(3) &mdash; those are "raw" file names which the file
- * system understands.
- * </para></listitem>
- * <listitem><para>
- * If you need to display a file name, convert it to UTF-8 first by
- * using g_filename_to_utf8(). If conversion fails, display a string like
- * "<literal>Unknown file name</literal>". <emphasis>Do not</emphasis>
- * convert this string back into the encoding used for file names if you
- * wish to pass it to the file system; use the original file name instead.
- * For example, the document window of a word processor could display
- * "Unknown file name" in its title bar but still let the user save the
- * file, as it would keep the raw file name internally. This can happen
- * if the user has not set the <envar>G_FILENAME_ENCODING</envar>
- * environment variable even though he has files whose names are not
- * encoded in UTF-8.
- * </para></listitem>
- * <listitem><para>
- * If your user interface lets the user type a file name for saving or
- * renaming, convert it to the encoding used for file names in the file
- * system by using g_filename_from_utf8(). Pass the converted file name
- * to functions like fopen(3). If conversion fails, ask the user to enter
- * a different file name. This can happen if the user types Japanese
- * characters when <envar>G_FILENAME_ENCODING</envar> is set to
- * <literal>ISO-8859-1</literal>, for example.
- * </para></listitem>
- * </orderedlist>
- * </refsect3>
- * </refsect2>
+ *
+ * 1. If you get a file name from the file system from a function
+ *    such as readdir() or gtk_file_chooser_get_filename(), you do
+ *    not need to do any conversion to pass that file name to
+ *    functions like open(), rename(), or fopen() -- those are "raw"
+ *    file names which the file system understands.
+ *
+ * 2. If you need to display a file name, convert it to UTF-8 first
+ *    by using g_filename_to_utf8(). If conversion fails, display a
+ *    string like "Unknown file name". Do not convert this string back
+ *    into the encoding used for file names if you wish to pass it to
+ *    the file system; use the original file name instead.
+ *
+ *    For example, the document window of a word processor could display
+ *    "Unknown file name" in its title bar but still let the user save
+ *    the file, as it would keep the raw file name internally. This
+ *    can happen if the user has not set the `G_FILENAME_ENCODING`
+ *    environment variable even though he has files whose names are
+ *    not encoded in UTF-8.
+ *
+ * 3. If your user interface lets the user type a file name for saving
+ *    or renaming, convert it to the encoding used for file names in
+ *    the file system by using g_filename_from_utf8(). Pass the converted
+ *    file name to functions like fopen(). If conversion fails, ask the
+ *    user to enter a different file name. This can happen if the user
+ *    types Japanese characters when `G_FILENAME_ENCODING` is set to
+ *    `ISO-8859-1`, for example.
  */
 
 
@@ -5432,7 +5432,7 @@
  * or ISO timestamps or the like. It extrapolates the current Gregorian
  * calendar forward and backward in time; there is no attempt to change
  * the calendar to match time periods or locations. #GDate does not store
- * time information; it represents a <emphasis>day</emphasis>.
+ * time information; it represents a day.
  *
  * The #GDate implementation has several nice features; it is only a
  * 64-bit struct, so storing large numbers of dates is very efficient. It
@@ -5450,16 +5450,16 @@
  * calling g_date_clear(). A cleared date is sane; it's safe to call
  * g_date_set_dmy() and the other mutator functions to initialize the
  * value of a cleared date. However, a cleared date is initially
- * <emphasis>invalid</emphasis>, meaning that it doesn't represent a day
- * that exists. It is undefined to call any of the date calculation
- * routines on an invalid date. If you obtain a date from a user or other
+ * invalid, meaning that it doesn't represent a day that exists.
+ * It is undefined to call any of the date calculation routines on an
+ * invalid date. If you obtain a date from a user or other
  * unpredictable source, you should check its validity with the
  * g_date_valid() predicate. g_date_valid() is also used to check for
  * errors with g_date_set_parse() and other functions that can
  * fail. Dates can be invalidated by calling g_date_clear() again.
  *
- * <emphasis>It is very important to use the API to access the #GDate
- * struct.</emphasis> Often only the day-month-year or only the Julian
+ * It is very important to use the API to access the #GDate
+ * struct. Often only the day-month-year or only the Julian
  * representation is valid. Sometimes neither is valid. Use the API.
  *
  * GLib also features #GDateTime which represents a precise time.
@@ -5508,18 +5508,18 @@
  * GLib provides a standard method of reporting errors from a called
  * function to the calling code. (This is the same problem solved by
  * exceptions in other languages.) It's important to understand that
- * this method is both a <emphasis>data type</emphasis> (the #GError
- * object) and a <emphasis>set of rules.</emphasis> If you use #GError
- * incorrectly, then your code will not properly interoperate with other
- * code that uses #GError, and users of your API will probably get confused.
- *
- * First and foremost: <emphasis>#GError should only be used to report
- * recoverable runtime errors, never to report programming
- * errors.</emphasis> If the programmer has screwed up, then you should
- * use g_warning(), g_return_if_fail(), g_assert(), g_error(), or some
- * similar facility. (Incidentally, remember that the g_error() function
- * should <emphasis>only</emphasis> be used for programming errors, it
- * should not be used to print any error reportable via #GError.)
+ * this method is both a data type (the #GError struct) and a set of
+ * rules. If you use #GError incorrectly, then your code will not
+ * properly interoperate with other code that uses #GError, and users
+ * of your API will probably get confused.
+ *
+ * First and foremost: #GError should only be used to report recoverable
+ * runtime errors, never to report programming errors. If the programmer
+ * has screwed up, then you should use g_warning(), g_return_if_fail(),
+ * g_assert(), g_error(), or some similar facility. (Incidentally,
+ * remember that the g_error() function should only be used for
+ * programming errors, it should not be used to print any error
+ * reportable via #GError.)
  *
  * Examples of recoverable runtime errors are "file not found" or
  * "failed to parse input." Examples of programming errors are "NULL
@@ -5531,25 +5531,25 @@
  *
  * Functions that can fail take a return location for a #GError as their
  * last argument. For example:
- * |[
+ * |[<!-- language="C" -->
  * gboolean g_file_get_contents (const gchar  *filename,
  *                               gchar       **contents,
  *                               gsize        *length,
  *                               GError      **error);
  * ]|
- * If you pass a non-%NULL value for the <literal>error</literal>
- * argument, it should point to a location where an error can be placed.
- * For example:
- * |[
+ * If you pass a non-%NULL value for the `error` argument, it should
+ * point to a location where an error can be placed. For example:
+ * |[<!-- language="C" -->
  * gchar *contents;
  * GError *err = NULL;
- * g_file_get_contents ("foo.txt", &amp;contents, NULL, &amp;err);
- * g_assert ((contents == NULL &amp;&amp; err != NULL) || (contents != NULL &amp;&amp; err == NULL));
+ *
+ * g_file_get_contents ("foo.txt", &contents, NULL, &err);
+ * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
  * if (err != NULL)
  *   {
  *     /&ast; Report error to user, and free error &ast;/
  *     g_assert (contents == NULL);
- *     fprintf (stderr, "Unable to read file: &percnt;s\n", err->message);
+ *     fprintf (stderr, "Unable to read file: %s\n", err->message);
  *     g_error_free (err);
  *   }
  * else
@@ -5558,44 +5558,41 @@
  *     g_assert (contents != NULL);
  *   }
  * ]|
- * Note that <literal>err != NULL</literal> in this example is a
- * <emphasis>reliable</emphasis> indicator of whether
- * g_file_get_contents() failed. Additionally, g_file_get_contents()
- * returns a boolean which indicates whether it was successful.
+ * Note that `err != NULL` in this example is a reliable indicator
+ * of whether g_file_get_contents() failed. Additionally,
+ * g_file_get_contents() returns a boolean which
+ * indicates whether it was successful.
  *
  * Because g_file_get_contents() returns %FALSE on failure, if you
  * are only interested in whether it failed and don't need to display
- * an error message, you can pass %NULL for the <literal>error</literal>
- * argument:
- * |[
- * if (g_file_get_contents ("foo.txt", &amp;contents, NULL, NULL)) /&ast; ignore errors &ast;/
+ * an error message, you can pass %NULL for the @error argument:
+ * |[<!-- language="C" -->
+ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /&ast; ignore errors &ast;/
  *   /&ast; no error occurred &ast;/ ;
  * else
  *   /&ast; error &ast;/ ;
  * ]|
  *
- * The #GError object contains three fields: <literal>domain</literal>
- * indicates the module the error-reporting function is located in,
- * <literal>code</literal> indicates the specific error that occurred,
- * and <literal>message</literal> is a user-readable error message with
+ * The #GError object contains three fields: @domain indicates the module
+ * the error-reporting function is located in, @code indicates the specific
+ * error that occurred, and @message is a user-readable error message with
  * as many details as possible. Several functions are provided to deal
  * with an error received from a called function: g_error_matches()
  * returns %TRUE if the error matches a given domain and code,
  * g_propagate_error() copies an error into an error location (so the
  * calling function will receive it), and g_clear_error() clears an
  * error location by freeing the error and resetting the location to
- * %NULL. To display an error to the user, simply display
- * <literal>error-&gt;message</literal>, perhaps along with additional
- * context known only to the calling function (the file being opened,
- * or whatever -- though in the g_file_get_contents() case,
- * <literal>error-&gt;message</literal> already contains a filename).
+ * %NULL. To display an error to the user, simply display the @message,
+ * perhaps along with additional context known only to the calling
+ * function (the file being opened, or whatever - though in the
+ * g_file_get_contents() case, the @message already contains a filename).
  *
  * When implementing a function that can report errors, the basic
  * tool is g_set_error(). Typically, if a fatal error occurs you
  * want to g_set_error(), then return immediately. g_set_error()
  * does nothing if the error location passed to it is %NULL.
  * Here's an example:
- * |[
+ * |[<!-- language="C" -->
  * gint
  * foo_open_file (GError **error)
  * {
@@ -5603,12 +5600,12 @@
  *
  *   fd = open ("file.txt", O_RDONLY);
  *
- *   if (fd &lt; 0)
+ *   if (fd < 0)
  *     {
  *       g_set_error (error,
  *                    FOO_ERROR,                 /&ast; error domain &ast;/
  *                    FOO_ERROR_BLAH,            /&ast; error code &ast;/
- *                    "Failed to open file: &percnt;s", /&ast; error message format string &ast;/
+ *                    "Failed to open file: %s", /&ast; error message format string &ast;/
  *                    g_strerror (errno));
  *       return -1;
  *     }
@@ -5621,7 +5618,7 @@
  * function that can report a #GError. If the sub-function indicates
  * fatal errors in some way other than reporting a #GError, such as
  * by returning %TRUE on success, you can simply do the following:
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -5643,7 +5640,7 @@
  * reporting a #GError, you need to create a temporary #GError
  * since the passed-in one may be %NULL. g_propagate_error() is
  * intended for use in this case.
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -5652,7 +5649,7 @@
  *   g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
  *
  *   tmp_error = NULL;
- *   sub_function_that_can_fail (&amp;tmp_error);
+ *   sub_function_that_can_fail (&tmp_error);
  *
  *   if (tmp_error != NULL)
  *     {
@@ -5668,7 +5665,7 @@
  * ]|
  *
  * Error pileups are always a bug. For example, this code is incorrect:
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -5677,8 +5674,8 @@
  *   g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
  *
  *   tmp_error = NULL;
- *   sub_function_that_can_fail (&amp;tmp_error);
- *   other_function_that_can_fail (&amp;tmp_error);
+ *   sub_function_that_can_fail (&tmp_error);
+ *   other_function_that_can_fail (&tmp_error);
  *
  *   if (tmp_error != NULL)
  *     {
@@ -5687,15 +5684,15 @@
  *     }
  * }
  * ]|
- * <literal>tmp_error</literal> should be checked immediately after
- * sub_function_that_can_fail(), and either cleared or propagated
- * upward. The rule is: <emphasis>after each error, you must either
- * handle the error, or return it to the calling function</emphasis>.
+ * @tmp_error should be checked immediately after sub_function_that_can_fail(),
+ * and either cleared or propagated upward. The rule is: after each error,
+ * you must either handle the error, or return it to the calling function.
+ *
  * Note that passing %NULL for the error location is the equivalent
  * of handling an error by always doing nothing about it. So the
  * following code is fine, assuming errors in sub_function_that_can_fail()
  * are not fatal to my_function_that_can_fail():
- * |[
+ * |[<!-- language="C" -->
  * gboolean
  * my_function_that_can_fail (GError **err)
  * {
@@ -5706,7 +5703,7 @@
  *   sub_function_that_can_fail (NULL); /&ast; ignore errors &ast;/
  *
  *   tmp_error = NULL;
- *   other_function_that_can_fail (&amp;tmp_error);
+ *   other_function_that_can_fail (&tmp_error);
  *
  *   if (tmp_error != NULL)
  *     {
@@ -5716,116 +5713,93 @@
  * }
  * ]|
  *
- * Note that passing %NULL for the error location
- * <emphasis>ignores</emphasis> errors; it's equivalent to
- * <literal>try { sub_function_that_can_fail (); } catch (...) {}</literal>
- * in C++. It does <emphasis>not</emphasis> mean to leave errors
- * unhandled; it means to handle them by doing nothing.
+ * Note that passing %NULL for the error location ignores errors;
+ * it's equivalent to
+ * `try { sub_function_that_can_fail (); } catch (...) {}`
+ * in C++. It does not mean to leave errors unhandled; it means
+ * to handle them by doing nothing.
  *
  * Error domains and codes are conventionally named as follows:
- * <itemizedlist>
- * <listitem><para>
- *   The error domain is called
- *   <literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR</literal>,
+ *
+ * - The error domain is called &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR,
  *   for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
- *   |[
- * #define G_SPAWN_ERROR g_spawn_error_quark ()
+ *   |[<!-- language="C" -->
+ *   #define G_SPAWN_ERROR g_spawn_error_quark ()
  *
- * GQuark
- * g_spawn_error_quark (void)
- * {
- *   return g_quark_from_static_string ("g-spawn-error-quark");
- * }
+ *   GQuark
+ *   g_spawn_error_quark (void)
+ *   {
+ *       return g_quark_from_static_string ("g-spawn-error-quark");
+ *   }
  *   ]|
- * </para></listitem>
- * <listitem><para>
- *   The quark function for the error domain is called
- *   <literal>&lt;namespace&gt;_&lt;module&gt;_error_quark</literal>,
+ *
+ * - The quark function for the error domain is called
+ *   &lt;namespace&gt;_&lt;module&gt;_error_quark,
  *   for example g_spawn_error_quark() or g_thread_error_quark().
- * </para></listitem>
- * <listitem><para>
- *   The error codes are in an enumeration called
- *   <literal>&lt;Namespace&gt;&lt;Module&gt;Error</literal>;
+ *
+ * - The error codes are in an enumeration called
+ *   &lt;Namespace&gt;&lt;Module&gt;Error;
  *   for example,#GThreadError or #GSpawnError.
- * </para></listitem>
- * <listitem><para>
- *   Members of the error code enumeration are called
- *   <literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;</literal>,
+ *
+ * - Members of the error code enumeration are called
+ *   &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_&lt;CODE&gt;,
  *   for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
- * </para></listitem>
- * <listitem><para>
- *   If there's a "generic" or "unknown" error code for unrecoverable
+ *
+ * - If there's a "generic" or "unknown" error code for unrecoverable
  *   errors it doesn't make sense to distinguish with specific codes,
- *   it should be called <literal>&lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED</literal>,
+ *   it should be called &lt;NAMESPACE&gt;_&lt;MODULE&gt;_ERROR_FAILED,
  *   for example %G_SPAWN_ERROR_FAILED.
- * </para></listitem>
- * </itemizedlist>
  *
  * Summary of rules for use of #GError:
- * <itemizedlist>
- * <listitem><para>
- *   Do not report programming errors via #GError.
- * </para></listitem>
- * <listitem><para>
- *   The last argument of a function that returns an error should
+ *
+ * - Do not report programming errors via #GError.
+ *
+ * - The last argument of a function that returns an error should
  *   be a location where a #GError can be placed (i.e. "#GError** error").
  *   If #GError is used with varargs, the #GError** should be the last
  *   argument before the "...".
- * </para></listitem>
- * <listitem><para>
- *   The caller may pass %NULL for the #GError** if they are not interested
+ *
+ * - The caller may pass %NULL for the #GError** if they are not interested
  *   in details of the exact error that occurred.
- * </para></listitem>
- * <listitem><para>
- *   If %NULL is passed for the #GError** argument, then errors should
+ *
+ * - If %NULL is passed for the #GError** argument, then errors should
  *   not be returned to the caller, but your function should still
  *   abort and return if an error occurs. That is, control flow should
  *   not be affected by whether the caller wants to get a #GError.
- * </para></listitem>
- * <listitem><para>
- *   If a #GError is reported, then your function by definition
- *   <emphasis>had a fatal failure and did not complete whatever
- *   it was supposed to do</emphasis>. If the failure was not fatal,
- *   then you handled it and you should not report it. If it was fatal,
- *   then you must report it and discontinue whatever you were doing
- *   immediately.
- * </para></listitem>
- * <listitem><para>
- *   If a #GError is reported, out parameters are not guaranteed to
+ *
+ * - If a #GError is reported, then your function by definition had a
+ *   fatal failure and did not complete whatever it was supposed to do.
+ *   If the failure was not fatal, then you handled it and you should not
+ *   report it. If it was fatal, then you must report it and discontinue
+ *   whatever you were doing immediately.
+ *
+ * - If a #GError is reported, out parameters are not guaranteed to
  *   be set to any defined value.
- * </para></listitem>
- * <listitem><para>
- *   A #GError* must be initialized to %NULL before passing its address
+ *
+ * - A #GError* must be initialized to %NULL before passing its address
  *   to a function that can report errors.
- * </para></listitem>
- * <listitem><para>
- *   "Piling up" errors is always a bug. That is, if you assign a
+ *
+ * - "Piling up" errors is always a bug. That is, if you assign a
  *   new #GError to a #GError* that is non-%NULL, thus overwriting
  *   the previous error, it indicates that you should have aborted
  *   the operation instead of continuing. If you were able to continue,
  *   you should have cleared the previous error with g_clear_error().
  *   g_set_error() will complain if you pile up errors.
- * </para></listitem>
- * <listitem><para>
- *   By convention, if you return a boolean value indicating success
+ *
+ * - By convention, if you return a boolean value indicating success
  *   then %TRUE means success and %FALSE means failure. If %FALSE is
- *   returned, the error <emphasis>must</emphasis> be set to a non-%NULL
- *   value.
- * </para></listitem>
- * <listitem><para>
- *   A %NULL return value is also frequently used to mean that an error
+ *   returned, the error must be set to a non-%NULL value.
+ *
+ * - A %NULL return value is also frequently used to mean that an error
  *   occurred. You should make clear in your documentation whether %NULL
  *   is a valid return value in non-error cases; if %NULL is a valid value,
  *   then users must check whether an error was returned to see if the
  *   function succeeded.
- * </para></listitem>
- * <listitem><para>
- *   When implementing a function that can report errors, you may want
+ *
+ * - When implementing a function that can report errors, you may want
  *   to add a check at the top of your function that the error return
  *   location is either %NULL or contains a %NULL error (e.g.
- *   <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>).
- * </para></listitem>
- * </itemizedlist>
+ *   `g_return_if_fail (error == NULL || *error == NULL);`).
  */
 
 
@@ -5843,8 +5817,8 @@
  *
  * The pathname argument should be in the GLib file name encoding.
  * On POSIX this is the actual on-disk encoding which might correspond
- * to the locale settings of the process (or the
- * <envar>G_FILENAME_ENCODING</envar> environment variable), or not.
+ * to the locale settings of the process (or the `G_FILENAME_ENCODING`
+ * environment variable), or not.
  *
  * On Windows the GLib file name encoding is UTF-8. Note that the
  * Microsoft C library does not use UTF-8, but has separate APIs for
@@ -5866,9 +5840,9 @@
  * converting between Unicode and ASCII-encoded forms of
  * Internationalized Domain Names (IDNs).
  *
- * The <ulink
- * url="http://www.ietf.org/rfc/rfc3490.txt">Internationalized Domain
- * Names for Applications (IDNA)</ulink> standards allow for the use
+ * The
+ * [Internationalized Domain Names for Applications (IDNA)](http://www.ietf.org/rfc/rfc3490.txt)
+ * standards allow for the use
  * of Unicode domain names in applications, while providing
  * backward-compatibility with the old ASCII-only DNS, by defining an
  * ASCII-Compatible Encoding of any given Unicode name, which can be
@@ -5883,7 +5857,7 @@
  * @short_description: matches strings against regular expressions
  * @see_also: <xref linkend="glib-regex-syntax"/>
  *
- * The <function>g_regex_*()</function> functions implement regular
+ * The g_regex_*() functions implement regular
  * expression pattern matching using syntax and semantics similar to
  * Perl regular expression.
  *
@@ -5937,7 +5911,7 @@
  * '\U' always matches 'U' instead of being an error in the pattern. Finally,
  * pattern matching is modified so that back references to an unset subpattern
  * group produces a match with the empty string instead of an error. See
- * <ulink>man:pcreapi(3)</ulink> for more information.
+ * pcreapi(3) for more information.
  *
  * Creating and manipulating the same #GRegex structure from different
  * threads is not a problem as #GRegex does not modify its internal
@@ -5945,8 +5919,9 @@
  * is not threadsafe.
  *
  * The regular expressions low-level functionalities are obtained through
- * the excellent <ulink url="http://www.pcre.org/">PCRE</ulink> library
- * written by Philip Hazel.
+ * the excellent
+ * [PCRE](http://www.pcre.org/)
+ * library written by Philip Hazel.
  */
 
 
@@ -5972,8 +5947,9 @@
  * @short_description: manipulating URIs
  *
  * Functions for manipulating Universal Resource Identifiers (URIs) as
- * defined by <ulink url="http://www.ietf.org/rfc/rfc3986.txt">
- * RFC 3986</ulink>. It is highly recommended that you have read and
+ * defined by
+ * [RFC 3986](http://www.ietf.org/rfc/rfc3986.txt).
+ * It is highly recommended that you have read and
  * understand RFC 3986 for understanding this API.
  */
 
@@ -6035,201 +6011,168 @@
  * values.  #GVariant includes a printer for this language and a parser
  * with type inferencing.
  *
- * <refsect2>
- *  <title>Memory Use</title>
- *  <para>
- *   #GVariant tries to be quite efficient with respect to memory use.
- *   This section gives a rough idea of how much memory is used by the
- *   current implementation.  The information here is subject to change
- *   in the future.
- *  </para>
- *  <para>
- *   The memory allocated by #GVariant can be grouped into 4 broad
- *   purposes: memory for serialised data, memory for the type
- *   information cache, buffer management memory and memory for the
- *   #GVariant structure itself.
- *  </para>
- *  <refsect3 id="gvariant-serialised-data-memory">
- *   <title>Serialised Data Memory</title>
- *   <para>
- *    This is the memory that is used for storing GVariant data in
- *    serialised form.  This is what would be sent over the network or
- *    what would end up on disk.
- *   </para>
- *   <para>
- *    The amount of memory required to store a boolean is 1 byte.  16,
- *    32 and 64 bit integers and double precision floating point numbers
- *    use their "natural" size.  Strings (including object path and
- *    signature strings) are stored with a nul terminator, and as such
- *    use the length of the string plus 1 byte.
- *   </para>
- *   <para>
- *    Maybe types use no space at all to represent the null value and
- *    use the same amount of space (sometimes plus one byte) as the
- *    equivalent non-maybe-typed value to represent the non-null case.
- *   </para>
- *   <para>
- *    Arrays use the amount of space required to store each of their
- *    members, concatenated.  Additionally, if the items stored in an
- *    array are not of a fixed-size (ie: strings, other arrays, etc)
- *    then an additional framing offset is stored for each item.  The
- *    size of this offset is either 1, 2 or 4 bytes depending on the
- *    overall size of the container.  Additionally, extra padding bytes
- *    are added as required for alignment of child values.
- *   </para>
- *   <para>
- *    Tuples (including dictionary entries) use the amount of space
- *    required to store each of their members, concatenated, plus one
- *    framing offset (as per arrays) for each non-fixed-sized item in
- *    the tuple, except for the last one.  Additionally, extra padding
- *    bytes are added as required for alignment of child values.
- *   </para>
- *   <para>
- *    Variants use the same amount of space as the item inside of the
- *    variant, plus 1 byte, plus the length of the type string for the
- *    item inside the variant.
- *   </para>
- *   <para>
- *    As an example, consider a dictionary mapping strings to variants.
- *    In the case that the dictionary is empty, 0 bytes are required for
- *    the serialisation.
- *   </para>
- *   <para>
- *    If we add an item "width" that maps to the int32 value of 500 then
- *    we will use 4 byte to store the int32 (so 6 for the variant
- *    containing it) and 6 bytes for the string.  The variant must be
- *    aligned to 8 after the 6 bytes of the string, so that's 2 extra
- *    bytes.  6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
- *    for the dictionary entry.  An additional 1 byte is added to the
- *    array as a framing offset making a total of 15 bytes.
- *   </para>
- *   <para>
- *    If we add another entry, "title" that maps to a nullable string
- *    that happens to have a value of null, then we use 0 bytes for the
- *    null value (and 3 bytes for the variant to contain it along with
- *    its type string) plus 6 bytes for the string.  Again, we need 2
- *    padding bytes.  That makes a total of 6 + 2 + 3 = 11 bytes.
- *   </para>
- *   <para>
- *    We now require extra padding between the two items in the array.
- *    After the 14 bytes of the first item, that's 2 bytes required.  We
- *    now require 2 framing offsets for an extra two bytes.  14 + 2 + 11
- *    + 2 = 29 bytes to encode the entire two-item dictionary.
- *   </para>
- *  </refsect3>
- *  <refsect3>
- *   <title>Type Information Cache</title>
- *   <para>
- *    For each GVariant type that currently exists in the program a type
- *    information structure is kept in the type information cache.  The
- *    type information structure is required for rapid deserialisation.
- *   </para>
- *   <para>
- *    Continuing with the above example, if a #GVariant exists with the
- *    type "a{sv}" then a type information struct will exist for
- *    "a{sv}", "{sv}", "s", and "v".  Multiple uses of the same type
- *    will share the same type information.  Additionally, all
- *    single-digit types are stored in read-only static memory and do
- *    not contribute to the writable memory footprint of a program using
- *    #GVariant.
- *   </para>
- *   <para>
- *    Aside from the type information structures stored in read-only
- *    memory, there are two forms of type information.  One is used for
- *    container types where there is a single element type: arrays and
- *    maybe types.  The other is used for container types where there
- *    are multiple element types: tuples and dictionary entries.
- *   </para>
- *   <para>
- *    Array type info structures are 6 * sizeof (void *), plus the
- *    memory required to store the type string itself.  This means that
- *    on 32bit systems, the cache entry for "a{sv}" would require 30
- *    bytes of memory (plus malloc overhead).
- *   </para>
- *   <para>
- *    Tuple type info structures are 6 * sizeof (void *), plus 4 *
- *    sizeof (void *) for each item in the tuple, plus the memory
- *    required to store the type string itself.  A 2-item tuple, for
- *    example, would have a type information structure that consumed
- *    writable memory in the size of 14 * sizeof (void *) (plus type
- *    string)  This means that on 32bit systems, the cache entry for
- *    "{sv}" would require 61 bytes of memory (plus malloc overhead).
- *   </para>
- *   <para>
- *    This means that in total, for our "a{sv}" example, 91 bytes of
- *    type information would be allocated.
- *   </para>
- *   <para>
- *    The type information cache, additionally, uses a #GHashTable to
- *    store and lookup the cached items and stores a pointer to this
- *    hash table in static storage.  The hash table is freed when there
- *    are zero items in the type cache.
- *   </para>
- *   <para>
- *    Although these sizes may seem large it is important to remember
- *    that a program will probably only have a very small number of
- *    different types of values in it and that only one type information
- *    structure is required for many different values of the same type.
- *   </para>
- *  </refsect3>
- *  <refsect3>
- *   <title>Buffer Management Memory</title>
- *   <para>
- *    #GVariant uses an internal buffer management structure to deal
- *    with the various different possible sources of serialised data
- *    that it uses.  The buffer is responsible for ensuring that the
- *    correct call is made when the data is no longer in use by
- *    #GVariant.  This may involve a g_free() or a g_slice_free() or
- *    even g_mapped_file_unref().
- *   </para>
- *   <para>
- *    One buffer management structure is used for each chunk of
- *    serialised data.  The size of the buffer management structure is 4
- *    * (void *).  On 32bit systems, that's 16 bytes.
- *   </para>
- *  </refsect3>
- *  <refsect3>
- *   <title>GVariant structure</title>
- *   <para>
- *    The size of a #GVariant structure is 6 * (void *).  On 32 bit
- *    systems, that's 24 bytes.
- *   </para>
- *   <para>
- *    #GVariant structures only exist if they are explicitly created
- *    with API calls.  For example, if a #GVariant is constructed out of
- *    serialised data for the example given above (with the dictionary)
- *    then although there are 9 individual values that comprise the
- *    entire dictionary (two keys, two values, two variants containing
- *    the values, two dictionary entries, plus the dictionary itself),
- *    only 1 #GVariant instance exists -- the one referring to the
- *    dictionary.
- *   </para>
- *   <para>
- *    If calls are made to start accessing the other values then
- *    #GVariant instances will exist for those values only for as long
- *    as they are in use (ie: until you call g_variant_unref()).  The
- *    type information is shared.  The serialised data and the buffer
- *    management structure for that serialised data is shared by the
- *    child.
- *   </para>
- *  </refsect3>
- *  <refsect3>
- *   <title>Summary</title>
- *   <para>
- *    To put the entire example together, for our dictionary mapping
- *    strings to variants (with two entries, as given above), we are
- *    using 91 bytes of memory for type information, 29 byes of memory
- *    for the serialised data, 16 bytes for buffer management and 24
- *    bytes for the #GVariant instance, or a total of 160 bytes, plus
- *    malloc overhead.  If we were to use g_variant_get_child_value() to
- *    access the two dictionary entries, we would use an additional 48
- *    bytes.  If we were to have other dictionaries of the same type, we
- *    would use more memory for the serialised data and buffer
- *    management for those dictionaries, but the type information would
- *    be shared.
- *   </para>
- *  </refsect3>
- * </refsect2>
+ * ## Memory Use
+ *
+ * #GVariant tries to be quite efficient with respect to memory use.
+ * This section gives a rough idea of how much memory is used by the
+ * current implementation.  The information here is subject to change
+ * in the future.
+ *
+ * The memory allocated by #GVariant can be grouped into 4 broad
+ * purposes: memory for serialised data, memory for the type
+ * information cache, buffer management memory and memory for the
+ * #GVariant structure itself.
+ *
+ * ## Serialised Data Memory
+ *
+ * This is the memory that is used for storing GVariant data in
+ * serialised form.  This is what would be sent over the network or
+ * what would end up on disk.
+ *
+ * The amount of memory required to store a boolean is 1 byte. 16,
+ * 32 and 64 bit integers and double precision floating point numbers
+ * use their "natural" size.  Strings (including object path and
+ * signature strings) are stored with a nul terminator, and as such
+ * use the length of the string plus 1 byte.
+ *
+ * Maybe types use no space at all to represent the null value and
+ * use the same amount of space (sometimes plus one byte) as the
+ * equivalent non-maybe-typed value to represent the non-null case.
+ *
+ * Arrays use the amount of space required to store each of their
+ * members, concatenated.  Additionally, if the items stored in an
+ * array are not of a fixed-size (ie: strings, other arrays, etc)
+ * then an additional framing offset is stored for each item.  The
+ * size of this offset is either 1, 2 or 4 bytes depending on the
+ * overall size of the container.  Additionally, extra padding bytes
+ * are added as required for alignment of child values.
+ *
+ * Tuples (including dictionary entries) use the amount of space
+ * required to store each of their members, concatenated, plus one
+ * framing offset (as per arrays) for each non-fixed-sized item in
+ * the tuple, except for the last one.  Additionally, extra padding
+ * bytes are added as required for alignment of child values.
+ *
+ * Variants use the same amount of space as the item inside of the
+ * variant, plus 1 byte, plus the length of the type string for the
+ * item inside the variant.
+ *
+ * As an example, consider a dictionary mapping strings to variants.
+ * In the case that the dictionary is empty, 0 bytes are required for
+ * the serialisation.
+ *
+ * If we add an item "width" that maps to the int32 value of 500 then
+ * we will use 4 byte to store the int32 (so 6 for the variant
+ * containing it) and 6 bytes for the string.  The variant must be
+ * aligned to 8 after the 6 bytes of the string, so that's 2 extra
+ * bytes.  6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
+ * for the dictionary entry.  An additional 1 byte is added to the
+ * array as a framing offset making a total of 15 bytes.
+ *
+ * If we add another entry, "title" that maps to a nullable string
+ * that happens to have a value of null, then we use 0 bytes for the
+ * null value (and 3 bytes for the variant to contain it along with
+ * its type string) plus 6 bytes for the string.  Again, we need 2
+ * padding bytes.  That makes a total of 6 + 2 + 3 = 11 bytes.
+ *
+ * We now require extra padding between the two items in the array.
+ * After the 14 bytes of the first item, that's 2 bytes required. We
+ * now require 2 framing offsets for an extra two bytes.  14 + 2 + 11
+ * + 2 = 29 bytes to encode the entire two-item dictionary.
+ *
+ * ## Type Information Cache
+ *
+ * For each GVariant type that currently exists in the program a type
+ * information structure is kept in the type information cache.  The
+ * type information structure is required for rapid deserialisation.
+ *
+ * Continuing with the above example, if a #GVariant exists with the
+ * type "a{sv}" then a type information struct will exist for
+ * "a{sv}", "{sv}", "s", and "v".  Multiple uses of the same type
+ * will share the same type information.  Additionally, all
+ * single-digit types are stored in read-only static memory and do
+ * not contribute to the writable memory footprint of a program using
+ * #GVariant.
+ *
+ * Aside from the type information structures stored in read-only
+ * memory, there are two forms of type information.  One is used for
+ * container types where there is a single element type: arrays and
+ * maybe types.  The other is used for container types where there
+ * are multiple element types: tuples and dictionary entries.
+ *
+ * Array type info structures are 6 * sizeof (void *), plus the
+ * memory required to store the type string itself.  This means that
+ * on 32-bit systems, the cache entry for "a{sv}" would require 30
+ * bytes of memory (plus malloc overhead).
+ *
+ * Tuple type info structures are 6 * sizeof (void *), plus 4 *
+ * sizeof (void *) for each item in the tuple, plus the memory
+ * required to store the type string itself.  A 2-item tuple, for
+ * example, would have a type information structure that consumed
+ * writable memory in the size of 14 * sizeof (void *) (plus type
+ * string)  This means that on 32-bit systems, the cache entry for
+ * "{sv}" would require 61 bytes of memory (plus malloc overhead).
+ *
+ * This means that in total, for our "a{sv}" example, 91 bytes of
+ * type information would be allocated.
+ *
+ * The type information cache, additionally, uses a #GHashTable to
+ * store and lookup the cached items and stores a pointer to this
+ * hash table in static storage.  The hash table is freed when there
+ * are zero items in the type cache.
+ *
+ * Although these sizes may seem large it is important to remember
+ * that a program will probably only have a very small number of
+ * different types of values in it and that only one type information
+ * structure is required for many different values of the same type.
+ *
+ * ## Buffer Management Memory
+ *
+ * #GVariant uses an internal buffer management structure to deal
+ * with the various different possible sources of serialised data
+ * that it uses.  The buffer is responsible for ensuring that the
+ * correct call is made when the data is no longer in use by
+ * #GVariant.  This may involve a g_free() or a g_slice_free() or
+ * even g_mapped_file_unref().
+ *
+ * One buffer management structure is used for each chunk of
+ * serialised data.  The size of the buffer management structure
+ * is 4 * (void *).  On 32-bit systems, that's 16 bytes.
+ *
+ * ## GVariant structure
+ *
+ * The size of a #GVariant structure is 6 * (void *).  On 32-bit
+ * systems, that's 24 bytes.
+ *
+ * #GVariant structures only exist if they are explicitly created
+ * with API calls.  For example, if a #GVariant is constructed out of
+ * serialised data for the example given above (with the dictionary)
+ * then although there are 9 individual values that comprise the
+ * entire dictionary (two keys, two values, two variants containing
+ * the values, two dictionary entries, plus the dictionary itself),
+ * only 1 #GVariant instance exists -- the one referring to the
+ * dictionary.
+ *
+ * If calls are made to start accessing the other values then
+ * #GVariant instances will exist for those values only for as long
+ * as they are in use (ie: until you call g_variant_unref()).  The
+ * type information is shared.  The serialised data and the buffer
+ * management structure for that serialised data is shared by the
+ * child.
+ *
+ * ## Summary
+ *
+ * To put the entire example together, for our dictionary mapping
+ * strings to variants (with two entries, as given above), we are
+ * using 91 bytes of memory for type information, 29 byes of memory
+ * for the serialised data, 16 bytes for buffer management and 24
+ * bytes for the #GVariant instance, or a total of 160 bytes, plus
+ * malloc overhead.  If we were to use g_variant_get_child_value() to
+ * access the two dictionary entries, we would use an additional 48
+ * bytes.  If we were to have other dictionaries of the same type, we
+ * would use more memory for the serialised data and buffer
+ * management for those dictionaries, but the type information would
+ * be shared.
  */
 
 
@@ -6239,18 +6182,18 @@
  * @short_description: introduction to the GVariant type system
  * @see_also: #GVariantType, #GVariant
  *
- * This section introduces the GVariant type system.  It is based, in
- * large part, on the D-Bus type system, with two major changes and some minor
- * lifting of restrictions.  The <ulink
- * url='http://dbus.freedesktop.org/doc/dbus-specification.html'>DBus
- * specification</ulink>, therefore, provides a significant amount of
+ * This section introduces the GVariant type system. It is based, in
+ * large part, on the D-Bus type system, with two major changes and
+ * some minor lifting of restrictions. The
+ * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html),
+ * therefore, provides a significant amount of
  * information that is useful when working with GVariant.
  *
  * The first major change with respect to the D-Bus type system is the
  * introduction of maybe (or "nullable") types.  Any type in GVariant can be
  * converted to a maybe type, in which case, "nothing" (or "null") becomes a
  * valid value.  Maybe types have been added by introducing the
- * character "<literal>m</literal>" to type strings.
+ * character "m" to type strings.
  *
  * The second major change is that the GVariant type system supports the
  * concept of "indefinite types" -- types that are less specific than
@@ -6258,8 +6201,7 @@
  * of "an array of any type" in GVariant, where the D-Bus type system
  * would require you to speak of "an array of integers" or "an array of
  * strings".  Indefinite types have been added by introducing the
- * characters "<literal>*</literal>", "<literal>?</literal>" and
- * "<literal>r</literal>" to type strings.
+ * characters "*", "?" and "r" to type strings.
  *
  * Finally, all arbitrary restrictions relating to the complexity of
  * types are lifted along with the restriction that dictionary entries
@@ -6297,67 +6239,32 @@
  * that the #GtkWindow is a #GtkBin (since #GtkWindow is a subclass of
  * #GtkBin).
  *
- * A detailed description of GVariant type strings is given here:
- *
- * <refsect2 id='gvariant-typestrings'>
- *  <title>GVariant Type Strings</title>
- *  <para>
- *   A GVariant type string can be any of the following:
- *  </para>
- *  <itemizedlist>
- *   <listitem>
- *    <para>
- *     any basic type string (listed below)
- *    </para>
- *   </listitem>
- *   <listitem>
- *    <para>
- *     "<literal>v</literal>", "<literal>r</literal>" or
- *     "<literal>*</literal>"
- *    </para>
- *   </listitem>
- *   <listitem>
- *    <para>
- *     one of the characters '<literal>a</literal>' or
- *     '<literal>m</literal>', followed by another type string
- *    </para>
- *   </listitem>
- *   <listitem>
- *    <para>
- *     the character '<literal>(</literal>', followed by a concatenation
- *     of zero or more other type strings, followed by the character
- *     '<literal>)</literal>'
- *    </para>
- *   </listitem>
- *   <listitem>
- *    <para>
- *     the character '<literal>{</literal>', followed by a basic type
- *     string (see below), followed by another type string, followed by
- *     the character '<literal>}</literal>'
- *    </para>
- *   </listitem>
- *  </itemizedlist>
- *  <para>
- *   A basic type string describes a basic type (as per
- *   g_variant_type_is_basic()) and is always a single
- *   character in length.  The valid basic type strings are
- *   "<literal>b</literal>", "<literal>y</literal>",
- *   "<literal>n</literal>", "<literal>q</literal>",
- *   "<literal>i</literal>", "<literal>u</literal>",
- *   "<literal>x</literal>", "<literal>t</literal>",
- *   "<literal>h</literal>", "<literal>d</literal>",
- *   "<literal>s</literal>", "<literal>o</literal>",
- *   "<literal>g</literal>" and "<literal>?</literal>".
- *  </para>
- *  <para>
- *   The above definition is recursive to arbitrary depth.
- *   "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
- *   are both valid type strings, as is
- *   "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
- *  </para>
- *  <para>
- *   The meaning of each of the characters is as follows:
- *  </para>
+ * ## GVariant Type Strings
+ *
+ * A GVariant type string can be any of the following:
+ *
+ * - any basic type string (listed below)
+ *
+ * - "v", "r" or "*"
+ *
+ * - one of the characters 'a' or 'm', followed by another type string
+ *
+ * - the character '(', followed by a concatenation of zero or more other
+ *   type strings, followed by the character ')'
+ *
+ * - the character '{', followed by a basic type string (see below),
+ *   followed by another type string, followed by the character '}'
+ *
+ * A basic type string describes a basic type (as per
+ * g_variant_type_is_basic()) and is always a single character in length.
+ * The valid basic type strings are "b", "y", "n", "q", "i", "u", "x", "t",
+ * "h", "d", "s", "o", "g" and "?".
+ *
+ * The above definition is recursive to arbitrary depth. "aaaaai" and
+ * "(ui(nq((y)))s)" are both valid type strings, as is
+ * "a(aa(ui)(qna{ya(yd)}))".
+ *
+ * The meaning of each of the characters is as follows:
  *  <informaltable>
  *   <tgroup cols='2'>
  *    <tbody>
@@ -6376,7 +6283,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>b</literal>
+ *        b
  *       </para>
  *      </entry>
  *      <entry>
@@ -6388,7 +6295,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>y</literal>
+ *        y
  *       </para>
  *      </entry>
  *      <entry>
@@ -6400,7 +6307,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>n</literal>
+ *        n
  *       </para>
  *      </entry>
  *      <entry>
@@ -6413,7 +6320,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>q</literal>
+ *        q
  *       </para>
  *      </entry>
  *      <entry>
@@ -6426,7 +6333,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>i</literal>
+ *        i
  *       </para>
  *      </entry>
  *      <entry>
@@ -6439,7 +6346,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>u</literal>
+ *        u
  *       </para>
  *      </entry>
  *      <entry>
@@ -6452,7 +6359,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>x</literal>
+ *        x
  *       </para>
  *      </entry>
  *      <entry>
@@ -6465,7 +6372,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>t</literal>
+ *        t
  *       </para>
  *      </entry>
  *      <entry>
@@ -6478,7 +6385,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>h</literal>
+ *        h
  *       </para>
  *      </entry>
  *      <entry>
@@ -6492,7 +6399,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>d</literal>
+ *        d
  *       </para>
  *      </entry>
  *      <entry>
@@ -6505,7 +6412,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>s</literal>
+ *        s
  *       </para>
  *      </entry>
  *      <entry>
@@ -6517,7 +6424,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>o</literal>
+ *        o
  *       </para>
  *      </entry>
  *      <entry>
@@ -6530,7 +6437,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>g</literal>
+ *        g
  *       </para>
  *      </entry>
  *      <entry>
@@ -6543,7 +6450,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>?</literal>
+ *        ?
  *       </para>
  *      </entry>
  *      <entry>
@@ -6556,7 +6463,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>v</literal>
+ *        v
  *       </para>
  *      </entry>
  *      <entry>
@@ -6569,51 +6476,50 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>a</literal>
+ *        a
  *       </para>
  *      </entry>
  *      <entry>
  *       <para>
  *        used as a prefix on another type string to mean an array of
- *        that type; the type string "<literal>ai</literal>", for
- *        example, is the type of an array of 32 bit signed integers.
+ *        that type; the type string "ai", for example, is the type of
+ *        an array of signed 32-bit integers.
  *       </para>
  *      </entry>
  *     </row>
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>m</literal>
+ *        m
  *       </para>
  *      </entry>
  *      <entry>
  *       <para>
  *        used as a prefix on another type string to mean a "maybe", or
- *        "nullable", version of that type; the type string
- *        "<literal>ms</literal>", for example, is the type of a value
- *        that maybe contains a string, or maybe contains nothing.
+ *        "nullable", version of that type; the type string "ms", for example,
+ *        is the type of a value that maybe contains a string, or maybe
+ *        contains nothing.
  *       </para>
  *      </entry>
  *     </row>
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>()</literal>
+ *        ()
  *       </para>
  *      </entry>
  *      <entry>
  *       <para>
  *        used to enclose zero or more other concatenated type strings
- *        to create a tuple type; the type string
- *        "<literal>(is)</literal>", for example, is the type of a pair
- *        of an integer and a string.
+ *        to create a tuple type; the type string "(is)", for example,
+ *        is the type of a pair of an integer and a string.
  *       </para>
  *      </entry>
  *     </row>
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>r</literal>
+ *        r
  *       </para>
  *      </entry>
  *      <entry>
@@ -6627,7 +6533,7 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>{}</literal>
+ *        {}
  *       </para>
  *      </entry>
  *      <entry>
@@ -6635,13 +6541,12 @@
  *        used to enclose a basic type string concatenated with another
  *        type string to create a dictionary entry type, which usually
  *        appears inside of an array to form a dictionary; the type
- *        string "<literal>a{sd}</literal>", for example, is the type of
- *        a dictionary that maps strings to double precision floating
- *        point values.
+ *        string "a{sd}", for example, is the type of a dictionary that
+ *        maps strings to double precision floating point values.
  *       </para>
  *       <para>
  *        The first type (the basic type) is the key type and the second
- *        type is the value type.  The reason that the first type is
+ *        type is the value type. The reason that the first type is
  *        restricted to being a basic type is so that it can easily be
  *        hashed.
  *       </para>
@@ -6650,14 +6555,14 @@
  *     <row>
  *      <entry>
  *       <para>
- *        <literal>*</literal>
+ *        *
  *       </para>
  *      </entry>
  *      <entry>
  *       <para>
  *        the type string of %G_VARIANT_TYPE_ANY; the indefinite type
  *        that is a supertype of all types.  Note that, as with all type
- *        strings, this character represents exactly one type.  It
+ *        strings, this character represents exactly one type. It
  *        cannot be used inside of tuples to mean "any number of items".
  *       </para>
  *      </entry>
@@ -6665,24 +6570,20 @@
  *    </tbody>
  *   </tgroup>
  *  </informaltable>
- *  <para>
- *   Any type string of a container that contains an indefinite type is,
- *   itself, an indefinite type.  For example, the type string
- *   "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
- *   an indefinite type that is a supertype of every array type.
- *   "<literal>(*s)</literal>" is a supertype of all tuples that
- *   contain exactly two items where the second item is a string.
- *  </para>
- *  <para>
- *   "<literal>a{?*}</literal>" is an indefinite type that is a
- *   supertype of all arrays containing dictionary entries where the key
- *   is any basic type and the value is any type at all.  This is, by
- *   definition, a dictionary, so this type string corresponds to
- *   %G_VARIANT_TYPE_DICTIONARY.  Note that, due to the restriction that
- *   the key of a dictionary entry must be a basic type,
- *   "<literal>{**}</literal>" is not a valid type string.
- *  </para>
- * </refsect2>
+ *
+ * Any type string of a container that contains an indefinite type is,
+ * itself, an indefinite type. For example, the type string "a*"
+ * (corresponding to %G_VARIANT_TYPE_ARRAY) is an indefinite type
+ * that is a supertype of every array type. "(*s)" is a supertype
+ * of all tuples that contain exactly two items where the second
+ * item is a string.
+ *
+ * "a{?*}" is an indefinite type that is a supertype of all arrays
+ * containing dictionary entries where the key is any basic type and
+ * the value is any type at all.  This is, by definition, a dictionary,
+ * so this type string corresponds to %G_VARIANT_TYPE_DICTIONARY. Note
+ * that, due to the restriction that the key of a dictionary entry must
+ * be a basic type, "{**}" is not a valid type string.
  */
 
 
@@ -6747,7 +6648,8 @@
  * HMACs should be used when producing a cookie or hash based on data
  * and a key. Simple mechanisms for using SHA1 and other algorithms to
  * digest a key and data together are vulnerable to various security
- * issues. <ulink url="http://en.wikipedia.org/wiki/HMAC">HMAC</ulink>
+ * issues.
+ * [HMAC](http://en.wikipedia.org/wiki/HMAC)
  * uses algorithms like SHA1 in a secure way to produce a digest of a
  * key and data.
  *
@@ -6780,12 +6682,12 @@
  * easy-to-use form.
  *
  * In order to use these macros in an application, you must include
- * <filename>glib/gi18n.h</filename>. For use in a library, you must include
- * <filename>glib/gi18n-lib.h</filename> <emphasis>after</emphasis> defining
- * the GETTEXT_PACKAGE macro suitably for your library:
- * |[
- * &num;define GETTEXT_PACKAGE "gtk20"
- * &num;include &lt;glib/gi18n-lib.h&gt;
+ * `&lt;glib/gi18n.h&gt;`. For use in a library, you must include
+ * `&lt;glib/gi18n-lib.h&gt;`
+ * after defining the %GETTEXT_PACKAGE macro suitably for your library:
+ * |[<!-- language="C" -->
+ * #define GETTEXT_PACKAGE "gtk20"
+ * #include <glib/gi18n-lib.h>
  * ]|
  * For an application, note that you also have to call bindtextdomain(),
  * bind_textdomain_codeset(), textdomain() and setlocale() early on in your
@@ -6804,15 +6706,9 @@
 /**
  * SECTION:iochannels
  * @title: IO Channels
- * @short_description: portable support for using files, pipes and
- *                     sockets
- * @see_also: <para> <variablelist> <varlistentry>
- *            <term>g_io_add_watch(), g_io_add_watch_full(),
- *            g_source_remove()</term> <listitem><para> Convenience
- *            functions for creating #GIOChannel instances and adding
- *            them to the <link linkend="glib-The-Main-Event-Loop">main
- *            event loop</link>. </para></listitem> </varlistentry>
- *            </variablelist> </para>
+ * @short_description: portable support for using files, pipes and sockets
+ * @see_also: g_io_add_watch(), g_io_add_watch_full(), g_source_remove(),
+ *     #GMainLoop
  *
  * The #GIOChannel data type aims to provide a portable method for
  * using file descriptors, pipes, and sockets, and integrating them
@@ -6859,17 +6755,15 @@
  * @short_description: parses .ini-like config files
  *
  * #GKeyFile lets you parse, edit or create files containing groups of
- * key-value pairs, which we call <firstterm>key files</firstterm> for
- * lack of a better name. Several freedesktop.org specifications use
- * key files now, e.g the
- * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
- * Entry Specification</ulink> and the
- * <ulink url="http://freedesktop.org/Standards/icon-theme-spec">Icon
- * Theme Specification</ulink>.
+ * key-value pairs, which we call "key files" for lack of a better name.
+ * Several freedesktop.org specifications use key files now, e.g the
+ * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec)
+ * and the
+ * [Icon Theme Specification](http://freedesktop.org/Standards/icon-theme-spec).
  *
  * The syntax of key files is described in detail in the
- * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
- * Entry Specification</ulink>, here is a quick summary: Key files
+ * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
+ * here is a quick summary: Key files
  * consists of groups of key-value pairs, interspersed with comments.
  *
  * |[
@@ -6900,11 +6794,11 @@
  * in '[' and ']', and ended implicitly by the start of the next group or
  * the end of the file. Each key-value pair must be contained in a group.
  *
- * Key-value pairs generally have the form <literal>key=value</literal>,
- * with the exception of localized strings, which have the form
- * <literal>key[locale]=value</literal>, with a locale identifier of the
- * form <literal>lang_COUNTRY@MODIFIER</literal> where
- * <literal>COUNTRY</literal> and <literal>MODIFIER</literal> are optional.
+ * Key-value pairs generally have the form `key=value`, with the
+ * exception of localized strings, which have the form
+ * `key[locale]=value`, with a locale identifier of the
+ * form `lang_COUNTRY\@MODIFIER` where `COUNTRY` and `MODIFIER`
+ * are optional.
  * Space before and after the '=' character are ignored. Newline, tab,
  * carriage return and backslash characters in value are escaped as \n,
  * \t, \r, and \\, respectively. To preserve leading spaces in values,
@@ -6917,24 +6811,25 @@
  *
  * This syntax is obviously inspired by the .ini files commonly met
  * on Windows, but there are some important differences:
- * <itemizedlist>
- *   <listitem>.ini files use the ';' character to begin comments,
- *     key files use the '#' character.</listitem>
- *   <listitem>Key files do not allow for ungrouped keys meaning only
- *     comments can precede the first group.</listitem>
- *   <listitem>Key files are always encoded in UTF-8.</listitem>
- *   <listitem>Key and Group names are case-sensitive. For example, a
- *     group called <literal>[GROUP]</literal> is a different from
- *     <literal>[group]</literal>.</listitem>
- *   <listitem>.ini files don't have a strongly typed boolean entry type,
- *     they only have GetProfileInt(). In key files, only
- *     <literal>true</literal> and <literal>false</literal> (in lower case)
- *     are allowed.</listitem>
- *  </itemizedlist>
+ *
+ * - .ini files use the ';' character to begin comments,
+ *   key files use the '#' character.
+ *
+ * - Key files do not allow for ungrouped keys meaning only
+ *   comments can precede the first group.
+ *
+ * - Key files are always encoded in UTF-8.
+ *
+ * - Key and Group names are case-sensitive. For example, a group called
+ *   [GROUP] is a different from [group].
+ *
+ * - .ini files don't have a strongly typed boolean entry type,
+ *    they only have GetProfileInt(). In key files, only
+ *    true and false (in lower case) are allowed.
  *
  * Note that in contrast to the
- * <ulink url="http://freedesktop.org/Standards/desktop-entry-spec">Desktop
- * Entry Specification</ulink>, groups in key files may contain the same
+ * [Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec),
+ * groups in key files may contain the same
  * key multiple times; the last entry wins. Key files may also contain
  * multiple groups with the same name; they are merged together.
  * Another difference is that keys and group names in key files are not
@@ -6983,7 +6878,7 @@
  * g_list_insert() and g_list_insert_sorted().
  *
  * To visit all elements in the list, use a loop over the list:
- * |[
+ * |[<!-- language="C" -->
  * GList *l;
  * for (l = list; l != NULL; l = l->next)
  *   {
@@ -6995,7 +6890,7 @@
  *
  * To loop over the list and modify it (e.g. remove a certain element)
  * a while loop is more appropriate, for example:
- * |[
+ * |[<!-- language="C" -->
  * GList *l = list;
  * while (l != NULL)
  *   {
@@ -7132,42 +7027,46 @@
  * GTK+ contains wrappers of some of these functions, e.g. gtk_main(),
  * gtk_main_quit() and gtk_events_pending().
  *
- * <refsect2><title>Creating new source types</title>
- * <para>One of the unusual features of the #GMainLoop functionality
+ * ## Creating new source types
+ *
+ * One of the unusual features of the #GMainLoop functionality
  * is that new types of event source can be created and used in
  * addition to the builtin type of event source. A new event source
  * type is used for handling GDK events. A new source type is created
- * by <firstterm>deriving</firstterm> from the #GSource structure.
- * The derived type of source is represented by a structure that has
- * the #GSource structure as a first element, and other elements specific
- * to the new source type. To create an instance of the new source type,
- * call g_source_new() passing in the size of the derived structure and
+ * by "deriving" from the #GSource structure. The derived type of
+ * source is represented by a structure that has the #GSource structure
+ * as a first element, and other elements specific to the new source
+ * type. To create an instance of the new source type, call
+ * g_source_new() passing in the size of the derived structure and
  * a table of functions. These #GSourceFuncs determine the behavior of
- * the new source type.</para>
- * <para>New source types basically interact with the main context
+ * the new source type.
+ *
+ * New source types basically interact with the main context
  * in two ways. Their prepare function in #GSourceFuncs can set a timeout
  * to determine the maximum amount of time that the main loop will sleep
  * before checking the source again. In addition, or as well, the source
  * can add file descriptors to the set that the main context checks using
- * g_source_add_poll().</para>
- * </refsect2>
- * <refsect2><title>Customizing the main loop iteration</title>
- * <para>Single iterations of a #GMainContext can be run with
+ * g_source_add_poll().
+ *
+ * ## Customizing the main loop iteration
+ *
+ * Single iterations of a #GMainContext can be run with
  * g_main_context_iteration(). In some cases, more detailed control
  * of exactly how the details of the main loop work is desired, for
  * instance, when integrating the #GMainLoop with an external main loop.
  * In such cases, you can call the component functions of
  * g_main_context_iteration() directly. These functions are
  * g_main_context_prepare(), g_main_context_query(),
- * g_main_context_check() and g_main_context_dispatch().</para>
- * <para>The operation of these functions can best be seen in terms
- * of a state diagram, as shown in <xref linkend="mainloop-states"/>.</para>
- * <figure id="mainloop-states"><title>States of a Main Context</title>
- * <graphic fileref="mainloop-states.gif" format="GIF"></graphic>
- * </figure>
- * </refsect2>
- *
- * On Unix, the GLib mainloop is incompatible with fork().  Any program
+ * g_main_context_check() and g_main_context_dispatch().
+ *
+ * ## State of a Main Context # {#mainloop-states}
+ *
+ * The operation of these functions can best be seen in terms
+ * of a state diagram, as shown in this image.
+ *
+ * ![](mainloop-states.gif)
+ *
+ * On UNIX, the GLib mainloop is incompatible with fork(). Any program
  * using the mainloop must either exec() or exit() from the child
  * without returning to the mainloop.
  */
@@ -7175,10 +7074,8 @@
 
 /**
  * SECTION:markup
- * @Title: Simple XML Subset Parser
- * @Short_description: parses a subset of XML
- * @See_also: <ulink url="http://www.w3.org/TR/REC-xml/">XML
- *     Specification</ulink>
+ * @Title: Simple XML Subset Parser * @Short_description: parses a subset of XML
+ * @See_also: [XML Specification](http://www.w3.org/TR/REC-xml/)
  *
  * The "GMarkup" parser is intended to parse a simple markup format
  * that's a subset of XML. This is a small, efficient, easy-to-use
@@ -7192,31 +7089,34 @@
  *
  * GMarkup is not guaranteed to signal an error on all invalid XML;
  * the parser may accept documents that an XML parser would not.
- * However, XML documents which are not well-formed<footnote
- * id="wellformed">Being wellformed is a weaker condition than being
- * valid. See the <ulink url="http://www.w3.org/TR/REC-xml/">XML
- * specification</ulink> for definitions of these terms.</footnote>
- * are not considered valid GMarkup documents.
+ * However, XML documents which are not well-formed (which is a
+ * weaker condition than being valid. See the
+ * [XML specification](http://www.w3.org/TR/REC-xml/)
+ * for definitions of these terms.) are not considered valid GMarkup
+ * documents.
  *
  * Simplifications to XML include:
- * <itemizedlist>
- * <listitem>Only UTF-8 encoding is allowed</listitem>
- * <listitem>No user-defined entities</listitem>
- * <listitem>Processing instructions, comments and the doctype declaration
- * are "passed through" but are not interpreted in any way</listitem>
- * <listitem>No DTD or validation.</listitem>
- * </itemizedlist>
+ *
+ * - Only UTF-8 encoding is allowed
+ *
+ * - No user-defined entities
+ *
+ * - Processing instructions, comments and the doctype declaration
+ *   are "passed through" but are not interpreted in any way
+ *
+ * - No DTD or validation
  *
  * The markup format does support:
- * <itemizedlist>
- * <listitem>Elements</listitem>
- * <listitem>Attributes</listitem>
- * <listitem>5 standard entities:
- *   <literal>&amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;</literal>
- * </listitem>
- * <listitem>Character references</listitem>
- * <listitem>Sections marked as CDATA</listitem>
- * </itemizedlist>
+ *
+ * - Elements
+ *
+ * - Attributes
+ *
+ * - 5 standard entities: &amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;
+ *
+ * - Character references
+ *
+ * - Sections marked as CDATA
  */
 
 
@@ -7227,18 +7127,15 @@
  *
  * These functions provide support for allocating and freeing memory.
  *
- * <note>
  * If any call to allocate memory fails, the application is terminated.
  * This also means that there is no need to check if the call succeeded.
- * </note>
  *
- * <note>
- * It's important to match g_malloc() with g_free(), plain malloc() with free(),
- * and (if you're using C++) new with delete and new[] with delete[]. Otherwise
- * bad things can happen, since these allocators may use different memory
- * pools (and new/delete call constructors and destructors). See also
- * g_mem_set_vtable().
- * </note>
+ * It's important to match g_malloc() (and wrappers such as g_new()) with
+ * g_free(), g_slice_alloc() and wrappers such as g_slice_new()) with
+ * g_slice_free(), plain malloc() with free(), and (if you're using C++)
+ * new with delete and new[] with delete[]. Otherwise bad things can happen,
+ * since these allocators may use different memory pools (and new/delete call
+ * constructors and destructors). See also g_mem_set_vtable().
  */
 
 
@@ -7255,12 +7152,13 @@
  *
  * To achieve these goals, the slice allocator uses a sophisticated,
  * layered design that has been inspired by Bonwick's slab allocator
- * <footnote><para>
- * <ulink url="http://citeseer.ist.psu.edu/bonwick94slab.html">[Bonwick94]</ulink> Jeff Bonwick, The slab allocator: An object-caching kernel
+ * ([Bonwick94](http://citeseer.ist.psu.edu/bonwick94slab.html)
+ * Jeff Bonwick, The slab allocator: An object-caching kernel
  * memory allocator. USENIX 1994, and
- * <ulink url="http://citeseer.ist.psu.edu/bonwick01magazines.html">[Bonwick01]</ulink> Bonwick and Jonathan Adams, Magazines and vmem: Extending the
- * slab allocator to many cpu's and arbitrary resources. USENIX 2001
- * </para></footnote>.
+ * [Bonwick01](http://citeseer.ist.psu.edu/bonwick01magazines.html)
+ * Bonwick and Jonathan Adams, Magazines and vmem: Extending the
+ * slab allocator to many cpu's and arbitrary resources. USENIX 2001)
+ *
  * It uses posix_memalign() to optimize allocations of many equally-sized
  * chunks, and has per-thread free lists (the so-called magazine layer)
  * to quickly satisfy allocation requests of already known structure sizes.
@@ -7275,36 +7173,33 @@
  * unlike malloc(), it does not reserve extra space per block. For large block
  * sizes, g_slice_new() and g_slice_alloc() will automatically delegate to the
  * system malloc() implementation. For newly written code it is recommended
- * to use the new <literal>g_slice</literal> API instead of g_malloc() and
+ * to use the new `g_slice` API instead of g_malloc() and
  * friends, as long as objects are not resized during their lifetime and the
  * object size used at allocation time is still available when freeing.
  *
- * <example>
- * <title>Using the slice allocator</title>
- * <programlisting>
+ * Here is an example for using the slice allocator:
+ * |[<!-- language="C" -->
  * gchar *mem[10000];
  * gint i;
  *
  * /&ast; Allocate 10000 blocks. &ast;/
- * for (i = 0; i &lt; 10000; i++)
+ * for (i = 0; i < 10000; i++)
  *   {
  *     mem[i] = g_slice_alloc (50);
  *
  *     /&ast; Fill in the memory with some junk. &ast;/
- *     for (j = 0; j &lt; 50; j++)
+ *     for (j = 0; j < 50; j++)
  *       mem[i][j] = i * j;
  *   }
  *
  * /&ast; Now free all of the blocks. &ast;/
- * for (i = 0; i &lt; 10000; i++)
- *   {
- *     g_slice_free1 (50, mem[i]);
- *   }
- * </programlisting></example>
+ * for (i = 0; i < 10000; i++)
+ *   g_slice_free1 (50, mem[i]);
+ * ]|
  *
- * <example>
- * <title>Using the slice allocator with data structures</title>
- * <programlisting>
+ * And here is an example for using the using the slice allocator
+ * with data structures:
+ * |[<!-- language="C" -->
  * GRealArray *array;
  *
  * /&ast; Allocate one block, using the g_slice_new() macro. &ast;/
@@ -7320,7 +7215,7 @@
  *
  * /&ast; We can free the block, so it can be reused. &ast;/
  * g_slice_free (GRealArray, array);
- * </programlisting></example>
+ * ]|
  */
 
 
@@ -7360,7 +7255,7 @@
  * sign, mantissa and exponent of IEEE floats and doubles. These unions are
  * defined as appropriate for a given platform. IEEE floats and doubles are
  * supported (used for storage) by at least Intel, PPC and Sparc. See
- * <ulink url="http://en.wikipedia.org/wiki/IEEE_float">IEEE 754-2008</ulink>
+ * [IEEE 754-2008](http://en.wikipedia.org/wiki/IEEE_float)
  * for more information about IEEE number formats.
  */
 
@@ -7374,40 +7269,37 @@
  * for the popt library. It supports short and long commandline options,
  * as shown in the following example:
  *
- * <literal>testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2</literal>
+ * `testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2`
  *
  * The example demonstrates a number of features of the GOption
- * commandline parser
- * <itemizedlist><listitem><para>
- *   Options can be single letters, prefixed by a single dash. Multiple
- *   short options can be grouped behind a single dash.
- * </para></listitem><listitem><para>
- *   Long options are prefixed by two consecutive dashes.
- * </para></listitem><listitem><para>
- *   Options can have an extra argument, which can be a number, a string or
+ * commandline parser:
+ *
+ * - Options can be single letters, prefixed by a single dash.
+ *
+ * - Multiple short options can be grouped behind a single dash.
+ *
+ * - Long options are prefixed by two consecutive dashes.
+ *
+ * - Options can have an extra argument, which can be a number, a string or
  *   a filename. For long options, the extra argument can be appended with
  *   an equals sign after the option name, which is useful if the extra
  *   argument starts with a dash, which would otherwise cause it to be
  *   interpreted as another option.
- * </para></listitem><listitem><para>
- *   Non-option arguments are returned to the application as rest arguments.
- * </para></listitem><listitem><para>
- *   An argument consisting solely of two dashes turns off further parsing,
+ *
+ * - Non-option arguments are returned to the application as rest arguments.
+ *
+ * - An argument consisting solely of two dashes turns off further parsing,
  *   any remaining arguments (even those starting with a dash) are returned
  *   to the application as rest arguments.
- * </para></listitem></itemizedlist>
  *
  * Another important feature of GOption is that it can automatically
  * generate nicely formatted help output. Unless it is explicitly turned
  * off with g_option_context_set_help_enabled(), GOption will recognize
- * the <option>--help</option>, <option>-?</option>,
- * <option>--help-all</option> and
- * <option>--help-</option><replaceable>groupname</replaceable> options
- * (where <replaceable>groupname</replaceable> is the name of a
- * #GOptionGroup) and write a text similar to the one shown in the
- * following example to stdout.
- *
- * <informalexample><screen>
+ * the `--help`, `-?`, `--help-all` and `--help-groupname` options
+ * (where `groupname` is the name of a #GOptionGroup) and write a text
+ * similar to the one shown in the following example to stdout.
+ *
+ * |[
  * Usage:
  *   testtreemodel [OPTION...] - test tree model performance
  *  
@@ -7423,9 +7315,9 @@
  *   -v, --verbose            Be verbose
  *   -b, --beep               Beep when done
  *   --rand                   Randomize the data
- * </screen></informalexample>
+ * ]|
  *
- * GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
+ * GOption groups options in #GOptionGroups, which makes it easy to
  * incorporate options from multiple sources. The intended use for this is
  * to let applications collect option groups from the libraries it uses,
  * add them to their #GOptionContext, and parse all options by a single call
@@ -7439,8 +7331,7 @@
  *
  * Here is a complete example of setting up GOption to parse the example
  * commandline above and produce the example help output.
- *
- * <informalexample><programlisting>
+ * |[<!-- language="C" -->
  * static gint repeats = 2;
  * static gint max_size = 8;
  * static gboolean verbose = FALSE;
@@ -7475,7 +7366,7 @@
  *   /&ast; ... &ast;/
  *
  * }
- * </programlisting></informalexample>
+ * ]|
  *
  * On UNIX systems, the argv that is passed to main() has no particular
  * encoding, even to the extent that different parts of it may have
@@ -7499,7 +7390,7 @@
  * The following example shows how you can use #GOptionContext directly
  * in order to correctly deal with Unicode filenames on Windows:
  *
- * |[
+ * |[<!-- language="C" -->
  * int
  * main (int argc, char **argv)
  * {
@@ -7536,16 +7427,14 @@
  * @short_description: matches strings against patterns containing '*'
  *                     (wildcard) and '?' (joker)
  *
- * The <function>g_pattern_match*</function> functions match a string
+ * The g_pattern_match* functions match a string
  * against a pattern containing '*' and '?' wildcards with similar
  * semantics as the standard glob() function: '*' matches an arbitrary,
  * possibly empty, string, '?' matches an arbitrary character.
  *
- * Note that in contrast to glob(), the '/' character
- * <emphasis>can</emphasis> be matched by the wildcards, there are no
- * '[...]' character ranges and '*' and '?' can
- * <emphasis>not</emphasis> be escaped to include them literally in a
- * pattern.
+ * Note that in contrast to glob(), the '/' character can be matched by
+ * the wildcards, there are no '[...]' character ranges and '*' and '?'
+ * can not be escaped to include them literally in a pattern.
  *
  * When multiple strings must be matched against the same pattern, it
  * is better to compile the pattern to a #GPatternSpec using
@@ -7559,7 +7448,7 @@
  * SECTION:quarks
  * @title: Quarks
  * @short_description: a 2-way association between a string and a
- *                     unique integer identifier
+ *     unique integer identifier
  *
  * Quarks are associations between strings and integer identifiers.
  * Given either the string or the #GQuark identifier it is possible to
@@ -7622,51 +7511,47 @@
  * The following functions allow you to use a portable, fast and good
  * pseudo-random number generator (PRNG).
  *
- * <warning><para>Do not use this API for cryptographic purposes such as key
- * generation, nonces, salts or one-time pads.</para></warning>
+ * Do not use this API for cryptographic purposes such as key
+ * generation, nonces, salts or one-time pads.
  *
  * This PRNG is suitable for non-cryptographic use such as in games
- * (shuffling a card deck, generating levels), generating data for a
- * test suite, etc. If you need random data for cryptographic
- * purposes, it is recommended to use platform-specific APIs such as
- * <literal>/dev/random</literal> on Unix, or CryptGenRandom() on
- * Windows.
+ * (shuffling a card deck, generating levels), generating data for
+ * a test suite, etc. If you need random data for cryptographic
+ * purposes, it is recommended to use platform-specific APIs such
+ * as `/dev/random` on UNIX, or CryptGenRandom() on Windows.
  *
  * GRand uses the Mersenne Twister PRNG, which was originally
  * developed by Makoto Matsumoto and Takuji Nishimura. Further
- * information can be found at <ulink
- * url="http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html">
- * http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html</ulink>.
- *
- * If you just need a random number, you simply call the
- * <function>g_random_*</function> functions, which will create a
- * globally used #GRand and use the according
- * <function>g_rand_*</function> functions internally. Whenever you
- * need a stream of reproducible random numbers, you better create a
- * #GRand yourself and use the <function>g_rand_*</function> functions
- * directly, which will also be slightly faster. Initializing a #GRand
- * with a certain seed will produce exactly the same series of random
- * numbers on all platforms. This can thus be used as a seed for e.g.
- * games.
- *
- * The <function>g_rand*_range</function> functions will return high
- * quality equally distributed random numbers, whereas for example the
- * <literal>(g_random_int()&percnt;max)</literal> approach often
+ * information can be found at
+ * [this page](http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html).
+ *
+ * If you just need a random number, you simply call the g_random_*
+ * functions, which will create a globally used #GRand and use the
+ * according g_rand_* functions internally. Whenever you need a
+ * stream of reproducible random numbers, you better create a
+ * #GRand yourself and use the g_rand_* functions directly, which
+ * will also be slightly faster. Initializing a #GRand with a
+ * certain seed will produce exactly the same series of random
+ * numbers on all platforms. This can thus be used as a seed for
+ * e.g. games.
+ *
+ * The g_rand*_range functions will return high quality equally
+ * distributed random numbers, whereas for example the
+ * `(g_random_int()&percnt;max)` approach often
  * doesn't yield equally distributed numbers.
  *
  * GLib changed the seeding algorithm for the pseudo-random number
- * generator Mersenne Twister, as used by
- * <structname>GRand</structname> and <structname>GRandom</structname>.
- * This was necessary, because some seeds would yield very bad
- * pseudo-random streams.  Also the pseudo-random integers generated by
- * <function>g_rand*_int_range()</function> will have a slightly better
- * equal distribution with the new version of GLib.
+ * generator Mersenne Twister, as used by #GRand. This was necessary,
+ * because some seeds would yield very bad pseudo-random streams.
+ * Also the pseudo-random integers generated by g_rand*_int_range()
+ * will have a slightly better equal distribution with the new
+ * version of GLib.
  *
- * The original seeding and generation algorithms, as found in GLib
- * 2.0.x, can be used instead of the new ones by setting the
- * environment variable <envar>G_RANDOM_VERSION</envar> to the value of
- * '2.0'. Use the GLib-2.0 algorithms only if you have sequences of
- * numbers generated with Glib-2.0 that you need to reproduce exactly.
+ * The original seeding and generation algorithms, as found in
+ * GLib 2.0.x, can be used instead of the new ones by setting the
+ * environment variable `G_RANDOM_VERSION` to the value of '2.0'.
+ * Use the GLib-2.0 algorithms only if you have sequences of numbers
+ * generated with Glib-2.0 that you need to reproduce exactly.
  */
 
 
@@ -7693,12 +7578,11 @@
  * linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
  * or simply pointers to any type of data.
  *
- * A #GSequence is accessed through <firstterm>iterators</firstterm>,
- * represented by a #GSequenceIter. An iterator represents a position
- * between two elements of the sequence. For example, the
- * <firstterm>begin</firstterm> iterator represents the gap immediately
- * before the first element of the sequence, and the
- * <firstterm>end</firstterm> iterator represents the gap immediately
+ * A #GSequence is accessed through "iterators", represented by a
+ * #GSequenceIter. An iterator represents a position between two
+ * elements of the sequence. For example, the "begin" iterator
+ * represents the gap immediately before the first element of the
+ * sequence, and the "end" iterator represents the gap immediately
  * after the last element. In an empty sequence, the begin and end
  * iterators are the same.
  *
@@ -7711,7 +7595,7 @@
  *
  * The function g_sequence_get() is used with an iterator to access the
  * element immediately following the gap that the iterator represents.
- * The iterator is said to <firstterm>point</firstterm> to that element.
+ * The iterator is said to "point" to that element.
  *
  * Iterators are stable across most operations on a #GSequence. For
  * example an iterator pointing to some element of a sequence will
@@ -7777,27 +7661,25 @@
  *
  * Note that the functions g_printf(), g_fprintf(), g_sprintf(),
  * g_snprintf(), g_vprintf(), g_vfprintf(), g_vsprintf() and g_vsnprintf()
- * are declared in the header <filename>gprintf.h</filename> which is
- * <emphasis>not</emphasis> included in <filename>glib.h</filename>
- * (otherwise using <filename>glib.h</filename> would drag in
- * <filename>stdio.h</filename>), so you'll have to explicitly include
- * <literal>&lt;glib/gprintf.h&gt;</literal> in order to use the GLib
+ * are declared in the header `gprintf.h` which is not included in `glib.h`
+ * (otherwise using `glib.h` would drag in `stdio.h`), so you'll have to
+ * explicitly include `&lt;glib/gprintf.h&gt;` in order to use the GLib
  * printf() functions.
  *
- * <para id="string-precision">While you may use the printf() functions
- * to format UTF-8 strings, notice that the precision of a
- * <literal>&percnt;Ns</literal> parameter is interpreted as the
- * number of <emphasis>bytes</emphasis>, not <emphasis>characters</emphasis>
- * to print. On top of that, the GNU libc implementation of the printf()
- * functions has the "feature" that it checks that the string given for
- * the <literal>&percnt;Ns</literal> parameter consists of a whole number
- * of characters in the current encoding. So, unless you are sure you are
- * always going to be in an UTF-8 locale or your know your text is restricted
- * to ASCII, avoid using <literal>&percnt;Ns</literal>. If your intention is
- * to format strings for a certain number of columns, then
- * <literal>&percnt;Ns</literal> is not a correct solution anyway, since it
- * fails to take wide characters (see g_unichar_iswide()) into account.
- * </para>
+ * ## String precision pitfalls # {#string-precision}
+ *
+ * While you may use the printf() functions to format UTF-8 strings,
+ * notice that the precision of a &percnt;Ns parameter is interpreted
+ * as the number of bytes, not characters to print. On top of that,
+ * the GNU libc implementation of the printf() functions has the
+ * "feature" that it checks that the string given for the &percnt;Ns
+ * parameter consists of a whole number of characters in the current
+ * encoding. So, unless you are sure you are always going to be in an
+ * UTF-8 locale or your know your text is restricted to ASCII, avoid
+ * using &percnt;Ns. If your intention is to format strings for a
+ * certain number of columns, then &percnt;Ns is not a correct solution
+ * anyway, since it fails to take wide characters (see g_unichar_iswide())
+ * into account.
  */
 
 
@@ -7833,30 +7715,22 @@
  * to established concepts found in the other test frameworks (JUnit, NUnit,
  * RUnit), which in turn is based on smalltalk unit testing concepts.
  *
- * <variablelist>
- *   <varlistentry>
- *     <term>Test case</term>
- *     <listitem>Tests (test methods) are grouped together with their
- *       fixture into test cases.</listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>Fixture</term>
- *     <listitem>A test fixture consists of fixture data and setup and
- *       teardown methods to establish the environment for the test
- *       functions. We use fresh fixtures, i.e. fixtures are newly set
- *       up and torn down around each test invocation to avoid dependencies
- *       between tests.</listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>Test suite</term>
- *     <listitem>Test cases can be grouped into test suites, to allow
- *       subsets of the available tests to be run. Test suites can be
- *       grouped into other test suites as well.</listitem>
- *   </varlistentry>
- * </variablelist>
+ * - Test case: Tests (test methods) are grouped together with their
+ *   fixture into test cases.
+ *
+ * - Fixture: A test fixture consists of fixture data and setup and
+ *   teardown methods to establish the environment for the test
+ *   functions. We use fresh fixtures, i.e. fixtures are newly set
+ *   up and torn down around each test invocation to avoid dependencies
+ *   between tests.
+ *
+ * - Test suite: Test cases can be grouped into test suites, to allow
+ *   subsets of the available tests to be run. Test suites can be
+ *   grouped into other test suites as well.
+ *
  * The API is designed to handle creation and registration of test suites
  * and test cases implicitly. A simple call like
- * |[
+ * |[<!-- language="C" -->
  *   g_test_add_func ("/misc/assertions", test_assertions);
  * ]|
  * creates a test suite called "misc" with a single test case named
@@ -7954,54 +7828,46 @@
  * Originally, UNIX did not have threads, and therefore some traditional
  * UNIX APIs are problematic in threaded programs. Some notable examples
  * are
- * <itemizedlist>
- *   <listitem>
- *     C library functions that return data in statically allocated
- *     buffers, such as strtok() or strerror(). For many of these,
- *     there are thread-safe variants with a _r suffix, or you can
- *     look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
- *   </listitem>
- *   <listitem>
- *     setenv() and unsetenv() manipulate the process environment in
- *     a not thread-safe way, and may interfere with getenv() calls
- *     in other threads. Note that getenv() calls may be
- *     <quote>hidden</quote> behind other APIs. For example, GNU gettext()
- *     calls getenv() under the covers. In general, it is best to treat
- *     the environment as readonly. If you absolutely have to modify the
- *     environment, do it early in main(), when no other threads are around yet.
- *   </listitem>
- *   <listitem>
- *     setlocale() changes the locale for the entire process, affecting
- *     all threads. Temporary changes to the locale are often made to
- *     change the behavior of string scanning or formatting functions
- *     like scanf() or printf(). GLib offers a number of string APIs
- *     (like g_ascii_formatd() or g_ascii_strtod()) that can often be
- *     used as an alternative. Or you can use the uselocale() function
- *     to change the locale only for the current thread.
- *   </listitem>
- *   <listitem>
- *     fork() only takes the calling thread into the child's copy of the
- *     process image.  If other threads were executing in critical
- *     sections they could have left mutexes locked which could easily
- *     cause deadlocks in the new child.  For this reason, you should
- *     call exit() or exec() as soon as possible in the child and only
- *     make signal-safe library calls before that.
- *   </listitem>
- *   <listitem>
- *     daemon() uses fork() in a way contrary to what is described
- *     above.  It should not be used with GLib programs.
- *   </listitem>
- * </itemizedlist>
+ *
+ * - C library functions that return data in statically allocated
+ *   buffers, such as strtok() or strerror(). For many of these,
+ *   there are thread-safe variants with a _r suffix, or you can
+ *   look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
+ *
+ * - setenv() and unsetenv() manipulate the process environment in
+ *   a not thread-safe way, and may interfere with getenv() calls
+ *   in other threads. Note that getenv() calls may be hidden behind
+ *   other APIs. For example, GNU gettext() calls getenv() under the
+ *   covers. In general, it is best to treat the environment as readonly.
+ *   If you absolutely have to modify the environment, do it early in
+ *   main(), when no other threads are around yet.
+ *
+ * - setlocale() changes the locale for the entire process, affecting
+ *   all threads. Temporary changes to the locale are often made to
+ *   change the behavior of string scanning or formatting functions
+ *   like scanf() or printf(). GLib offers a number of string APIs
+ *   (like g_ascii_formatd() or g_ascii_strtod()) that can often be
+ *   used as an alternative. Or you can use the uselocale() function
+ *   to change the locale only for the current thread.
+ *
+ * - fork() only takes the calling thread into the child's copy of the
+ *   process image. If other threads were executing in critical
+ *   sections they could have left mutexes locked which could easily
+ *   cause deadlocks in the new child. For this reason, you should
+ *   call exit() or exec() as soon as possible in the child and only
+ *   make signal-safe library calls before that.
+ *
+ * - daemon() uses fork() in a way contrary to what is described
+ *   above. It should not be used with GLib programs.
  *
  * GLib itself is internally completely thread-safe (all global data is
  * automatically locked), but individual data structure instances are
  * not automatically locked for performance reasons. For example,
  * you must coordinate accesses to the same #GHashTable from multiple
  * threads. The two notable exceptions from this rule are #GMainLoop
- * and #GAsyncQueue, which <emphasis>are</emphasis> thread-safe and
- * need no further application-level locking to be accessed from
- * multiple threads. Most refcounting functions such as g_object_ref()
- * are also thread-safe.
+ * and #GAsyncQueue, which are thread-safe and need no further
+ * application-level locking to be accessed from multiple threads.
+ * Most refcounting functions such as g_object_ref() are also thread-safe.
  */
 
 
@@ -8137,7 +8003,7 @@
  * data" to a callback, in the form of a void pointer. From time to time
  * you want to pass an integer instead of a pointer. You could allocate
  * an integer, with something like:
- * |[
+ * |[<!-- language="C" -->
  *   int *ip = g_new (int, 1);
  *   *ip = 42;
  * ]|
@@ -8147,15 +8013,15 @@
  * Pointers are always at least 32 bits in size (on all platforms GLib
  * intends to support). Thus you can store at least 32-bit integer values
  * in a pointer value. Naively, you might try this, but it's incorrect:
- * |[
+ * |[<!-- language="C" -->
  *   gpointer p;
  *   int i;
  *   p = (void*) 42;
  *   i = (int) p;
  * ]|
- * Again, that example was <emphasis>not</emphasis> correct, don't copy it.
+ * Again, that example was not correct, don't copy it.
  * The problem is that on some systems you need to do this:
- * |[
+ * |[<!-- language="C" -->
  *   gpointer p;
  *   int i;
  *   p = (void*) (long) 42;
@@ -8164,11 +8030,10 @@
  * The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
  * to do the right thing on the every platform.
  *
- * <warning><para>You may not store pointers in integers. This is not
- * portable in any way, shape or form. These macros <emphasis>only</emphasis>
- * allow storing integers in pointers, and only preserve 32 bits of the
- * integer; values outside the range of a 32-bit integer will be mangled.
- * </para></warning>
+ * Warning: You may not store pointers in integers. This is not
+ * portable in any way, shape or form. These macros only allow storing
+ * integers in pointers, and only preserve 32 bits of the integer; values
+ * outside the range of a 32-bit integer will be mangled.
  */
 
 
@@ -8206,16 +8071,16 @@
  * @See_also: g_locale_to_utf8(), g_locale_from_utf8()
  *
  * This section describes a number of functions for dealing with
- * Unicode characters and strings.  There are analogues of the
- * traditional <filename>ctype.h</filename> character classification
- * and case conversion functions, UTF-8 analogues of some string utility
- * functions, functions to perform normalization, case conversion and
- * collation on UTF-8 strings and finally functions to convert between
- * the UTF-8, UTF-16 and UCS-4 encodings of Unicode.
+ * Unicode characters and strings. There are analogues of the
+ * traditional `ctype.h` character classification and case conversion
+ * functions, UTF-8 analogues of some string utility functions,
+ * functions to perform normalization, case conversion and collation
+ * on UTF-8 strings and finally functions to convert between the UTF-8,
+ * UTF-16 and UCS-4 encodings of Unicode.
  *
  * The implementations of the Unicode functions in GLib are based
  * on the Unicode Character Data tables, which are available from
- * <ulink url="http://www.unicode.org/">www.unicode.org</ulink>.
+ * [www.unicode.org](http://www.unicode.org/).
  * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1,
  * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1,
  * GLib 2.30 supports Unicode 6.0.
@@ -8252,15 +8117,16 @@
  *
  * These functions provide support for outputting messages.
  *
- * The <function>g_return</function> family of macros (g_return_if_fail(),
- * g_return_val_if_fail(), g_return_if_reached(), g_return_val_if_reached())
- * should only be used for programming errors, a typical use case is
- * checking for invalid parameters at the beginning of a public function.
- * They should not be used if you just mean "if (error) return", they
- * should only be used if you mean "if (bug in program) return".
- * The program behavior is generally considered undefined after one
- * of these checks fails. They are not intended for normal control
- * flow, only to give a perhaps-helpful warning before giving up.
+ * The g_return family of macros (g_return_if_fail(),
+ * g_return_val_if_fail(), g_return_if_reached(),
+ * g_return_val_if_reached()) should only be used for programming
+ * errors, a typical use case is checking for invalid parameters at
+ * the beginning of a public function. They should not be used if
+ * you just mean "if (error) return", they should only be used if
+ * you mean "if (bug in program) return". The program behavior is
+ * generally considered undefined after one of these checks fails.
+ * They are not intended for normal control flow, only to give a
+ * perhaps-helpful warning before giving up.
  */
 
 
@@ -8322,44 +8188,44 @@
  * See your C library manual for more details about access().
  *
  * Returns: zero if the pathname refers to an existing file system
- * object that has all the tested permissions, or -1 otherwise or on
- * error.
+ *     object that has all the tested permissions, or -1 otherwise
+ *     or on error.
  * Since: 2.8
  */
 
 
 /**
  * g_array_append_val:
- * @a: a #GArray.
- * @v: the value to append to the #GArray.
+ * @a: a #GArray
+ * @v: the value to append to the #GArray
  *
  * Adds the value on to the end of the array. The array will grow in
  * size automatically if necessary.
  *
- * <note><para>g_array_append_val() is a macro which uses a reference
- * to the value parameter @v. This means that you cannot use it with
- * literal values such as "27". You must use variables.</para></note>
+ * g_array_append_val() is a macro which uses a reference to the value
+ * parameter @v. This means that you cannot use it with literal values
+ * such as "27". You must use variables.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_append_vals:
- * @array: a #GArray.
- * @data: a pointer to the elements to append to the end of the array.
- * @len: the number of elements to append.
+ * @array: a #GArray
+ * @data: a pointer to the elements to append to the end of the array
+ * @len: the number of elements to append
  *
  * Adds @len elements onto the end of the array.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_free:
- * @array: a #GArray.
- * @free_segment: if %TRUE the actual element data is freed as well.
+ * @array: a #GArray
+ * @free_segment: if %TRUE the actual element data is freed as well
  *
  * Frees the memory allocated for the #GArray. If @free_segment is
  * %TRUE it frees the memory block holding the elements as well and
@@ -8369,95 +8235,94 @@
  * is greater than one, the #GArray wrapper is preserved but the size
  * of @array will be set to zero.
  *
- * <note><para>If array elements contain dynamically-allocated memory,
- * they should be freed separately.</para></note>
+ * If array elements contain dynamically-allocated memory, they should
+ * be freed separately.
  *
  * Returns: the element data if @free_segment is %FALSE, otherwise
- *          %NULL.  The element data should be freed using g_free().
+ *     %NULL. The element data should be freed using g_free().
  */
 
 
 /**
  * g_array_get_element_size:
- * @array: A #GArray.
+ * @array: A #GArray
  *
  * Gets the size of the elements in @array.
  *
- * Returns: Size of each element, in bytes.
+ * Returns: Size of each element, in bytes
  * Since: 2.22
  */
 
 
 /**
  * g_array_index:
- * @a: a #GArray.
- * @t: the type of the elements.
- * @i: the index of the element to return.
+ * @a: a #GArray
+ * @t: the type of the elements
+ * @i: the index of the element to return
  *
  * Returns the element of a #GArray at the given index. The return
  * value is cast to the given type.
  *
- * <example>
- *  <title>Getting a pointer to an element in a #GArray</title>
- *  <programlisting>
+ * This example gets a pointer to an element in a #GArray:
+ * |[<!-- language="C" -->
  *   EDayViewEvent *event;
- *   /<!-- -->* This gets a pointer to the 4th element
- *      in the array of EDayViewEvent structs. *<!-- -->/
- *   event = &amp;g_array_index (events, EDayViewEvent, 3);
- *  </programlisting>
- * </example>
+ *   /&ast; This gets a pointer to the 4th element
+ *    &ast; in the array of EDayViewEvent structs.
+ *    &ast;/
+ *   event = &g_array_index (events, EDayViewEvent, 3);
+ * ]|
  *
- * Returns: the element of the #GArray at the index given by @i.
+ * Returns: the element of the #GArray at the index given by @i
  */
 
 
 /**
  * g_array_insert_val:
- * @a: a #GArray.
- * @i: the index to place the element at.
- * @v: the value to insert into the array.
+ * @a: a #GArray
+ * @i: the index to place the element at
+ * @v: the value to insert into the array
  *
  * Inserts an element into an array at the given index.
  *
- * <note><para>g_array_insert_val() is a macro which uses a reference
- * to the value parameter @v. This means that you cannot use it with
- * literal values such as "27". You must use variables.</para></note>
+ * g_array_insert_val() is a macro which uses a reference to the value
+ * parameter @v. This means that you cannot use it with literal values
+ * such as "27". You must use variables.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_insert_vals:
- * @array: a #GArray.
- * @index_: the index to place the elements at.
- * @data: a pointer to the elements to insert.
- * @len: the number of elements to insert.
+ * @array: a #GArray
+ * @index_: the index to place the elements at
+ * @data: a pointer to the elements to insert
+ * @len: the number of elements to insert
  *
  * Inserts @len elements into a #GArray at the given index.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_new:
  * @zero_terminated: %TRUE if the array should have an extra element at
- *                   the end which is set to 0.
+ *     the end which is set to 0
  * @clear_: %TRUE if #GArray elements should be automatically cleared
- *          to 0 when they are allocated.
- * @element_size: the size of each element in bytes.
+ *     to 0 when they are allocated
+ * @element_size: the size of each element in bytes
  *
  * Creates a new #GArray with a reference count of 1.
  *
- * Returns: the new #GArray.
+ * Returns: the new #GArray
  */
 
 
 /**
  * g_array_prepend_val:
- * @a: a #GArray.
- * @v: the value to prepend to the #GArray.
+ * @a: a #GArray
+ * @v: the value to prepend to the #GArray
  *
  * Adds the value on to the start of the array. The array will grow in
  * size automatically if necessary.
@@ -8466,20 +8331,19 @@
  * existing elements in the array have to be moved to make space for
  * the new element.
  *
- * <note><para>g_array_prepend_val() is a macro which uses a reference
- * to the value parameter @v. This means that you cannot use it with
- * literal values such as "27". You must use variables.</para></note>
+ * g_array_prepend_val() is a macro which uses a reference to the value
+ * parameter @v. This means that you cannot use it with literal values
+ * such as "27". You must use variables.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_prepend_vals:
- * @array: a #GArray.
- * @data: a pointer to the elements to prepend to the start of the
- *        array.
- * @len: the number of elements to prepend.
+ * @array: a #GArray
+ * @data: a pointer to the elements to prepend to the start of the array
+ * @len: the number of elements to prepend
  *
  * Adds @len elements onto the start of the array.
  *
@@ -8487,58 +8351,58 @@
  * existing elements in the array have to be moved to make space for
  * the new elements.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_ref:
- * @array: A #GArray.
+ * @array: A #GArray
  *
- * Atomically increments the reference count of @array by one. This
- * function is MT-safe and may be called from any thread.
+ * Atomically increments the reference count of @array by one.
+ * This function is MT-safe and may be called from any thread.
  *
- * Returns: The passed in #GArray.
+ * Returns: The passed in #GArray
  * Since: 2.22
  */
 
 
 /**
  * g_array_remove_index:
- * @array: a #GArray.
- * @index_: the index of the element to remove.
+ * @array: a #GArray
+ * @index_: the index of the element to remove
  *
  * Removes the element at the given index from a #GArray. The following
  * elements are moved down one place.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_remove_index_fast:
- * @array: a @GArray.
- * @index_: the index of the element to remove.
+ * @array: a @GArray
+ * @index_: the index of the element to remove
  *
  * Removes the element at the given index from a #GArray. The last
  * element in the array is used to fill in the space, so this function
  * does not preserve the order of the #GArray. But it is faster than
  * g_array_remove_index().
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_remove_range:
- * @array: a @GArray.
- * @index_: the index of the first element to remove.
- * @length: the number of elements to remove.
+ * @array: a @GArray
+ * @index_: the index of the first element to remove
+ * @length: the number of elements to remove
  *
  * Removes the given number of elements starting at the given index
  * from a #GArray.  The following elements are moved to close the gap.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  * Since: 2.4
  */
 
@@ -8564,38 +8428,38 @@
 
 /**
  * g_array_set_size:
- * @array: a #GArray.
- * @length: the new size of the #GArray.
+ * @array: a #GArray
+ * @length: the new size of the #GArray
  *
  * Sets the size of the array, expanding it if necessary. If the array
  * was created with @clear_ set to %TRUE, the new elements are set to 0.
  *
- * Returns: the #GArray.
+ * Returns: the #GArray
  */
 
 
 /**
  * g_array_sized_new:
  * @zero_terminated: %TRUE if the array should have an extra element at
- *                   the end with all bits cleared.
+ *     the end with all bits cleared
  * @clear_: %TRUE if all bits in the array should be cleared to 0 on
- *          allocation.
- * @element_size: size of each element in the array.
- * @reserved_size: number of elements preallocated.
+ *     allocation
+ * @element_size: size of each element in the array
+ * @reserved_size: number of elements preallocated
  *
  * Creates a new #GArray with @reserved_size elements preallocated and
  * a reference count of 1. This avoids frequent reallocation, if you
  * are going to add many elements to the array. Note however that the
  * size of the array is still 0.
  *
- * Returns: the new #GArray.
+ * Returns: the new #GArray
  */
 
 
 /**
  * g_array_sort:
- * @array: a #GArray.
- * @compare_func: comparison function.
+ * @array: a #GArray
+ * @compare_func: comparison function
  *
  * Sorts a #GArray using @compare_func which should be a qsort()-style
  * comparison function (returns less than zero for first arg is less
@@ -8608,9 +8472,9 @@
 
 /**
  * g_array_sort_with_data:
- * @array: a #GArray.
- * @compare_func: comparison function.
- * @user_data: data to pass to @compare_func.
+ * @array: a #GArray
+ * @compare_func: comparison function
+ * @user_data: data to pass to @compare_func
  *
  * Like g_array_sort(), but the comparison function receives an extra
  * user data argument.
@@ -8625,7 +8489,7 @@
 
 /**
  * g_array_unref:
- * @array: A #GArray.
+ * @array: A #GArray
  *
  * Atomically decrements the reference count of @array by one. If the
  * reference count drops to 0, all memory allocated by the array is
@@ -8638,15 +8502,14 @@
 
 /**
  * g_ascii_digit_value:
- * @c: an ASCII character.
+ * @c: an ASCII character
  *
- * Determines the numeric value of a character as a decimal
- * digit. Differs from g_unichar_digit_value() because it takes
- * a char, so there's no worry about sign extension if characters
- * are signed.
+ * Determines the numeric value of a character as a decimal digit.
+ * Differs from g_unichar_digit_value() because it takes a char, so
+ * there's no worry about sign extension if characters are signed.
  *
- * Returns: If @c is a decimal digit (according to
- * g_ascii_isdigit()), its numeric value. Otherwise, -1.
+ * Returns: If @c is a decimal digit (according to g_ascii_isdigit()),
+ *    its numeric value. Otherwise, -1.
  */
 
 
@@ -8698,9 +8561,9 @@
  * Unlike the standard C library isalnum() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII alphanumeric character
  */
@@ -8715,9 +8578,9 @@
  * Unlike the standard C library isalpha() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII alphabetic character
  */
@@ -8732,9 +8595,9 @@
  * Unlike the standard C library iscntrl() function, this only
  * recognizes standard ASCII control characters and ignores the
  * locale, returning %FALSE for all non-ASCII characters. Also,
- * unlike the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * unlike the standard library function, this takes a char, not
+ * an int, so don't call it on %EOF, but no need to cast to #guchar
+ * before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII control character.
  */
@@ -8747,9 +8610,8 @@
  * Determines whether a character is digit (0-9).
  *
  * Unlike the standard C library isdigit() function, this takes
- * a <type>char</type>, not an <type>int</type>, so don't call it
- * on <literal>EOF</literal>, but no need to cast to #guchar before passing a possibly
- * non-ASCII character in.
+ * a char, not an int, so don't call it  on %EOF, but no need to
+ * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII digit.
  */
@@ -8764,9 +8626,9 @@
  * Unlike the standard C library isgraph() function, this only
  * recognizes standard ASCII characters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
- * to cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII printing character other than space.
  */
@@ -8781,10 +8643,9 @@
  * Unlike the standard C library islower() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
- * to worry about casting to #guchar before passing a possibly
- * non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to worry about casting
+ * to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII lower case letter
  */
@@ -8799,9 +8660,9 @@
  * Unlike the standard C library isprint() function, this only
  * recognizes standard ASCII characters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need
- * to cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII printing character.
  */
@@ -8816,9 +8677,9 @@
  * Unlike the standard C library ispunct() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII punctuation character.
  */
@@ -8833,9 +8694,9 @@
  * Unlike the standard C library isspace() function, this only
  * recognizes standard ASCII white-space and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * cast to #guchar before passing a possibly non-ASCII character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to cast to #guchar before
+ * passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII white-space character
  */
@@ -8850,10 +8711,9 @@
  * Unlike the standard C library isupper() function, this only
  * recognizes standard ASCII letters and ignores the locale,
  * returning %FALSE for all non-ASCII characters. Also, unlike
- * the standard library function, this takes a <type>char</type>,
- * not an <type>int</type>, so don't call it on <literal>EOF</literal>, but no need to
- * worry about casting to #guchar before passing a possibly non-ASCII
- * character in.
+ * the standard library function, this takes a char, not an int,
+ * so don't call it on %EOF, but no need to worry about casting
+ * to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII upper case letter
  */
@@ -8866,9 +8726,8 @@
  * Determines whether a character is a hexadecimal-digit character.
  *
  * Unlike the standard C library isxdigit() function, this takes
- * a <type>char</type>, not an <type>int</type>, so don't call it
- * on <literal>EOF</literal>, but no need to cast to #guchar before passing a
- * possibly non-ASCII character in.
+ * a char, not an int, so don't call it on %EOF, but no need to
+ * cast to #guchar before passing a possibly non-ASCII character in.
  *
  * Returns: %TRUE if @c is an ASCII hexadecimal-digit character.
  */
@@ -8876,8 +8735,8 @@
 
 /**
  * g_ascii_strcasecmp:
- * @s1: string to compare with @s2.
- * @s2: string to compare with @s1.
+ * @s1: string to compare with @s2
+ * @s2: string to compare with @s1
  *
  * Compare two strings, ignoring the case of ASCII characters.
  *
@@ -8896,30 +8755,29 @@
  * Both @s1 and @s2 must be non-%NULL.
  *
  * Returns: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *   or a positive value if @s1 &gt; @s2.
+ *     or a positive value if @s1 &gt; @s2.
  */
 
 
 /**
  * g_ascii_strdown:
- * @str: a string.
- * @len: length of @str in bytes, or -1 if @str is nul-terminated.
+ * @str: a string
+ * @len: length of @str in bytes, or -1 if @str is nul-terminated
  *
  * Converts all upper case ASCII letters to lower case ASCII letters.
  *
  * Returns: a newly-allocated string, with all the upper case
- *               characters in @str converted to lower case, with
- *               semantics that exactly match g_ascii_tolower(). (Note
- *               that this is unlike the old g_strdown(), which modified
- *               the string in place.)
+ *     characters in @str converted to lower case, with semantics that
+ *     exactly match g_ascii_tolower(). (Note that this is unlike the
+ *     old g_strdown(), which modified the string in place.)
  */
 
 
 /**
  * g_ascii_strncasecmp:
- * @s1: string to compare with @s2.
- * @s2: string to compare with @s1.
- * @n: number of characters to compare.
+ * @s1: string to compare with @s2
+ * @s2: string to compare with @s1
+ * @n: number of characters to compare
  *
  * Compare @s1 and @s2, ignoring the case of ASCII characters and any
  * characters after the first @n in each string.
@@ -8933,7 +8791,7 @@
  * corresponding to ASCII letters always represent themselves.
  *
  * Returns: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *   or a positive value if @s1 &gt; @s2.
+ *     or a positive value if @s1 &gt; @s2.
  */
 
 
@@ -8959,12 +8817,12 @@
  * To convert from a #gdouble to a string in a locale-insensitive
  * way, use g_ascii_dtostr().
  *
- * If the correct value would cause overflow, plus or minus <literal>HUGE_VAL</literal>
- * is returned (according to the sign of the value), and <literal>ERANGE</literal> is
- * stored in <literal>errno</literal>. If the correct value would cause underflow,
- * zero is returned and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+ * If the correct value would cause overflow, plus or minus %HUGE_VAL
+ * is returned (according to the sign of the value), and %ERANGE is
+ * stored in %errno. If the correct value would cause underflow,
+ * zero is returned and %ERANGE is stored in %errno.
  *
- * This function resets <literal>errno</literal> before calling strtod() so that
+ * This function resets %errno before calling strtod() so that
  * you can reliably detect overflow and underflow.
  *
  * Returns: the #gdouble value.
@@ -8990,9 +8848,9 @@
  * locale-sensitive system strtoll() function.
  *
  * If the correct value would cause overflow, %G_MAXINT64 or %G_MININT64
- * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+ * is returned, and `ERANGE` is stored in `errno`.
  * If the base is outside the valid range, zero is returned, and
- * <literal>EINVAL</literal> is stored in <literal>errno</literal>. If the
+ * `EINVAL` is stored in `errno`. If the
  * string conversion fails, zero is returned, and @endptr returns @nptr
  * (if @endptr is non-%NULL).
  *
@@ -9020,9 +8878,9 @@
  * locale-sensitive system strtoull() function.
  *
  * If the correct value would cause overflow, %G_MAXUINT64
- * is returned, and <literal>ERANGE</literal> is stored in <literal>errno</literal>.
+ * is returned, and `ERANGE` is stored in `errno`.
  * If the base is outside the valid range, zero is returned, and
- * <literal>EINVAL</literal> is stored in <literal>errno</literal>.
+ * `EINVAL` is stored in `errno`.
  * If the string conversion fails, zero is returned, and @endptr returns
  * @nptr (if @endptr is non-%NULL).
  *
@@ -9033,22 +8891,21 @@
 
 /**
  * g_ascii_strup:
- * @str: a string.
- * @len: length of @str in bytes, or -1 if @str is nul-terminated.
+ * @str: a string
+ * @len: length of @str in bytes, or -1 if @str is nul-terminated
  *
  * Converts all lower case ASCII letters to upper case ASCII letters.
  *
  * Returns: a newly allocated string, with all the lower case
- *               characters in @str converted to upper case, with
- *               semantics that exactly match g_ascii_toupper(). (Note
- *               that this is unlike the old g_strup(), which modified
- *               the string in place.)
+ *     characters in @str converted to upper case, with semantics that
+ *     exactly match g_ascii_toupper(). (Note that this is unlike the
+ *     old g_strup(), which modified the string in place.)
  */
 
 
 /**
  * g_ascii_tolower:
- * @c: any character.
+ * @c: any character
  *
  * Convert a character to ASCII lower case.
  *
@@ -9057,18 +8914,17 @@
  * all non-ASCII characters unchanged, even if they are lower case
  * letters in a particular character set. Also unlike the standard
  * library function, this takes and returns a char, not an int, so
- * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
+ * don't call it on %EOF but no need to worry about casting to #guchar
  * before passing a possibly non-ASCII character in.
  *
- * Returns: the result of converting @c to lower case.
- *               If @c is not an ASCII upper case letter,
- *               @c is returned unchanged.
+ * Returns: the result of converting @c to lower case. If @c is
+ *     not an ASCII upper case letter, @c is returned unchanged.
  */
 
 
 /**
  * g_ascii_toupper:
- * @c: any character.
+ * @c: any character
  *
  * Convert a character to ASCII upper case.
  *
@@ -9077,12 +8933,11 @@
  * all non-ASCII characters unchanged, even if they are upper case
  * letters in a particular character set. Also unlike the standard
  * library function, this takes and returns a char, not an int, so
- * don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
+ * don't call it on %EOF but no need to worry about casting to #guchar
  * before passing a possibly non-ASCII character in.
  *
- * Returns: the result of converting @c to upper case.
- *               If @c is not an ASCII lower case letter,
- *               @c is returned unchanged.
+ * Returns: the result of converting @c to upper case. If @c is not
+ *    an ASCII lower case letter, @c is returned unchanged.
  */
 
 
@@ -9095,8 +8950,8 @@
  * a char, so there's no worry about sign extension if characters
  * are signed.
  *
- * Returns: If @c is a hex digit (according to
- * g_ascii_isxdigit()), its numeric value. Otherwise, -1.
+ * Returns: If @c is a hex digit (according to g_ascii_isxdigit()),
+ *     its numeric value. Otherwise, -1.
  */
 
 
@@ -9109,7 +8964,7 @@
  * an error message is logged and the application is terminated.
  *
  * The macro can be turned off in final releases of code by defining
- * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
+ * `G_DISABLE_ASSERT` when compiling the application.
  */
 
 
@@ -9122,8 +8977,8 @@
  *
  * Debugging macro to compare two floating point numbers.
  *
- * The effect of <literal>g_assert_cmpfloat (n1, op, n2)</literal> is
- * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage
+ * The effect of `g_assert_cmpfloat (n1, op, n2)` is
+ * the same as `g_assert_true (n1 op n2)`. The advantage
  * of this macro is that it can produce a message that includes the
  * actual values of @n1 and @n2.
  *
@@ -9156,8 +9011,8 @@
  *
  * Debugging macro to compare two integers.
  *
- * The effect of <literal>g_assert_cmpint (n1, op, n2)</literal> is
- * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage
+ * The effect of `g_assert_cmpint (n1, op, n2)` is
+ * the same as `g_assert_true (n1 op n2)`. The advantage
  * of this macro is that it can produce a message that includes the
  * actual values of @n1 and @n2.
  *
@@ -9177,12 +9032,12 @@
  * or the testcase marked as failed.
  * The strings are compared using g_strcmp0().
  *
- * The effect of <literal>g_assert_cmpstr (s1, op, s2)</literal> is
- * the same as <literal>g_assert_true (g_strcmp0 (s1, s2) op 0)</literal>.
+ * The effect of `g_assert_cmpstr (s1, op, s2)` is
+ * the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`.
  * The advantage of this macro is that it can produce a message that
  * includes the actual values of @s1 and @s2.
  *
- * |[
+ * |[<!-- language="C" -->
  *   g_assert_cmpstr (mystring, ==, "fubar");
  * ]|
  *
@@ -9199,8 +9054,8 @@
  *
  * Debugging macro to compare two unsigned integers.
  *
- * The effect of <literal>g_assert_cmpuint (n1, op, n2)</literal> is
- * the same as <literal>g_assert_true (n1 op n2)</literal>. The advantage
+ * The effect of `g_assert_cmpuint (n1, op, n2)` is
+ * the same as `g_assert_true (n1 op n2)`. The advantage
  * of this macro is that it can produce a message that includes the
  * actual values of @n1 and @n2.
  *
@@ -9217,15 +9072,15 @@
  * Debugging macro to check that a method has returned
  * the correct #GError.
  *
- * The effect of <literal>g_assert_error (err, dom, c)</literal> is
- * the same as <literal>g_assert_true (err != NULL &amp;&amp; err->domain
- * == dom &amp;&amp; err->code == c)</literal>. The advantage of this
+ * The effect of `g_assert_error (err, dom, c)` is
+ * the same as `g_assert_true (err != NULL &amp;&amp; err->domain
+ * == dom &amp;&amp; err->code == c)`. The advantage of this
  * macro is that it can produce a message that includes the incorrect
  * error message and code.
  *
  * This can only be used to test for a specific error. If you want to
  * test that @err is set, but don't care what it's set to, just use
- * <literal>g_assert (err != NULL)</literal>
+ * `g_assert (err != NULL)`
  *
  * Since: 2.20
  */
@@ -9253,8 +9108,8 @@
  *
  * Debugging macro to check that a #GError is not set.
  *
- * The effect of <literal>g_assert_no_error (err)</literal> is
- * the same as <literal>g_assert_true (err == NULL)</literal>. The advantage
+ * The effect of `g_assert_no_error (err)` is
+ * the same as `g_assert_true (err == NULL)`. The advantage
  * of this macro is that it can produce a message that includes
  * the error message and code.
  *
@@ -9286,7 +9141,7 @@
  * application is terminated.
  *
  * The macro can be turned off in final releases of code by defining
- * <envar>G_DISABLE_ASSERT</envar> when compiling the application.
+ * `G_DISABLE_ASSERT` when compiling the application.
  */
 
 
@@ -9369,8 +9224,8 @@
  * Call g_async_queue_unlock() to drop the lock again.
  *
  * While holding the lock, you can only call the
- * <function>g_async_queue_*_unlocked()</function> functions
- * on @queue. Otherwise, deadlock may occur.
+ * g_async_queue_*_unlocked() functions on @queue. Otherwise,
+ * deadlock may occur.
  */
 
 
@@ -9531,7 +9386,7 @@
  *
  * If you were sorting a list of priority numbers to make sure the
  * lowest priority would be at the top of the queue, you could use:
- * |[
+ * |[<!-- language="C" -->
  *  gint32 id1;
  *  gint32 id2;
  *
@@ -9750,7 +9605,7 @@
  * Atomically adds @val to the value of @atomic.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic += @val; return tmp; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9773,7 +9628,7 @@
  * This call acts as a full compiler and hardware memory barrier.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic &= @val; return tmp; }`.
  *
  * Returns: the value of @atomic before the operation, unsigned
  * Since: 2.30
@@ -9792,7 +9647,7 @@
  * This compare and exchange is done atomically.
  *
  * Think of this operation as an atomic version of
- * <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal>
+ * `{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9808,7 +9663,7 @@
  * Decrements the value of @atomic by 1.
  *
  * Think of this operation as an atomic version of
- * <literal>{ *@atomic -= 1; return (*@atomic == 0); }</literal>
+ * `{ *@atomic -= 1; return (*@atomic == 0); }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9852,8 +9707,7 @@
  *
  * Increments the value of @atomic by 1.
  *
- * Think of this operation as an atomic version of
- * <literal>{ *@atomic += 1; }</literal>
+ * Think of this operation as an atomic version of `{ *@atomic += 1; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9870,7 +9724,7 @@
  * storing the result back in @atomic.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic |= @val; return tmp; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9902,7 +9756,7 @@
  * storing the result back in @atomic.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic ^= @val; return tmp; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9919,7 +9773,7 @@
  * Atomically adds @val to the value of @atomic.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic += @val; return tmp; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9937,7 +9791,7 @@
  * storing the result back in @atomic.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic &= @val; return tmp; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9958,7 +9812,7 @@
  * This compare and exchange is done atomically.
  *
  * Think of this operation as an atomic version of
- * <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal>
+ * `{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -9990,7 +9844,7 @@
  * storing the result back in @atomic.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic |= @val; return tmp; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -10022,7 +9876,7 @@
  * storing the result back in @atomic.
  *
  * Think of this operation as an atomic version of
- * <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal>
+ * `{ tmp = *atomic; *@atomic ^= @val; return tmp; }`.
  *
  * This call acts as a full compiler and hardware memory barrier.
  *
@@ -10143,9 +9997,9 @@
  * @break_lines is typically used when putting base64-encoded data in emails.
  * It breaks the lines at 72 columns instead of putting all of the text on
  * the same line. This avoids problems with long lines in the email system.
- * Note however that it breaks the lines with <literal>LF</literal>
- * characters, not <literal>CR LF</literal> sequences, so the result cannot
- * be passed directly to SMTP or certain other protocols.
+ * Note however that it breaks the lines with `LF` characters, not
+ * `CR LF` sequences, so the result cannot be passed directly to SMTP
+ * or certain other protocols.
  *
  * Returns: The number of bytes of output that was written
  * Since: 2.12
@@ -10980,15 +10834,14 @@
  * Creates a filename from a series of elements using the correct
  * separator for filenames.
  *
- * On Unix, this function behaves identically to <literal>g_build_path
- * (G_DIR_SEPARATOR_S, first_element, ....)</literal>.
+ * On Unix, this function behaves identically to `g_build_path
+ * (G_DIR_SEPARATOR_S, first_element, ....)`.
  *
  * On Windows, it takes into account that either the backslash
- * (<literal>\</literal> or slash (<literal>/</literal>) can be used
- * as separator in filenames, but otherwise behaves as on Unix. When
- * file pathname separators need to be inserted, the one that last
- * previously occurred in the parameters (reading from left to right)
- * is used.
+ * (`\` or slash (`/`) can be used as separator in filenames, but
+ * otherwise behaves as on UNIX. When file pathname separators need
+ * to be inserted, the one that last previously occurred in the
+ * parameters (reading from left to right) is used.
  *
  * No attempt is made to force the resulting filename to be an absolute
  * path. If the first element is a relative path, the result will
@@ -11033,8 +10886,7 @@
  * the same as the number of trailing copies of the separator on
  * the last non-empty element. (Determination of the number of
  * trailing copies is done without stripping leading copies, so
- * if the separator is <literal>ABA</literal>, <literal>ABABA</literal>
- * has 1 trailing copy.)
+ * if the separator is `ABA`, then `ABABA` has 1 trailing copy.)
  *
  * However, if there is only a single non-empty element, and there
  * are no characters in that element not part of the leading or
@@ -11065,21 +10917,21 @@
 
 /**
  * g_byte_array_append:
- * @array: a #GByteArray.
- * @data: the byte data to be added.
- * @len: the number of bytes to add.
+ * @array: a #GByteArray
+ * @data: the byte data to be added
+ * @len: the number of bytes to add
  *
- * Adds the given bytes to the end of the #GByteArray. The array will
- * grow in size automatically if necessary.
+ * Adds the given bytes to the end of the #GByteArray.
+ * The array will grow in size automatically if necessary.
  *
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
  */
 
 
 /**
  * g_byte_array_free:
- * @array: a #GByteArray.
- * @free_segment: if %TRUE the actual byte data is freed as well.
+ * @array: a #GByteArray
+ * @free_segment: if %TRUE the actual byte data is freed as well
  *
  * Frees the memory allocated by the #GByteArray. If @free_segment is
  * %TRUE it frees the actual byte data. If the reference count of
@@ -11105,8 +10957,8 @@
  * together.
  *
  * Since: 2.32
- * Returns: (transfer full): a new immutable #GBytes representing same byte
- *          data that was in the array
+ * Returns: (transfer full): a new immutable #GBytes representing same
+ *     byte data that was in the array
  */
 
 
@@ -11115,7 +10967,7 @@
  *
  * Creates a new #GByteArray with a reference count of 1.
  *
- * Returns: (transfer full): the new #GByteArray.
+ * Returns: (transfer full): the new #GByteArray
  */
 
 
@@ -11134,97 +10986,97 @@
 
 /**
  * g_byte_array_prepend:
- * @array: a #GByteArray.
- * @data: the byte data to be added.
- * @len: the number of bytes to add.
+ * @array: a #GByteArray
+ * @data: the byte data to be added
+ * @len: the number of bytes to add
  *
- * Adds the given data to the start of the #GByteArray. The array will
- * grow in size automatically if necessary.
+ * Adds the given data to the start of the #GByteArray.
+ * The array will grow in size automatically if necessary.
  *
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
  */
 
 
 /**
  * g_byte_array_ref:
- * @array: A #GByteArray.
+ * @array: A #GByteArray
  *
- * Atomically increments the reference count of @array by one. This
- * function is MT-safe and may be called from any thread.
+ * Atomically increments the reference count of @array by one.
+ * This function is thread-safe and may be called from any thread.
  *
- * Returns: The passed in #GByteArray.
+ * Returns: The passed in #GByteArray
  * Since: 2.22
  */
 
 
 /**
  * g_byte_array_remove_index:
- * @array: a #GByteArray.
- * @index_: the index of the byte to remove.
+ * @array: a #GByteArray
+ * @index_: the index of the byte to remove
  *
- * Removes the byte at the given index from a #GByteArray. The
- * following bytes are moved down one place.
+ * Removes the byte at the given index from a #GByteArray.
+ * The following bytes are moved down one place.
  *
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
  */
 
 
 /**
  * g_byte_array_remove_index_fast:
- * @array: a #GByteArray.
- * @index_: the index of the byte to remove.
+ * @array: a #GByteArray
+ * @index_: the index of the byte to remove
  *
  * Removes the byte at the given index from a #GByteArray. The last
  * element in the array is used to fill in the space, so this function
  * does not preserve the order of the #GByteArray. But it is faster
  * than g_byte_array_remove_index().
  *
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
  */
 
 
 /**
  * g_byte_array_remove_range:
- * @array: a @GByteArray.
- * @index_: the index of the first byte to remove.
- * @length: the number of bytes to remove.
+ * @array: a @GByteArray
+ * @index_: the index of the first byte to remove
+ * @length: the number of bytes to remove
  *
  * Removes the given number of bytes starting at the given index from a
  * #GByteArray.  The following elements are moved to close the gap.
  *
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
  * Since: 2.4
  */
 
 
 /**
  * g_byte_array_set_size:
- * @array: a #GByteArray.
- * @length: the new size of the #GByteArray.
+ * @array: a #GByteArray
+ * @length: the new size of the #GByteArray
  *
  * Sets the size of the #GByteArray, expanding it if necessary.
  *
- * Returns: the #GByteArray.
+ * Returns: the #GByteArray
  */
 
 
 /**
  * g_byte_array_sized_new:
- * @reserved_size: number of bytes preallocated.
+ * @reserved_size: number of bytes preallocated
  *
  * Creates a new #GByteArray with @reserved_size bytes preallocated.
  * This avoids frequent reallocation, if you are going to add many
  * bytes to the array. Note however that the size of the array is still
  * 0.
  *
- * Returns: the new #GByteArray.
+ * Returns: the new #GByteArray
  */
 
 
 /**
  * g_byte_array_sort:
- * @array: a #GByteArray.
- * @compare_func: comparison function.
+ * @array: a #GByteArray
+ * @compare_func: comparison function
  *
  * Sorts a byte array, using @compare_func which should be a
  * qsort()-style comparison function (returns less than zero for first
@@ -11241,9 +11093,9 @@
 
 /**
  * g_byte_array_sort_with_data:
- * @array: a #GByteArray.
- * @compare_func: comparison function.
- * @user_data: data to pass to @compare_func.
+ * @array: a #GByteArray
+ * @compare_func: comparison function
+ * @user_data: data to pass to @compare_func
  *
  * Like g_byte_array_sort(), but the comparison function takes an extra
  * user data argument.
@@ -11252,11 +11104,11 @@
 
 /**
  * g_byte_array_unref:
- * @array: A #GByteArray.
+ * @array: A #GByteArray
  *
  * Atomically decrements the reference count of @array by one. If the
  * reference count drops to 0, all memory allocated by the array is
- * released. This function is MT-safe and may be called from any
+ * released. This function is thread-safe and may be called from any
  * thread.
  *
  * Since: 2.22
@@ -11706,8 +11558,7 @@
  * executed.
  *
  * Note that child watch sources can only be used in conjunction with
- * <literal>g_spawn...</literal> when the %G_SPAWN_DO_NOT_REAP_CHILD
- * flag is used.
+ * `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used.
  *
  * Note that on platforms where #GPid must be explicitly closed
  * (see g_spawn_close_pid()) @pid must not be closed while the
@@ -11715,9 +11566,9 @@
  * g_spawn_close_pid() in the callback function for the source.
  *
  * Note further that using g_child_watch_source_new() is not
- * compatible with calling <literal>waitpid</literal> with a
- * nonpositive first argument in the application. Calling waitpid()
- * for individual pids will still work fine.
+ * compatible with calling `waitpid` with a nonpositive first
+ * argument in the application. Calling waitpid() for individual
+ * pids will still work fine.
  *
  * Returns: the newly-created child watch source
  * Since: 2.4
@@ -11740,7 +11591,7 @@
  *
  * See your C library manual for more details about chmod().
  *
- * Returns: zero if the operation succeeded, -1 on error.
+ * Returns: 0 if the operation succeeded, -1 on error
  * Since: 2.8
  */
 
@@ -11981,10 +11832,10 @@
  * passed.
  *
  * The following code shows how to correctly perform a timed wait on a
- * condition variable (extended the example presented in the
+ * condition variable (extending the example presented in the
  * documentation for #GCond):
  *
- * |[
+ * |[<!-- language="C" -->
  * gpointer
  * pop_data_timed (void)
  * {
@@ -11997,12 +11848,12 @@
  *   while (!current_data)
  *     if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
  *       {
- *         // timeout has passed.
+ *         /&ast; timeout has passed. &ast;/
  *         g_mutex_unlock (&data_mutex);
  *         return NULL;
  *       }
  *
- *   // there is data for us
+ *   /&ast; there is data for us &ast;/
  *   data = current_data;
  *   current_data = NULL;
  *
@@ -12028,13 +11879,9 @@
  * g_convert:
  * @str: the string to convert
  * @len: the length of the string, or -1 if the string is
- *                 nul-terminated<footnote id="nul-unsafe">
- *                      <para>
- *                        Note that some encodings may allow nul bytes to
- *                        occur inside strings. In that case, using -1 for
- *                        the @len parameter is unsafe.
- *                      </para>
- *                    </footnote>.
+ *                 nul-terminated (Note that some encodings may allow nul
+ *                 bytes to occur inside strings. In that case, using -1
+ *                 for the @len parameter is unsafe)
  * @to_codeset: name of character set into which to convert @str
  * @from_codeset: character set of @str.
  * @bytes_read: (out): location to store the number of bytes in the
@@ -12052,8 +11899,15 @@
  *
  * Converts a string from one character set to another.
  *
- * Note that you should use g_iconv() for streaming
- * conversions<footnoteref linkend="streaming-state"/>.
+ * Note that you should use g_iconv() for streaming conversions.
+ * Despite the fact that @byes_read can return information about partial
+ * characters, the g_convert_... functions are not generally suitable
+ * for streaming. If the underlying converter maintains internal state,
+ * then this won't be preserved across successive calls to g_convert(),
+ * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+ * this is the GNU C converter for CP1255 which does not emit a base
+ * character until it knows that the next character is not a mark that
+ * could combine with the base character.)
  *
  * Returns: If the conversion was successful, a newly allocated
  *               nul-terminated string, which must be freed with
@@ -12065,7 +11919,9 @@
  * g_convert_with_fallback:
  * @str: the string to convert
  * @len: the length of the string, or -1 if the string is
- *                nul-terminated<footnoteref linkend="nul-unsafe"/>.
+ *                 nul-terminated (Note that some encodings may allow nul
+ *                 bytes to occur inside strings. In that case, using -1
+ *                 for the @len parameter is unsafe)
  * @to_codeset: name of character set into which to convert @str
  * @from_codeset: character set of @str.
  * @fallback: UTF-8 string to use in place of character not
@@ -12091,8 +11947,15 @@
  * to @to_codeset in their iconv() functions,
  * in which case GLib will simply return that approximate conversion.
  *
- * Note that you should use g_iconv() for streaming
- * conversions<footnoteref linkend="streaming-state"/>.
+ * Note that you should use g_iconv() for streaming conversions.
+ * Despite the fact that @byes_read can return information about partial
+ * characters, the g_convert_... functions are not generally suitable
+ * for streaming. If the underlying converter maintains internal state,
+ * then this won't be preserved across successive calls to g_convert(),
+ * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+ * this is the GNU C converter for CP1255 which does not emit a base
+ * character until it knows that the next character is not a mark that
+ * could combine with the base character.)
  *
  * Returns: If the conversion was successful, a newly allocated
  *               nul-terminated string, which must be freed with
@@ -12104,7 +11967,9 @@
  * g_convert_with_iconv:
  * @str: the string to convert
  * @len: the length of the string, or -1 if the string is
- *                 nul-terminated<footnoteref linkend="nul-unsafe"/>.
+ *                 nul-terminated (Note that some encodings may allow nul
+ *                 bytes to occur inside strings. In that case, using -1
+ *                 for the @len parameter is unsafe)
  * @converter: conversion descriptor from g_iconv_open()
  * @bytes_read: location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
@@ -12121,20 +11986,15 @@
  *
  * Converts a string from one character set to another.
  *
- * Note that you should use g_iconv() for streaming
- * conversions<footnote id="streaming-state">
- *  <para>
+ * Note that you should use g_iconv() for streaming conversions.
  * Despite the fact that @byes_read can return information about partial
- * characters, the <literal>g_convert_...</literal> functions
- * are not generally suitable for streaming. If the underlying converter
- * being used maintains internal state, then this won't be preserved
- * across successive calls to g_convert(), g_convert_with_iconv() or
- * g_convert_with_fallback(). (An example of this is the GNU C converter
- * for CP1255 which does not emit a base character until it knows that
- * the next character is not a mark that could combine with the base
- * character.)
- *  </para>
- * </footnote>.
+ * characters, the g_convert_... functions are not generally suitable
+ * for streaming. If the underlying converter maintains internal state,
+ * then this won't be preserved across successive calls to g_convert(),
+ * g_convert_with_iconv() or g_convert_with_fallback(). (An example of
+ * this is the GNU C converter for CP1255 which does not emit a base
+ * character until it knows that the next character is not a mark that
+ * could combine with the base character.)
  *
  * Returns: If the conversion was successful, a newly allocated
  *               nul-terminated string, which must be freed with
@@ -12167,8 +12027,9 @@
  *
  * See your C library manual for more details about creat().
  *
- * Returns: a new file descriptor, or -1 if an error occurred. The
- * return value can be used exactly like the return value from creat().
+ * Returns: a new file descriptor, or -1 if an error occurred.
+ *     The return value can be used exactly like the return value
+ *     from creat().
  * Since: 2.8
  */
 
@@ -12186,8 +12047,8 @@
  * example.
  *
  * You can also make critical warnings fatal at runtime by
- * setting the <envar>G_DEBUG</envar> environment variable (see
- * <ulink url="glib-running.html">Running GLib Applications</ulink>).
+ * setting the `G_DEBUG` environment variable (see
+ * [Running GLib Applications](glib-running.html)).
  *
  * If g_log_default_handler() is used as the log handler function, a new-line
  * character will automatically be appended to @..., and need not be entered
@@ -12862,11 +12723,11 @@
  * @year: year to check
  *
  * Returns %TRUE if the year is a leap year.
- * <footnote><para>For the purposes of this function,
- * leap year is every year divisible by 4 unless that year
- * is divisible by 100. If it is divisible by 100 it would
- * be a leap year only if that year is also divisible
- * by 400.</para></footnote>
+ *
+ * For the purposes of this function, leap year is every year
+ * divisible by 4 unless that year is divisible by 100. If it
+ * is divisible by 100 it would be a leap year only if that year
+ * is also divisible by 400.
  *
  * Returns: %TRUE if the year is a leap year
  */
@@ -12997,14 +12858,14 @@
 /**
  * g_date_set_time_t:
  * @date: a #GDate
- * @timet: <type>time_t</type> value to set
+ * @timet: time_t value to set
  *
  * Sets the value of a date to the date corresponding to a time
  * specified as a time_t. The time to date conversion is done using
  * the user's current timezone.
  *
  * To set the value of a date to the current day, you could write:
- * |[
+ * |[<!-- language="C" -->
  *  g_date_set_time_t (date, time (NULL));
  * ]|
  *
@@ -13293,266 +13154,81 @@
  *
  * The following format specifiers are supported:
  *
- * <variablelist>
- *  <varlistentry><term>
- *    <literal>\%a</literal>:
- *   </term><listitem><simpara>
- *    the abbreviated weekday name according to the current locale
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%A</literal>:
- *   </term><listitem><simpara>
- *    the full weekday name according to the current locale
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%b</literal>:
- *   </term><listitem><simpara>
- *    the abbreviated month name according to the current locale
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%B</literal>:
- *   </term><listitem><simpara>
- *    the full month name according to the current locale
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%c</literal>:
- *   </term><listitem><simpara>
- *    the  preferred  date  and  time  representation  for the current locale
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%C</literal>:
- *   </term><listitem><simpara>
- *    The century number (year/100) as a 2-digit integer (00-99)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%d</literal>:
- *   </term><listitem><simpara>
- *    the day of the month as a decimal number (range 01 to 31)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%e</literal>:
- *   </term><listitem><simpara>
- *    the day of the month as a decimal number (range  1 to 31)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%F</literal>:
- *   </term><listitem><simpara>
- *    equivalent to <literal>\%Y-\%m-\%d</literal> (the ISO 8601 date
- *    format)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%g</literal>:
- *   </term><listitem><simpara>
- *    the last two digits of the ISO 8601 week-based year as a decimal
- *    number (00-99).  This works well with \%V and \%u.
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%G</literal>:
- *   </term><listitem><simpara>
- *    the ISO 8601 week-based year as a decimal number.  This works well
- *    with \%V and \%u.
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%h</literal>:
- *   </term><listitem><simpara>
- *    equivalent to <literal>\%b</literal>
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%H</literal>:
- *   </term><listitem><simpara>
- *    the hour as a decimal number using a 24-hour clock (range 00 to
- *    23)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%I</literal>:
- *   </term><listitem><simpara>
- *    the hour as a decimal number using a 12-hour clock (range 01 to
- *    12)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%j</literal>:
- *   </term><listitem><simpara>
- *    the day of the year as a decimal number (range 001 to 366)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%k</literal>:
- *   </term><listitem><simpara>
- *    the hour (24-hour clock) as a decimal number (range 0 to 23);
- *    single digits are preceded by a blank
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%l</literal>:
- *   </term><listitem><simpara>
- *    the hour (12-hour clock) as a decimal number (range 1 to 12);
- *    single digits are preceded by a blank
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%m</literal>:
- *   </term><listitem><simpara>
- *    the month as a decimal number (range 01 to 12)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%M</literal>:
- *   </term><listitem><simpara>
- *    the minute as a decimal number (range 00 to 59)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%p</literal>:
- *   </term><listitem><simpara>
- *    either "AM" or "PM" according to the given time value, or the
- *    corresponding  strings for the current locale.  Noon is treated as
- *    "PM" and midnight as "AM".
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%P</literal>:
- *   </term><listitem><simpara>
- *    like \%p but lowercase: "am" or "pm" or a corresponding string for
- *    the current locale
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%r</literal>:
- *   </term><listitem><simpara>
- *    the time in a.m. or p.m. notation
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%R</literal>:
- *   </term><listitem><simpara>
- *    the time in 24-hour notation (<literal>\%H:\%M</literal>)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%s</literal>:
- *   </term><listitem><simpara>
- *    the number of seconds since the Epoch, that is, since 1970-01-01
- *    00:00:00 UTC
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%S</literal>:
- *   </term><listitem><simpara>
- *    the second as a decimal number (range 00 to 60)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%t</literal>:
- *   </term><listitem><simpara>
- *    a tab character
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%T</literal>:
- *   </term><listitem><simpara>
- *    the time in 24-hour notation with seconds (<literal>\%H:\%M:\%S</literal>)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%u</literal>:
- *   </term><listitem><simpara>
- *    the ISO 8601 standard day of the week as a decimal, range 1 to 7,
- *    Monday being 1.  This works well with \%G and \%V.
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%V</literal>:
- *   </term><listitem><simpara>
- *    the ISO 8601 standard week number of the current year as a decimal
- *    number, range 01 to 53, where week 1 is the first week that has at
- *    least 4 days in the new year. See g_date_time_get_week_of_year().
- *    This works well with \%G and \%u.
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%w</literal>:
- *   </term><listitem><simpara>
- *    the day of the week as a decimal, range 0 to 6, Sunday being 0.
- *    This is not the ISO 8601 standard format -- use \%u instead.
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%x</literal>:
- *   </term><listitem><simpara>
- *    the preferred date representation for the current locale without
- *    the time
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%X</literal>:
- *   </term><listitem><simpara>
- *    the preferred time representation for the current locale without
- *    the date
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%y</literal>:
- *   </term><listitem><simpara>
- *    the year as a decimal number without the century
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%Y</literal>:
- *   </term><listitem><simpara>
- *    the year as a decimal number including the century
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%z</literal>:
- *   </term><listitem><simpara>
- *    the time zone as an offset from UTC (+hhmm)
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%:z</literal>:
- *   </term><listitem><simpara>
- *    the time zone as an offset from UTC (+hh:mm). This is a gnulib strftime extension. Since: 2.38
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%::z</literal>:
- *   </term><listitem><simpara>
- *    the time zone as an offset from UTC (+hh:mm:ss). This is a gnulib strftime extension. Since: 2.38
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%:::z</literal>:
- *   </term><listitem><simpara>
- *    the time zone as an offset from UTC, with : to necessary precision
- *    (e.g., -04, +05:30). This is a gnulib strftime extension. Since: 2.38
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%Z</literal>:
- *   </term><listitem><simpara>
- *    the time zone or name or abbreviation
- *  </simpara></listitem></varlistentry>
- *  <varlistentry><term>
- *    <literal>\%\%</literal>:
- *   </term><listitem><simpara>
- *    a literal <literal>\%</literal> character
- *  </simpara></listitem></varlistentry>
- * </variablelist>
+ * - \%a: the abbreviated weekday name according to the current locale
+ * - \%A: the full weekday name according to the current locale
+ * - \%b: the abbreviated month name according to the current locale
+ * - \%B: the full month name according to the current locale
+ * - \%c: the  preferred date and time rpresentation for the current locale
+ * - \%C: the century number (year/100) as a 2-digit integer (00-99)
+ * - \%d: the day of the month as a decimal number (range 01 to 31)
+ * - \%e: the day of the month as a decimal number (range  1 to 31)
+ * - \%F: equivalent to `\%Y-\%m-\%d` (the ISO 8601 date format)
+ * - \%g: the last two digits of the ISO 8601 week-based year as a
+ *   decimal number (00-99). This works well with \%V and \%u.
+ * - \%G: the ISO 8601 week-based year as a decimal number. This works
+ *   well with \%V and \%u.
+ * - \%h: equivalent to \%b
+ * - \%H: the hour as a decimal number using a 24-hour clock (range 00 to 23)
+ * - \%I: the hour as a decimal number using a 12-hour clock (range 01 to 12)
+ * - \%j: the day of the year as a decimal number (range 001 to 366)
+ * - \%k: the hour (24-hour clock) as a decimal number (range 0 to 23);
+ *   single digits are preceded by a blank
+ * - \%l: the hour (12-hour clock) as a decimal number (range 1 to 12);
+ *   single digits are preceded by a blank
+ * - \%m: the month as a decimal number (range 01 to 12)
+ * - \%M: the minute as a decimal number (range 00 to 59)
+ * - \%p: either "AM" or "PM" according to the given time value, or the
+ *   corresponding  strings for the current locale.  Noon is treated as
+ *   "PM" and midnight as "AM".
+ * - \%P: like \%p but lowercase: "am" or "pm" or a corresponding string for
+ *   the current locale
+ * - \%r: the time in a.m. or p.m. notation
+ * - \%R: the time in 24-hour notation (\%H:\%M)
+ * - \%s: the number of seconds since the Epoch, that is, since 1970-01-01
+ *   00:00:00 UTC
+ * - \%S: the second as a decimal number (range 00 to 60)
+ * - \%t: a tab character
+ * - \%T: the time in 24-hour notation with seconds (\%H:\%M:\%S)
+ * - \%u: the ISO 8601 standard day of the week as a decimal, range 1 to 7,
+ *    Monday being 1. This works well with \%G and \%V.
+ * - \%V: the ISO 8601 standard week number of the current year as a decimal
+ *   number, range 01 to 53, where week 1 is the first week that has at
+ *   least 4 days in the new year. See g_date_time_get_week_of_year().
+ *   This works well with \%G and \%u.
+ * - \%w: the day of the week as a decimal, range 0 to 6, Sunday being 0.
+ *   This is not the ISO 8601 standard format -- use \%u instead.
+ * - \%x: the preferred date representation for the current locale without
+ *   the time
+ * - \%X: the preferred time representation for the current locale without
+ *   the date
+ * - \%y: the year as a decimal number without the century
+ * - \%Y: the year as a decimal number including the century
+ * - \%z: the time zone as an offset from UTC (+hhmm)
+ * - \%:z: the time zone as an offset from UTC (+hh:mm).
+ *   This is a gnulib strftime() extension. Since: 2.38
+ * - \%::z: the time zone as an offset from UTC (+hh:mm:ss). This is a
+ *   gnulib strftime() extension. Since: 2.38
+ * - \%:::z: the time zone as an offset from UTC, with : to necessary
+ *   precision (e.g., -04, +05:30). This is a gnulib strftime() extension. Since: 2.38
+ * - \%Z: the time zone or name or abbreviation
+ * - \%\%: a literal \% character
  *
  * Some conversion specifications can be modified by preceding the
  * conversion specifier by one or more modifier characters. The
  * following modifiers are supported for many of the numeric
  * conversions:
- * <variablelist>
- *   <varlistentry>
- *     <term>O</term>
- *     <listitem>
- *       Use alternative numeric symbols, if the current locale
- *       supports those.
- *     </listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>_</term>
- *     <listitem>
- *       Pad a numeric result with spaces.
- *       This overrides the default padding for the specifier.
- *     </listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>-</term>
- *     <listitem>
- *       Do not pad a numeric result.
- *       This overrides the default padding for the specifier.
- *     </listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term>0</term>
- *     <listitem>
- *       Pad a numeric result with zeros.
- *       This overrides the default padding for the specifier.
- *     </listitem>
- *   </varlistentry>
- * </variablelist>
+ *
+ * - O: Use alternative numeric symbols, if the current locale supports those.
+ * - _: Pad a numeric result with spaces. This overrides the default padding
+ *   for the specifier.
+ * - -: Do not pad a numeric result. This overrides the default padding
+ *   for the specifier.
+ * - 0: Pad a numeric result with zeros. This overrides the default padding
+ *   for the specifier.
  *
  * Returns: a newly allocated string formatted to the requested format
- *          or %NULL in the case that there was an error.  The string
- *          should be freed with g_free().
+ *     or %NULL in the case that there was an error. The string
+ *     should be freed with g_free().
  * Since: 2.26
  */
 
@@ -14140,12 +13816,11 @@
 
 /**
  * g_date_to_struct_tm:
- * @date: a #GDate to set the <structname>struct tm</structname> from
- * @tm: <structname>struct tm</structname> to fill
+ * @date: a #GDate to set the struct tm from
+ * @tm: struct tm to fill
  *
- * Fills in the date-related bits of a <structname>struct tm</structname>
- * using the @date value. Initializes the non-date parts with something
- * sane but meaningless.
+ * Fills in the date-related bits of a struct tm using the @date value.
+ * Initializes the non-date parts with something sane but meaningless.
  */
 
 
@@ -14238,7 +13913,7 @@
  * @category: a locale category
  *
  * This is a variant of g_dgettext() that allows specifying a locale
- * category instead of always using <envar>LC_MESSAGES</envar>. See g_dgettext() for
+ * category instead of always using `LC_MESSAGES`. See g_dgettext() for
  * more information about how this functions differs from calling
  * dcgettext() directly.
  *
@@ -14286,17 +13961,19 @@
  *
  * This function disables translations if and only if upon its first
  * call all the following conditions hold:
- * <itemizedlist>
- * <listitem>@domain is not %NULL</listitem>
- * <listitem>textdomain() has been called to set a default text domain</listitem>
- * <listitem>there is no translations available for the default text domain
- *           and the current locale</listitem>
- * <listitem>current locale is not "C" or any English locales (those
- *           starting with "en_")</listitem>
- * </itemizedlist>
+ *
+ * - @domain is not %NULL
+ *
+ * - textdomain() has been called to set a default text domain
+ *
+ * - there is no translations available for the default text domain
+ *   and the current locale
+ *
+ * - current locale is not "C" or any English locales (those
+ *   starting with "en_")
  *
  * Note that this behavior may not be desired for example if an application
- * has its untranslated messages in a language other than English.  In those
+ * has its untranslated messages in a language other than English. In those
  * cases the application should call textdomain() after initializing GTK+.
  *
  * Applications should normally not use this function directly,
@@ -14370,8 +14047,7 @@
  * factors.
  *
  * %NULL may also be returned in case of errors. On Unix, you can
- * check <literal>errno</literal> to find out if %NULL was returned
- * because of an error.
+ * check `errno` to find out if %NULL was returned because of an error.
  *
  * On Unix, the '.' and '..' entries are omitted, and the returned
  * name is in the on-disk encoding.
@@ -14401,11 +14077,11 @@
  *
  * Compares two #gpointer arguments and returns %TRUE if they are equal.
  * It can be passed to g_hash_table_new() as the @key_equal_func
- * parameter, when using opaque pointers compared by pointer value as keys
- * in a #GHashTable.
+ * parameter, when using opaque pointers compared by pointer value as
+ * keys in a #GHashTable.
  *
- * This equality function is also appropriate for keys that are integers stored
- * in pointers, such as <literal>GINT_TO_POINTER (n)</literal>.
+ * This equality function is also appropriate for keys that are integers
+ * stored in pointers, such as `GINT_TO_POINTER (n)`.
  *
  * Returns: %TRUE if the two keys match.
  */
@@ -14420,8 +14096,8 @@
  * when using opaque pointers compared by pointer value as keys in a
  * #GHashTable.
  *
- * This hash function is also appropriate for keys that are integers stored
- * in pointers, such as <literal>GINT_TO_POINTER (n)</literal>.
+ * This hash function is also appropriate for keys that are integers
+ * stored in pointers, such as `GINT_TO_POINTER (n)`.
  *
  * Returns: a hash value corresponding to the key.
  */
@@ -14695,8 +14371,8 @@
  * @err_no: an "errno" value
  *
  * Gets a #GFileError constant based on the passed-in @err_no.
- * For example, if you pass in <literal>EEXIST</literal> this function returns
- * #G_FILE_ERROR_EXIST. Unlike <literal>errno</literal> values, you can portably
+ * For example, if you pass in `EEXIST` this function returns
+ * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
  * assume that all #GFileError values will exist.
  *
  * Normally a #GFileError value goes into a #GError returned
@@ -14790,24 +14466,19 @@
  *
  * This write is atomic in the sense that it is first written to a temporary
  * file which is then renamed to the final name. Notes:
- * <itemizedlist>
- * <listitem>
- *    On Unix, if @filename already exists hard links to @filename will break.
- *    Also since the file is recreated, existing permissions, access control
- *    lists, metadata etc. may be lost. If @filename is a symbolic link,
- *    the link itself will be replaced, not the linked file.
- * </listitem>
- * <listitem>
- *   On Windows renaming a file will not remove an existing file with the
+ *
+ * - On UNIX, if @filename already exists hard links to @filename will break.
+ *   Also since the file is recreated, existing permissions, access control
+ *   lists, metadata etc. may be lost. If @filename is a symbolic link,
+ *   the link itself will be replaced, not the linked file.
+ *
+ * - On Windows renaming a file will not remove an existing file with the
  *   new name, so on Windows there is a race condition between the existing
  *   file being removed and the temporary file being renamed.
- * </listitem>
- * <listitem>
- *   On Windows there is no way to remove a file that is open to some
+ *
+ * - On Windows there is no way to remove a file that is open to some
  *   process, or mapped into memory. Thus, this function will fail if
  *   @filename already exists and is open.
- * </listitem>
- * </itemizedlist>
  *
  * If the call was successful, it returns %TRUE. If the call was not successful,
  * it returns %FALSE and sets @error. The error domain is #G_FILE_ERROR.
@@ -14827,11 +14498,11 @@
  * @test: bitfield of #GFileTest flags
  *
  * Returns %TRUE if any of the tests in the bitfield @test are
- * %TRUE. For example, <literal>(G_FILE_TEST_EXISTS |
- * G_FILE_TEST_IS_DIR)</literal> will return %TRUE if the file exists;
- * the check whether it's a directory doesn't matter since the existence
- * test is %TRUE. With the current set of available tests, there's no point
- * passing in more than one test at a time.
+ * %TRUE. For example, `(G_FILE_TEST_EXISTS | G_FILE_TEST_IS_DIR)`
+ * will return %TRUE if the file exists; the check whether it's a
+ * directory doesn't matter since the existence test is %TRUE. With
+ * the current set of available tests, there's no point passing in
+ * more than one test at a time.
  *
  * Apart from %G_FILE_TEST_IS_SYMLINK all tests follow symbolic links,
  * so for a symbolic link to a regular file g_file_test() will return
@@ -14846,7 +14517,7 @@
  * For example, you might think you could use %G_FILE_TEST_IS_SYMLINK
  * to know whether it is safe to write to a file without being
  * tricked into writing into a different location. It doesn't work!
- * |[
+ * |[<!-- language="C" -->
  * /&ast; DON'T DO THIS &ast;/
  *  if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
  *    {
@@ -14866,7 +14537,7 @@
  * %G_FILE_TEST_IS_SYMLINK will always return %FALSE. Testing for
  * %G_FILE_TEST_IS_EXECUTABLE will just check that the file exists and
  * its name indicates that it is executable, checking for well-known
- * extensions and those listed in the <envar>PATHEXT</envar> environment variable.
+ * extensions and those listed in the `PATHEXT` environment variable.
  *
  * Returns: whether a test was %TRUE
  */
@@ -14991,7 +14662,9 @@
  * g_filename_to_utf8:
  * @opsysstring: a string in the encoding for filenames
  * @len: the length of the string, or -1 if the string is
- *                 nul-terminated<footnoteref linkend="nul-unsafe"/>.
+ *                 nul-terminated (Note that some encodings may allow nul
+ *                 bytes to occur inside strings. In that case, using -1
+ *                 for the @len parameter is unsafe)
  * @bytes_read: location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
  *                 Even if the conversion was successful, this may be
@@ -15026,15 +14699,15 @@
  *  
  * On Windows, if @program does not have a file type suffix, tries
  * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in
- * the <envar>PATHEXT</envar> environment variable.
+ * the `PATHEXT` environment variable.
  *
  * On Windows, it looks for the file in the same way as CreateProcess()
  * would. This means first in the directory where the executing
  * program was loaded from, then in the current directory, then in the
  * Windows 32-bit system directory, then in the Windows directory, and
- * finally in the directories in the <envar>PATH</envar> environment
- * variable. If the program is found, the return value contains the
- * full name including the type suffix.
+ * finally in the directories in the `PATH` environment variable. If
+ * the program is found, the return value contains the full name
+ * including the type suffix.
  *
  * Returns: a newly-allocated string with the absolute path, or %NULL
  */
@@ -15043,24 +14716,22 @@
 /**
  * g_fopen:
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @mode: a string describing the mode in which the file should be
- *   opened
+ * @mode: a string describing the mode in which the file should be opened
  *
  * A wrapper for the stdio fopen() function. The fopen() function
  * opens a file and associates a new stream with it.
  *
  * Because file descriptors are specific to the C library on Windows,
- * and a file descriptor is partof the <type>FILE</type> struct, the
- * <type>FILE</type> pointer returned by this function makes sense
- * only to functions in the same C library. Thus if the GLib-using
- * code uses a different C library than GLib does, the
- * <type>FILE</type> pointer returned by this function cannot be
- * passed to C library functions like fprintf() or fread().
+ * and a file descriptor is part of the FILE struct, the FILE* returned
+ * by this function makes sense only to functions in the same C library.
+ * Thus if the GLib-using code uses a different C library than GLib does,
+ * the FILE* returned by this function cannot be passed to C library
+ * functions like fprintf() or fread().
  *
  * See your C library manual for more details about fopen().
  *
- * Returns: A <type>FILE</type> pointer if the file was successfully
- *    opened, or %NULL if an error occurred
+ * Returns: A FILE* if the file was successfully opened, or %NULL if
+ *     an error occurred
  * Since: 2.6
  */
 
@@ -15152,8 +14823,7 @@
 /**
  * g_freopen:
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @mode: a string describing the mode in which the file should be
- *   opened
+ * @mode: a string describing the mode in which the file should be  opened
  * @stream: (allow-none): an existing stream which will be reused, or %NULL
  *
  * A wrapper for the POSIX freopen() function. The freopen() function
@@ -15161,8 +14831,8 @@
  *
  * See your C library manual for more details about freopen().
  *
- * Returns: A <literal>FILE</literal> pointer if the file was successfully
- *    opened, or %NULL if an error occurred.
+ * Returns: A FILE* if the file was successfully opened, or %NULL if
+ *     an error occurred.
  * Since: 2.6
  */
 
@@ -15277,24 +14947,23 @@
  * representation of a filename, see g_filename_display_name().
  *
  * On Unix, the character sets are determined by consulting the
- * environment variables <envar>G_FILENAME_ENCODING</envar> and
- * <envar>G_BROKEN_FILENAMES</envar>. On Windows, the character set
- * used in the GLib API is always UTF-8 and said environment variables
- * have no effect.
- *
- * <envar>G_FILENAME_ENCODING</envar> may be set to a comma-separated list
- * of character set names. The special token "&commat;locale" is taken to
- * mean the character set for the <link linkend="setlocale">current
- * locale</link>. If <envar>G_FILENAME_ENCODING</envar> is not set, but
- * <envar>G_BROKEN_FILENAMES</envar> is, the character set of the current
- * locale is taken as the filename encoding. If neither environment variable
+ * environment variables `G_FILENAME_ENCODING` and `G_BROKEN_FILENAMES`.
+ * On Windows, the character set used in the GLib API is always UTF-8
+ * and said environment variables have no effect.
+ *
+ * `G_FILENAME_ENCODING` may be set to a comma-separated list of
+ * character set names. The special token "&commat;locale" is taken
+ * to  mean the character set for the <link linkend="setlocale">current
+ * locale</link>. If `G_FILENAME_ENCODING` is not set, but
+ * `G_BROKEN_FILENAMES` is, the character set of the current locale
+ * is taken as the filename encoding. If neither environment variable
  * is set, UTF-8 is taken as the filename encoding, but the character
  * set of the current locale is also put in the list of encodings.
  *
  * The returned @charsets belong to GLib and must not be freed.
  *
  * Note that on Unix, regardless of the locale character set or
- * <envar>G_FILENAME_ENCODING</envar> value, the actual file names present
+ * `G_FILENAME_ENCODING` value, the actual file names present
  * on a system might be in any random encoding or just gibberish.
  *
  * Returns: %TRUE if the filename encoding is UTF-8.
@@ -15308,28 +14977,23 @@
  * Gets the current user's home directory.
  *
  * As with most UNIX tools, this function will return the value of the
- * <envar>HOME</envar> environment variable if it is set to an existing
- * absolute path name, falling back to the <filename>passwd</filename>
- * file in the case that it is unset.
- *
- * If the path given in <envar>HOME</envar> is non-absolute, does not
- * exist, or is not a directory, the result is undefined.
- *
- * <note><para>
- *   Before version 2.36 this function would ignore the
- *   <envar>HOME</envar> environment variable, taking the value from the
- *   <filename>passwd</filename> database instead.  This was changed to
- *   increase the compatibility of GLib with other programs (and the XDG
- *   basedir specification) and to increase testability of programs
- *   based on GLib (by making it easier to run them from test
- *   frameworks).
- * </para><para>
- *   If your program has a strong requirement for either the new or the
- *   old behaviour (and if you don't wish to increase your GLib
- *   dependency to ensure that the new behaviour is in effect) then you
- *   should either directly check the <envar>HOME</envar> environment
- *   variable yourself or unset it before calling any functions in GLib.
- * </para></note>
+ * `HOME` environment variable if it is set to an existing absolute path
+ * name, falling back to the `passwd` file in the case that it is unset.
+ *
+ * If the path given in `HOME` is non-absolute, does not exist, or is
+ * not a directory, the result is undefined.
+ *
+ * Before version 2.36 this function would ignore the `HOME` environment
+ * variable, taking the value from the `passwd` database instead. This was
+ * changed to increase the compatibility of GLib with other programs (and
+ * the XDG basedir specification) and to increase testability of programs
+ * based on GLib (by making it easier to run them from test frameworks).
+ *
+ * If your program has a strong requirement for either the new or the
+ * old behaviour (and if you don't wish to increase your GLib
+ * dependency to ensure that the new behaviour is in effect) then you
+ * should either directly check the `HOME` environment variable yourself
+ * or unset it before calling any functions in GLib.
  *
  * Returns: the current user's home directory
  */
@@ -15367,9 +15031,9 @@
  * For example, if LANGUAGE=de:en_US, then the returned list is
  * "de", "en_US", "en", "C".
  *
- * This function consults the environment variables <envar>LANGUAGE</envar>,
- * <envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar> and <envar>LANG</envar>
- * to find the list of locales specified by the user.
+ * This function consults the environment variables `LANGUAGE`, `LC_ALL`,
+ * `LC_MESSAGES` and `LANG` to find the list of locales specified by the
+ * user.
  *
  * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib
  *    that must not be modified or freed.
@@ -15389,7 +15053,7 @@
  * For example, if @locale is "fr_BE", then the returned list
  * is "fr_BE", "fr".
  *
- * If you need the list of variants for the <emphasis>current locale</emphasis>,
+ * If you need the list of variants for the current locale,
  * use g_get_language_names().
  *
  * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly
@@ -15404,12 +15068,12 @@
  *
  * Queries the system monotonic time, if available.
  *
- * On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call
+ * On POSIX systems with clock_gettime() and `CLOCK_MONOTONIC` this call
  * is a very shallow wrapper for that.  Otherwise, we make a best effort
  * that probably involves returning the wall clock time (with at least
  * microsecond accuracy, subject to the limitations of the OS kernel).
  *
- * It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does
+ * It's important to note that POSIX `CLOCK_MONOTONIC` does
  * not count time spent while the machine is suspended.
  *
  * On Windows, "limitations of the OS kernel" is a rather substantial
@@ -15440,24 +15104,25 @@
 /**
  * g_get_prgname:
  *
- * Gets the name of the program. This name should <emphasis>not</emphasis>
- * be localized, contrast with g_get_application_name().
- * (If you are using GDK or GTK+ the program name is set in gdk_init(),
+ * Gets the name of the program. This name should not be localized,
+ * in contrast to g_get_application_name().
+ *
+ * If you are using GDK or GTK+ the program name is set in gdk_init(),
  * which is called by gtk_init(). The program name is found by taking
- * the last component of <literal>argv[0]</literal>.)
+ * the last component of @argv[0].
  *
  * Returns: the name of the program. The returned string belongs
- * to GLib and must not be modified or freed.
+ *     to GLib and must not be modified or freed.
  */
 
 
 /**
  * g_get_real_name:
  *
- * Gets the real name of the user. This usually comes from the user's entry
- * in the <filename>passwd</filename> file. The encoding of the returned
- * string is system-defined. (On Windows, it is, however, always UTF-8.)
- * If the real user name cannot be determined, the string "Unknown" is
+ * Gets the real name of the user. This usually comes from the user's
+ * entry in the `passwd` file. The encoding of the returned string is
+ * system-defined. (On Windows, it is, however, always UTF-8.) If the
+ * real user name cannot be determined, the string "Unknown" is
  * returned.
  *
  * Returns: the user's real name.
@@ -15488,10 +15153,10 @@
  * Returns an ordered list of base directories in which to access
  * system-wide configuration information.
  *
- * On UNIX platforms this is determined using the mechanisms described in
- * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
- * XDG Base Directory Specification</ulink>.
- * In this case the list of directories retrieved will be XDG_CONFIG_DIRS.
+ * On UNIX platforms this is determined using the mechanisms described
+ * in the
+ * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+ * In this case the list of directories retrieved will be `XDG_CONFIG_DIRS`.
  *
  * On Windows is the directory that contains application data for all users.
  * A typical path is C:\Documents and Settings\All Users\Application Data.
@@ -15512,9 +15177,9 @@
  * Returns an ordered list of base directories in which to access
  * system-wide application data.
  *
- * On UNIX platforms this is determined using the mechanisms described in
- * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
- * XDG Base Directory Specification</ulink>
+ * On UNIX platforms this is determined using the mechanisms described
+ * in the
+ * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec)
  * In this case the list of directories retrieved will be XDG_DATA_DIRS.
  *
  * On Windows the first elements in the list are the Application Data
@@ -15550,17 +15215,18 @@
  *
  * Gets the directory to use for temporary files.
  *
- * On UNIX, this is taken from the <envar>TMPDIR</envar> environment
- * variable.  If the variable is not set, <literal>P_tmpdir</literal> is
- * used, as defined by the system C library.  Failing that, a hard-coded
- * default of "/tmp" is returned.
+ * On UNIX, this is taken from the `TMPDIR` environment variable.
+ * If the variable is not set, `P_tmpdir` is
+ * used, as defined by the system C library. Failing that, a
+ * hard-coded default of "/tmp" is returned.
  *
- * On Windows, the <envar>TEMP</envar> environment variable is used,
- * with the root directory of the Windows installation (eg: "C:\") used
+ * On Windows, the `TEMP` environment variable is used, with the
+ * root directory of the Windows installation (eg: "C:\") used
  * as a default.
  *
- * The encoding of the returned string is system-defined. On Windows, it
- * is always UTF-8. The return value is never %NULL or the empty string.
+ * The encoding of the returned string is system-defined. On Windows,
+ * it is always UTF-8. The return value is never %NULL or the empty
+ * string.
  *
  * Returns: the directory to use for temporary files.
  */
@@ -15572,9 +15238,9 @@
  * Returns a base directory in which to store non-essential, cached
  * data specific to particular user.
  *
- * On UNIX platforms this is determined using the mechanisms described in
- * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
- * XDG Base Directory Specification</ulink>.
+ * On UNIX platforms this is determined using the mechanisms described
+ * in the
+ * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
  * In this case the directory retrieved will be XDG_CACHE_HOME.
  *
  * On Windows is the directory that serves as a common repository for
@@ -15594,10 +15260,10 @@
  * Returns a base directory in which to store user-specific application
  * configuration information such as user preferences and settings.
  *
- * On UNIX platforms this is determined using the mechanisms described in
- * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
- * XDG Base Directory Specification</ulink>.
- * In this case the directory retrieved will be XDG_CONFIG_HOME.
+ * On UNIX platforms this is determined using the mechanisms described
+ * in the
+ * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+ * In this case the directory retrieved will be `XDG_CONFIG_HOME`.
  *
  * On Windows this is the folder to use for local (as opposed to
  * roaming) application data. See documentation for
@@ -15616,10 +15282,10 @@
  * Returns a base directory in which to access application data such
  * as icons that is customized for a particular user.
  *
- * On UNIX platforms this is determined using the mechanisms described in
- * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
- * XDG Base Directory Specification</ulink>.
- * In this case the directory retrieved will be XDG_DATA_HOME.
+ * On UNIX platforms this is determined using the mechanisms described
+ * in the
+ * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+ * In this case the directory retrieved will be `XDG_DATA_HOME`.
  *
  * On Windows this is the folder to use for local (as opposed to
  * roaming) application data. See documentation for
@@ -15650,10 +15316,11 @@
  * Returns a directory that is unique to the current user on the local
  * system.
  *
- * On UNIX platforms this is determined using the mechanisms described in
- * the <ulink url="http://www.freedesktop.org/Standards/basedir-spec">
- * XDG Base Directory Specification</ulink>.  This is the directory
- * specified in the <envar>XDG_RUNTIME_DIR</envar> environment variable.
+ * On UNIX platforms this is determined using the mechanisms described
+ * in the
+ * [XDG Base Directory Specification](http://www.freedesktop.org/Standards/basedir-spec).
+ * This is the directory
+ * specified in the `XDG_RUNTIME_DIR` environment variable.
  * In the case that this variable is not set, GLib will issue a warning
  * message to stderr and return the value of g_get_user_cache_dir().
  *
@@ -15673,10 +15340,10 @@
  *
  * Returns the full path of a special directory using its logical id.
  *
- * On Unix this is done using the XDG special user directories.
+ * On UNIX this is done using the XDG special user directories.
  * For compatibility with existing practise, %G_USER_DIRECTORY_DESKTOP
- * falls back to <filename>$HOME/Desktop</filename> when XDG special
- * user directories have not been set up.
+ * falls back to `$HOME/Desktop` when XDG special user directories have
+ * not been set up.
  *
  * Depending on the platform, the user might be able to change the path
  * of the special directory without requiring the session to restart; GLib
@@ -15935,7 +15602,7 @@
  * Initializes a key/value pair iterator and associates it with
  * @hash_table. Modifying the hash table after calling this function
  * invalidates the returned iterator.
- * |[
+ * |[<!-- language="C" -->
  * GHashTableIter iter;
  * gpointer key, value;
  *
@@ -16505,7 +16172,7 @@
  * g_hook_list_init:
  * @hook_list: a #GHookList
  * @hook_size: the size of each element in the #GHookList,
- *     typically <literal>sizeof (GHook)</literal>
+ *     typically `sizeof (GHook)`.
  *
  * Initializes a #GHookList.
  * This must be called before the #GHookList is used.
@@ -16887,9 +16554,9 @@
  * parameter, when using non-%NULL pointers to integers as keys in a
  * #GHashTable.
  *
- * Note that this function acts on pointers to #gint, not on #gint directly:
- * if your hash table's keys are of the form
- * <literal>GINT_TO_POINTER (n)</literal>, use g_direct_equal() instead.
+ * Note that this function acts on pointers to #gint, not on #gint
+ * directly: if your hash table's keys are of the form
+ * `GINT_TO_POINTER (n)`, use g_direct_equal() instead.
  *
  * Returns: %TRUE if the two keys match.
  */
@@ -16903,9 +16570,9 @@
  * It can be passed to g_hash_table_new() as the @hash_func parameter,
  * when using non-%NULL pointers to integer values as keys in a #GHashTable.
  *
- * Note that this function acts on pointers to #gint, not on #gint directly:
- * if your hash table's keys are of the form
- * <literal>GINT_TO_POINTER (n)</literal>, use g_direct_hash() instead.
+ * Note that this function acts on pointers to #gint, not on #gint
+ * directly: if your hash table's keys are of the form
+ * `GINT_TO_POINTER (n)`, use g_direct_hash() instead.
  *
  * Returns: a hash value corresponding to the key.
  */
@@ -16986,9 +16653,9 @@
 
 /**
  * g_io_channel_error_from_errno:
- * @en: an <literal>errno</literal> error number, e.g. <literal>EINVAL</literal>
+ * @en: an `errno` error number, e.g. `EINVAL`
  *
- * Converts an <literal>errno</literal> error number to a #GIOChannelError.
+ * Converts an `errno` error number to a #GIOChannelError.
  *
  * Returns: a #GIOChannelError error number, e.g.
  *      %G_IO_CHANNEL_ERROR_INVAL.
@@ -17347,43 +17014,34 @@
  *
  * The encoding can only be set if one of the following conditions
  * is true:
- * <itemizedlist>
- * <listitem><para>
- *    The channel was just created, and has not been written to or read
- *    from yet.
- * </para></listitem>
- * <listitem><para>
- *    The channel is write-only.
- * </para></listitem>
- * <listitem><para>
- *    The channel is a file, and the file pointer was just
- *    repositioned by a call to g_io_channel_seek_position().
- *    (This flushes all the internal buffers.)
- * </para></listitem>
- * <listitem><para>
- *    The current encoding is %NULL or UTF-8.
- * </para></listitem>
- * <listitem><para>
- *    One of the (new API) read functions has just returned %G_IO_STATUS_EOF
- *    (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
- * </para></listitem>
- * <listitem><para>
- *    One of the functions g_io_channel_read_chars() or
+ *
+ * - The channel was just created, and has not been written to or read from yet.
+ *
+ * - The channel is write-only.
+ *
+ * - The channel is a file, and the file pointer was just repositioned
+ *   by a call to g_io_channel_seek_position(). (This flushes all the
+ *   internal buffers.)
+ *
+ * - The current encoding is %NULL or UTF-8.
+ *
+ * - One of the (new API) read functions has just returned %G_IO_STATUS_EOF
+ *   (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
+ *
+ * -  One of the functions g_io_channel_read_chars() or
  *    g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
  *    %G_IO_STATUS_ERROR. This may be useful in the case of
  *    %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
  *    Returning one of these statuses from g_io_channel_read_line(),
  *    g_io_channel_read_line_string(), or g_io_channel_read_to_end()
- *    does <emphasis>not</emphasis> guarantee that the encoding can
- *    be changed.
- * </para></listitem>
- * </itemizedlist>
+ *    does not guarantee that the encoding can be changed.
+ *
  * Channels which do not meet one of the above conditions cannot call
  * g_io_channel_seek_position() with an offset of %G_SEEK_CUR, and, if
  * they are "seekable", cannot call g_io_channel_write_chars() after
  * calling one of the API "read" functions.
  *
- * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set.
+ * Returns: %G_IO_STATUS_NORMAL if the encoding was successfully set
  */
 
 
@@ -17995,16 +17653,15 @@
  * Looks whether the key file has the key @key in the group
  * @group_name.
  *
- * <note>This function does not follow the rules for #GError strictly;
+ * Note that this function does not follow the rules for #GError strictly;
  * the return value both carries meaning and signals an error.  To use
  * this function, you must pass a #GError pointer in @error, and check
- * whether it is not %NULL to see if an error occurred.</note>
+ * whether it is not %NULL to see if an error occurred.
  *
  * Language bindings should use g_key_file_get_value() to test whether
  * or not a key exists.
  *
- * Returns: %TRUE if @key is a part of @group_name, %FALSE
- * otherwise.
+ * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise
  * Since: 2.6
  */
 
@@ -18453,7 +18110,7 @@
  * to avoid the inefficiency is to use g_list_prepend() and reverse
  * the list with g_list_reverse() when all elements have been added.
  *
- * |[
+ * |[<!-- language="C" -->
  * /&ast; Notice that these are initialized to the empty list. &ast;/
  * GList *string_list = NULL, *number_list = NULL;
  *
@@ -18482,7 +18139,7 @@
  *
  * This function is for example used to move an element in the list.
  * The following example moves an element to the top of the list:
- * |[
+ * |[<!-- language="C" -->
  * list = g_list_remove_link (list, llink);
  * list = g_list_concat (llink, list);
  * ]|
@@ -18497,12 +18154,10 @@
  *
  * Copies a #GList.
  *
- * <note><para>
  * Note that this is a "shallow" copy. If the list elements
  * consist of pointers to data, the pointers are copied but
  * the actual data is not. See g_list_copy_deep() if you need
  * to copy the data as well.
- * </para></note>
  *
  * Returns: the start of the new list that holds the same data as @list
  */
@@ -18525,12 +18180,12 @@
  * if the copy function takes only one argument.
  *
  * For instance, if @list holds a list of GObjects, you can do:
- * |[
+ * |[<!-- language="C" -->
  * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
  * ]|
  *
  * And, to entirely free the new list, you could do:
- * |[
+ * |[<!-- language="C" -->
  * g_list_free_full (another_list, g_object_unref);
  * ]|
  *
@@ -18608,13 +18263,10 @@
  * @list: a #GList
  *
  * Frees all of the memory used by a #GList.
- * The freed elements are returned to the slice allocator
+ * The freed elements are returned to the slice allocator.
  *
- * <note><para>
- * If list elements contain dynamically-allocated memory,
- * you should either use g_list_free_full() or free them manually
- * first.
- * </para></note>
+ * If list elements contain dynamically-allocated memory, you should
+ * either use g_list_free_full() or free them manually first.
  */
 
 
@@ -18698,12 +18350,10 @@
  * Inserts a new element into the list, using the given comparison
  * function to determine its position.
  *
- * <note><para>
  * If you are adding many new elements to a list, and the number of
  * new elements is much larger than the length of the list, use
  * g_list_prepend() to add the new items and sort the list afterwards
- * with g_list_sort()
- * </para></note>
+ * with g_list_sort().
  *
  * Returns: the (possibly changed) start of the #GList
  */
@@ -18722,12 +18372,10 @@
  * Inserts a new element into the list, using the given comparison
  * function to determine its position.
  *
- * <note><para>
  * If you are adding many new elements to a list, and the number of
  * new elements is much larger than the length of the list, use
  * g_list_prepend() to add the new items and sort the list afterwards
- * with g_list_sort()
- * </para></note>
+ * with g_list_sort().
  *
  * Returns: the (possibly changed) start of the #GList
  * Since: 2.10
@@ -18751,11 +18399,9 @@
  *
  * Gets the number of elements in a #GList.
  *
- * <note><para>
  * This function iterates over the whole list to count its elements.
- * Use a <link linkend="glib-Double-ended-Queues">GQueue</link> instead
- * of a GList if you regularly need the number of items.
- * </para></note>
+ * Use a #GQueue instead of a GList if you regularly need the number
+ * of items.
  *
  * Returns: the number of elements in the #GList
  */
@@ -18832,7 +18478,7 @@
  * Note that the return value is the new start of the list,
  * which will have changed, so make sure you store the new value.
  *
- * |[
+ * |[<!-- language="C" -->
  * /&ast; Notice that it is initialized to the empty list. &ast;/
  * GList *list = NULL;
  *
@@ -18840,10 +18486,8 @@
  * list = g_list_prepend (list, "first");
  * ]|
  *
- * <note><para>
- * Do not use this function to prepend a new element to a different element
- * than the start of the list. Use g_list_insert_before() instead.
- * </para></note>
+ * Do not use this function to prepend a new element to a different
+ * element than the start of the list. Use g_list_insert_before() instead.
  *
  * Returns: a pointer to the newly prepended element, which is the new
  *     start of the #GList
@@ -18902,7 +18546,7 @@
  * This function is for example used to move an element in the list
  * (see the example for g_list_concat()) or to remove an element in
  * the list before freeing its data:
- * |[
+ * |[<!-- language="C" -->
  * list = g_list_remove_link (list, llink);
  * free_some_data_that_may_access_the_list_again (llink->data);
  * g_list_free (llink);
@@ -18974,7 +18618,9 @@
  * g_locale_from_utf8:
  * @utf8string: a UTF-8 encoded string
  * @len: the length of the string, or -1 if the string is
- *                 nul-terminated<footnoteref linkend="nul-unsafe"/>.
+ *                 nul-terminated (Note that some encodings may allow nul
+ *                 bytes to occur inside strings. In that case, using -1
+ *                 for the @len parameter is unsafe)
  * @bytes_read: location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
  *                 Even if the conversion was successful, this may be
@@ -19003,7 +18649,9 @@
  * @opsysstring: a string in the encoding of the current locale. On Windows
  *                 this means the system codepage.
  * @len: the length of the string, or -1 if the string is
- *                 nul-terminated<footnoteref linkend="nul-unsafe"/>.
+ *                 nul-terminated (Note that some encodings may allow nul
+ *                 bytes to occur inside strings. In that case, using -1
+ *                 for the @len parameter is unsafe)
  * @bytes_read: location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
  *                 Even if the conversion was successful, this may be
@@ -19063,23 +18711,14 @@
  *
  * The behavior of this log handler can be influenced by a number of
  * environment variables:
- * <variablelist>
- *   <varlistentry>
- *     <term><envar>G_MESSAGES_PREFIXED</envar></term>
- *     <listitem>
- *       A :-separated list of log levels for which messages should
- *       be prefixed by the program name and PID of the aplication.
- *     </listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term><envar>G_MESSAGES_DEBUG</envar></term>
- *     <listitem>
- *       A space-separated list of log domains for which debug and
- *       informational messages are printed. By default these
- *       messages are not printed.
- *     </listitem>
- *   </varlistentry>
- * </variablelist>
+ *
+ * - `G_MESSAGES_PREFIXED`: A :-separated list of log levels for which
+ *   messages should be prefixed by the program name and PID of the
+ *   aplication.
+ *
+ * - `G_MESSAGES_DEBUG`: A space-separated list of log domains for
+ *   which debug and informational messages are printed. By default
+ *   these messages are not printed.
  *
  * stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
  * %G_LOG_LEVEL_WARNING and %G_LOG_LEVEL_MESSAGE. stdout is used for
@@ -19108,8 +18747,8 @@
  * %G_LOG_LEVEL_ERROR is always fatal.
  *
  * You can also make some message levels fatal at runtime by setting
- * the <envar>G_DEBUG</envar> environment variable (see
- * <ulink url="glib-running.html">Running GLib Applications</ulink>).
+ * the `G_DEBUG` environment variable (see
+ * [Running GLib Applications](glib-running.html)).
  *
  * Returns: the old fatal mask
  */
@@ -19162,31 +18801,24 @@
  * you want to set a handler for this log level you must combine it with
  * #G_LOG_FLAG_FATAL.
  *
- * <example>
- * <title>Adding a log handler for all warning messages in the default
- * (application) domain</title>
- * <programlisting>
+ * Here is an example for adding a log handler for all warning messages
+ * in the default domain:
+ * |[<!-- language="C" -->
  * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
  *                    | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
- * </programlisting>
- * </example>
+ * ]|
  *
- * <example>
- * <title>Adding a log handler for all critical messages from GTK+</title>
- * <programlisting>
+ * This example adds a log handler for all critical messages from GTK+:
+ * |[<!-- language="C" -->
  * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
  *                    | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
- * </programlisting>
- * </example>
+ * ]|
  *
- * <example>
- * <title>Adding a log handler for <emphasis>all</emphasis> messages from
- * GLib</title>
- * <programlisting>
+ * This example adds a log handler for all messages from GLib:
+ * |[<!-- language="C" -->
  * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
  *                    | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
- * </programlisting>
- * </example>
+ * ]|
  *
  * Returns: the id of the new handler
  */
@@ -19213,8 +18845,8 @@
 /**
  * g_lstat:
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @buf: a pointer to a <structname>stat</structname> struct, which
- *    will be filled with the file information
+ * @buf: a pointer to a stat struct, which will be filled with the file
+ *     information
  *
  * A wrapper for the POSIX lstat() function. The lstat() function is
  * like stat() except that in the case of symbolic links, it returns
@@ -19224,8 +18856,8 @@
  *
  * See your C library manual for more details about lstat().
  *
- * Returns: 0 if the information was successfully retrieved, -1 if an error
- *    occurred
+ * Returns: 0 if the information was successfully retrieved,
+ *     -1 if an error occurred
  * Since: 2.6
  */
 
@@ -19354,7 +18986,7 @@
  * operations that want to be able to be run in contexts other than
  * the default one should call this method or
  * g_main_context_ref_thread_default() to get a #GMainContext to add
- * their #GSource<!-- -->s to. (Note that even in single-threaded
+ * their #GSources to. (Note that even in single-threaded
  * programs applications may sometimes want to temporarily push a
  * non-default context, so it is not safe to assume that this will
  * always return %NULL if you are running in the default thread.)
@@ -19512,10 +19144,9 @@
  * started in this thread to run under @context and deliver their
  * results to its main loop, rather than running under the global
  * default context in the main thread. Note that calling this function
- * changes the context returned by
- * g_main_context_get_thread_default(), <emphasis>not</emphasis> the
- * one returned by g_main_context_default(), so it does not affect the
- * context used by functions like g_idle_add().
+ * changes the context returned by g_main_context_get_thread_default(),
+ * not the one returned by g_main_context_default(), so it does not affect
+ * the context used by functions like g_idle_add().
  *
  * Normally you would call this function shortly after creating a new
  * thread, passing it a #GMainContext which will be run by a
@@ -19660,7 +19291,7 @@
  * Another related use for this function is when implementing a main
  * loop with a termination condition, computed from multiple threads:
  *
- * |[
+ * |[<!-- language="C" -->
  *   #define NUM_TASKS 10
  *   static volatile gint tasks_remaining = NUM_TASKS;
  *   ...
@@ -19670,7 +19301,7 @@
  * ]|
  *  
  * Then in a thread:
- * |[
+ * |[<!-- language="C" -->
  *   perform_work();
  *
  *   if (g_atomic_int_dec_and_test (&tasks_remaining))
@@ -19703,7 +19334,7 @@
  * This function is useful in a situation like the following:
  * Imagine an extremely simple "garbage collected" system.
  *
- * |[
+ * |[<!-- language="C" -->
  * static GList *free_list;
  *
  * gpointer
@@ -19740,7 +19371,7 @@
  * doesn't work, since the idle function could be called from a
  * recursive callback. This can be fixed by using g_main_depth()
  *
- * |[
+ * |[<!-- language="C" -->
  * gpointer
  * allocate_memory (gsize size)
  * {
@@ -19785,23 +19416,14 @@
  * many things that the user could do. Instead, you can use the
  * following techniques:
  *
- * <orderedlist>
- *  <listitem>
- *   <para>
- *     Use gtk_widget_set_sensitive() or modal dialogs to prevent
- *     the user from interacting with elements while the main
- *     loop is recursing.
- *   </para>
- *  </listitem>
- *  <listitem>
- *   <para>
- *     Avoid main loop recursion in situations where you can't handle
- *     arbitrary  callbacks. Instead, structure your code so that you
- *     simply return to the main loop and then get called again when
- *     there is more work to do.
- *   </para>
- *  </listitem>
- * </orderedlist>
+ * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
+ *    the user from interacting with elements while the main
+ *    loop is recursing.
+ *
+ * 2. Avoid main loop recursion in situations where you can't handle
+ *    arbitrary  callbacks. Instead, structure your code so that you
+ *    simply return to the main loop and then get called again when
+ *    there is more work to do.
  *
  * Returns: The main loop recursion level in the current thread
  */
@@ -20326,7 +19948,7 @@
  * As an example, see the following implementation of a simple
  * parser that counts the number of tags encountered.
  *
- * |[
+ * |[<!-- language="C" -->
  * typedef struct
  * {
  *   gint tag_count;
@@ -20368,7 +19990,7 @@
  * In order to allow this parser to be easily used as a subparser, the
  * following interface is provided:
  *
- * |[
+ * |[<!-- language="C" -->
  * void
  * start_counting (GMarkupParseContext *context)
  * {
@@ -20393,7 +20015,7 @@
  *
  * The subparser would then be used as follows:
  *
- * |[
+ * |[<!-- language="C" -->
  * static void start_element (context, element_name, ...)
  * {
  *   if (strcmp (element_name, "count-these") == 0)
@@ -20449,15 +20071,15 @@
  * output, without having to worry that the strings
  * might themselves contain markup.
  *
- * |[
- * const char *store = "Fortnum &amp; Mason";
+ * |[<!-- language="C" -->
+ * const char *store = "Fortnum & Mason";
  * const char *item = "Tea";
  * char *output;
- * &nbsp;
- * output = g_markup_printf_escaped ("&lt;purchase&gt;"
- *                                   "&lt;store&gt;&percnt;s&lt;/store&gt;"
- *                                   "&lt;item&gt;&percnt;s&lt;/item&gt;"
- *                                   "&lt;/purchase&gt;",
+ *
+ * output = g_markup_printf_escaped ("<purchase>"
+ *                                   "<store>%s</store>"
+ *                                   "<item>%s</item>"
+ *                                   "</purchase>",
  *                                   store, item);
  * ]|
  *
@@ -20516,7 +20138,7 @@
  * @match_info: #GMatchInfo structure
  * @match_num: number of the sub expression
  *
- * Retrieves the text matching the @match_num<!-- -->'th capturing
+ * Retrieves the text matching the @match_num'th capturing
  * parentheses. 0 is the full text of the match, 1 is the first paren
  * set, 2 the second, and so on.
  *
@@ -20618,7 +20240,7 @@
  * @end_pos: (out) (allow-none): pointer to location where to store
  *     the end position, or %NULL
  *
- * Retrieves the position in bytes of the @match_num<!-- -->'th capturing
+ * Retrieves the position in bytes of the @match_num'th capturing
  * parentheses. 0 is the full text of the match, 1 is the first
  * paren set, 2 the second, and so on.
  *
@@ -20730,7 +20352,7 @@
  * There were formerly some restrictions on the pattern for partial matching.
  * The restrictions no longer apply.
  *
- * See <ulink>man:pcrepartial</ulink> for more information on partial matching.
+ * See pcrepartial(3) for more information on partial matching.
  *
  * Returns: %TRUE if the match was partial, %FALSE otherwise
  * Since: 2.14
@@ -20791,8 +20413,8 @@
 /**
  * g_mem_gc_friendly:
  *
- * This variable is %TRUE if the <envar>G_DEBUG</envar> environment variable
- * includes the key <literal>gc-friendly</literal>.
+ * This variable is %TRUE if the `G_DEBUG` environment variable
+ * includes the key `gc-friendly`.
  */
 
 
@@ -20831,13 +20453,17 @@
  * g_mem_set_vtable:
  * @vtable: table of memory allocation routines.
  *
- * Sets the #GMemVTable to use for memory allocation. You can use this to provide
- * custom memory allocation routines. <emphasis>This function must be called
- * before using any other GLib functions.</emphasis> The @vtable only needs to
- * provide malloc(), realloc(), and free() functions; GLib can provide default
- * implementations of the others. The malloc() and realloc() implementations
- * should return %NULL on failure, GLib will handle error-checking for you.
- * @vtable is copied, so need not persist after this function has been called.
+ * Sets the #GMemVTable to use for memory allocation. You can use this
+ * to provide custom memory allocation routines.
+ *
+ * The @vtable only needs to provide malloc(), realloc(), and free()
+ * functions; GLib can provide default implementations of the others.
+ * The malloc() and realloc() implementations should return %NULL on
+ * failure, GLib will handle error-checking for you. @vtable is copied,
+ * so need not persist after this function has been called.
+ *
+ * Note that this function must be called before using any other GLib
+ * functions.
  */
 
 
@@ -21035,7 +20661,7 @@
  * It is not necessary to initialize a mutex that has been
  * statically allocated.
  *
- * |[
+ * |[<!-- language="C" -->
  *   typedef struct {
  *     GMutex m;
  *     ...
@@ -21065,10 +20691,10 @@
  * current thread will block until @mutex is unlocked by the other
  * thread.
  *
- * <note>#GMutex is neither guaranteed to be recursive nor to be
+ * #GMutex is neither guaranteed to be recursive nor to be
  * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
  * already been locked by the same thread results in undefined behaviour
- * (including but not limited to deadlocks).</note>
+ * (including but not limited to deadlocks).
  */
 
 
@@ -21080,11 +20706,10 @@
  * it immediately returns %FALSE. Otherwise it locks @mutex and returns
  * %TRUE.
  *
- * <note>#GMutex is neither guaranteed to be recursive nor to be
+ * #GMutex is neither guaranteed to be recursive nor to be
  * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
  * already been locked by the same thread results in undefined behaviour
  * (including but not limited to deadlocks or arbitrary return values).
- * </note>
  *
  * Returns: %TRUE if @mutex could be locked
  */
@@ -21448,19 +21073,19 @@
 
 /**
  * g_on_error_query:
- * @prg_name: the program name, needed by <command>gdb</command>
- *     for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname()
- *     is called to get the program name (which will work correctly if
- *     gdk_init() or gtk_init() has been called)
+ * @prg_name: the program name, needed by gdb for the "[S]tack trace"
+ *     option. If @prg_name is %NULL, g_get_prgname() is called to get
+ *     the program name (which will work correctly if gdk_init() or
+ *     gtk_init() has been called)
  *
  * Prompts the user with
- * <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>.
+ * `[E]xit, [H]alt, show [S]tack trace or [P]roceed`.
  * This function is intended to be used for debugging use only.
  * The following example shows how it can be used together with
  * the g_log() functions.
  *
- * |[
- * &num;include &lt;glib.h&gt;
+ * |[<!-- language="C" -->
+ * #include <glib.h>
  *
  * static void
  * log_handler (const gchar   *log_domain,
@@ -21482,17 +21107,17 @@
  *                      G_LOG_LEVEL_CRITICAL,
  *                      log_handler,
  *                      NULL);
- *   /&ast; ... &ast;/
+ *   ...
  * ]|
  *
- * If [E]xit is selected, the application terminates with a call
- * to <literal>_exit(0)</literal>.
+ * If "[E]xit" is selected, the application terminates with a call
+ * to _exit(0).
  *
- * If [S]tack trace is selected, g_on_error_stack_trace() is called.
- * This invokes <command>gdb</command>, which attaches to the current
- * process and shows a stack trace. The prompt is then shown again.
+ * If "[S]tack" trace is selected, g_on_error_stack_trace() is called.
+ * This invokes gdb, which attaches to the current process and shows
+ * a stack trace. The prompt is then shown again.
  *
- * If [P]roceed is selected, the function returns.
+ * If "[P]roceed" is selected, the function returns.
  *
  * This function may cause different actions on non-UNIX platforms.
  */
@@ -21500,14 +21125,14 @@
 
 /**
  * g_on_error_stack_trace:
- * @prg_name: the program name, needed by <command>gdb</command>
- *     for the [S]tack trace option.
+ * @prg_name: the program name, needed by gdb for the "[S]tack trace"
+ *     option
  *
- * Invokes <command>gdb</command>, which attaches to the current
- * process and shows a stack trace. Called by g_on_error_query()
- * when the [S]tack trace option is selected. You can get the current
- * process's "program name" with g_get_prgname(), assuming that you
- * have called gtk_init() or gdk_init().
+ * Invokes gdb, which attaches to the current process and shows a
+ * stack trace. Called by g_on_error_query() when the "[S]tack trace"
+ * option is selected. You can get the current process's program name
+ * with g_get_prgname(), assuming that you have called gtk_init() or
+ * gdk_init().
  *
  * This function may cause different actions on non-UNIX platforms.
  */
@@ -21534,7 +21159,7 @@
  * Calling g_once() recursively on the same #GOnce struct in
  * @func will lead to a deadlock.
  *
- * |[
+ * |[<!-- language="C" -->
  *   gpointer
  *   get_debug_flags (void)
  *   {
@@ -21564,17 +21189,17 @@
  * blocked until initialization completed. To be used in constructs
  * like this:
  *
- * |[
+ * |[<!-- language="C" -->
  *   static gsize initialization_value = 0;
  *
- *   if (g_once_init_enter (&amp;initialization_value))
+ *   if (g_once_init_enter (&initialization_value))
  *     {
- *       gsize setup_value = 42; /&ast;* initialization code here *&ast;/
+ *       gsize setup_value = 42; /&ast; initialization code here &ast;/
  *
- *       g_once_init_leave (&amp;initialization_value, setup_value);
+ *       g_once_init_leave (&initialization_value, setup_value);
  *     }
  *
- *   /&ast;* use initialization_value here *&ast;/
+ *   /&ast; use initialization_value here &ast;/
  * ]|
  *
  * Returns: %TRUE if the initialization section should be entered,
@@ -21623,8 +21248,9 @@
  *
  * See your C library manual for more details about open().
  *
- * Returns: a new file descriptor, or -1 if an error occurred. The
- * return value can be used exactly like the return value from open().
+ * Returns: a new file descriptor, or -1 if an error occurred.
+ *     The return value can be used exactly like the return value
+ *     from open().
  * Since: 2.6
  */
 
@@ -21647,9 +21273,9 @@
 /**
  * g_option_context_add_main_entries:
  * @context: a #GOptionContext
- * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
+ * @entries: a %NULL-terminated array of #GOptionEntrys
  * @translation_domain: (allow-none): a translation domain to use for translating
- *    the <option>--help</option> output for the options in @entries
+ *    the `--help` output for the options in @entries
  *    with gettext(), or %NULL
  *
  * A convenience function which creates a main group if it doesn't
@@ -21691,12 +21317,12 @@
  * @group: (allow-none): the #GOptionGroup to create help for, or %NULL
  *
  * Returns a formatted, translated help text for the given context.
- * To obtain the text produced by <option>--help</option>, call
- * <literal>g_option_context_get_help (context, TRUE, NULL)</literal>.
- * To obtain the text produced by <option>--help-all</option>, call
- * <literal>g_option_context_get_help (context, FALSE, NULL)</literal>.
+ * To obtain the text produced by `--help`, call
+ * `g_option_context_get_help (context, TRUE, NULL)`.
+ * To obtain the text produced by `--help-all`, call
+ * `g_option_context_get_help (context, FALSE, NULL)`.
  * To obtain the help text for an option group, call
- * <literal>g_option_context_get_help (context, FALSE, group)</literal>.
+ * `g_option_context_get_help (context, FALSE, group)`.
  *
  * Returns: A newly allocated string containing the help text
  * Since: 2.14
@@ -21707,7 +21333,7 @@
  * g_option_context_get_help_enabled:
  * @context: a #GOptionContext
  *
- * Returns whether automatic <option>--help</option> generation
+ * Returns whether automatic `--help` generation
  * is turned on for @context. See g_option_context_set_help_enabled().
  *
  * Returns: %TRUE if automatic help generation is turned on.
@@ -21754,9 +21380,8 @@
 /**
  * g_option_context_new:
  * @parameter_string: (allow-none): a string which is displayed in
- *    the first line of <option>--help</option> output, after the
- *    usage summary
- *    <literal><replaceable>programname</replaceable> [OPTION...]</literal>
+ *    the first line of `--help` output, after the usage summary
+ *    `programname [OPTION...]`
  *
  * Creates a new option context.
  *
@@ -21803,11 +21428,11 @@
  * or some of the options after it start with '-'. In case
  * of an error, @argc and @argv are left unmodified.
  *
- * If automatic <option>--help</option> support is enabled
+ * If automatic `--help` support is enabled
  * (see g_option_context_set_help_enabled()), and the
  * @argv array contains one of the recognized help options,
  * this function will produce help output to stdout and
- * call <literal>exit (0)</literal>.
+ * call `exit (0)`.
  *
  * Note that function depends on the
  * <link linkend="setlocale">current locale</link> for
@@ -21853,12 +21478,11 @@
 /**
  * g_option_context_set_description:
  * @context: a #GOptionContext
- * @description: (allow-none): a string to be shown in <option>--help</option> output
+ * @description: (allow-none): a string to be shown in `--help` output
  *   after the list of options, or %NULL
  *
- * Adds a string to be displayed in <option>--help</option> output
- * after the list of options. This text often includes a bug reporting
- * address.
+ * Adds a string to be displayed in `--help` output after the list
+ * of options. This text often includes a bug reporting address.
  *
  * Note that the summary is translated (see
  * g_option_context_set_translate_func()).
@@ -21870,14 +21494,12 @@
 /**
  * g_option_context_set_help_enabled:
  * @context: a #GOptionContext
- * @help_enabled: %TRUE to enable <option>--help</option>, %FALSE to disable it
+ * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it
  *
- * Enables or disables automatic generation of <option>--help</option>
- * output. By default, g_option_context_parse() recognizes
- * <option>--help</option>, <option>-h</option>,
- * <option>-?</option>, <option>--help-all</option>
- * and <option>--help-</option><replaceable>groupname</replaceable> and creates
- * suitable output to stdout.
+ * Enables or disables automatic generation of `--help` output.
+ * By default, g_option_context_parse() recognizes `--help`, `-h`,
+ * `-?`, `--help-all` and `--help-groupname` and creates suitable
+ * output to stdout.
  *
  * Since: 2.6
  */
@@ -21909,7 +21531,7 @@
  * Sets a #GOptionGroup as main group of the @context.
  * This has the same effect as calling g_option_context_add_group(),
  * the only difference is that the options in the main group are
- * treated differently when generating <option>--help</option> output.
+ * treated differently when generating `--help` output.
  *
  * Since: 2.6
  */
@@ -21918,12 +21540,11 @@
 /**
  * g_option_context_set_summary:
  * @context: a #GOptionContext
- * @summary: (allow-none): a string to be shown in <option>--help</option> output
+ * @summary: (allow-none): a string to be shown in `--help` output
  *  before the list of options, or %NULL
  *
- * Adds a string to be displayed in <option>--help</option> output
- * before the list of options. This is typically a summary of the
- * program functionality.
+ * Adds a string to be displayed in `--help` output before the list
+ * of options. This is typically a summary of the program functionality.
  *
  * Note that the summary is translated (see
  * g_option_context_set_translate_func() and
@@ -21941,8 +21562,8 @@
  * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL
  *
  * Sets the function which is used to translate the contexts
- * user-visible strings, for <option>--help</option> output.
- * If @func is %NULL, strings are not translated.
+ * user-visible strings, for `--help` output. If @func is %NULL,
+ * strings are not translated.
  *
  * Note that option groups have their own translation functions,
  * this function only affects the @parameter_string (see g_option_context_new()),
@@ -21971,7 +21592,7 @@
 /**
  * g_option_group_add_entries:
  * @group: a #GOptionGroup
- * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s
+ * @entries: a %NULL-terminated array of #GOptionEntrys
  *
  * Adds the options specified in @entries to @group.
  *
@@ -21983,8 +21604,8 @@
  * g_option_group_free:
  * @group: a #GOptionGroup
  *
- * Frees a #GOptionGroup. Note that you must <emphasis>not</emphasis>
- * free groups which have been added to a #GOptionContext.
+ * Frees a #GOptionGroup. Note that you must not free groups
+ * which have been added to a #GOptionContext.
  *
  * Since: 2.6
  */
@@ -21993,11 +21614,11 @@
 /**
  * g_option_group_new:
  * @name: the name for the option group, this is used to provide
- *   help for the options in this group with <option>--help-</option>@name
+ *   help for the options in this group with `--help-`@name
  * @description: a description for this group to be shown in
- *   <option>--help</option>. This string is translated using the translation
+ *   `--help`. This string is translated using the translation
  *   domain or translation function of the group
- * @help_description: a description for the <option>--help-</option>@name option.
+ * @help_description: a description for the `--help-`@name option.
  *   This string is translated using the translation domain or translation function
  *   of the group
  * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks,
@@ -22052,10 +21673,9 @@
  * @data: (allow-none): user data to pass to @func, or %NULL
  * @destroy_notify: (allow-none): a function which gets called to free @data, or %NULL
  *
- * Sets the function which is used to translate user-visible
- * strings, for <option>--help</option> output. Different
- * groups can use different #GTranslateFunc<!-- -->s. If @func
- * is %NULL, strings are not translated.
+ * Sets the function which is used to translate user-visible strings,
+ * for `--help` output. Different groups can use different
+ * #GTranslateFuncs. If @func is %NULL, strings are not translated.
  *
  * If you are using gettext(), you only need to set the translation
  * domain, see g_option_group_set_translation_domain().
@@ -22082,19 +21702,19 @@
  * commas, or %NULL.
  * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate
  *     strings with bit flags.
- * @nkeys: the number of #GDebugKey<!-- -->s in the array.
+ * @nkeys: the number of #GDebugKeys in the array.
  *
  * Parses a string containing debugging options
  * into a %guint containing bit flags. This is used
  * within GDK and GTK+ to parse the debug options passed on the
  * command line or through environment variables.
  *
- * If @string is equal to <code>"all"</code>, all flags are set. Any flags
- * specified along with <code>"all"</code> in @string are inverted; thus,
- * <code>"all,foo,bar"</code> or <code>"foo,bar,all"</code> sets all flags
- * except those corresponding to <code>"foo"</code> and <code>"bar"</code>.
+ * If @string is equal to "all", all flags are set. Any flags
+ * specified along with "all" in @string are inverted; thus,
+ * "all,foo,bar" or "foo,bar,all" sets all flags except those
+ * corresponding to "foo" and "bar".
  *
- * If @string is equal to <code>"help"</code>, all the available keys in @keys
+ * If @string is equal to "help", all the available keys in @keys
  * are printed out to standard error.
  *
  * Returns: the combined set of bit flags.
@@ -22179,7 +21799,7 @@
  * g_pattern_match:
  * @pspec: a #GPatternSpec
  * @string_length: the length of @string (in bytes, i.e. strlen(),
- *                 <emphasis>not</emphasis> g_utf8_strlen())
+ *     not g_utf8_strlen())
  * @string: the UTF-8 encoded string to match
  * @string_reversed: (allow-none): the reverse of @string or %NULL
  *
@@ -22197,10 +21817,9 @@
  * constructions thereof in the various calls to g_pattern_match().
  *
  * Note also that the reverse of a UTF-8 encoded string can in general
- * <emphasis>not</emphasis> be obtained by g_strreverse(). This works
- * only if the string doesn't contain any multibyte characters. GLib
- * offers the g_utf8_strreverse() function to reverse UTF-8 encoded
- * strings.
+ * not be obtained by g_strreverse(). This works only if the string
+ * does not contain any multibyte characters. GLib offers the
+ * g_utf8_strreverse() function to reverse UTF-8 encoded strings.
  *
  * Returns: %TRUE if @string matches @pspec
  */
@@ -22331,7 +21950,7 @@
  * file descriptor, but the situation is much more complicated on
  * Windows. If you need to use g_poll() in code that has to run on
  * Windows, the easiest solution is to construct all of your
- * #GPollFD<!-- -->s with g_io_channel_win32_make_pollfd().
+ * #GPollFDs with g_io_channel_win32_make_pollfd().
  *
  * Returns: the number of entries in @fds whose %revents fields
  * were filled in, or 0 if the operation timed out, or -1 on error or
@@ -22346,16 +21965,13 @@
  * @format: printf()-style format string
  * @...: arguments to @format
  *
- * Formats a string according to @format and
- * prefix it to an existing error message.  If
- * @err is %NULL (ie: no error variable) then do
+ * Formats a string according to @format and prefix it to an existing
+ * error message. If @err is %NULL (ie: no error variable) then do
  * nothing.
  *
- * If *@err is %NULL (ie: an error variable is
- * present but there is no error condition) then
- * also do nothing.  Whether or not it makes
- * sense to take advantage of this feature is up
- * to you.
+ * If *@err is %NULL (ie: an error variable is present but there is no
+ * error condition) then also do nothing. Whether or not it makes sense
+ * to take advantage of this feature is up to you.
  *
  * Since: 2.16
  */
@@ -22485,9 +22101,8 @@
  * @format: printf()-style format string
  * @...: arguments to @format
  *
- * If @dest is %NULL, free @src; otherwise,
- * moves @src into *@dest. *@dest must be %NULL.
- * After the move, add a prefix as with
+ * If @dest is %NULL, free @src; otherwise, moves @src into *@dest.
+ * *@dest must be %NULL. After the move, add a prefix as with
  * g_prefix_error().
  *
  * Since: 2.16
@@ -22496,8 +22111,8 @@
 
 /**
  * g_ptr_array_add:
- * @array: a #GPtrArray.
- * @data: the pointer to add.
+ * @array: a #GPtrArray
+ * @data: the pointer to add
  *
  * Adds a pointer to the end of the pointer array. The array will grow
  * in size automatically if necessary.
@@ -22518,8 +22133,8 @@
 
 /**
  * g_ptr_array_free:
- * @array: a #GPtrArray.
- * @free_seg: if %TRUE the actual pointer array is freed as well.
+ * @array: a #GPtrArray
+ * @free_seg: if %TRUE the actual pointer array is freed as well
  *
  * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
  * it frees the memory block holding the elements as well. Pass %FALSE
@@ -22528,34 +22143,33 @@
  * is greater than one, the #GPtrArray wrapper is preserved but the
  * size of @array will be set to zero.
  *
- * <note><para>If array contents point to dynamically-allocated
- * memory, they should be freed separately if @free_seg is %TRUE and no
- * #GDestroyNotify function has been set for @array.</para></note>
+ * If array contents point to dynamically-allocated memory, they should
+ * be freed separately if @free_seg is %TRUE and no #GDestroyNotify
+ * function has been set for @array.
  *
  * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
- *          The pointer array should be freed using g_free().
+ *     The pointer array should be freed using g_free().
  */
 
 
 /**
  * g_ptr_array_index:
- * @array: a #GPtrArray.
- * @index_: the index of the pointer to return.
+ * @array: a #GPtrArray
+ * @index_: the index of the pointer to return
  *
  * Returns the pointer at the given index of the pointer array.
  *
- * <note><para>
- * This does not perform bounds checking on the given @index_, so you are
- * responsible for checking it against the array length.</para></note>
+ * This does not perform bounds checking on the given @index_,
+ * so you are responsible for checking it against the array length.
  *
- * Returns: the pointer at the given index.
+ * Returns: the pointer at the given index
  */
 
 
 /**
  * g_ptr_array_insert:
- * @array: a #GPtrArray.
- * @index_: the index to place the new element at, or -1 to append.
+ * @array: a #GPtrArray
+ * @index_: the index to place the new element at, or -1 to append
  * @data: the pointer to add.
  *
  * Inserts an element into the pointer array at the given index. The
@@ -22570,38 +22184,40 @@
  *
  * Creates a new #GPtrArray with a reference count of 1.
  *
- * Returns: the new #GPtrArray.
+ * Returns: the new #GPtrArray
  */
 
 
 /**
  * g_ptr_array_new_full:
- * @reserved_size: number of pointers preallocated.
- * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL.
+ * @reserved_size: number of pointers preallocated
+ * @element_free_func: (allow-none): A function to free elements with
+ *     destroy @array or %NULL
  *
  * Creates a new #GPtrArray with @reserved_size pointers preallocated
  * and a reference count of 1. This avoids frequent reallocation, if
  * you are going to add many pointers to the array. Note however that
  * the size of the array is still 0. It also set @element_free_func
  * for freeing each element when the array is destroyed either via
- * g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment
- * set to %TRUE or when removing elements.
+ * g_ptr_array_unref(), when g_ptr_array_free() is called with
+ * @free_segment set to %TRUE or when removing elements.
  *
- * Returns: A new #GPtrArray.
+ * Returns: A new #GPtrArray
  * Since: 2.30
  */
 
 
 /**
  * g_ptr_array_new_with_free_func:
- * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL.
+ * @element_free_func: (allow-none): A function to free elements with
+ *     destroy @array or %NULL
  *
- * Creates a new #GPtrArray with a reference count of 1 and use @element_free_func
- * for freeing each element when the array is destroyed either via
- * g_ptr_array_unref(), when g_ptr_array_free() is called with @free_segment
- * set to %TRUE or when removing elements.
+ * Creates a new #GPtrArray with a reference count of 1 and use
+ * @element_free_func for freeing each element when the array is destroyed
+ * either via g_ptr_array_unref(), when g_ptr_array_free() is called with
+ * @free_segment set to %TRUE or when removing elements.
  *
- * Returns: A new #GPtrArray.
+ * Returns: A new #GPtrArray
  * Since: 2.22
  */
 
@@ -22620,8 +22236,8 @@
 
 /**
  * g_ptr_array_remove:
- * @array: a #GPtrArray.
- * @data: the pointer to remove.
+ * @array: a #GPtrArray
+ * @data: the pointer to remove
  *
  * Removes the first occurrence of the given pointer from the pointer
  * array. The following elements are moved down one place. If @array
@@ -22631,55 +22247,55 @@
  * It returns %TRUE if the pointer was removed, or %FALSE if the
  * pointer was not found.
  *
- * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is
- *          not found in the array.
+ * Returns: %TRUE if the pointer is removed, %FALSE if the pointer
+ *     is not found in the array
  */
 
 
 /**
  * g_ptr_array_remove_fast:
- * @array: a #GPtrArray.
- * @data: the pointer to remove.
+ * @array: a #GPtrArray
+ * @data: the pointer to remove
  *
  * Removes the first occurrence of the given pointer from the pointer
  * array. The last element in the array is used to fill in the space,
- * so this function does not preserve the order of the array. But it is
- * faster than g_ptr_array_remove(). If @array has a non-%NULL
+ * so this function does not preserve the order of the array. But it
+ * is faster than g_ptr_array_remove(). If @array has a non-%NULL
  * #GDestroyNotify function it is called for the removed element.
  *
  * It returns %TRUE if the pointer was removed, or %FALSE if the
  * pointer was not found.
  *
- * Returns: %TRUE if the pointer was found in the array.
+ * Returns: %TRUE if the pointer was found in the array
  */
 
 
 /**
  * g_ptr_array_remove_index:
- * @array: a #GPtrArray.
- * @index_: the index of the pointer to remove.
+ * @array: a #GPtrArray
+ * @index_: the index of the pointer to remove
  *
- * Removes the pointer at the given index from the pointer array. The
- * following elements are moved down one place. If @array has a
- * non-%NULL #GDestroyNotify function it is called for the removed
+ * Removes the pointer at the given index from the pointer array.
+ * The following elements are moved down one place. If @array has
+ * a non-%NULL #GDestroyNotify function it is called for the removed
  * element.
  *
- * Returns: the pointer which was removed.
+ * Returns: the pointer which was removed
  */
 
 
 /**
  * g_ptr_array_remove_index_fast:
- * @array: a #GPtrArray.
- * @index_: the index of the pointer to remove.
+ * @array: a #GPtrArray
+ * @index_: the index of the pointer to remove
  *
- * Removes the pointer at the given index from the pointer array. The
- * last element in the array is used to fill in the space, so this
- * function does not preserve the order of the array. But it is faster
- * than g_ptr_array_remove_index(). If @array has a non-%NULL
+ * Removes the pointer at the given index from the pointer array.
+ * The last element in the array is used to fill in the space, so
+ * this function does not preserve the order of the array. But it
+ * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL
  * #GDestroyNotify function it is called for the removed element.
  *
- * Returns: the pointer which was removed.
+ * Returns: the pointer which was removed
  */
 
 
@@ -22690,9 +22306,9 @@
  * @length: the number of pointers to remove
  *
  * Removes the given number of pointers starting at the given index
- * from a #GPtrArray.  The following elements are moved to close the
- * gap. If @array has a non-%NULL #GDestroyNotify function it is called
- * for the removed elements.
+ * from a #GPtrArray. The following elements are moved to close the
+ * gap. If @array has a non-%NULL #GDestroyNotify function it is
+ * called for the removed elements.
  *
  * Returns: the @array
  * Since: 2.4
@@ -22701,8 +22317,9 @@
 
 /**
  * g_ptr_array_set_free_func:
- * @array: A #GPtrArray.
- * @element_free_func: (allow-none): A function to free elements with destroy @array or %NULL.
+ * @array: A #GPtrArray
+ * @element_free_func: (allow-none): A function to free elements with
+ *     destroy @array or %NULL
  *
  * Sets a function for freeing each element when @array is destroyed
  * either via g_ptr_array_unref(), when g_ptr_array_free() is called
@@ -22714,8 +22331,8 @@
 
 /**
  * g_ptr_array_set_size:
- * @array: a #GPtrArray.
- * @length: the new length of the pointer array.
+ * @array: a #GPtrArray
+ * @length: the new length of the pointer array
  *
  * Sets the size of the array. When making the array larger,
  * newly-added elements will be set to %NULL. When making it smaller,
@@ -22726,30 +22343,30 @@
 
 /**
  * g_ptr_array_sized_new:
- * @reserved_size: number of pointers preallocated.
+ * @reserved_size: number of pointers preallocated
  *
  * Creates a new #GPtrArray with @reserved_size pointers preallocated
  * and a reference count of 1. This avoids frequent reallocation, if
  * you are going to add many pointers to the array. Note however that
  * the size of the array is still 0.
  *
- * Returns: the new #GPtrArray.
+ * Returns: the new #GPtrArray
  */
 
 
 /**
  * g_ptr_array_sort:
- * @array: a #GPtrArray.
- * @compare_func: comparison function.
+ * @array: a #GPtrArray
+ * @compare_func: comparison function
  *
  * Sorts the array, using @compare_func which should be a qsort()-style
  * comparison function (returns less than zero for first arg is less
  * than second arg, zero for equal, greater than zero if irst arg is
  * greater than second arg).
  *
- * <note><para>The comparison function for g_ptr_array_sort() doesn't
+ * Note that the comparison function for g_ptr_array_sort() doesn't
  * take the pointers from the array as arguments, it takes pointers to
- * the pointers in the array.</para></note>
+ * the pointers in the array.
  *
  * This is guaranteed to be a stable sort since version 2.32.
  */
@@ -22757,16 +22374,16 @@
 
 /**
  * g_ptr_array_sort_with_data:
- * @array: a #GPtrArray.
- * @compare_func: comparison function.
- * @user_data: data to pass to @compare_func.
+ * @array: a #GPtrArray
+ * @compare_func: comparison function
+ * @user_data: data to pass to @compare_func
  *
  * Like g_ptr_array_sort(), but the comparison function has an extra
  * user data argument.
  *
- * <note><para>The comparison function for g_ptr_array_sort_with_data()
+ * Note that the comparison function for g_ptr_array_sort_with_data()
  * doesn't take the pointers from the array as arguments, it takes
- * pointers to the pointers in the array.</para></note>
+ * pointers to the pointers in the array.
  *
  * This is guaranteed to be a stable sort since version 2.32.
  */
@@ -22774,7 +22391,7 @@
 
 /**
  * g_ptr_array_unref:
- * @array: A #GPtrArray.
+ * @array: A #GPtrArray
  *
  * Atomically decrements the reference count of @array by one. If the
  * reference count drops to 0, the effect is the same as calling
@@ -22802,7 +22419,7 @@
 
 /**
  * g_quark_from_static_string:
- * @string: (allow-none): a string.
+ * @string: (allow-none): a string
  *
  * Gets the #GQuark identifying the given (static) string. If the
  * string does not currently have an associated #GQuark, a new #GQuark
@@ -22811,27 +22428,25 @@
  * Note that this function is identical to g_quark_from_string() except
  * that if a new #GQuark is created the string itself is used rather
  * than a copy. This saves memory, but can only be used if the string
- * will <emphasis>always</emphasis> exist. It can be used with
- * statically allocated strings in the main program, but not with
+ * will continue to exist until the program terminates. It can be used
+ * with statically allocated strings in the main program, but not with
  * statically allocated memory in dynamically loaded modules, if you
  * expect to ever unload the module again (e.g. do not use this
  * function in GTK+ theme engines).
  *
- * Returns: the #GQuark identifying the string, or 0 if @string is
- *     %NULL.
+ * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
  */
 
 
 /**
  * g_quark_from_string:
- * @string: (allow-none): a string.
+ * @string: (allow-none): a string
  *
  * Gets the #GQuark identifying the given string. If the string does
  * not currently have an associated #GQuark, a new #GQuark is created,
  * using a copy of the string.
  *
- * Returns: the #GQuark identifying the string, or 0 if @string is
- *     %NULL.
+ * Returns: the #GQuark identifying the string, or 0 if @string is %NULL
  */
 
 
@@ -22847,7 +22462,7 @@
 
 /**
  * g_quark_try_string:
- * @string: (allow-none): a string.
+ * @string: (allow-none): a string
  *
  * Gets the #GQuark associated with the given string, or 0 if string is
  * %NULL or it has no associated #GQuark.
@@ -22856,7 +22471,7 @@
  * use g_quark_from_string() or g_quark_from_static_string().
  *
  * Returns: the #GQuark associated with the string, or 0 if @string is
- *           %NULL or there is no #GQuark associated with it.
+ *     %NULL or there is no #GQuark associated with it
  */
 
 
@@ -22887,7 +22502,7 @@
 /**
  * g_queue_delete_link:
  * @queue: a #GQueue
- * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @link_: a #GList link that must be part of @queue
  *
  * Removes @link_ from @queue and frees it.
  *
@@ -22948,11 +22563,8 @@
  * if @queue was created with g_queue_new(). If queue elements contain
  * dynamically-allocated memory, they should be freed first.
  *
- * <note><para>
- * If queue elements contain dynamically-allocated memory,
- * you should either use g_queue_free_full() or free them manually
- * first.
- * </para></note>
+ * If queue elements contain dynamically-allocated memory, you should
+ * either use g_queue_free_full() or free them manually first.
  */
 
 
@@ -23008,7 +22620,7 @@
 /**
  * g_queue_insert_after:
  * @queue: a #GQueue
- * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @sibling: a #GList link that must be part of @queue
  * @data: the data to insert
  *
  * Inserts @data into @queue after @sibling
@@ -23022,7 +22634,7 @@
 /**
  * g_queue_insert_before:
  * @queue: a #GQueue
- * @sibling: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @sibling: a #GList link that must be part of @queue
  * @data: the data to insert
  *
  * Inserts @data into @queue before @sibling.
@@ -23232,8 +22844,7 @@
 /**
  * g_queue_push_head_link:
  * @queue: a #GQueue
- * @link_: a single #GList element, <emphasis>not</emphasis> a list with
- *     more than one element
+ * @link_: a single #GList element, not a list with more than one element
  *
  * Adds a new element at the head of the queue.
  */
@@ -23279,8 +22890,7 @@
 /**
  * g_queue_push_tail_link:
  * @queue: a #GQueue
- * @link_: a single #GList element, <emphasis>not</emphasis> a list with
- *   more than one element
+ * @link_: a single #GList element, not a list with more than one element
  *
  * Adds a new element at the tail of the queue.
  */
@@ -23338,10 +22948,10 @@
 /**
  * g_queue_unlink:
  * @queue: a #GQueue
- * @link_: a #GList link that <emphasis>must</emphasis> be part of @queue
+ * @link_: a #GList link that must be part of @queue
  *
- * Unlinks @link_ so that it will no longer be part of @queue. The link is
- * not freed.
+ * Unlinks @link_ so that it will no longer be part of @queue.
+ * The link is not freed.
  *
  * @link_ must be part of @queue.
  *
@@ -23351,55 +22961,55 @@
 
 /**
  * g_rand_boolean:
- * @rand_: a #GRand.
+ * @rand_: a #GRand
  *
- * Returns a random #gboolean from @rand_. This corresponds to a
- * unbiased coin toss.
+ * Returns a random #gboolean from @rand_.
+ * This corresponds to a unbiased coin toss.
  *
- * Returns: a random #gboolean.
+ * Returns: a random #gboolean
  */
 
 
 /**
  * g_rand_copy:
- * @rand_: a #GRand.
+ * @rand_: a #GRand
  *
  * Copies a #GRand into a new one with the same exact state as before.
  * This way you can take a snapshot of the random number generator for
  * replaying later.
  *
- * Returns: the new #GRand.
+ * Returns: the new #GRand
  * Since: 2.4
  */
 
 
 /**
  * g_rand_double:
- * @rand_: a #GRand.
+ * @rand_: a #GRand
  *
  * Returns the next random #gdouble from @rand_ equally distributed over
  * the range [0..1).
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
 /**
  * g_rand_double_range:
- * @rand_: a #GRand.
- * @begin: lower closed bound of the interval.
- * @end: upper open bound of the interval.
+ * @rand_: a #GRand
+ * @begin: lower closed bound of the interval
+ * @end: upper open bound of the interval
  *
  * Returns the next random #gdouble from @rand_ equally distributed over
  * the range [@begin..@end).
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
 /**
  * g_rand_free:
- * @rand_: a #GRand.
+ * @rand_: a #GRand
  *
  * Frees the memory allocated for the #GRand.
  */
@@ -23407,25 +23017,25 @@
 
 /**
  * g_rand_int:
- * @rand_: a #GRand.
+ * @rand_: a #GRand
  *
  * Returns the next random #guint32 from @rand_ equally distributed over
  * the range [0..2^32-1].
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
 /**
  * g_rand_int_range:
- * @rand_: a #GRand.
- * @begin: lower closed bound of the interval.
- * @end: upper open bound of the interval.
+ * @rand_: a #GRand
+ * @begin: lower closed bound of the interval
+ * @end: upper open bound of the interval
  *
  * Returns the next random #gint32 from @rand_ equally distributed over
  * the range [@begin..@end-1].
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
@@ -23433,40 +23043,42 @@
  * g_rand_new:
  *
  * Creates a new random number generator initialized with a seed taken
- * either from <filename>/dev/urandom</filename> (if existing) or from
- * the current time (as a fallback).  On Windows, the seed is taken from
- * rand_s().
+ * either from `/dev/urandom` (if existing) or from the current time
+ * (as a fallback).
+ *
+ * On Windows, the seed is taken from rand_s().
  *
- * Returns: the new #GRand.
+ * Returns: the new #GRand
  */
 
 
 /**
  * g_rand_new_with_seed:
- * @seed: a value to initialize the random number generator.
+ * @seed: a value to initialize the random number generator
  *
  * Creates a new random number generator initialized with @seed.
  *
- * Returns: the new #GRand.
+ * Returns: the new #GRand
  */
 
 
 /**
  * g_rand_new_with_seed_array:
- * @seed: an array of seeds to initialize the random number generator.
- * @seed_length: an array of seeds to initialize the random number generator.
+ * @seed: an array of seeds to initialize the random number generator
+ * @seed_length: an array of seeds to initialize the random number
+ *     generator
  *
  * Creates a new random number generator initialized with @seed.
  *
- * Returns: the new #GRand.
+ * Returns: the new #GRand
  * Since: 2.4
  */
 
 
 /**
  * g_rand_set_seed:
- * @rand_: a #GRand.
- * @seed: a value to reinitialize the random number generator.
+ * @rand_: a #GRand
+ * @seed: a value to reinitialize the random number generator
  *
  * Sets the seed for the random number generator #GRand to @seed.
  */
@@ -23474,15 +23086,15 @@
 
 /**
  * g_rand_set_seed_array:
- * @rand_: a #GRand.
+ * @rand_: a #GRand
  * @seed: array to initialize with
  * @seed_length: length of array
  *
- * Initializes the random number generator by an array of
- * longs.  Array can be of arbitrary size, though only the
- * first 624 values are taken.  This function is useful
- * if you have many low entropy seeds, or if you require more then
- * 32bits of actual entropy for your application.
+ * Initializes the random number generator by an array of longs.
+ * Array can be of arbitrary size, though only the first 624 values
+ * are taken.  This function is useful if you have many low entropy
+ * seeds, or if you require more then 32 bits of actual entropy for
+ * your application.
  *
  * Since: 2.4
  */
@@ -23491,9 +23103,10 @@
 /**
  * g_random_boolean:
  *
- * Returns a random #gboolean. This corresponds to a unbiased coin toss.
+ * Returns a random #gboolean.
+ * This corresponds to a unbiased coin toss.
  *
- * Returns: a random #gboolean.
+ * Returns: a random #gboolean
  */
 
 
@@ -23502,18 +23115,19 @@
  *
  * Returns a random #gdouble equally distributed over the range [0..1).
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
 /**
  * g_random_double_range:
- * @begin: lower closed bound of the interval.
- * @end: upper open bound of the interval.
+ * @begin: lower closed bound of the interval
+ * @end: upper open bound of the interval
  *
- * Returns a random #gdouble equally distributed over the range [@begin..@end).
+ * Returns a random #gdouble equally distributed over the range
+ * [@begin..@end).
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
@@ -23523,28 +23137,28 @@
  * Return a random #guint32 equally distributed over the range
  * [0..2^32-1].
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
 /**
  * g_random_int_range:
- * @begin: lower closed bound of the interval.
- * @end: upper open bound of the interval.
+ * @begin: lower closed bound of the interval
+ * @end: upper open bound of the interval
  *
  * Returns a random #gint32 equally distributed over the range
  * [@begin..@end-1].
  *
- * Returns: A random number.
+ * Returns: a random number
  */
 
 
 /**
  * g_random_set_seed:
- * @seed: a value to reinitialize the global random number generator.
+ * @seed: a value to reinitialize the global random number generator
  *
  * Sets the seed for the global random number generator, which is used
- * by the <function>g_random_*</function> functions, to @seed.
+ * by the g_random_* functions, to @seed.
  */
 
 
@@ -23607,7 +23221,7 @@
  * It is not necessary to initialise a recursive mutex that has been
  * statically allocated.
  *
- * |[
+ * |[<!-- language="C" -->
  *   typedef struct {
  *     GRecMutex m;
  *     ...
@@ -23844,16 +23458,16 @@
  * To retrieve all the non-overlapping matches of the pattern in
  * string you can use g_match_info_next().
  *
- * |[
+ * |[<!-- language="C" -->
  * static void
  * print_uppercase_words (const gchar *string)
  * {
  *   /&ast; Print all uppercase-only words. &ast;/
  *   GRegex *regex;
  *   GMatchInfo *match_info;
- *   &nbsp;
+ *  
  *   regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- *   g_regex_match (regex, string, 0, &amp;match_info);
+ *   g_regex_match (regex, string, 0, &match_info);
  *   while (g_match_info_matches (match_info))
  *     {
  *       gchar *word = g_match_info_fetch (match_info, 0);
@@ -23989,7 +23603,7 @@
  * To retrieve all the non-overlapping matches of the pattern in
  * string you can use g_match_info_next().
  *
- * |[
+ * |[<!-- language="C" -->
  * static void
  * print_uppercase_words (const gchar *string)
  * {
@@ -23997,15 +23611,15 @@
  *   GRegex *regex;
  *   GMatchInfo *match_info;
  *   GError *error = NULL;
- *   &nbsp;
+ *   
  *   regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- *   g_regex_match_full (regex, string, -1, 0, 0, &amp;match_info, &amp;error);
+ *   g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
  *   while (g_match_info_matches (match_info))
  *     {
  *       gchar *word = g_match_info_fetch (match_info, 0);
  *       g_print ("Found: %s\n", word);
  *       g_free (word);
- *       g_match_info_next (match_info, &amp;error);
+ *       g_match_info_next (match_info, &error);
  *     }
  *   g_match_info_free (match_info);
  *   g_regex_unref (regex);
@@ -24089,35 +23703,14 @@
  * to the captured subexpression with the given name. '\0' refers to the
  * complete match, but '\0' followed by a number is the octal representation
  * of a character. To include a literal '\' in the replacement, write '\\'.
+ *
  * There are also escapes that changes the case of the following text:
  *
- * <variablelist>
- * <varlistentry><term>\l</term>
- * <listitem>
- * <para>Convert to lower case the next character</para>
- * </listitem>
- * </varlistentry>
- * <varlistentry><term>\u</term>
- * <listitem>
- * <para>Convert to upper case the next character</para>
- * </listitem>
- * </varlistentry>
- * <varlistentry><term>\L</term>
- * <listitem>
- * <para>Convert to lower case till \E</para>
- * </listitem>
- * </varlistentry>
- * <varlistentry><term>\U</term>
- * <listitem>
- * <para>Convert to upper case till \E</para>
- * </listitem>
- * </varlistentry>
- * <varlistentry><term>\E</term>
- * <listitem>
- * <para>End case modification</para>
- * </listitem>
- * </varlistentry>
- * </variablelist>
+ * - \l: Convert to lower case the next character
+ * - \u: Convert to upper case the next character
+ * - \L: Convert to lower case till \E
+ * - \U: Convert to upper case till \E
+ * - \E: End case modification
  *
  * If you do not need to use backreferences use g_regex_replace_literal().
  *
@@ -24154,7 +23747,7 @@
  *
  * The following example uses g_regex_replace_eval() to replace multiple
  * strings at once:
- * |[
+ * |[<!-- language="C" -->
  * static gboolean
  * eval_cb (const GMatchInfo *info,
  *          GString          *res,
@@ -24444,7 +24037,7 @@
  * necessary to initialise a reader-writer lock that has been statically
  * allocated.
  *
- * |[
+ * |[<!-- language="C" -->
  *   typedef struct {
  *     GRWLock l;
  *     ...
@@ -24911,8 +24504,8 @@
  * @seq: a #GSequence
  *
  * Frees the memory allocated for @seq. If @seq has a data destroy
- * function associated with it, that function is called on all items in
- * @seq.
+ * function associated with it, that function is called on all items
+ * in @seq.
  *
  * Since: 2.14
  */
@@ -24954,7 +24547,7 @@
 /**
  * g_sequence_get_iter_at_pos:
  * @seq: a #GSequence
- * @pos: a position in @seq, or -1 for the end.
+ * @pos: a position in @seq, or -1 for the end
  *
  * Returns the iterator at position @pos. If @pos is negative or larger
  * than the number of items in @seq, the end iterator is returned.
@@ -25044,8 +24637,8 @@
  *
  * The @a and @b iterators must point into the same sequence.
  *
- * Returns: A negative number if @a comes before @b, 0 if they are
- * equal, and a positive number if @a comes after @b.
+ * Returns: a negative number if @a comes before @b, 0 if they are
+ *     equal, and a positive number if @a comes after @b
  * Since: 2.14
  */
 
@@ -25067,7 +24660,7 @@
  *
  * Returns the #GSequence that @iter points into.
  *
- * Returns: the #GSequence that @iter points into.
+ * Returns: the #GSequence that @iter points into
  * Since: 2.14
  */
 
@@ -25089,7 +24682,7 @@
  *
  * Returns whether @iter is the end iterator
  *
- * Returns: Whether @iter is the end iterator.
+ * Returns: Whether @iter is the end iterator
  * Since: 2.14
  */
 
@@ -25098,14 +24691,14 @@
  * g_sequence_iter_move:
  * @iter: a #GSequenceIter
  * @delta: A positive or negative number indicating how many positions away
- *    from @iter the returned #GSequenceIter will be.
+ *    from @iter the returned #GSequenceIter will be
  *
  * Returns the #GSequenceIter which is @delta positions away from @iter.
  * If @iter is closer than -@delta positions to the beginning of the sequence,
  * the begin iterator is returned. If @iter is closer than @delta positions
  * to the end of the sequence, the end iterator is returned.
  *
- * Returns: a #GSequenceIter which is @delta positions away from @iter.
+ * Returns: a #GSequenceIter which is @delta positions away from @iter
  * Since: 2.14
  */
 
@@ -25114,10 +24707,10 @@
  * g_sequence_iter_next:
  * @iter: a #GSequenceIter
  *
- * Returns an iterator pointing to the next position after @iter. If
- * @iter is the end iterator, the end iterator is returned.
+ * Returns an iterator pointing to the next position after @iter.
+ * If @iter is the end iterator, the end iterator is returned.
  *
- * Returns: a #GSequenceIter pointing to the next position after @iter.
+ * Returns: a #GSequenceIter pointing to the next position after @iter
  * Since: 2.14
  */
 
@@ -25126,11 +24719,11 @@
  * g_sequence_iter_prev:
  * @iter: a #GSequenceIter
  *
- * Returns an iterator pointing to the previous position before @iter. If
- * @iter is the begin iterator, the begin iterator is returned.
+ * Returns an iterator pointing to the previous position before @iter.
+ * If @iter is the begin iterator, the begin iterator is returned.
  *
- * Returns: a #GSequenceIter pointing to the previous position before
- * @iter.
+ * Returns: a #GSequenceIter pointing to the previous position
+ *     before @iter
  * Since: 2.14
  */
 
@@ -25140,7 +24733,7 @@
  * @seq: a #GSequence
  * @data: data to lookup
  * @cmp_func: the function used to compare items in the sequence
- * @cmp_data: user data passed to @cmp_func.
+ * @cmp_data: user data passed to @cmp_func
  *
  * Returns an iterator pointing to the position of the first item found
  * equal to @data according to @cmp_func and @cmp_data. If more than one
@@ -25153,17 +24746,15 @@
  * the first item comes before the second, and a positive value if
  * the second item comes before the first.
  *
- * <note><para>
  * This function will fail if the data contained in the sequence is
  * unsorted.  Use g_sequence_insert_sorted() or
  * g_sequence_insert_sorted_iter() to add data to your sequence or, if
  * you want to add a large amount of data, call g_sequence_sort() after
  * doing unsorted insertions.
- * </para></note>
  *
  * Returns: an #GSequenceIter pointing to the position of the
  *     first item found equal to @data according to @cmp_func and
- *     @cmp_data, or %NULL if no such item exists.
+ *     @cmp_data, or %NULL if no such item exists
  * Since: 2.28
  */
 
@@ -25183,17 +24774,15 @@
  * if the first iterator comes before the second, and a positive
  * value if the second iterator comes before the first.
  *
- * <note><para>
  * This function will fail if the data contained in the sequence is
  * unsorted.  Use g_sequence_insert_sorted() or
  * g_sequence_insert_sorted_iter() to add data to your sequence or, if
  * you want to add a large amount of data, call g_sequence_sort() after
  * doing unsorted insertions.
- * </para></note>
  *
  * Returns: an #GSequenceIter pointing to the position of
  *     the first item found equal to @data according to @cmp_func
- *     and @cmp_data, or %NULL if no such item exists.
+ *     and @cmp_data, or %NULL if no such item exists
  * Since: 2.28
  */
 
@@ -25202,7 +24791,7 @@
  * g_sequence_move:
  * @src: a #GSequenceIter pointing to the item to move
  * @dest: a #GSequenceIter pointing to the position to which
- *        the item is moved.
+ *     the item is moved
  *
  * Moves the item pointed to by @src to the position indicated by @dest.
  * After calling this function @dest will point to the position immediately
@@ -25264,13 +24853,13 @@
  *
  * Finds an iterator somewhere in the range (@begin, @end). This
  * iterator will be close to the middle of the range, but is not
- * guaranteed to be <emphasis>exactly</emphasis> in the middle.
+ * guaranteed to be exactly in the middle.
  *
- * The @begin and @end iterators must both point to the same sequence and
- * @begin must come before or be equal to @end in the sequence.
+ * The @begin and @end iterators must both point to the same sequence
+ * and @begin must come before or be equal to @end in the sequence.
  *
- * Returns: A #GSequenceIter pointing somewhere in the
- * (@begin, @end) range.
+ * Returns: a #GSequenceIter pointing somewhere in the
+ *    (@begin, @end) range
  * Since: 2.14
  */
 
@@ -25308,7 +24897,7 @@
  * @seq: a #GSequence
  * @data: data for the new item
  * @cmp_func: the function used to compare items in the sequence
- * @cmp_data: user data passed to @cmp_func.
+ * @cmp_data: user data passed to @cmp_func
  *
  * Returns an iterator pointing to the position where @data would
  * be inserted according to @cmp_func and @cmp_data.
@@ -25321,16 +24910,14 @@
  * If you are simply searching for an existing element of the sequence,
  * consider using g_sequence_lookup().
  *
- * <note><para>
  * This function will fail if the data contained in the sequence is
  * unsorted.  Use g_sequence_insert_sorted() or
  * g_sequence_insert_sorted_iter() to add data to your sequence or, if
  * you want to add a large amount of data, call g_sequence_sort() after
  * doing unsorted insertions.
- * </para></note>
  *
  * Returns: an #GSequenceIter pointing to the position where @data
- * would have been inserted according to @cmp_func and @cmp_data.
+ *     would have been inserted according to @cmp_func and @cmp_data
  * Since: 2.14
  */
 
@@ -25353,17 +24940,15 @@
  * If you are simply searching for an existing element of the sequence,
  * consider using g_sequence_lookup_iter().
  *
- * <note><para>
  * This function will fail if the data contained in the sequence is
  * unsorted.  Use g_sequence_insert_sorted() or
  * g_sequence_insert_sorted_iter() to add data to your sequence or, if
  * you want to add a large amount of data, call g_sequence_sort() after
  * doing unsorted insertions.
- * </para></note>
  *
  * Returns: a #GSequenceIter pointing to the position in @seq
  *     where @data would have been inserted according to @iter_cmp
- *     and @cmp_data.
+ *     and @cmp_data
  * Since: 2.14
  */
 
@@ -25521,9 +25106,10 @@
  * g_set_prgname:
  * @prgname: the name of the program.
  *
- * Sets the name of the program. This name should <emphasis>not</emphasis>
- * be localized, contrast with g_set_application_name(). Note that for
- * thread-safety reasons this function can only be called once.
+ * Sets the name of the program. This name should not be localized,
+ * in contrast to g_set_application_name().
+ *
+ * Note that for thread-safety reasons this function can only be called once.
  */
 
 
@@ -25573,20 +25159,18 @@
  * Note that on some systems, when variables are overwritten, the memory
  * used for the previous variables and its value isn't reclaimed.
  *
- * <warning><para>
- * Environment variable handling in UNIX is not thread-safe, and your
- * program may crash if one thread calls g_setenv() while another
- * thread is calling getenv(). (And note that many functions, such as
- * gettext(), call getenv() internally.) This function is only safe to
- * use at the very start of your program, before creating any other
- * threads (or creating objects that create worker threads of their
- * own).
- * </para><para>
+ * You should be mindful fo the fact that environment variable handling
+ * in UNIX is not thread-safe, and your program may crash if one thread
+ * calls g_setenv() while another thread is calling getenv(). (And note
+ * that many functions, such as gettext(), call getenv() internally.)
+ * This function is only safe to use at the very start of your program,
+ * before creating any other threads (or creating objects that create
+ * worker threads of their own).
+ *
  * If you need to set up the environment for a child process, you can
  * use g_get_environ() to get an environment array, modify that with
  * g_environ_setenv() and g_environ_unsetenv(), and then pass that
  * array directly to execvpe(), g_spawn_async(), or the like.
- * </para></warning>
  *
  * Returns: %FALSE if the environment variable couldn't be set.
  * Since: 2.4
@@ -25666,7 +25250,7 @@
  *
  * Allocates a block of memory from the slice allocator.
  * The block adress handed out can be expected to be aligned
- * to at least <literal>1 * sizeof (void*)</literal>,
+ * to at least 1 * sizeof (void*),
  * though in general slices are 2 * sizeof (void*) bytes aligned,
  * if a malloc() fallback implementation is used instead,
  * the alignment may be reduced in a libc dependent fashion.
@@ -25715,7 +25299,7 @@
  * A convenience macro to duplicate a block of memory using
  * the slice allocator.
  *
- * It calls g_slice_copy() with <literal>sizeof (@type)</literal>
+ * It calls g_slice_copy() with `sizeof (@type)`
  * and casts the returned pointer to a pointer of the given type,
  * avoiding a type cast in the source code.
  * Note that the underlying slice allocation mechanism can
@@ -25735,7 +25319,7 @@
  * A convenience macro to free a block of memory that has
  * been allocated from the slice allocator.
  *
- * It calls g_slice_free1() using <literal>sizeof (type)</literal>
+ * It calls g_slice_free1() using `sizeof (type)`
  * as the block size.
  * Note that the exact release behaviour can be changed with the
  * <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
@@ -25813,11 +25397,11 @@
  * A convenience macro to allocate a block of memory from the
  * slice allocator.
  *
- * It calls g_slice_alloc() with <literal>sizeof (@type)</literal>
- * and casts the returned pointer to a pointer of the given type,
- * avoiding a type cast in the source code.
- * Note that the underlying slice allocation mechanism can
- * be changed with the <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+ * It calls g_slice_alloc() with `sizeof (@type)` and casts the
+ * returned pointer to a pointer of the given type, avoiding a type
+ * cast in the source code. Note that the underlying slice allocation
+ * mechanism can be changed with the
+ * <link linkend="G_SLICE">G_SLICE=always-malloc</link>
  * environment variable.
  *
  * Returns: a pointer to the allocated block, cast to a pointer to @type
@@ -25832,7 +25416,7 @@
  * A convenience macro to allocate a block of memory from the
  * slice allocator and set the memory to 0.
  *
- * It calls g_slice_alloc0() with <literal>sizeof (@type)</literal>
+ * It calls g_slice_alloc0() with `sizeof (@type)`
  * and casts the returned pointer to a pointer of the given type,
  * avoiding a type cast in the source code.
  * Note that the underlying slice allocation mechanism can
@@ -25861,19 +25445,15 @@
  *
  * Adds a new element on to the end of the list.
  *
- * <note><para>
  * The return value is the new start of the list, which may
  * have changed, so make sure you store the new value.
- * </para></note>
  *
- * <note><para>
  * Note that g_slist_append() has to traverse the entire list
  * to find the end, which is inefficient when adding multiple
  * elements. A common idiom to avoid the inefficiency is to prepend
  * the elements and reverse the list when all elements have been added.
- * </para></note>
  *
- * |[
+ * |[<!-- language="C" -->
  * /&ast; Notice that these are initialized to the empty list. &ast;/
  * GSList *list = NULL, *number_list = NULL;
  *
@@ -25909,12 +25489,10 @@
  *
  * Copies a #GSList.
  *
- * <note><para>
  * Note that this is a "shallow" copy. If the list elements
  * consist of pointers to data, the pointers are copied but
  * the actual data isn't. See g_slist_copy_deep() if you need
  * to copy the data as well.
- * </para></note>
  *
  * Returns: a copy of @list
  */
@@ -25936,12 +25514,12 @@
  * one argument.
  *
  * For instance, if @list holds a list of GObjects, you can do:
- * |[
+ * |[<!-- language="C" -->
  * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL);
  * ]|
  *
  * And, to entirely free the new list, you could do:
- * |[
+ * |[<!-- language="C" -->
  * g_slist_free_full (another_list, g_object_unref);
  * ]|
  *
@@ -25959,11 +25537,11 @@
  * Compare this to g_slist_remove_link() which removes the node
  * without freeing it.
  *
- * <note>Removing arbitrary nodes from a singly-linked list
- * requires time that is proportional to the length of the list
- * (ie. O(n)). If you find yourself using g_slist_delete_link()
- * frequently, you should consider a different data structure, such
- * as the doubly-linked #GList.</note>
+ * Removing arbitrary nodes from a singly-linked list requires time
+ * that is proportional to the length of the list (ie. O(n)). If you
+ * find yourself using g_slist_delete_link() frequently, you should
+ * consider a different data structure, such as the doubly-linked
+ * #GList.
  *
  * Returns: the new head of @list
  */
@@ -26017,11 +25595,9 @@
  * Frees all of the memory used by a #GSList.
  * The freed elements are returned to the slice allocator.
  *
- * <note><para>
  * If list elements contain dynamically-allocated memory,
  * you should either use g_slist_free_full() or free them manually
  * first.
- * </para></note>
  */
 
 
@@ -26133,9 +25709,7 @@
  *
  * Gets the last element in a #GSList.
  *
- * <note><para>
  * This function iterates over the whole list.
- * </para></note>
  *
  * Returns: the last element in the #GSList,
  *     or %NULL if the #GSList has no elements
@@ -26148,10 +25722,8 @@
  *
  * Gets the number of elements in a #GSList.
  *
- * <note><para>
  * This function iterates over the whole list to
  * count its elements.
- * </para></note>
  *
  * Returns: the number of elements in the #GSList
  */
@@ -26211,12 +25783,10 @@
  *
  * Adds a new element on to the start of the list.
  *
- * <note><para>
  * The return value is the new start of the list, which
  * may have changed, so make sure you store the new value.
- * </para></note>
  *
- * |[
+ * |[<!-- language="C" -->
  * /&ast; Notice that it is initialized to the empty list. &ast;/
  * GSList *list = NULL;
  * list = g_slist_prepend (list, "last");
@@ -26264,11 +25834,11 @@
  * link is set to %NULL, so that it becomes a
  * self-contained list with one element.
  *
- * <note>Removing arbitrary nodes from a singly-linked list
+ * Removing arbitrary nodes from a singly-linked list
  * requires time that is proportional to the length of the list
  * (ie. O(n)). If you find yourself using g_slist_remove_link()
- * frequently, you should consider a different data structure, such
- * as the doubly-linked #GList.</note>
+ * frequently, you should consider a different data structure,
+ * such as the doubly-linked #GList.
  *
  * Returns: the new start of the #GSList, without the element
  */
@@ -26426,7 +25996,8 @@
  *
  * Removes a source from its #GMainContext, if any, and mark it as
  * destroyed.  The source cannot be subsequently added to another
- * context.
+ * context. It is safe to call this on sources which have already been
+ * removed from their context.
  */
 
 
@@ -26549,16 +26120,16 @@
  * from within idle handlers, but may have freed the object
  * before the dispatch of your idle handler.
  *
- * |[
+ * |[<!-- language="C" -->
  * static gboolean
  * idle_callback (gpointer data)
  * {
  *   SomeWidget *self = data;
  *    
- *   GDK_THREADS_ENTER (<!-- -->);
- *   /<!-- -->* do stuff with self *<!-- -->/
+ *   GDK_THREADS_ENTER ();
+ *   /&ast; do stuff with self &ast;/
  *   self->idle_id = 0;
- *   GDK_THREADS_LEAVE (<!-- -->);
+ *   GDK_THREADS_LEAVE ();
  *    
  *   return G_SOURCE_REMOVE;
  * }
@@ -26587,7 +26158,7 @@
  * this particular problem, is to check to if the source
  * has already been destroy within the callback.
  *
- * |[
+ * |[<!-- language="C" -->
  * static gboolean
  * idle_callback (gpointer data)
  * {
@@ -26596,7 +26167,7 @@
  *   GDK_THREADS_ENTER ();
  *   if (!g_source_is_destroyed (g_main_current_source ()))
  *     {
- *       /<!-- -->* do stuff with self *<!-- -->/
+ *       /&ast; do stuff with self &ast;/
  *     }
  *   GDK_THREADS_LEAVE ();
  *   
@@ -26637,7 +26208,7 @@
  * Creates a new #GSource structure. The size is specified to
  * allow creating structures derived from #GSource that contain
  * additional data. The size passed in must be at least
- * <literal>sizeof (GSource)</literal>.
+ * `sizeof (GSource)`.
  *
  * The source will not initially be associated with any #GMainContext
  * and must be added to one with g_source_attach() before it will be
@@ -26936,17 +26507,14 @@
  * You should call g_spawn_close_pid() on the returned child process
  * reference when you don't need it any more.
  *
- * <note><para>
- * If you are writing a GTK+ application, and the program you
- * are spawning is a graphical application, too, then you may
- * want to use gdk_spawn_on_screen() instead to ensure that
- * the spawned program opens its windows on the right screen.
- * </para></note>
+ * If you are writing a GTK+ application, and the program you are
+ * spawning is a graphical application, too, then you may want to
+ * use gdk_spawn_on_screen() instead to ensure that the spawned program
+ * opens its windows on the right screen.
  *
- * <note><para> Note that the returned @child_pid on Windows is a
- * handle to the child process and not its identifier. Process handles
- * and process identifiers are different concepts on Windows.
- * </para></note>
+ * Note that the returned @child_pid on Windows is a handle to the child
+ * process and not its identifier. Process handles and process identifiers
+ * are different concepts on Windows.
  *
  * Returns: %TRUE on success, %FALSE if error is set
  */
@@ -26968,18 +26536,18 @@
  *
  * Executes a child program asynchronously (your program will not
  * block waiting for the child to exit). The child program is
- * specified by the only argument that must be provided, @argv. @argv
- * should be a %NULL-terminated array of strings, to be passed as the
- * argument vector for the child. The first string in @argv is of
- * course the name of the program to execute. By default, the name of
- * the program must be a full path. If @flags contains the
- * %G_SPAWN_SEARCH_PATH flag, the <envar>PATH</envar> environment variable
- * is used to search for the executable. If @flags contains the
- * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the <envar>PATH</envar> variable from
- * @envp is used to search for the executable.
- * If both the %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
- * flags are set, the <envar>PATH</envar> variable from @envp takes precedence
- * over the environment variable.
+ * specified by the only argument that must be provided, @argv.
+ * @argv should be a %NULL-terminated array of strings, to be passed
+ * as the argument vector for the child. The first string in @argv
+ * is of course the name of the program to execute. By default, the
+ * name of the program must be a full path. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
+ * used to search for the executable. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
+ * @envp is used to search for the executable. If both the
+ * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
+ * are set, the `PATH` variable from @envp takes precedence over
+ * the environment variable.
  *
  * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
  * used, then the program will be run from the current directory (or
@@ -27004,21 +26572,19 @@
  * level wide character command line passed to the spawned program
  * using the GetCommandLineW() function.
  *
- * On Windows the low-level child process creation API
- * <function>CreateProcess()</function> doesn't use argument vectors,
- * but a command line. The C runtime library's
- * <function>spawn*()</function> family of functions (which
- * g_spawn_async_with_pipes() eventually calls) paste the argument
- * vector elements together into a command line, and the C runtime startup code
- * does a corresponding reconstruction of an argument vector from the
- * command line, to be passed to main(). Complications arise when you have
- * argument vector elements that contain spaces of double quotes. The
- * <function>spawn*()</function> functions don't do any quoting or
- * escaping, but on the other hand the startup code does do unquoting
- * and unescaping in order to enable receiving arguments with embedded
- * spaces or double quotes. To work around this asymmetry,
- * g_spawn_async_with_pipes() will do quoting and escaping on argument
- * vector elements that need it before calling the C runtime
+ * On Windows the low-level child process creation API CreateProcess()
+ * doesn't use argument vectors, but a command line. The C runtime
+ * library's spawn*() family of functions (which g_spawn_async_with_pipes()
+ * eventually calls) paste the argument vector elements together into
+ * a command line, and the C runtime startup code does a corresponding
+ * reconstruction of an argument vector from the command line, to be
+ * passed to main(). Complications arise when you have argument vector
+ * elements that contain spaces of double quotes. The spawn*() functions
+ * don't do any quoting or escaping, but on the other hand the startup
+ * code does do unquoting and unescaping in order to enable receiving
+ * arguments with embedded spaces or double quotes. To work around this
+ * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
+ * argument vector elements that need it before calling the C runtime
  * spawn() function.
  *
  * The returned @child_pid on Windows is a handle to the child
@@ -27026,9 +26592,8 @@
  * identifiers are different concepts on Windows.
  *
  * @envp is a %NULL-terminated array of strings, where each string
- * has the form <literal>KEY=VALUE</literal>. This will become
- * the child's environment. If @envp is %NULL, the child inherits its
- * parent's environment.
+ * has the form `KEY=VALUE`. This will become the child's environment.
+ * If @envp is %NULL, the child inherits its parent's environment.
  *
  * @flags should be the bitwise OR of any flags you want to affect the
  * function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the
@@ -27037,22 +26602,21 @@
  * call g_spawn_close_pid() on the @child_pid, in order to free
  * resources which may be associated with the child process. (On Unix,
  * using a child watch is equivalent to calling waitpid() or handling
- * the <literal>SIGCHLD</literal> signal manually. On Windows, calling g_spawn_close_pid()
+ * the %SIGCHLD signal manually. On Windows, calling g_spawn_close_pid()
  * is equivalent to calling CloseHandle() on the process handle returned
- * in @child_pid).  See g_child_watch_add().
+ * in @child_pid). See g_child_watch_add().
  *
  * %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that the parent's open file
- * descriptors will be inherited by the child; otherwise all
- * descriptors except stdin/stdout/stderr will be closed before
- * calling exec() in the child. %G_SPAWN_SEARCH_PATH
- * means that <literal>argv[0]</literal> need not be an absolute path, it
- * will be looked for in the <envar>PATH</envar> environment variable.
- * %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an absolute path, it
- * will be looked for in the <envar>PATH</envar> variable from @envp. If
- * both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP are used,
- * the value from @envp takes precedence over the environment.
- * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output will
- * be discarded, instead of going to the same location as the parent's
+ * descriptors will be inherited by the child; otherwise all descriptors
+ * except stdin/stdout/stderr will be closed before calling exec() in
+ * the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
+ * absolute path, it will be looked for in the `PATH` environment
+ * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
+ * absolute path, it will be looked for in the `PATH` variable from
+ * @envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP
+ * are used, the value from @envp takes precedence over the environment.
+ * %G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output
+ * will be discarded, instead of going to the same location as the parent's
  * standard output. If you use this flag, @standard_output must be %NULL.
  * %G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error
  * will be discarded, instead of going to the same location as the parent's
@@ -27061,42 +26625,40 @@
  * standard input (by default, the child's standard input is attached to
  * /dev/null). If you use this flag, @standard_input must be %NULL.
  * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
- * the file to execute, while the remaining elements are the
- * actual argument vector to pass to the file. Normally
- * g_spawn_async_with_pipes() uses @argv[0] as the file to execute, and
- * passes all of @argv to the child.
+ * the file to execute, while the remaining elements are the actual
+ * argument vector to pass to the file. Normally g_spawn_async_with_pipes()
+ * uses @argv[0] as the file to execute, and passes all of @argv to the child.
  *
  * @child_setup and @user_data are a function and user data. On POSIX
  * platforms, the function is called in the child after GLib has
  * performed all the setup it plans to perform (including creating
- * pipes, closing file descriptors, etc.) but before calling
- * exec(). That is, @child_setup is called just
- * before calling exec() in the child. Obviously
- * actions taken in this function will only affect the child, not the
- * parent.
- *
- * On Windows, there is no separate fork() and exec()
- * functionality. Child processes are created and run with a single
- * API call, CreateProcess(). There is no sensible thing @child_setup
+ * pipes, closing file descriptors, etc.) but before calling exec().
+ * That is, @child_setup is called just before calling exec() in the
+ * child. Obviously actions taken in this function will only affect
+ * the child, not the parent.
+ *
+ * On Windows, there is no separate fork() and exec() functionality.
+ * Child processes are created and run with a single API call,
+ * CreateProcess(). There is no sensible thing @child_setup
  * could be used for on Windows so it is ignored and not called.
  *
  * If non-%NULL, @child_pid will on Unix be filled with the child's
- * process ID. You can use the process ID to send signals to the
- * child, or to use g_child_watch_add() (or waitpid()) if you specified the
+ * process ID. You can use the process ID to send signals to the child,
+ * or to use g_child_watch_add() (or waitpid()) if you specified the
  * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
  * filled with a handle to the child process only if you specified the
  * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
  * process using the Win32 API, for example wait for its termination
- * with the <function>WaitFor*()</function> functions, or examine its
- * exit code with GetExitCodeProcess(). You should close the handle
- * with CloseHandle() or g_spawn_close_pid() when you no longer need it.
+ * with the WaitFor*() functions, or examine its exit code with
+ * GetExitCodeProcess(). You should close the handle with CloseHandle()
+ * or g_spawn_close_pid() when you no longer need it.
  *
  * If non-%NULL, the @standard_input, @standard_output, @standard_error
  * locations will be filled with file descriptors for writing to the child's
  * standard input or reading from its standard output or standard error.
  * The caller of g_spawn_async_with_pipes() must close these file descriptors
- * when they are no longer in use. If these parameters are %NULL, the corresponding
- * pipe won't be created.
+ * when they are no longer in use. If these parameters are %NULL, the
+ * corresponding pipe won't be created.
  *
  * If @standard_input is NULL, the child's standard input is attached to
  * /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
@@ -27110,11 +26672,11 @@
  * is set.
  *
  * @error can be %NULL to ignore errors, or non-%NULL to report errors.
- * If an error is set, the function returns %FALSE. Errors
- * are reported even if they occur in the child (for example if the
- * executable in <literal>argv[0]</literal> is not found). Typically
- * the <literal>message</literal> field of returned errors should be displayed
- * to users. Possible errors are those from the #G_SPAWN_ERROR domain.
+ * If an error is set, the function returns %FALSE. Errors are reported
+ * even if they occur in the child (for example if the executable in
+ * @argv[0] is not found). Typically the `message` field of returned
+ * errors should be displayed to users. Possible errors are those from
+ * the #G_SPAWN_ERROR domain.
  *
  * If an error occurs, @child_pid, @standard_input, @standard_output,
  * and @standard_error will not be filled with valid values.
@@ -27122,12 +26684,10 @@
  * If @child_pid is not %NULL and an error does not occur then the returned
  * process reference must be closed using g_spawn_close_pid().
  *
- * <note><para>
  * If you are writing a GTK+ application, and the program you
  * are spawning is a graphical application, too, then you may
  * want to use gdk_spawn_on_screen_with_pipes() instead to ensure that
  * the spawned program opens its windows on the right screen.
- * </para></note>
  *
  * Returns: %TRUE on success, %FALSE if an error was set
  */
@@ -27143,25 +26703,23 @@
  *
  * The g_spawn_sync() and g_child_watch_add() family of APIs return an
  * exit status for subprocesses encoded in a platform-specific way.
- * On Unix, this is guaranteed to be in the same format
- * <literal>waitpid(2)</literal> returns, and on Windows it is
- * guaranteed to be the result of
- * <literal>GetExitCodeProcess()</literal>.  Prior to the introduction
- * of this function in GLib 2.34, interpreting @exit_status required
- * use of platform-specific APIs, which is problematic for software
- * using GLib as a cross-platform layer.
+ * On Unix, this is guaranteed to be in the same format waitpid() returns,
+ * and on Windows it is guaranteed to be the result of GetExitCodeProcess().
+ *
+ * Prior to the introduction of this function in GLib 2.34, interpreting
+ * @exit_status required use of platform-specific APIs, which is problematic
+ * for software using GLib as a cross-platform layer.
  *
  * Additionally, many programs simply want to determine whether or not
  * the child exited successfully, and either propagate a #GError or
- * print a message to standard error.  In that common case, this
- * function can be used.  Note that the error message in @error will
- * contain human-readable information about the exit status.
+ * print a message to standard error. In that common case, this function
+ * can be used. Note that the error message in @error will contain
+ * human-readable information about the exit status.
  *
- * The <literal>domain</literal> and <literal>code</literal> of @error
- * have special semantics in the case where the process has an "exit
- * code", as opposed to being killed by a signal.  On Unix, this
- * happens if <literal>WIFEXITED</literal> would be true of
- * @exit_status.  On Windows, it is always the case.
+ * The @domain and @code of @error have special semantics in the case
+ * where the process has an "exit code", as opposed to being killed by
+ * a signal. On Unix, this happens if WIFEXITED() would be true of
+ * @exit_status. On Windows, it is always the case.
  *
  * The special semantics are that the actual exit code will be the
  * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
@@ -27173,12 +26731,12 @@
  *
  * This function just offers convenience; you can of course also check
  * the available platform via a macro such as %G_OS_UNIX, and use
- * <literal>WIFEXITED()</literal> and <literal>WEXITSTATUS()</literal>
- * on @exit_status directly.  Do not attempt to scan or parse the
- * error message string; it may be translated and/or change in future
- * versions of GLib.
+ * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt
+ * to scan or parse the error message string; it may be translated and/or
+ * change in future versions of GLib.
  *
- * Returns: %TRUE if child exited successfully, %FALSE otherwise (and @error will be set)
+ * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
+ *     @error will be set)
  * Since: 2.34
  */
 
@@ -27209,7 +26767,7 @@
  *
  * The same concerns on Windows apply as for g_spawn_command_line_sync().
  *
- * Returns: %TRUE on success, %FALSE if error is set.
+ * Returns: %TRUE on success, %FALSE if error is set
  */
 
 
@@ -27280,7 +26838,7 @@
  * function for full details on the other parameters and details on
  * how these functions work on Windows.
  *
- * Returns: %TRUE on success, %FALSE if an error was set.
+ * Returns: %TRUE on success, %FALSE if an error was set
  */
 
 
@@ -27309,33 +26867,32 @@
 /**
  * g_stat:
  * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @buf: a pointer to a <structname>stat</structname> struct, which
- *    will be filled with the file information
+ * @buf: a pointer to a stat struct, which will be filled with the file
+ *     information
  *
  * A wrapper for the POSIX stat() function. The stat() function
  * returns information about a file. On Windows the stat() function in
  * the C library checks only the FAT-style READONLY attribute and does
  * not look at the ACL at all. Thus on Windows the protection bits in
- * the st_mode field are a fabrication of little use.
+ * the @st_mode field are a fabrication of little use.
  *
  * On Windows the Microsoft C libraries have several variants of the
- * <structname>stat</structname> struct and stat() function with names
- * like "_stat", "_stat32", "_stat32i64" and "_stat64i32". The one
- * used here is for 32-bit code the one with 32-bit size and time
- * fields, specifically called "_stat32".
+ * stat struct and stat() function with names like _stat(), _stat32(),
+ * _stat32i64() and _stat64i32(). The one used here is for 32-bit code
+ * the one with 32-bit size and time fields, specifically called _stat32().
  *
- * In Microsoft's compiler, by default "struct stat" means one with
- * 64-bit time fields while in MinGW "struct stat" is the legacy one
+ * In Microsoft's compiler, by default struct stat means one with
+ * 64-bit time fields while in MinGW struct stat is the legacy one
  * with 32-bit fields. To hopefully clear up this messs, the gstdio.h
- * header defines a type GStatBuf which is the appropriate struct type
+ * header defines a type #GStatBuf which is the appropriate struct type
  * depending on the platform and/or compiler being used. On POSIX it
- * is just "struct stat", but note that even on POSIX platforms,
- * "stat" might be a macro.
+ * is just struct stat, but note that even on POSIX platforms, stat()
+ * might be a macro.
  *
  * See your C library manual for more details about stat().
  *
- * Returns: 0 if the information was successfully retrieved, -1 if an error
- *    occurred
+ * Returns: 0 if the information was successfully retrieved,
+ *     -1 if an error occurred
  * Since: 2.6
  */
 
@@ -27402,11 +26959,11 @@
  *
  * Converts a string to a hash value.
  *
- * This function implements the widely used "djb" hash apparently posted
- * by Daniel Bernstein to comp.lang.c some time ago.  The 32 bit
- * unsigned hash value starts at 5381 and for each byte 'c' in the
- * string, is updated: <literal>hash = hash * 33 + c</literal>.  This
- * function uses the signed value of each byte.
+ * This function implements the widely used "djb" hash apparently
+ * posted by Daniel Bernstein to comp.lang.c some time ago.  The 32
+ * bit unsigned hash value starts at 5381 and for each byte 'c' in
+ * the string, is updated: `hash = hash * 33 + c`. This function
+ * uses the signed value of each byte.
  *
  * It can be passed to g_hash_table_new() as the @hash_func parameter,
  * when using non-%NULL strings as keys in a #GHashTable.
@@ -27417,12 +26974,12 @@
 
 /**
  * g_str_is_ascii:
- * @string: a string.
+ * @str: a string
  *
- * Determines if a string is pure ASCII.  A string is pure ASCII if it
+ * Determines if a string is pure ASCII. A string is pure ASCII if it
  * contains no bytes with the high bit set.
  *
- * Returns: %TRUE if @string is ascii
+ * Returns: %TRUE if @str is ASCII
  * Since: 2.40
  */
 
@@ -27496,11 +27053,11 @@
  * @valid_chars: bytes permitted in @string
  * @substitutor: replacement character for disallowed bytes
  *
- * For each character in @string, if the character is not in
- * @valid_chars, replaces the character with @substitutor.
- * Modifies @string in place, and return @string itself, not
- * a copy. The return value is to allow nesting such as
- * |[
+ * For each character in @string, if the character is not in @valid_chars,
+ * replaces the character with @substitutor. Modifies @string in place,
+ * and return @string itself, not a copy. The return value is to allow
+ * nesting such as
+ * |[<!-- language="C" -->
  *   g_ascii_strup (g_strcanon (str, "abc", '?'))
  * ]|
  *
@@ -27510,16 +27067,16 @@
 
 /**
  * g_strcasecmp:
- * @s1: a string.
- * @s2: a string to compare with @s1.
+ * @s1: a string
+ * @s2: a string to compare with @s1
  *
  * A case-insensitive string comparison, corresponding to the standard
  * strcasecmp() function on platforms which support it.
  *
  * Returns: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *   or a positive value if @s1 &gt; @s2.
- * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this function
- *   is deprecated and how to replace it.
+ *     or a positive value if @s1 &gt; @s2.
+ * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this
+ *     function is deprecated and how to replace it.
  */
 
 
@@ -27592,17 +27149,16 @@
  * @string1: the first string to add, which must not be %NULL
  * @...: a %NULL-terminated list of strings to append to the string
  *
- * Concatenates all of the given strings into one long string.
- * The returned string should be freed with g_free() when no longer needed.
+ * Concatenates all of the given strings into one long string. The
+ * returned string should be freed with g_free() when no longer needed.
+ *
+ * The variable argument list must end with %NULL. If you forget the %NULL,
+ * g_strconcat() will start appending random memory junk to your string.
  *
  * Note that this function is usually not the right function to use to
  * assemble a translated message from pieces, since proper translation
  * often requires the pieces to be reordered.
  *
- * <warning><para>The variable argument list <emphasis>must</emphasis> end
- * with %NULL. If you forget the %NULL, g_strconcat() will start appending
- * random memory junk to your string.</para></warning>
- *
  * Returns: a newly-allocated string containing all the string arguments
  */
 
@@ -27610,8 +27166,8 @@
 /**
  * g_strdelimit:
  * @string: the string to convert
- * @delimiters: (allow-none): a string containing the current delimiters, or %NULL
- *     to use the standard delimiters defined in #G_STR_DELIMITERS
+ * @delimiters: (allow-none): a string containing the current delimiters,
+ *     or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS
  * @new_delimiter: the new delimiter character
  *
  * Converts any delimiter characters in @string to @new_delimiter.
@@ -27619,7 +27175,7 @@
  * changed to the @new_delimiter character. Modifies @string in place,
  * and returns @string itself, not a copy. The return value is to
  * allow nesting such as
- * |[
+ * |[<!-- language="C" -->
  *   g_ascii_strup (g_strdelimit (str, "abc", '?'))
  * ]|
  *
@@ -28359,7 +27915,8 @@
 
 /**
  * g_strjoin:
- * @separator: (allow-none): a string to insert between each of the strings, or %NULL
+ * @separator: (allow-none): a string to insert between each of the
+ *     strings, or %NULL
  * @...: a %NULL-terminated list of strings to join
  *
  * Joins a number of strings together to form one long string, with the
@@ -28373,7 +27930,8 @@
 
 /**
  * g_strjoinv:
- * @separator: (allow-none): a string to insert between each of the strings, or %NULL
+ * @separator: (allow-none): a string to insert between each of the
+ *     strings, or %NULL
  * @str_array: a %NULL-terminated array of strings to join
  *
  * Joins a number of strings together to form one long string, with the
@@ -28397,19 +27955,18 @@
  * guaranteeing nul-termination for @dest. The total size of @dest won't
  * exceed @dest_size.
  *
- * At most dest_size - 1 characters will be copied.
- * Unlike strncat, dest_size is the full size of dest, not the space left over.
- * This function does NOT allocate memory.
- * This always NUL terminates (unless siz == 0 or there were no NUL characters
- * in the dest_size characters of dest to start with).
+ * At most @dest_size - 1 characters will be copied. Unlike strncat(),
+ * @dest_size is the full size of dest, not the space left over. This
+ * function does not allocate memory. It always nul-terminates (unless
+ * @dest_size == 0 or there were no nul characters in the @dest_size
+ * characters of dest to start with).
  *
- * <note><para>Caveat: this is supposedly a more secure alternative to
- * strcat() or strncat(), but for real security g_strconcat() is harder
- * to mess up.</para></note>
+ * Caveat: this is supposedly a more secure alternative to strcat() or
+ * strncat(), but for real security g_strconcat() is harder to mess up.
  *
  * Returns: size of attempted result, which is MIN (dest_size, strlen
- *          (original dest)) + strlen (src), so if retval >= dest_size,
- *          truncation occurred.
+ *     (original dest)) + strlen (src), so if retval >= dest_size,
+ *     truncation occurred.
  */
 
 
@@ -28422,17 +27979,17 @@
  * Portability wrapper that calls strlcpy() on systems which have it,
  * and emulates strlcpy() otherwise. Copies @src to @dest; @dest is
  * guaranteed to be nul-terminated; @src must be nul-terminated;
- * @dest_size is the buffer size, not the number of chars to copy.
+ * @dest_size is the buffer size, not the number of bytes to copy.
  *
- * At most dest_size - 1 characters will be copied. Always nul-terminates
- * (unless dest_size == 0). This function does <emphasis>not</emphasis>
- * allocate memory. Unlike strncpy(), this function doesn't pad dest (so
- * it's often faster). It returns the size of the attempted result,
- * strlen (src), so if @retval >= @dest_size, truncation occurred.
+ * At most @dest_size - 1 characters will be copied. Always nul-terminates
+ * (unless @dest_size is 0). This function does not allocate memory. Unlike
+ * strncpy(), this function doesn't pad @dest (so it's often faster). It
+ * returns the size of the attempted result, strlen (src), so if
+ * @retval >= @dest_size, truncation occurred.
  *
- * <note><para>Caveat: strlcpy() is supposedly more secure than
- * strcpy() or strncpy(), but if you really want to avoid screwups,
- * g_strdup() is an even better idea.</para></note>
+ * Caveat: strlcpy() is supposedly more secure than strcpy() or strncpy(),
+ * but if you really want to avoid screwups, g_strdup() is an even better
+ * idea.
  *
  * Returns: length of @src
  */
@@ -28440,31 +27997,31 @@
 
 /**
  * g_strncasecmp:
- * @s1: a string.
- * @s2: a string to compare with @s1.
- * @n: the maximum number of characters to compare.
+ * @s1: a string
+ * @s2: a string to compare with @s1
+ * @n: the maximum number of characters to compare
  *
  * A case-insensitive string comparison, corresponding to the standard
- * strncasecmp() function on platforms which support it.
- * It is similar to g_strcasecmp() except it only compares the first @n
- * characters of the strings.
+ * strncasecmp() function on platforms which support it. It is similar
+ * to g_strcasecmp() except it only compares the first @n characters of
+ * the strings.
  *
  * Returns: 0 if the strings match, a negative value if @s1 &lt; @s2,
- *   or a positive value if @s1 &gt; @s2.
- * Deprecated: 2.2: The problem with g_strncasecmp() is that it does the
- * comparison by calling toupper()/tolower(). These functions are
- * locale-specific and operate on single bytes. However, it is impossible
- * to handle things correctly from an I18N standpoint by operating on
- * bytes, since characters may be multibyte. Thus g_strncasecmp() is
- * broken if your string is guaranteed to be ASCII, since it's
- * locale-sensitive, and it's broken if your string is localized, since
- * it doesn't work on many encodings at all, including UTF-8, EUC-JP,
- * etc.
+ *     or a positive value if @s1 &gt; @s2.
+ * Deprecated: 2.2: The problem with g_strncasecmp() is that it does
+ *     the comparison by calling toupper()/tolower(). These functions
+ *     are locale-specific and operate on single bytes. However, it is
+ *     impossible to handle things correctly from an internationalization
+ *     standpoint by operating on bytes, since characters may be multibyte.
+ *     Thus g_strncasecmp() is broken if your string is guaranteed to be
+ *     ASCII, since it is locale-sensitive, and it's broken if your string
+ *     is localized, since it doesn't work on many encodings at all,
+ *     including UTF-8, EUC-JP, etc.
  *
- * There are therefore two replacement techniques: g_ascii_strncasecmp(),
- * which only works on ASCII and is not locale-sensitive, and
- * g_utf8_casefold() followed by strcmp() on the resulting strings, which is
- * good for case-insensitive sorting of UTF-8.
+ *     There are therefore two replacement techniques: g_ascii_strncasecmp(),
+ *     which only works on ASCII and is not locale-sensitive, and
+ *     g_utf8_casefold() followed by strcmp() on the resulting strings,
+ *     which is good for case-insensitive sorting of UTF-8.
  */
 
 
@@ -28474,18 +28031,16 @@
  * @n: the maximum number of bytes to copy from @str
  *
  * Duplicates the first @n bytes of a string, returning a newly-allocated
- * buffer @n + 1 bytes long which will always be nul-terminated.
- * If @str is less than @n bytes long the buffer is padded with nuls.
- * If @str is %NULL it returns %NULL.
- * The returned value should be freed when no longer needed.
+ * buffer @n + 1 bytes long which will always be nul-terminated. If @str
+ * is less than @n bytes long the buffer is padded with nuls. If @str is
+ * %NULL it returns %NULL. The returned value should be freed when no longer
+ * needed.
  *
- * <note><para>
- * To copy a number of characters from a UTF-8 encoded string, use
- * g_utf8_strncpy() instead.
- * </para></note>
+ * To copy a number of characters from a UTF-8 encoded string,
+ * use g_utf8_strncpy() instead.
  *
  * Returns: a newly-allocated buffer containing the first @n bytes
- *          of @str, nul-terminated
+ *     of @str, nul-terminated
  */
 
 
@@ -28506,8 +28061,7 @@
  * @string: the string to reverse
  *
  * Reverses all of the bytes in a string. For example,
- * <literal>g_strreverse ("abcdef")</literal> will result
- * in "fedcba".
+ * `g_strreverse ("abcdef")` will result in "fedcba".
  *
  * Note that g_strreverse() doesn't work on UTF-8 strings
  * containing multibyte characters. For that purpose, use
@@ -28547,8 +28101,7 @@
 
 /**
  * g_strsignal:
- * @signum: the signal number. See the <literal>signal</literal>
- *     documentation
+ * @signum: the signal number. See the `signal` documentation
  *
  * Returns a string describing the given signal, e.g. "Segmentation fault".
  * You should use this function in preference to strsignal(), because it
@@ -28673,13 +28226,14 @@
 
 /**
  * g_strup:
- * @string: the string to convert.
+ * @string: the string to convert
  *
  * Converts a string to upper case.
  *
  * Returns: the string
- * Deprecated: 2.2: This function is totally broken for the reasons discussed
- * in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
+ * Deprecated: 2.2: This function is totally broken for the reasons
+ *     discussed in the g_strncasecmp() docs - use g_ascii_strup()
+ *     or g_utf8_strup() instead.
  */
 
 
@@ -28729,8 +28283,7 @@
  *
  * If @testpath includes the component "subprocess" anywhere in it,
  * the test will be skipped by default, and only run if explicitly
- * required via the <option>-p</option> command-line option or
- * g_test_trap_subprocess().
+ * required via the `-p` command-line option or g_test_trap_subprocess().
  *
  * Since: 2.16
  */
@@ -28762,8 +28315,7 @@
  *
  * If @testpath includes the component "subprocess" anywhere in it,
  * the test will be skipped by default, and only run if explicitly
- * required via the <option>-p</option> command-line option or
- * g_test_trap_subprocess().
+ * required via the `-p` command-line option or g_test_trap_subprocess().
  *
  * Since: 2.16
  */
@@ -28910,7 +28462,7 @@
  *
  * For example:
  *
- * |[
+ * |[<!-- language="C" -->
  *   /&ast; g_main_context_push_thread_default() should fail if the
  *    &ast; context is already owned by another thread.
  *    &ast;/
@@ -29047,88 +28599,38 @@
  * @argv: Address of the @argv parameter of main().
  *        Any parameters understood by g_test_init() stripped before return.
  * @...: %NULL-terminated list of special options. Currently the only
- *       defined option is <literal>"no_g_set_prgname"</literal>, which
+ *       defined option is `"no_g_set_prgname"`, which
  *       will cause g_test_init() to not call g_set_prgname().
  *
  * Initialize the GLib testing framework, e.g. by seeding the
  * test random number generator, the name for g_get_prgname()
  * and parsing test related command line args.
+ *
  * So far, the following arguments are understood:
- * <variablelist>
- *   <varlistentry>
- *     <term><option>-l</option></term>
- *     <listitem><para>
- *       List test cases available in a test executable.
- *     </para></listitem>
- *   </varlistentry>
- *   <varlistentry>
- *     <term><option>--seed=<replaceable>RANDOMSEED</replaceable></option></term>
- *     <listitem><para>
- *       Provide a random seed to reproduce test runs using random numbers.
- *     </para></listitem>
- *     </varlistentry>
- *     <varlistentry>
- *       <term><option>--verbose</option></term>
- *       <listitem><para>Run tests verbosely.</para></listitem>
- *     </varlistentry>
- *     <varlistentry>
- *       <term><option>-q</option>, <option>--quiet</option></term>
- *       <listitem><para>Run tests quietly.</para></listitem>
- *     </varlistentry>
- *     <varlistentry>
- *       <term><option>-p <replaceable>TESTPATH</replaceable></option></term>
- *       <listitem><para>
- *         Execute all tests matching <replaceable>TESTPATH</replaceable>.
- *         This can also be used to force a test to run that would otherwise
- *         be skipped (ie, a test whose name contains "/subprocess").
- *       </para></listitem>
- *     </varlistentry>
- *     <varlistentry>
- *       <term><option>-m {perf|slow|thorough|quick|undefined|no-undefined}</option></term>
- *       <listitem><para>
- *         Execute tests according to these test modes:
- *         <variablelist>
- *           <varlistentry>
- *             <term>perf</term>
- *             <listitem><para>
- *               Performance tests, may take long and report results.
- *             </para></listitem>
- *           </varlistentry>
- *           <varlistentry>
- *             <term>slow, thorough</term>
- *             <listitem><para>
- *               Slow and thorough tests, may take quite long and
- *               maximize coverage.
- *             </para></listitem>
- *           </varlistentry>
- *           <varlistentry>
- *             <term>quick</term>
- *             <listitem><para>
- *               Quick tests, should run really quickly and give good coverage.
- *             </para></listitem>
- *           </varlistentry>
- *           <varlistentry>
- *             <term>undefined</term>
- *             <listitem><para>
- *               Tests for undefined behaviour, may provoke programming errors
- *               under g_test_trap_subprocess() or g_test_expect_messages() to check
- *               that appropriate assertions or warnings are given
- *             </para></listitem>
- *           </varlistentry>
- *           <varlistentry>
- *             <term>no-undefined</term>
- *             <listitem><para>
- *               Avoid tests for undefined behaviour
- *             </para></listitem>
- *           </varlistentry>
- *         </variablelist>
- *       </para></listitem>
- *     </varlistentry>
- *     <varlistentry>
- *       <term><option>--debug-log</option></term>
- *       <listitem><para>Debug test logging output.</para></listitem>
- *     </varlistentry>
- *  </variablelist>
+ *
+ * - `-l`: List test cases available in a test executable.
+ * - `--seed=SEED`: Provide a random seed to reproduce test
+ *   runs using random numbers.
+ * - `--verbose`: Run tests verbosely.
+ * - `-q`, `--quiet`: Run tests quietly.
+ * - `-p PATH`: Execute all tests matching the given path.
+ *   This can also be used to force a test to run that would otherwise
+ *   be skipped (ie, a test whose name contains "/subprocess").
+ * - `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes:
+ *
+ *   `perf`: Performance tests, may take long and report results.
+ *
+ *   `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage.
+ *
+ *   `quick`: Quick tests, should run really quickly and give good coverage.
+ *
+ *   `undefined`: Tests for undefined behaviour, may provoke programming errors
+ *   under g_test_trap_subprocess() or g_test_expect_messages() to check
+ *   that appropriate assertions or warnings are given
+ *
+ *   `no-undefined`: Avoid tests for undefined behaviour
+ *
+ * - `--debug-log`: Debug test logging output.
  *
  * Since: 2.16
  */
@@ -29387,15 +28889,13 @@
  *
  * Runs all tests under the toplevel suite which can be retrieved
  * with g_test_get_root(). Similar to g_test_run_suite(), the test
- * cases to be run are filtered according to
- * test path arguments (-p <replaceable>testpath</replaceable>) as
- * parsed by g_test_init().
- * g_test_run_suite() or g_test_run() may only be called once
- * in a program.
+ * cases to be run are filtered according to test path arguments
+ * (`-p testpath`) as parsed by g_test_init(). g_test_run_suite()
+ * or g_test_run() may only be called once in a program.
  *
  * In general, the tests and sub-suites within each suite are run in
  * the order in which they are defined. However, note that prior to
- * GLib 2.36, there was a bug in the <literal>g_test_add_*</literal>
+ * GLib 2.36, there was a bug in the `g_test_add_*`
  * functions which caused them to create multiple suites with the same
  * name, meaning that if you created tests "/foo/simple",
  * "/bar/simple", and "/foo/using-bar" in that order, they would get
@@ -29427,9 +28927,9 @@
  *
  * Execute the tests within @suite and all nested #GTestSuites.
  * The test suites to be executed are filtered according to
- * test path arguments (-p <replaceable>testpath</replaceable>)
- * as parsed by g_test_init(). See the g_test_run() documentation
- * for more information on the order that tests are run in.
+ * test path arguments (`-p testpath`) as parsed by g_test_init().
+ * See the g_test_run() documentation for more information on the
+ * order that tests are run in.
  *
  * g_test_run_suite() or g_test_run() may only be called once
  * in a program.
@@ -29661,7 +29161,7 @@
  * The forking parent process then asserts successful child program
  * termination and validates child program outputs.
  *
- * |[
+ * |[<!-- language="C" -->
  *   static void
  *   test_fork_patterns (void)
  *   {
@@ -29719,12 +29219,11 @@
  * You can use g_test_subprocess() to determine whether the test is in
  * a subprocess or not.
  *
- * @test_path can also be the name of the parent
- * test, followed by "<literal>/subprocess/</literal>" and then a name
- * for the specific subtest (or just ending with
- * "<literal>/subprocess</literal>" if the test only has one child
- * test); tests with names of this form will automatically be skipped
- * in the parent process.
+ * @test_path can also be the name of the parent test, followed by
+ * "`/subprocess/`" and then a name for the specific subtest (or just
+ * ending with "`/subprocess`" if the test only has one child test);
+ * tests with names of this form will automatically be skipped in the
+ * parent process.
  *
  * If @usec_timeout is non-0, the test subprocess is aborted and
  * considered failing if its run time exceeds it.
@@ -29739,15 +29238,15 @@
  * cannot be used if @test_flags specifies that the child should
  * inherit the parent stdout/stderr.)
  *
- * If your <literal>main ()</literal> needs to behave differently in
+ * If your `main ()` needs to behave differently in
  * the subprocess, you can call g_test_subprocess() (after calling
  * g_test_init()) to see whether you are in a subprocess.
  *
  * The following example tests that calling
- * <literal>my_object_new(1000000)</literal> will abort with an error
+ * `my_object_new(1000000)` will abort with an error
  * message.
  *
- * |[
+ * |[<!-- language="C" -->
  *   static void
  *   test_create_large_object_subprocess (void)
  *   {
@@ -29809,15 +29308,13 @@
  * waiting thread will be woken up and get @retval as the return value
  * of g_thread_join().
  *
- * Calling <literal>g_thread_exit (retval)</literal> is equivalent to
+ * Calling g_thread_exit() with a parameter @retval is equivalent to
  * returning @retval from the function @func, as given to g_thread_new().
  *
- * <note><para>
- *   You must only call g_thread_exit() from a thread that you created
- *   yourself with g_thread_new() or related APIs.  You must not call
- *   this function from a thread created with another threading library
- *   or or from within a #GThreadPool.
- * </para></note>
+ * You must only call g_thread_exit() from a thread that you created
+ * yourself with g_thread_new() or related APIs. You must not call
+ * this function from a thread created with another threading library
+ * or or from within a #GThreadPool.
  */
 
 
@@ -30248,11 +29745,11 @@
  * "YYYY-MM-DDTHH:MM:SSZ" or "YYYY-MM-DDTHH:MM:SS.fffffZ".
  *
  * This corresponds to the Internet date/time format defined by
- * <ulink url="https://www.ietf.org/rfc/rfc3339.txt">RFC 3339</ulink>, and
- * to either of the two most-precise formats defined by
- * <ulink url="http://www.w3.org/TR/NOTE-datetime-19980827">the W3C Note
- * "Date and Time Formats"</ulink>. Both of these documents are profiles of
- * ISO 8601.
+ * [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt),
+ * and to either of the two most-precise formats defined by
+ * the W3C Note
+ * [Date and Time Formats](http://www.w3.org/TR/NOTE-datetime-19980827).
+ * Both of these documents are profiles of ISO 8601.
  *
  * Use g_date_time_format() or g_strdup_printf() if a different
  * variation of ISO 8601 format is required.
@@ -30375,29 +29872,29 @@
  * Creates a #GTimeZone corresponding to @identifier.
  *
  * @identifier can either be an RFC3339/ISO 8601 time offset or
- * something that would pass as a valid value for the
- * <varname>TZ</varname> environment variable (including %NULL).
+ * something that would pass as a valid value for the `TZ` environment
+ * variable (including %NULL).
  *
  * In Windows, @identifier can also be the unlocalized name of a time
  * zone for standard time, for example "Pacific Standard Time".
  *
- * Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or
- * <literal>"±hh:mm"</literal>.  ISO 8601 additionally specifies
- * <literal>"±hhmm"</literal> and <literal>"±hh"</literal>.  Offsets are
+ * Valid RFC3339 time offsets are `"Z"` (for UTC) or
+ * `"±hh:mm"`.  ISO 8601 additionally specifies
+ * `"±hhmm"` and `"±hh"`.  Offsets are
  * time values to be added to Coordinated Universal Time (UTC) to get
  * the local time.
  *
- * In Unix, the <varname>TZ</varname> environment variable typically
- * corresponds to the name of a file in the zoneinfo database, or
- * string in "std offset [dst [offset],start[/time],end[/time]]"
- * (POSIX) format.  There  are  no spaces in the specification.  The
- * name of standard and daylight savings time zone must be three or more
- * alphabetic characters.  Offsets are time values to be added to local
- * time to get Coordinated Universal Time (UTC) and should be
- * <literal>"[±]hh[[:]mm[:ss]]"</literal>.  Dates are either
- * <literal>"Jn"</literal> (Julian day with n between 1 and 365, leap
- * years not counted), <literal>"n"</literal> (zero-based Julian day
- * with n between 0 and 365) or <literal>"Mm.w.d"</literal> (day d
+ * In UNIX, the `TZ` environment variable typically corresponds
+ * to the name of a file in the zoneinfo database, or string in
+ * "std offset [dst [offset],start[/time],end[/time]]" (POSIX) format.
+ * There  are  no spaces in the specification. The name of standard
+ * and daylight savings time zone must be three or more alphabetic
+ * characters. Offsets are time values to be added to local time to
+ * get Coordinated Universal Time (UTC) and should be
+ * `"[±]hh[[:]mm[:ss]]"`.  Dates are either
+ * `"Jn"` (Julian day with n between 1 and 365, leap
+ * years not counted), `"n"` (zero-based Julian day
+ * with n between 0 and 365) or `"Mm.w.d"` (day d
  * (0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day
  * 0 is a Sunday).  Times are in local wall clock time, the default is
  * 02:00:00.
@@ -30410,30 +29907,28 @@
  * Coordinated Universal Time (UTC).
  *
  * g_time_zone_new_local() calls this function with the value of the
- * <varname>TZ</varname> environment variable.  This function itself is
- * independent of the value of <varname>TZ</varname>, but if @identifier
- * is %NULL then <filename>/etc/localtime</filename> will be consulted
- * to discover the correct time zone on Unix and the registry will be
- * consulted or GetTimeZoneInformation() will be used to get the local
- * time zone on Windows.
- *
- * If intervals are not available, only time zone rules from
- * <varname>TZ</varname> environment variable or other means, then they
- * will be computed from year 1900 to 2037.  If the maximum year for the
- * rules is available and it is greater than 2037, then it will followed
+ * `TZ` environment variable. This function itself is independent of
+ * the value of `TZ`, but if @identifier is %NULL then `/etc/localtime`
+ * will be consulted to discover the correct time zone on UNIX and the
+ * registry will be consulted or GetTimeZoneInformation() will be used
+ * to get the local time zone on Windows.
+ *
+ * If intervals are not available, only time zone rules from `TZ`
+ * environment variable or other means, then they will be computed
+ * from year 1900 to 2037.  If the maximum year for the rules is
+ * available and it is greater than 2037, then it will followed
  * instead.
  *
- * See <ulink
- * url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339
- * §5.6</ulink> for a precise definition of valid RFC3339 time offsets
- * (the <varname>time-offset</varname> expansion) and ISO 8601 for the
- * full list of valid time offsets.  See <ulink
- * url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The
- * GNU C Library manual</ulink> for an explanation of the possible
- * values of the <varname>TZ</varname> environment variable.  See <ulink
- * url='http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx'>
- * Microsoft Time Zone Index Values</ulink> for the list of time zones
- * on Windows.
+ * See
+ * [RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6)
+ * for a precise definition of valid RFC3339 time offsets
+ * (the `time-offset` expansion) and ISO 8601 for the
+ * full list of valid time offsets.  See
+ * [The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html)
+ * for an explanation of the possible
+ * values of the `TZ` environment variable. See
+ * [Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx)
+ * for the list of time zones on Windows.
  *
  * You should release the return value by calling g_time_zone_unref()
  * when you are done with it.
@@ -30450,9 +29945,8 @@
  * zone may change between invocations to this function; for example,
  * if the system administrator changes it.
  *
- * This is equivalent to calling g_time_zone_new() with the value of the
- * <varname>TZ</varname> environment variable (including the possibility
- * of %NULL).
+ * This is equivalent to calling g_time_zone_new() with the value of
+ * the `TZ` environment variable (including the possibility of %NULL).
  *
  * You should release the return value by calling g_time_zone_unref()
  * when you are done with it.
@@ -30878,7 +30372,7 @@
  * is O(log n) (where n is the number of key/value pairs in the tree).
  *
  * Returns: the value corresponding to the key, or %NULL
- *     if the key was not found.
+ *     if the key was not found
  */
 
 
@@ -31018,7 +30512,7 @@
  * pairs that have a larger key.
  *
  * Returns: the value corresponding to the found key, or %NULL
- *     if the key was not found.
+ *     if the key was not found
  */
 
 
@@ -31151,24 +30645,23 @@
  * g_ucs4_to_utf16:
  * @str: a UCS-4 encoded string
  * @len: the maximum length (number of characters) of @str to use.
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of bytes read, or %NULL.
- *              If an error occurs then the index of the invalid input
- *              is stored here.
- * @items_written: (allow-none): location to store number of <type>gunichar2</type>
- *                 written, or %NULL. The value stored here does not
- *                 include the trailing 0.
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of bytes read,
+ *     or %NULL. If an error occurs then the index of the invalid input
+ *     is stored here.
+ * @items_written: (allow-none): location to store number of #gunichar2
+ *     written, or %NULL. The value stored here does not include the
+ *     trailing 0.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UCS-4 to UTF-16. A 0 character will be
  * added to the result after the converted text.
  *
  * Returns: a pointer to a newly allocated UTF-16 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
  */
 
 
@@ -31176,11 +30669,12 @@
  * g_ucs4_to_utf8:
  * @str: a UCS-4 encoded string
  * @len: the maximum length (number of characters) of @str to use.
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of characters read, or %NULL.
- * @items_written: (allow-none): location to store number of bytes written or %NULL.
- *                 The value here stored does not include the trailing 0
- *                 byte.
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of characters
+ *     read, or %NULL.
+ * @items_written: (allow-none): location to store number of bytes
+ *     written or %NULL. The value here stored does not include the
+ *     trailing 0 byte.
  * @error: location to store the error occurring, or %NULL to ignore
  *         errors. Any of the errors in #GConvertError other than
  *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
@@ -31189,11 +30683,9 @@
  * to UTF-8. The result will be terminated with a 0 byte.
  *
  * Returns: a pointer to a newly allocated UTF-8 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set. In that case, @items_read will be
- *               set to the position of the first invalid input
- *               character.
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set. In that case, @items_read
+ *     will be set to the position of the first invalid input character.
  */
 
 
@@ -31242,7 +30734,8 @@
  *
  * If @a and @b do not compose a new character, @ch is set to zero.
  *
- * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
+ * See
+ * [UAX#15](http://unicode.org/reports/tr15/)
  * for details.
  *
  * Returns: %TRUE if the characters could be composed
@@ -31276,7 +30769,8 @@
  * recursively call this function on @a.  Or use
  * g_unichar_fully_decompose().
  *
- * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
+ * See
+ * [UAX#15](http://unicode.org/reports/tr15/)
  * for details.
  *
  * Returns: %TRUE if the character could be decomposed
@@ -31319,7 +30813,8 @@
  * decompositions, so that is the size recommended. This is provided
  * as %G_UNICHAR_MAX_DECOMPOSITION_LENGTH.
  *
- * See <ulink url="http://unicode.org/reports/tr15/">UAX#15</ulink>
+ * See
+ * [UAX#15](http://unicode.org/reports/tr15/)
  * for details.
  *
  * Returns: the length of the full decomposition.
@@ -31332,10 +30827,10 @@
  * @ch: a Unicode character
  * @mirrored_ch: location to store the mirrored character
  *
- * In Unicode, some characters are <firstterm>mirrored</firstterm>. This
- * means that their images are mirrored horizontally in text that is laid
- * out from right to left. For instance, "(" would become its mirror image,
- * ")", in right-to-left text.
+ * In Unicode, some characters are "mirrored". This means that their
+ * images are mirrored horizontally in text that is laid out from right
+ * to left. For instance, "(" would become its mirror image, ")", in
+ * right-to-left text.
  *
  * If @ch has the Unicode mirrored property and there is another unicode
  * character that typically has a glyph that is the mirror image of @ch's
@@ -31552,9 +31047,9 @@
  * Determines if a character is typically rendered in a double-width
  * cell under legacy East Asian locales.  If a character is wide according to
  * g_unichar_iswide(), then it is also reported wide with this function, but
- * the converse is not necessarily true.  See the
- * <ulink url="http://www.unicode.org/reports/tr11/">Unicode Standard
- * Annex #11</ulink> for details.
+ * the converse is not necessarily true. See the
+ * [Unicode Standard Annex #11](http://www.unicode.org/reports/tr11/)
+ * for details.
  *
  * If a character passes the g_unichar_iswide() test then it will also pass
  * this test, but not the other way around.  Note that some characters may
@@ -31713,8 +31208,9 @@
  * big-endian fashion.  That is, the code expected for Arabic is
  * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
  *
- * See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the
- * representation of names of scripts</ulink> for details.
+ * See
+ * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
+ * for details.
  *
  * Returns: the Unicode script for @iso15924, or
  *   of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and
@@ -31733,8 +31229,9 @@
  * big-endian fashion.  That is, the code returned for Arabic is
  * 0x41726162 (0x41 is ASCII code for 'A', 0x72 is ASCII code for 'r', etc).
  *
- * See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the
- * representation of names of scripts</ulink> for details.
+ * See
+ * [Codes for the representation of names of scripts](http://unicode.org/iso15924/codelists.html)
+ * for details.
  *
  * Returns: the ISO 15924 code for @script, encoded as an integer,
  *   of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or
@@ -31808,19 +31305,17 @@
 /**
  * g_unix_open_pipe:
  * @fds: Array of two integers
- * @flags: Bitfield of file descriptor flags, see "man 2 fcntl"
+ * @flags: Bitfield of file descriptor flags, as for fcntl()
  * @error: a #GError
  *
  * Similar to the UNIX pipe() call, but on modern systems like Linux
  * uses the pipe2() system call, which atomically creates a pipe with
- * the configured flags.  The only supported flag currently is
- * <literal>FD_CLOEXEC</literal>.  If for example you want to configure
- * <literal>O_NONBLOCK</literal>, that must still be done separately with
- * fcntl().
+ * the configured flags. The only supported flag currently is
+ * %FD_CLOEXEC. If for example you want to configure %O_NONBLOCK, that
+ * must still be done separately with fcntl().
  *
- * <note>This function does *not* take <literal>O_CLOEXEC</literal>, it takes
- * <literal>FD_CLOEXEC</literal> as if for fcntl(); these are
- * different on Linux/glibc.</note>
+ * This function does not take %O_CLOEXEC, it takes %FD_CLOEXEC as if
+ * for fcntl(); these are different on Linux/glibc.
  *
  * Returns: %TRUE on success, %FALSE if not (and errno will be set).
  * Since: 2.30
@@ -31834,8 +31329,8 @@
  * @error: a #GError
  *
  * Control the non-blocking state of the given file descriptor,
- * according to @nonblock.  On most systems this uses <literal>O_NONBLOCK</literal>, but
- * on some older ones may use <literal>O_NDELAY</literal>.
+ * according to @nonblock. On most systems this uses %O_NONBLOCK, but
+ * on some older ones may use %O_NDELAY.
  *
  * Returns: %TRUE if successful
  * Since: 2.30
@@ -31880,17 +31375,15 @@
  * @signum: A signal number
  *
  * Create a #GSource that will be dispatched upon delivery of the UNIX
- * signal @signum.  In GLib versions before 2.36, only
- * <literal>SIGHUP</literal>, <literal>SIGINT</literal>,
- * <literal>SIGTERM</literal> can be monitored.  In GLib 2.36,
- * <literal>SIGUSR1</literal> and <literal>SIGUSR2</literal> were
- * added.
+ * signal @signum.  In GLib versions before 2.36, only `SIGHUP`, `SIGINT`,
+ * `SIGTERM` can be monitored.  In GLib 2.36, `SIGUSR1` and `SIGUSR2`
+ * were added.
  *
  * Note that unlike the UNIX default, all sources which have created a
  * watch will be dispatched, regardless of which underlying thread
  * invoked g_unix_signal_source_new().
  *
- * For example, an effective use of this function is to handle <literal>SIGTERM</literal>
+ * For example, an effective use of this function is to handle `SIGTERM`
  * cleanly; flushing any outstanding files, and then calling
  * g_main_loop_quit ().  It is not safe to do any of this a regular
  * UNIX signal handler; your handler may be invoked while malloc() or
@@ -31938,20 +31431,18 @@
  * Note that on some systems, when variables are overwritten, the
  * memory used for the previous variables and its value isn't reclaimed.
  *
- * <warning><para>
- * Environment variable handling in UNIX is not thread-safe, and your
- * program may crash if one thread calls g_unsetenv() while another
- * thread is calling getenv(). (And note that many functions, such as
- * gettext(), call getenv() internally.) This function is only safe
- * to use at the very start of your program, before creating any other
- * threads (or creating objects that create worker threads of their
- * own).
- * </para><para>
+ * You should be mindful of the fact that environment variable handling
+ * in UNIX is not thread-safe, and your program may crash if one thread
+ * calls g_unsetenv() while another thread is calling getenv(). (And note
+ * that many functions, such as gettext(), call getenv() internally.) This
+ * function is only safe to use at the very start of your program, before
+ * creating any other threads (or creating objects that create worker
+ * threads of their own).
+ *
  * If you need to set up the environment for a child process, you can
  * use g_get_environ() to get an environment array, modify that with
  * g_environ_setenv() and g_environ_unsetenv(), and then pass that
  * array directly to execvpe(), g_spawn_async(), or the like.
- * </para></warning>
  *
  * Since: 2.4
  */
@@ -31999,9 +31490,9 @@
  * @uri: a valid URI.
  *
  * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
- * <programlisting>
+ * |[
  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
- * </programlisting>
+ * ]|
  * Common schemes include "file", "http", "svn+ssh", etc.
  *
  * Returns: The "Scheme" component of the URI, or %NULL on error.
@@ -32068,46 +31559,42 @@
 /**
  * g_utf16_to_ucs4:
  * @str: a UTF-16 encoded string
- * @len: the maximum length (number of <type>gunichar2</type>) of @str to use.
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of words read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of characters written, or %NULL.
- *                 The value stored here does not include the trailing
- *                 0 character.
+ * @len: the maximum length (number of #gunichar2) of @str to use.
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of words read,
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial character. If
+ *     an error occurs then the index of the invalid input is stored here.
+ * @items_written: (allow-none): location to store number of characters
+ *     written, or %NULL. The value stored here does not include the trailing
+ *     0 character.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-16 to UCS-4. The result will be
  * nul-terminated.
  *
  * Returns: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
  */
 
 
 /**
  * g_utf16_to_utf8:
  * @str: a UTF-16 encoded string
- * @len: the maximum length (number of <type>gunichar2</type>) of @str to use.
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of words read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of bytes written, or %NULL.
- *                 The value stored here does not include the trailing
- *                 0 byte.
+ * @len: the maximum length (number of #gunichar2) of @str to use.
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of words read,
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial character. If
+ *     an error occurs then the index of the invalid input is stored here.
+ * @items_written: (allow-none): location to store number of bytes written,
+ *     or %NULL. The value stored here does not include the trailing 0 byte.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-16 to UTF-8. The result will be
  * terminated with a 0 byte.
@@ -32124,9 +31611,8 @@
  * things unpaired surrogates.
  *
  * Returns: a pointer to a newly allocated UTF-8 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
  */
 
 
@@ -32218,7 +31704,7 @@
  * g_utf8_find_next_char:
  * @p: a pointer to a position within a UTF-8 encoded string
  * @end: a pointer to the byte following the end of the string,
- * or %NULL to indicate that the string is nul-terminated.
+ *     or %NULL to indicate that the string is nul-terminated
  *
  * Finds the start of the next UTF-8 character in the string after @p.
  *
@@ -32252,8 +31738,9 @@
  * @p: a pointer to Unicode character encoded as UTF-8
  *
  * Converts a sequence of bytes encoded as UTF-8 to a Unicode character.
- * If @p does not point to a valid UTF-8 encoded character, results are
- * undefined. If you are not sure that the bytes are complete
+ *
+ * If @p does not point to a valid UTF-8 encoded character, results
+ * are undefined. If you are not sure that the bytes are complete
  * valid Unicode characters, you should use g_utf8_get_char_validated()
  * instead.
  *
@@ -32265,7 +31752,7 @@
  * g_utf8_get_char_validated:
  * @p: a pointer to Unicode character encoded as UTF-8
  * @max_len: the maximum number of bytes to read, or -1, for no maximum or
- *           if @p is nul-terminated
+ *     if @p is nul-terminated
  *
  * Convert a sequence of bytes encoded as UTF-8 to a Unicode character.
  * This function checks for incomplete characters, for invalid characters
@@ -32273,10 +31760,10 @@
  * overlong encodings of valid characters.
  *
  * Returns: the resulting character. If @p points to a partial
- *    sequence at the end of a string that could begin a valid
- *    character (or if @max_len is zero), returns (gunichar)-2;
- *    otherwise, if @p does not point to a valid UTF-8 encoded
- *    Unicode character, returns (gunichar)-1.
+ *     sequence at the end of a string that could begin a valid
+ *     character (or if @max_len is zero), returns (gunichar)-2;
+ *     otherwise, if @p does not point to a valid UTF-8 encoded
+ *     Unicode character, returns (gunichar)-1.
  */
 
 
@@ -32331,14 +31818,11 @@
  * instead of forwards if @offset is in the last fourth of the string,
  * since moving forward is about 3 times faster than moving backward.
  *
- * <note><para>
- * This function doesn't abort when reaching the end of @str. Therefore
- * you should be sure that @offset is within string boundaries before
- * calling that function. Call g_utf8_strlen() when unsure.
- *
+ * Note that this function doesn't abort when reaching the end of @str.
+ * Therefore you should be sure that @offset is within string boundaries
+ * before calling that function. Call g_utf8_strlen() when unsure.
  * This limitation exists as this function is called frequently during
  * text rendering and therefore has to be as fast as possible.
- * </para></note>
  *
  * Returns: the resulting pointer
  */
@@ -32370,7 +31854,7 @@
  * it starts with an appropriate byte. If @p might be the first
  * character of the string, you must use g_utf8_find_prev_char() instead.
  *
- * Returns: a pointer to the found character.
+ * Returns: a pointer to the found character
  */
 
 
@@ -32385,8 +31869,8 @@
  * If @len is -1, allow unbounded search.
  *
  * Returns: %NULL if the string does not contain the character,
- *   otherwise, a pointer to the start of the leftmost occurrence of
- *   the character in the string.
+ *     otherwise, a pointer to the start of the leftmost occurrence
+ *     of the character in the string.
  */
 
 
@@ -32428,11 +31912,10 @@
  * @src: UTF-8 encoded string
  * @n: character count
  *
- * Like the standard C strncpy() function, but
- * copies a given number of characters instead of a given number of
- * bytes. The @src string must be valid UTF-8 encoded text.
- * (Use g_utf8_validate() on all text before trying to use UTF-8
- * utility functions with it.)
+ * Like the standard C strncpy() function, but copies a given number
+ * of characters instead of a given number of bytes. The @src string
+ * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
+ * text before trying to use UTF-8 utility functions with it.)
  *
  * Returns: @dest
  */
@@ -32449,8 +31932,8 @@
  * If @len is -1, allow unbounded search.
  *
  * Returns: %NULL if the string does not contain the character,
- *   otherwise, a pointer to the start of the rightmost occurrence of the
- *   character in the string.
+ *     otherwise, a pointer to the start of the rightmost occurrence
+ *     of the character in the string.
  */
 
 
@@ -32458,7 +31941,7 @@
  * g_utf8_strreverse:
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
- *       then the string is nul-terminated.
+ *     then the string is nul-terminated.
  *
  * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text.
  * (Use g_utf8_validate() on all text before trying to use UTF-8
@@ -32474,7 +31957,7 @@
  * newly-allocated memory, which should be freed with g_free() when
  * no longer needed.
  *
- * Returns: a newly-allocated string which is the reverse of @str.
+ * Returns: a newly-allocated string which is the reverse of @str
  * Since: 2.2
  */
 
@@ -32502,8 +31985,7 @@
  * @end_pos: another character offset within @str
  *
  * Copies a substring out of a UTF-8 encoded string.
- * The substring will contain @end_pos - @start_pos
- * characters.
+ * The substring will contain @end_pos - @start_pos characters.
  *
  * Returns: a newly allocated copy of the requested
  *     substring. Free with g_free() when no longer needed.
@@ -32515,27 +31997,26 @@
  * g_utf8_to_ucs4:
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
- *       then the string is nul-terminated.
+ *     then the string is nul-terminated.
  * @items_read: (allow-none): location to store number of bytes read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of characters written or %NULL.
- *                 The value here stored does not include the trailing 0
- *                 character.
+ *     If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial
+ *     character. If an error occurs then the index of the
+ *     invalid input is stored here.
+ * @items_written: (allow-none): location to store number of characters
+ *     written or %NULL. The value here stored does not include the
+ *     trailing 0 character.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-8 to a 32-bit fixed width
  * representation as UCS-4. A trailing 0 character will be added to the
  * string after the converted text.
  *
  * Returns: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
  */
 
 
@@ -32543,9 +32024,9 @@
  * g_utf8_to_ucs4_fast:
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
- *       then the string is nul-terminated.
- * @items_written: (allow-none): location to store the number of characters in the
- *                 result, or %NULL.
+ *     then the string is nul-terminated.
+ * @items_written: (allow-none): location to store the number of
+ *     characters in the result, or %NULL.
  *
  * Convert a string from UTF-8 to a 32-bit fixed width
  * representation as UCS-4, assuming valid UTF-8 input.
@@ -32554,7 +32035,7 @@
  * will be added to the string after the converted text.
  *
  * Returns: a pointer to a newly allocated UCS-4 string.
- *               This value must be freed with g_free().
+ *     This value must be freed with g_free().
  */
 
 
@@ -32562,26 +32043,24 @@
  * g_utf8_to_utf16:
  * @str: a UTF-8 encoded string
  * @len: the maximum length (number of bytes) of @str to use.
- *       If @len < 0, then the string is nul-terminated.
- * @items_read: (allow-none): location to store number of bytes read, or %NULL.
- *              If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
- *              returned in case @str contains a trailing partial
- *              character. If an error occurs then the index of the
- *              invalid input is stored here.
- * @items_written: (allow-none): location to store number of <type>gunichar2</type> written,
- *                 or %NULL.
- *                 The value stored here does not include the trailing 0.
+ *     If @len < 0, then the string is nul-terminated.
+ * @items_read: (allow-none): location to store number of bytes read,
+ *     or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
+ *     returned in case @str contains a trailing partial character. If
+ *     an error occurs then the index of the invalid input is stored here.
+ * @items_written: (allow-none): location to store number of #gunichar2
+ *     written, or %NULL. The value stored here does not include the
+ *     trailing 0.
  * @error: location to store the error occurring, or %NULL to ignore
- *         errors. Any of the errors in #GConvertError other than
- *         %G_CONVERT_ERROR_NO_CONVERSION may occur.
+ *     errors. Any of the errors in #GConvertError other than
+ *     %G_CONVERT_ERROR_NO_CONVERSION may occur.
  *
  * Convert a string from UTF-8 to UTF-16. A 0 character will be
  * added to the result after the converted text.
  *
  * Returns: a pointer to a newly allocated UTF-16 string.
- *               This value must be freed with g_free(). If an
- *               error occurs, %NULL will be returned and
- *               @error set.
+ *     This value must be freed with g_free(). If an error occurs,
+ *     %NULL will be returned and @error set.
  */
 
 
@@ -32600,12 +32079,12 @@
  * being validated otherwise).
  *
  * Note that g_utf8_validate() returns %FALSE if @max_len is
- * positive and any of the @max_len bytes are NUL.
+ * positive and any of the @max_len bytes are nul.
  *
  * Returns %TRUE if all of @str was valid. Many GLib and GTK+
- * routines <emphasis>require</emphasis> valid UTF-8 as input;
- * so data read from a file or the network should be checked
- * with g_utf8_validate() before doing anything else with it.
+ * routines require valid UTF-8 as input; so data read from a file
+ * or the network should be checked with g_utf8_validate() before
+ * doing anything else with it.
  *
  * Returns: %TRUE if the text was valid UTF-8
  */
@@ -32622,8 +32101,7 @@
  * See your C library manual for more details about how utime() works
  * on your system.
  *
- * Returns: 0 if the operation was successful, -1 if an error
- *    occurred
+ * Returns: 0 if the operation was successful, -1 if an error occurred
  * Since: 2.18
  */
 
@@ -32639,9 +32117,13 @@
  * This call is a convenience wrapper that is exactly equivalent to
  * calling g_variant_new() followed by g_variant_builder_add_value().
  *
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format_string. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * This function might be used as follows:
  *
- * |[
+ * |[<!-- language="C" -->
  * GVariant *
  * make_pointless_dictionary (void)
  * {
@@ -32677,9 +32159,13 @@
  * calling g_variant_new_parsed() followed by
  * g_variant_builder_add_value().
  *
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format_string. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * This function might be used as follows:
  *
- * |[
+ * |[<!-- language="C" -->
  * GVariant *
  * make_pointless_dictionary (void)
  * {
@@ -32975,6 +32461,224 @@
 
 
 /**
+ * g_variant_dict_clear:
+ * @dict: a #GVariantDict
+ *
+ * Releases all memory associated with a #GVariantDict without freeing
+ * the #GVariantDict structure itself.
+ *
+ * It typically only makes sense to do this on a stack-allocated
+ * #GVariantDict if you want to abort building the value part-way
+ * through.  This function need not be called if you call
+ * g_variant_dict_end() and it also doesn't need to be called on dicts
+ * allocated with g_variant_dict_new (see g_variant_dict_unref() for
+ * that).
+ *
+ * It is valid to call this function on either an initialised
+ * #GVariantDict or one that was previously cleared by an earlier call
+ * to g_variant_dict_clear() but it is not valid to call this function
+ * on uninitialised memory.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_contains:
+ * @dict: a #GVariantDict
+ * @key: the key to lookup in the dictionary
+ *
+ * Checks if @key exists in @dict.
+ *
+ * Returns: %TRUE if @key is in @dict
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_end:
+ * @dict: a #GVariantDict
+ *
+ * Returns the current value of @dict as a #GVariant of type
+ * %G_VARIANT_TYPE_VARDICT, clearing it in the process.
+ *
+ * It is not permissible to use @dict in any way after this call except
+ * for reference counting operations (in the case of a heap-allocated
+ * #GVariantDict) or by reinitialising it with g_variant_dict_init() (in
+ * the case of stack-allocated).
+ *
+ * Returns: (transfer none): a new, floating, #GVariant
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_init: (skip)
+ * @dict: a #GVariantDict
+ * @from_asv: (allow-none): the initial value for @dict
+ *
+ * Initialises a #GVariantDict structure.
+ *
+ * If @from_asv is given, it is used to initialise the dictionary.
+ *
+ * This function completely ignores the previous contents of @dict.  On
+ * one hand this means that it is valid to pass in completely
+ * uninitialised memory.  On the other hand, this means that if you are
+ * initialising over top of an existing #GVariantDict you need to first
+ * call g_variant_dict_clear() in order to avoid leaking memory.
+ *
+ * You must not call g_variant_dict_ref() or g_variant_dict_unref() on a
+ * #GVariantDict that was initialised with this function.  If you ever
+ * pass a reference to a #GVariantDict outside of the control of your
+ * own code then you should assume that the person receiving that
+ * reference may try to use reference counting; you should use
+ * g_variant_dict_new() instead of this function.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_insert:
+ * @dict: a #GVariantDict
+ * @key: the key to insert a value for
+ * @format_string: a #GVariant varargs format string
+ * @...: arguments, as per @format_string
+ *
+ * Inserts a value into a #GVariantDict.
+ *
+ * This call is a convenience wrapper that is exactly equivalent to
+ * calling g_variant_new() followed by g_variant_dict_insert_value().
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_insert_value:
+ * @dict: a #GVariantDict
+ * @key: the key to insert a value for
+ * @value: the value to insert
+ *
+ * Inserts (or replaces) a key in a #GVariantDict.
+ *
+ * @value is consumed if it is floating.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_lookup:
+ * @dict: a #GVariantDict
+ * @key: the key to lookup in the dictionary
+ * @format_string: a GVariant format string
+ * @...: the arguments to unpack the value into
+ *
+ * Looks up a value in a #GVariantDict.
+ *
+ * This function is a wrapper around g_variant_dict_lookup_value() and
+ * g_variant_get().  In the case that %NULL would have been returned,
+ * this function returns %FALSE.  Otherwise, it unpacks the returned
+ * value and returns %TRUE.
+ *
+ * @format_string determines the C types that are used for unpacking
+ * the values and also determines if the values are copied or borrowed,
+ * see the section on
+ * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ *
+ * Returns: %TRUE if a value was unpacked
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_lookup_value:
+ * @dict: a #GVariantDict
+ * @key: the key to lookup in the dictionary
+ * @expected_type: (allow-none): a #GVariantType, or %NULL
+ *
+ * Looks up a value in a #GVariantDict.
+ *
+ * If @key is not found in @dictionary, %NULL is returned.
+ *
+ * The @expected_type string specifies what type of value is expected.
+ * If the value associated with @key has a different type then %NULL is
+ * returned.
+ *
+ * If the key is found and the value has the correct type, it is
+ * returned.  If @expected_type was specified then any non-%NULL return
+ * value will have this type.
+ *
+ * Returns: (transfer full): the value of the dictionary key, or %NULL
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_new:
+ * @from_asv: (allow-none): the #GVariant with which to initialise the
+ *   dictionary
+ *
+ * Allocates and initialises a new #GVariantDict.
+ *
+ * You should call g_variant_dict_unref() on the return value when it
+ * is no longer needed.  The memory will not be automatically freed by
+ * any other call.
+ *
+ * In some cases it may be easier to place a #GVariantDict directly on
+ * the stack of the calling function and initialise it with
+ * g_variant_dict_init().  This is particularly useful when you are
+ * using #GVariantDict to construct a #GVariant.
+ *
+ * Returns: (transfer full): a #GVariantDict
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_ref:
+ * @dict: a heap-allocated #GVariantDict
+ *
+ * Increases the reference count on @dict.
+ *
+ * Don't call this on stack-allocated #GVariantDict instances or bad
+ * things will happen.
+ *
+ * Returns: (transfer full): a new reference to @dict
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_remove:
+ * @dict: a #GVariantDict
+ * @key: the key to remove
+ *
+ * Removes a key and its associated value from a #GVariantDict.
+ *
+ * Returns: %TRUE if the key was found and removed
+ * Since: 2.40
+ */
+
+
+/**
+ * g_variant_dict_unref:
+ * @dict: (transfer full): a heap-allocated #GVariantDict
+ *
+ * Decreases the reference count on @dict.
+ *
+ * In the event that there are no more references, releases all memory
+ * associated with the #GVariantDict.
+ *
+ * Don't call this on stack-allocated #GVariantDict instances or bad
+ * things will happen.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * g_variant_dup_bytestring:
  * @value: an array-of-bytes #GVariant instance
  * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store
@@ -33313,8 +33017,8 @@
  * Memory</link>.
  *
  * In particular, arrays of these fixed-sized types can be interpreted
- * as an array of the given C type, with @element_size set to
- * <code>sizeof</code> the appropriate type:
+ * as an array of the given C type, with @element_size set to the size
+ * the appropriate type:
  *
  * <informaltable>
  * <tgroup cols='2'>
@@ -33331,16 +33035,16 @@
  * </tgroup>
  * </informaltable>
  *
- * For example, if calling this function for an array of 32 bit integers,
- * you might say <code>sizeof (gint32)</code>.  This value isn't used
- * except for the purpose of a double-check that the form of the
- * serialised data matches the caller's expectation.
+ * For example, if calling this function for an array of 32-bit integers,
+ * you might say sizeof(gint32). This value isn't used except for the purpose
+ * of a double-check that the form of the serialised data matches the caller's
+ * expectation.
  *
  * @n_elements, which must be non-%NULL is set equal to the number of
  * items in the array.
  *
  * Returns: (array length=n_elements) (transfer none): a pointer to
- *          the fixed array
+ *     the fixed array
  * Since: 2.24
  */
 
@@ -33844,13 +33548,9 @@
  * you must free or unreference all the unpacked values as you would with
  * g_variant_get(). Failure to do so will cause a memory leak.
  *
- * See the section on <link linkend='gvariant-format-strings'>GVariant
- * Format Strings</link>.
- *
- * <example>
- *  <title>Memory management with g_variant_iter_loop()</title>
- *  <programlisting>
- *   /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
+ * Here is an example for memory management with g_variant_iter_loop():
+ * |[<!-- language="C" -->
+ *   /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
  *   void
  *   iterate_dictionary (GVariant *dictionary)
  *   {
@@ -33864,12 +33564,12 @@
  *         g_print ("Item '%s' has type '%s'\n", key,
  *                  g_variant_get_type_string (value));
  *
- *         /<!-- -->* no need to free 'key' and 'value' here *<!-- -->/
- *         /<!-- -->* unless breaking out of this loop *<!-- -->/
+ *         /&ast; no need to free 'key' and 'value' here
+ *          &ast; unless breaking out of this loop
+ *          &ast;/
  *       }
  *   }
- *  </programlisting>
- * </example>
+ * ]|
  *
  * For most cases you should use g_variant_iter_next().
  *
@@ -33883,8 +33583,9 @@
  * thereby avoiding the need to free anything as well).
  *
  * @format_string determines the C types that are used for unpacking
- * the values and also determines if the values are copied or borrowed,
- * see the section on
+ * the values and also determines if the values are copied or borrowed.
+ *
+ * See the section on
  * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
  *
  * Returns: %TRUE if a value was unpacked, or %FALSE if there was no
@@ -33942,13 +33643,9 @@
  * responsibility of the caller to free all of the values returned by
  * the unpacking process.
  *
- * See the section on <link linkend='gvariant-format-strings'>GVariant
- * Format Strings</link>.
- *
- * <example>
- *  <title>Memory management with g_variant_iter_next()</title>
- *  <programlisting>
- *   /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
+ * Here is an example for memory management with g_variant_iter_next():
+ * |[<!-- language="C" -->
+ *   /&ast; Iterates a dictionary of type 'a{sv}' &ast;/
  *   void
  *   iterate_dictionary (GVariant *dictionary)
  *   {
@@ -33962,20 +33659,20 @@
  *         g_print ("Item '%s' has type '%s'\n", key,
  *                  g_variant_get_type_string (value));
  *
- *         /<!-- -->* must free data for ourselves *<!-- -->/
+ *         /&ast; must free data for ourselves &ast;/
  *         g_variant_unref (value);
  *         g_free (key);
  *       }
  *   }
- *  </programlisting>
- * </example>
+ * ]|
  *
  * For a solution that is likely to be more convenient to C programmers
  * when dealing with loops, see g_variant_iter_loop().
  *
  * @format_string determines the C types that are used for unpacking
- * the values and also determines if the values are copied or borrowed,
- * see the section on
+ * the values and also determines if the values are copied or borrowed.
+ *
+ * See the section on
  * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
  *
  * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
@@ -33993,10 +33690,9 @@
  * Use g_variant_unref() to drop your reference on the return value when
  * you no longer need it.
  *
- * <example>
- *  <title>Iterating with g_variant_iter_next_value()</title>
- *  <programlisting>
- *   /<!-- -->* recursively iterate a container *<!-- -->/
+ * Here is an example for iterating with g_variant_iter_next_value():
+ * |[<!-- language="C" -->
+ *   /&ast; recursively iterate a container &ast;/
  *   void
  *   iterate_container_recursive (GVariant *container)
  *   {
@@ -34014,8 +33710,7 @@
  *         g_variant_unref (child);
  *       }
  *   }
- * </programlisting>
- * </example>
+ * ]|
  *
  * Returns: (allow-none) (transfer full): a #GVariant, or %NULL
  * Since: 2.24
@@ -34041,6 +33736,9 @@
  * see the section on
  * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
  *
+ * This function is currently implemented with a linear scan.  If you
+ * plan to do many lookups then #GVariantDict may be more efficient.
+ *
  * Returns: %TRUE if a value was unpacked
  * Since: 2.28
  */
@@ -34054,26 +33752,26 @@
  *
  * Looks up a value in a dictionary #GVariant.
  *
- * This function works with dictionaries of the type
- * <literal>a{s*}</literal> (and equally well with type
- * <literal>a{o*}</literal>, but we only further discuss the string case
+ * This function works with dictionaries of the type a{s*} (and equally
+ * well with type a{o*}, but we only further discuss the string case
  * for sake of clarity).
  *
- * In the event that @dictionary has the type <literal>a{sv}</literal>,
- * the @expected_type string specifies what type of value is expected to
- * be inside of the variant.  If the value inside the variant has a
- * different type then %NULL is returned.  In the event that @dictionary
- * has a value type other than <literal>v</literal> then @expected_type
- * must directly match the key type and it is used to unpack the value
- * directly or an error occurs.
+ * In the event that @dictionary has the type a{sv}, the @expected_type
+ * string specifies what type of value is expected to be inside of the
+ * variant. If the value inside the variant has a different type then
+ * %NULL is returned. In the event that @dictionary has a value type other
+ * than v then @expected_type must directly match the key type and it is
+ * used to unpack the value directly or an error occurs.
  *
- * In either case, if @key is not found in @dictionary, %NULL is
- * returned.
+ * In either case, if @key is not found in @dictionary, %NULL is returned.
  *
  * If the key is found and the value has the correct type, it is
  * returned.  If @expected_type was specified then any non-%NULL return
  * value will have this type.
  *
+ * This function is currently implemented with a linear scan.  If you
+ * plan to do many lookups then #GVariantDict may be more efficient.
+ *
  * Returns: (transfer full): the value of the dictionary key, or %NULL
  * Since: 2.28
  */
@@ -34119,6 +33817,21 @@
  * 'r'; in essence, a new #GVariant must always be constructed by this
  * function (and not merely passed through it unmodified).
  *
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format_string. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
+ * <programlisting>
+ * MyFlags some_flags = FLAG_ONE | FLAG_TWO;
+ * const gchar *some_strings[] = { "a", "b", "c", NULL };
+ * GVariant *new_variant;
+ *
+ * new_variant = g_variant_new ("(t^as)",
+ *                              /<!-- -->* This cast is required. *<!-- -->/
+ *                              (guint64) some_flags,
+ *                              some_strings);
+ * </programlisting>
+ *
  * Returns: a new floating #GVariant instance
  * Since: 2.24
  */
@@ -34246,11 +33959,11 @@
  * @value must be an array with fixed-sized elements.  Numeric types are
  * fixed-size as are tuples containing only other fixed-sized types.
  *
- * @element_size must be the size of a single element in the array.  For
- * example, if calling this function for an array of 32 bit integers,
- * you might say <code>sizeof (gint32)</code>.  This value isn't used
- * except for the purpose of a double-check that the form of the
- * serialised data matches the caller's expectation.
+ * @element_size must be the size of a single element in the array.
+ * For example, if calling this function for an array of 32-bit integers,
+ * you might say sizeof(gint32). This value isn't used except for the purpose
+ * of a double-check that the form of the serialised data matches the caller's
+ * expectation.
  *
  * @n_elements, which must be non-%NULL is set equal to the number of
  * items in the array.
@@ -34429,15 +34142,21 @@
  * that case, the same arguments are collected from the argument list as
  * g_variant_new() would have collected.
  *
- * Consider this simple example:
+ * Note that the arguments must be of the correct width for their types
+ * specified in @format. This can be achieved by casting them. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
  *
- * <informalexample><programlisting>
+ * Consider this simple example:
+ * |[<!-- language="C" -->
  *  g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
- * </programlisting></informalexample>
+ * ]|
  *
  * In the example, the variable argument parameters are collected and
  * filled in as if they were part of the original string to produce the
- * result of <code>[('one', 1), ('two', 2), ('three', 3)]</code>.
+ * result of
+ * |[<!-- language="C" -->
+ * [('one', 1), ('two', 2), ('three', 3)]
+ * ]|
  *
  * This function is intended only to be used with @format as a string
  * literal.  Any parse error is fatal to the calling process.  If you
@@ -34468,6 +34187,10 @@
  * #GVariant pointer will be returned unmodified, without adding any
  * additional references.
  *
+ * Note that the arguments in @app must be of the correct width for their types
+ * specified in @format when collected into the #va_list. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * In order to behave correctly in all cases it is necessary for the
  * calling function to g_variant_ref_sink() the return result before
  * returning control to the user that originally provided the pointer.
@@ -34633,6 +34356,10 @@
  * @format_string, are collected from this #va_list and the list is left
  * pointing to the argument following the last.
  *
+ * Note that the arguments in @app must be of the correct width for their types
+ * specified in @format_string when collected into the #va_list. See
+ * the <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ *
  * These two generalisations allow mixing of multiple calls to
  * g_variant_new_va() and g_variant_get_va() within a single actual
  * varargs call by the user.
@@ -34754,6 +34481,13 @@
 
 
 /**
+ * g_variant_parser_get_error_quark:
+ *
+ * Deprecated: Use g_variant_parse_error_quark() instead.
+ */
+
+
+/**
  * g_variant_print:
  * @value: a #GVariant
  * @type_annotate: %TRUE if type information should be included in
@@ -34804,7 +34538,7 @@
  * @value: a #GVariant
  *
  * #GVariant uses a floating reference count system.  All functions with
- * names starting with <literal>g_variant_new_</literal> return floating
+ * names starting with `g_variant_new_` return floating
  * references.
  *
  * Calling g_variant_ref_sink() on a #GVariant with a floating reference
@@ -35572,13 +35306,13 @@
  *
  * A convenience function/macro to log a warning message.
  *
- * You can make warnings fatal at runtime by setting the
- * <envar>G_DEBUG</envar> environment variable (see
- * <ulink url="glib-running.html">Running GLib Applications</ulink>).
+ * You can make warnings fatal at runtime by setting the `G_DEBUG`
+ * environment variable (see
+ * [Running GLib Applications](glib-running.html)).
  *
- * If g_log_default_handler() is used as the log handler function, a new-line
- * character will automatically be appended to @..., and need not be entered
- * manually.
+ * If g_log_default_handler() is used as the log handler function,
+ * a newline character will automatically be appended to @..., and
+ * need not be entered manually.
  */
 
 
@@ -35651,10 +35385,10 @@
  *
  * The original intended use of @package was for a short identifier of
  * the package, typically the same identifier as used for
- * <literal>GETTEXT_PACKAGE</literal> in software configured using GNU
+ * `GETTEXT_PACKAGE` in software configured using GNU
  * autotools. The function first looks in the Windows Registry for the
- * value <literal>&num;InstallationDirectory</literal> in the key
- * <literal>&num;HKLM\Software\@package</literal>, and if that value
+ * value `&num;InstallationDirectory` in the key
+ * `&num;HKLM\Software\@package`, and if that value
  * exists and is a string, returns that.
  *
  * It is strongly recommended that packagers of GLib-using libraries
@@ -35833,7 +35567,7 @@
 /**
  * gchar:
  *
- * Corresponds to the standard C <type>char</type> type.
+ * Corresponds to the standard C char type.
  */
 
 
@@ -35851,7 +35585,7 @@
 /**
  * gdouble:
  *
- * Corresponds to the standard C <type>double</type> type.
+ * Corresponds to the standard C double type.
  * Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
  */
 
@@ -35859,7 +35593,7 @@
 /**
  * gfloat:
  *
- * Corresponds to the standard C <type>float</type> type.
+ * Corresponds to the standard C float type.
  * Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
  */
 
@@ -35867,7 +35601,7 @@
 /**
  * gint:
  *
- * Corresponds to the standard C <type>int</type> type.
+ * Corresponds to the standard C int type.
  * Values of this type can range from #G_MININT to #G_MAXINT.
  */
 
@@ -35921,7 +35655,7 @@
 /**
  * gintptr:
  *
- * Corresponds to the C99 type <type>intptr_t</type>,
+ * Corresponds to the C99 type intptr_t,
  * a signed integer type that can hold any pointer.
  *
  * To print or scan values of this type, use
@@ -35942,9 +35676,9 @@
 
 /**
  * glib_check_version:
- * @required_major: the required major version.
- * @required_minor: the required minor version.
- * @required_micro: the required micro version.
+ * @required_major: the required major version
+ * @required_minor: the required minor version
+ * @required_micro: the required micro version
  *
  * Checks that the GLib library in use is compatible with the
  * given version. Generally you would pass in the constants
@@ -35962,9 +35696,9 @@
  * (same major version.)
  *
  * Returns: %NULL if the GLib library is compatible with the
- *   given version, or a string describing the version mismatch.
- *   The returned string is owned by GLib and must not be modified
- *   or freed.
+ *     given version, or a string describing the version mismatch.
+ *     The returned string is owned by GLib and must not be modified
+ *     or freed.
  * Since: 2.6
  */
 
@@ -36011,7 +35745,7 @@
 /**
  * glong:
  *
- * Corresponds to the standard C <type>long</type> type.
+ * Corresponds to the standard C long type.
  * Values of this type can range from #G_MINLONG to #G_MAXLONG.
  */
 
@@ -36020,7 +35754,7 @@
  * goffset:
  *
  * A signed integer type that is used for file offsets,
- * corresponding to the C99 type <type>off64_t</type>.
+ * corresponding to the C99 type off64_t.
  * Values of this type can range from #G_MINOFFSET to
  * #G_MAXOFFSET.
  *
@@ -36035,15 +35769,14 @@
  * gpointer:
  *
  * An untyped pointer.
- * #gpointer looks better and is easier to use
- * than <type>void*</type>.
+ * #gpointer looks better and is easier to use than void*.
  */
 
 
 /**
  * gshort:
  *
- * Corresponds to the standard C <type>short</type> type.
+ * Corresponds to the standard C short type.
  * Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
  */
 
@@ -36052,10 +35785,10 @@
  * gsize:
  *
  * An unsigned integer type of the result of the sizeof operator,
- * corresponding to the <type>size_t</type> type defined in C99.
+ * corresponding to the size_t type defined in C99.
  * This type is wide enough to hold the numeric value of a pointer,
- * so it is usually 32bit wide on a 32bit platform and 64bit wide
- * on a 64bit platform. Values of this type can range from 0 to
+ * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide
+ * on a 64-bit platform. Values of this type can range from 0 to
  * #G_MAXSIZE.
  *
  * To print or scan values of this type, use
@@ -36067,7 +35800,7 @@
  * gssize:
  *
  * A signed variant of #gsize, corresponding to the
- * <type>ssize_t</type> defined on most platforms.
+ * ssize_t defined on most platforms.
  * Values of this type can range from #G_MINSSIZE
  * to #G_MAXSSIZE.
  *
@@ -36079,14 +35812,14 @@
 /**
  * guchar:
  *
- * Corresponds to the standard C <type>unsigned char</type> type.
+ * Corresponds to the standard C unsigned char type.
  */
 
 
 /**
  * guint:
  *
- * Corresponds to the standard C <type>unsigned int</type> type.
+ * Corresponds to the standard C unsigned int type.
  * Values of this type can range from 0 to #G_MAXUINT.
  */
 
@@ -36116,7 +35849,7 @@
 /**
  * guint64:
  *
- * An unsigned integer guaranteed to be 64 bits on all platforms.
+ * An unsigned integer guaranteed to be 64-bits on all platforms.
  * Values of this type can range from 0 to #G_MAXUINT64
  * (= 18,446,744,073,709,551,615).
  *
@@ -36136,7 +35869,7 @@
 /**
  * guintptr:
  *
- * Corresponds to the C99 type <type>uintptr_t</type>,
+ * Corresponds to the C99 type uintptr_t,
  * an unsigned integer type that can hold any pointer.
  *
  * To print or scan values of this type, use
@@ -36149,7 +35882,7 @@
 /**
  * gulong:
  *
- * Corresponds to the standard C <type>unsigned long</type> type.
+ * Corresponds to the standard C unsigned long type.
  * Values of this type can range from 0 to #G_MAXULONG.
  */
 
@@ -36157,7 +35890,7 @@
 /**
  * gushort:
  *
- * Corresponds to the standard C <type>unsigned short</type> type.
+ * Corresponds to the standard C unsigned short type.
  * Values of this type can range from 0 to #G_MAXUSHORT.
  */
 
diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c
index ccfbccaa..83fd6a92 100644
--- a/gir/gmodule-2.0.c
+++ b/gir/gmodule-2.0.c
@@ -16,7 +16,6 @@
  * @module: the #GModule corresponding to the module which has just been loaded
  *
  * Specifies the type of the module initialization function.
- * <indexterm zone="g-module-check-init"><primary>g_module_check_init</primary></indexterm>
  * If a module contains a function named g_module_check_init() it is called
  * automatically when the module is loaded. It is passed the #GModule structure
  * and should return %NULL on success or a string describing the initialization
@@ -46,7 +45,6 @@
  * GModuleUnload:
  * @module: the #GModule about to be unloaded
  *
- * <indexterm zone="g-module-unload"><primary>g_module_unload</primary></indexterm>
  * Specifies the type of the module function called when it is unloaded.
  * If a module contains a function named g_module_unload() it is called
  * automatically when the module is unloaded.
@@ -90,8 +88,7 @@
  * well as Windows platforms via DLLs.
  *
  * A program which wants to use these functions must be linked to the
- * libraries output by the command
- * <command>pkg-config --libs gmodule-2.0</command>.
+ * libraries output by the command `pkg-config --libs gmodule-2.0`.
  *
  * To use them you must first determine whether dynamic loading
  * is supported on the platform by calling g_module_supported().
@@ -109,12 +106,11 @@
  *
  * If your module introduces static data to common subsystems in the running
  * program, e.g. through calling
- * <literal>g_quark_from_static_string ("my-module-stuff")</literal>,
+ * `g_quark_from_static_string ("my-module-stuff")`,
  * it must ensure that it is never unloaded, by calling g_module_make_resident().
  *
- * <example>
- * <title>Calling a function defined in a <structname>GModule</structname></title>
- * <programlisting>
+ * Example: Calling a function defined in a GModule
+ * |[<!-- language="C" -->
  * /&ast; the function signature for 'say_hello' &ast;/
  * typedef void (* SayHelloFunc) (const char *message);
  *
@@ -128,16 +124,16 @@
  *   if (!module)
  *     {
  *       g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
- *                    "&percnt;s", g_module_error ());
+ *                    "%s", g_module_error ());
  *       return FALSE;
  *     }
  *
- *   if (!g_module_symbol (module, "say_hello", (gpointer *)&amp;say_hello))
+ *   if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
  *     {
  *       g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
- *                    "&percnt;s: &percnt;s", filename, g_module_error ());
+ *                    "%s: %s", filename, g_module_error ());
  *       if (!g_module_close (module))
- *         g_warning ("&percnt;s: &percnt;s", filename, g_module_error ());
+ *         g_warning ("%s: %s", filename, g_module_error ());
  *       return FALSE;
  *     }
  *
@@ -146,7 +142,7 @@
  *       g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
  *                    "symbol say_hello is NULL");
  *       if (!g_module_close (module))
- *         g_warning ("&percnt;s: &percnt;s", filename, g_module_error ());
+ *         g_warning ("%s: %s", filename, g_module_error ());
  *       return FALSE;
  *     }
  *
@@ -154,18 +150,17 @@
  *   say_hello ("Hello world!");
  *
  *   if (!g_module_close (module))
- *     g_warning ("&percnt;s: &percnt;s", filename, g_module_error ());
+ *     g_warning ("%s: %s", filename, g_module_error ());
  *   return TRUE;
  *  }
- * </programlisting>
- * </example>
+ * ]|
  */
 
 
 /**
  * g_module_build_path:
- * @directory: (allow-none): the directory where the module is. This can be %NULL
- *     or the empty string to indicate that the standard platform-specific
+ * @directory: (allow-none): the directory where the module is. This can be
+ *     %NULL or the empty string to indicate that the standard platform-specific
  *     directories will be used, though that is not recommended
  * @module_name: the name of the module
  *
@@ -179,10 +174,9 @@
  * since the wrong module may be found.
  *
  * For example, calling g_module_build_path() on a Linux system with a
- * @directory of <filename>/lib</filename> and a @module_name of "mylibrary"
- * will return <filename>/lib/libmylibrary.so</filename>. On a Windows system,
- * using <filename>\Windows</filename> as the directory it will return
- * <filename>\Windows\mylibrary.dll</filename>.
+ * @directory of `/lib` and a @module_name of "mylibrary" will return
+ * `/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the
+ * directory it will return `\Windows\mylibrary.dll`.
  *
  * Returns: the complete path of the module, including the standard library
  *     prefix and suffix. This should be freed when no longer needed
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index ab618f62..b25b8d0b 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -63,7 +63,7 @@
  * This signal is typically used to obtain change notification for a
  * single property, by specifying the property name as a detail in the
  * g_signal_connect() call, like this:
- * |[
+ * |[<!-- language="C" -->
  * g_signal_connect (text_view->buffer, "notify::paste-target-list",
  *                   G_CALLBACK (gtk_text_view_target_list_notify),
  *                   text_view)
@@ -77,7 +77,7 @@
 /**
  * GParamSpecPool:
  *
- * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s which can be
+ * A #GParamSpecPool maintains a collection of #GParamSpecs which can be
  * quickly accessed by owner and name. The implementation of the #GObject property
  * system uses such a pool to store the #GParamSpecs of the properties all object
  * types.
@@ -102,9 +102,9 @@
  * objects.
  *
  * If the object's #GObjectClass.dispose method results in additional
- * references to the object being held, any #GWeakRef<!-- -->s taken
+ * references to the object being held, any #GWeakRefs taken
  * before it was disposed will continue to point to %NULL.  If
- * #GWeakRef<!-- -->s are taken after the object is disposed and
+ * #GWeakRefs are taken after the object is disposed and
  * re-referenced, they will continue to point to it until its refcount
  * goes back to zero, at which point they too will be invalidated.
  */
@@ -146,21 +146,21 @@
  * value is applied to the target property; for instance, the following
  * binding:
  *
- * |[
+ * |[<!-- language="C" -->
  *   g_object_bind_property (object1, "property-a",
  *                           object2, "property-b",
  *                           G_BINDING_DEFAULT);
  * ]|
  *
- * will cause <emphasis>object2:property-b</emphasis> to be updated every
- * time g_object_set() or the specific accessor changes the value of
- * <emphasis>object1:property-a</emphasis>.
+ * will cause the property named "property-b" of @object2 to be updated
+ * every time g_object_set() or the specific accessor changes the value of
+ * the property "property-a" of @object1.
  *
  * It is possible to create a bidirectional binding between two properties
  * of two #GObject instances, so that if either property changes, the
  * other is updated as well, for instance:
  *
- * |[
+ * |[<!-- language="C" -->
  *   g_object_bind_property (object1, "property-a",
  *                           object2, "property-b",
  *                           G_BINDING_BIDIRECTIONAL);
@@ -173,7 +173,7 @@
  * transformation from the source value to the target value before
  * applying it; for instance, the following binding:
  *
- * |[
+ * |[<!-- language="C" -->
  *   g_object_bind_property_full (adjustment1, "value",
  *                                adjustment2, "value",
  *                                G_BINDING_BIDIRECTIONAL,
@@ -182,15 +182,15 @@
  *                                NULL, NULL);
  * ]|
  *
- * will keep the <emphasis>value</emphasis> property of the two adjustments
- * in sync; the <function>celsius_to_fahrenheit</function> function will be
- * called whenever the <emphasis>adjustment1:value</emphasis> property changes
- * and will transform the current value of the property before applying it
- * to the <emphasis>adjustment2:value</emphasis> property; vice versa, the
- * <function>fahrenheit_to_celsius</function> function will be called whenever
- * the <emphasis>adjustment2:value</emphasis> property changes, and will
- * transform the current value of the property before applying it to the
- * <emphasis>adjustment1:value</emphasis>.
+ * will keep the "value" property of the two adjustments in sync; the
+ * @celsius_to_fahrenheit function will be called whenever the "value"
+ * property of @adjustment1 changes and will transform the current value
+ * of the property before applying it to the "value" property of @adjustment2.
+ *
+ * Vice versa, the @fahrenheit_to_celsius function will be called whenever
+ * the "value" property of @adjustment2 changes, and will transform the
+ * current value of the property before applying it to the "value" property
+ * of @adjustment1.
  *
  * Note that #GBinding does not resolve cycles by itself; a cycle like
  *
@@ -211,10 +211,10 @@
  * either one of the #GObject instances it refers to are finalized, or when
  * the #GBinding instance loses its last reference.
  *
- * <note><para>Bindings for languages with garbage collection can use
+ * Bindings for languages with garbage collection can use
  * g_binding_unbind() to explicitly release a binding between the source
  * and target properties, instead of relying on the last reference on the
- * binding, source, and target instances to drop.</para></note>
+ * binding, source, and target instances to drop.
  *
  * #GBinding is available since GObject 2.26
  */
@@ -245,13 +245,13 @@
  * A #GClosure represents a callback supplied by the programmer. It
  * will generally comprise a function of some kind and a marshaller
  * used to call it. It is the reponsibility of the marshaller to
- * convert the arguments for the invocation from #GValue<!-- -->s into
+ * convert the arguments for the invocation from #GValues into
  * a suitable form, perform the callback on the converted arguments,
  * and transform the return value back into a #GValue.
  *
  * In the case of C programs, a closure usually just holds a pointer
  * to a function and maybe a data argument, and the marshaller
- * converts between #GValue<!-- --> and native C types. The GObject
+ * converts between #GValue and native C types. The GObject
  * library provides the #GCClosure type for this purpose. Bindings for
  * other languages need marshallers which convert between #GValue<!--
  * -->s and suitable representations in the runtime of the language in
@@ -273,22 +273,17 @@
  *
  * Using closures has a number of important advantages over a simple
  * callback function/data pointer combination:
- * <itemizedlist>
- * <listitem><para>
- * Closures allow the callee to get the types of the callback parameters,
- * which means that language bindings don't have to write individual glue
- * for each callback type.
- * </para></listitem>
- * <listitem><para>
- * The reference counting of #GClosure makes it easy to handle reentrancy
- * right; if a callback is removed while it is being invoked, the closure
- * and its parameters won't be freed until the invocation finishes.
- * </para></listitem>
- * <listitem><para>
- * g_closure_invalidate() and invalidation notifiers allow callbacks to be
- * automatically removed when the objects they point to go away.
- * </para></listitem>
- * </itemizedlist>
+ *
+ * - Closures allow the callee to get the types of the callback parameters,
+ *   which means that language bindings don't have to write individual glue
+ *   for each callback type.
+ *
+ * - The reference counting of #GClosure makes it easy to handle reentrancy
+ *   right; if a callback is removed while it is being invoked, the closure
+ *   and its parameters won't be freed until the invocation finishes.
+ *
+ * - g_closure_invalidate() and invalidation notifiers allow callbacks to be
+ *   automatically removed when the objects they point to go away.
  */
 
 
@@ -318,8 +313,8 @@
  * The code in the example program below demonstrates #GValue's
  * features.
  *
- * |[
- * #include &lt;glib-object.h&gt;
+ * |[<!-- language="C" -->
+ * #include <glib-object.h>
  *
  * static void
  * int2string (const GValue *src_value,
@@ -341,34 +336,34 @@
  *   const gchar *message;
  *
  *   /&ast; The GValue starts empty &ast;/
- *   g_assert (!G_VALUE_HOLDS_STRING (&amp;a));
+ *   g_assert (!G_VALUE_HOLDS_STRING (&a));
  *
  *   /&ast; Put a string in it &ast;/
- *   g_value_init (&amp;a, G_TYPE_STRING);
- *   g_assert (G_VALUE_HOLDS_STRING (&amp;a));
- *   g_value_set_static_string (&amp;a, "Hello, world!");
- *   g_printf ("%s\n", g_value_get_string (&amp;a));
+ *   g_value_init (&a, G_TYPE_STRING);
+ *   g_assert (G_VALUE_HOLDS_STRING (&a));
+ *   g_value_set_static_string (&a, "Hello, world!");
+ *   g_printf ("%s\n", g_value_get_string (&a));
  *
  *   /&ast; Reset it to its pristine state &ast;/
- *   g_value_unset (&amp;a);
+ *   g_value_unset (&a);
  *
  *   /&ast; It can then be reused for another type &ast;/
- *   g_value_init (&amp;a, G_TYPE_INT);
- *   g_value_set_int (&amp;a, 42);
+ *   g_value_init (&a, G_TYPE_INT);
+ *   g_value_set_int (&a, 42);
  *
  *   /&ast; Attempt to transform it into a GValue of type STRING &ast;/
- *   g_value_init (&amp;b, G_TYPE_STRING);
+ *   g_value_init (&b, G_TYPE_STRING);
  *
  *   /&ast; An INT is transformable to a STRING &ast;/
  *   g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
  *
- *   g_value_transform (&amp;a, &amp;b);
- *   g_printf ("%s\n", g_value_get_string (&amp;b));
+ *   g_value_transform (&a, &b);
+ *   g_printf ("%s\n", g_value_get_string (&b));
  *
  *   /&ast; Attempt to transform it again using a custom transform function &ast;/
  *   g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
- *   g_value_transform (&amp;a, &amp;b);
- *   g_printf ("%s\n", g_value_get_string (&amp;b));
+ *   g_value_transform (&a, &b);
+ *   g_printf ("%s\n", g_value_get_string (&b));
  *   return 0;
  * }
  * ]|
@@ -386,13 +381,13 @@
  * #GParamSpec is an object structure that encapsulates the metadata
  * required to specify parameters, such as e.g. #GObject properties.
  *
- * <para id="canonical-parameter-name">
- * Parameter names need to start with a letter (a-z or A-Z). Subsequent
- * characters can be letters, numbers or a '-'.
+ * ## Parameter names # {#canonical-parameter-names}
+ *
+ * Parameter names need to start with a letter (a-z or A-Z).
+ * Subsequent characters can be letters, numbers or a '-'.
  * All other characters are replaced by a '-' during construction.
- * The result of this replacement is called the canonical name of the
- * parameter.
- * </para>
+ * The result of this replacement is called the canonical name of
+ * the parameter.
  */
 
 
@@ -411,15 +406,18 @@
  * unloaded at run-time as dynamic types may be.  Static types are created
  * with g_type_register_static() that gets type specific information passed
  * in via a #GTypeInfo structure.
+ *
  * Dynamic types are created with g_type_register_dynamic() which takes a
  * #GTypePlugin structure instead. The remaining type information (the
  * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin
  * and the g_type_plugin_*() API.
+ *
  * These registration functions are usually called only once from a
  * function whose only purpose is to return the type identifier for a
  * specific class.  Once the type (or class or interface) is registered,
  * it may be instantiated, inherited, or implemented depending on exactly
  * what sort of type it is.
+ *
  * There is also a third registration function for registering fundamental
  * types called g_type_register_fundamental() which requires both a #GTypeInfo
  * structure and a #GTypeFundamentalInfo structure but it is seldom used
@@ -432,41 +430,30 @@
  * separately (typically by using #GArray or #GPtrArray) and put a pointer
  * to the buffer in the structure.
  *
- * A final word about type names.
- * Such an identifier needs to be at least three characters long. There is no
- * upper length limit. The first character needs to be a letter (a-z or A-Z)
- * or an underscore '_'. Subsequent characters can be letters, numbers or
- * any of '-_+'.
+ * A final word about type names: Such an identifier needs to be at least
+ * three characters long. There is no upper length limit. The first character
+ * needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent
+ * characters can be letters, numbers or any of '-_+'.
  */
 
 
 /**
  * SECTION:gtypemodule
  * @short_description: Type loading modules
- * @see_also: <variablelist>
- * <varlistentry>
- * <term>#GTypePlugin</term>
- * <listitem><para>The abstract type loader interface.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>#GModule</term>
- * <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
- * </varlistentry>
- * </variablelist>
+ * @see_also: #GTypePlugin, #GModule
  * @title: GTypeModule
  *
  * #GTypeModule provides a simple implementation of the #GTypePlugin
  * interface. The model of #GTypeModule is a dynamically loaded module
- * which implements some number of types and interface
- * implementations. When the module is loaded, it registers its types
- * and interfaces using g_type_module_register_type() and
- * g_type_module_add_interface().  As long as any instances of these
- * types and interface implementations are in use, the module is kept
- * loaded. When the types and interfaces are gone, the module may be
- * unloaded. If the types and interfaces become used again, the module
- * will be reloaded. Note that the last unref cannot happen in module
- * code, since that would lead to the caller's code being unloaded before
- * g_object_unref() returns to it.
+ * which implements some number of types and interface implementations.
+ * When the module is loaded, it registers its types and interfaces
+ * using g_type_module_register_type() and g_type_module_add_interface().
+ * As long as any instances of these types and interface implementations
+ * are in use, the module is kept loaded. When the types and interfaces
+ * are gone, the module may be unloaded. If the types and interfaces
+ * become used again, the module will be reloaded. Note that the last
+ * unref cannot happen in module code, since that would lead to the
+ * caller's code being unloaded before g_object_unref() returns to it.
  *
  * Keeping track of whether the module should be loaded or not is done by
  * using a use count - it starts at zero, and whenever it is greater than
@@ -491,49 +478,40 @@
  * @see_also: #GTypeModule and g_type_register_dynamic().
  * @title: GTypePlugin
  *
- * The GObject type system supports dynamic loading of types. The
- * #GTypePlugin interface is used to handle the lifecycle of
- * dynamically loaded types.  It goes as follows:
- *
- * <orderedlist>
- * <listitem><para>
- *   The type is initially introduced (usually upon loading the module
- *   the first time, or by your main application that knows what modules
- *   introduces what types), like this:
- *   |[
- *   new_type_id = g_type_register_dynamic (parent_type_id,
- *                                                 "TypeName",
- *                                                 new_type_plugin,
- *                                                 type_flags);
- *   ]|
- *   where <literal>new_type_plugin</literal> is an implementation of the
- *   #GTypePlugin interface.
- * </para></listitem>
- * <listitem><para>
- *    The type's implementation is referenced, e.g. through
+ * The GObject type system supports dynamic loading of types.
+ * The #GTypePlugin interface is used to handle the lifecycle
+ * of dynamically loaded types. It goes as follows:
+ *
+ * 1. The type is initially introduced (usually upon loading the module
+ *    the first time, or by your main application that knows what modules
+ *    introduces what types), like this:
+ *    |[<!-- language="C" -->
+ *    new_type_id = g_type_register_dynamic (parent_type_id,
+ *                                           "TypeName",
+ *                                           new_type_plugin,
+ *                                           type_flags);
+ *    ]|
+ *    where @new_type_plugin is an implementation of the
+ *    #GTypePlugin interface.
+ *
+ * 2. The type's implementation is referenced, e.g. through
  *    g_type_class_ref() or through g_type_create_instance() (this is
  *    being called by g_object_new()) or through one of the above done on
- *    a type derived from <literal>new_type_id</literal>.
- * </para></listitem>
- * <listitem><para>
- *    This causes the type system to load the type's implementation by calling
- *    g_type_plugin_use() and g_type_plugin_complete_type_info() on
- *    <literal>new_type_plugin</literal>.
- * </para></listitem>
- * <listitem><para>
- *    At some point the type's implementation isn't required anymore, e.g. after
- *    g_type_class_unref() or g_type_free_instance() (called when the reference
- *    count of an instance drops to zero).
- * </para></listitem>
- * <listitem><para>
- *    This causes the type system to throw away the information retrieved from
- *    g_type_plugin_complete_type_info() and then it calls
- *    g_type_plugin_unuse() on <literal>new_type_plugin</literal>.
- * </para></listitem>
- * <listitem><para>
- *    Things may repeat from the second step.
- * </para></listitem>
- * </orderedlist>
+ *    a type derived from @new_type_id.
+ *
+ * 3. This causes the type system to load the type's implementation by
+ *    calling g_type_plugin_use() and g_type_plugin_complete_type_info()
+ *    on @new_type_plugin.
+ *
+ * 4. At some point the type's implementation isn't required anymore,
+ *    e.g. after g_type_class_unref() or g_type_free_instance() (called
+ *    when the reference count of an instance drops to zero).
+ *
+ * 5. This causes the type system to throw away the information retrieved
+ *    from g_type_plugin_complete_type_info() and then it calls
+ *    g_type_plugin_unuse() on @new_type_plugin.
+ *
+ * 6. Things may repeat from the second step.
  *
  * So basically, you need to implement a #GTypePlugin type that
  * carries a use_count, once use_count goes from zero to one, you need
@@ -563,45 +541,45 @@
  * support.  Signals are described in detail in <xref
  * linkend="gobject-Signals"/>.
  *
- * <para id="floating-ref">
+ * ## Floating references # {#floating-ref}
+ *
  * GInitiallyUnowned is derived from GObject. The only difference between
  * the two is that the initial reference of a GInitiallyUnowned is flagged
- * as a <firstterm>floating</firstterm> reference.
- * This means that it is not specifically claimed to be "owned" by
- * any code portion. The main motivation for providing floating references is
- * C convenience. In particular, it allows code to be written as:
- * |[
+ * as a "floating" reference. This means that it is not specifically
+ * claimed to be "owned" by any code portion. The main motivation for
+ * providing floating references is C convenience. In particular, it
+ * allows code to be written as:
+ * |[<!-- language="C" -->
  * container = create_container ();
  * container_add_child (container, create_child());
  * ]|
- * If <function>container_add_child()</function> will g_object_ref_sink() the
- * passed in child, no reference of the newly created child is leaked.
- * Without floating references, <function>container_add_child()</function>
- * can only g_object_ref() the new child, so to implement this code without
- * reference leaks, it would have to be written as:
- * |[
+ * If container_add_child() calls g_object_ref_sink() on the passed-in child,
+ * no reference of the newly created child is leaked. Without floating
+ * references, container_add_child() can only g_object_ref() the new child,
+ * so to implement this code without reference leaks, it would have to be
+ * written as:
+ * |[<!-- language="C" -->
  * Child *child;
  * container = create_container ();
  * child = create_child ();
  * container_add_child (container, child);
  * g_object_unref (child);
  * ]|
- * The floating reference can be converted into
- * an ordinary reference by calling g_object_ref_sink().
- * For already sunken objects (objects that don't have a floating reference
- * anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns
- * a new reference.
+ * The floating reference can be converted into an ordinary reference by
+ * calling g_object_ref_sink(). For already sunken objects (objects that
+ * don't have a floating reference anymore), g_object_ref_sink() is equivalent
+ * to g_object_ref() and returns a new reference.
+ *
  * Since floating references are useful almost exclusively for C convenience,
  * language bindings that provide automated reference and memory ownership
  * maintenance (such as smart pointers or garbage collection) should not
  * expose floating references in their API.
- * </para>
  *
  * Some object implementations may need to save an objects floating state
  * across certain code portions (an example is #GtkMenu), to achieve this,
  * the following sequence can be used:
  *
- * |[
+ * |[<!-- language="C" -->
  * /&ast; save floating state &ast;/
  * gboolean was_floating = g_object_is_floating (object);
  * g_object_ref_sink (object);
@@ -642,58 +620,56 @@
  *     and a general purpose notification mechanism
  * @title: Signals
  *
- * The basic concept of the signal system is that of the
- * <emphasis>emission</emphasis> of a signal. Signals are introduced
- * per-type and are identified through strings.  Signals introduced
- * for a parent type are available in derived types as well, so
- * basically they are a per-type facility that is inherited.  A signal
- * emission mainly involves invocation of a certain set of callbacks
- * in precisely defined manner. There are two main categories of such
- * callbacks, per-object
- * <footnote><para>Although signals can deal with any kind of instantiatable
- * type, i'm referring to those types as "object types" in the following,
- * simply because that is the context most users will encounter signals in.
- * </para></footnote>
- * ones and user provided ones.
+ * The basic concept of the signal system is that of the emission
+ * of a signal. Signals are introduced per-type and are identified
+ * through strings. Signals introduced for a parent type are available
+ * in derived types as well, so basically they are a per-type facility
+ * that is inherited.
+ *
+ * A signal emission mainly involves invocation of a certain set of
+ * callbacks in precisely defined manner. There are two main categories
+ * of such callbacks, per-object ones and user provided ones.
+ * (Although signals can deal with any kind of instantiatable type, I'm
+ * referring to those types as "object types" in the following, simply
+ * because that is the context most users will encounter signals in.)
  * The per-object callbacks are most often referred to as "object method
  * handler" or "default (signal) handler", while user provided callbacks are
  * usually just called "signal handler".
+ *
  * The object method handler is provided at signal creation time (this most
  * frequently happens at the end of an object class' creation), while user
- * provided handlers are frequently connected and disconnected to/from a certain
- * signal on certain object instances.
+ * provided handlers are frequently connected and disconnected to/from a
+ * certain signal on certain object instances.
  *
  * A signal emission consists of five stages, unless prematurely stopped:
- * <variablelist>
- * <varlistentry><term></term><listitem><para>
- * 	1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 	2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 	3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 	4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * 	5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
- * </para></listitem></varlistentry>
- * </variablelist>
+ *
+ * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
+ *
+ * 2. Invocation of normal user-provided signal handlers (where the @after
+ *    flag is not set)
+ *
+ * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
+ *
+ * 4. Invocation of user provided signal handlers (where the @after flag is set)
+ *
+ * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
+ *  
  * The user-provided signal handlers are called in the order they were
  * connected in.
+ *
  * All handlers may prematurely stop a signal emission, and any number of
  * handlers may be connected, disconnected, blocked or unblocked during
  * a signal emission.
+ *
  * There are certain criteria for skipping user handlers in stages 2 and 4
  * of a signal emission.
- * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted
- * during callback invocation, to return from the "blocked" state, a
- * handler has to get unblocked exactly the same amount of times
- * it has been blocked before.
+ *
+ * First, user handlers may be blocked. Blocked handlers are omitted during
+ * callback invocation, to return from the blocked state, a handler has to
+ * get unblocked exactly the same amount of times it has been blocked before.
+ *
  * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
- * "detail" argument passed in to g_signal_emit() has to match the detail
+ * @detail argument passed in to g_signal_emit() has to match the detail
  * argument of the signal handler currently subject to invocation.
  * Specification of no detail argument for signal handlers (omission of the
  * detail part of the signal specification upon connection) serves as a
@@ -719,13 +695,13 @@
  * g_value_unset() as the clear function using g_array_set_clear_func(),
  * for instance, the following code:
  *
- * |[
+ * |[<!-- language="C" -->
  *   GValueArray *array = g_value_array_new (10);
  * ]|
  *
  * can be replaced by:
  *
- * |[
+ * |[<!-- language="C" -->
  *   GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
  *   g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
  * ]|
@@ -736,7 +712,7 @@
  * g_binding_get_flags:
  * @binding: a #GBinding
  *
- * Retrieves the flags passed when constructing the #GBinding
+ * Retrieves the flags passed when constructing the #GBinding.
  *
  * Returns: the #GBindingFlags used by the #GBinding
  * Since: 2.26
@@ -747,7 +723,7 @@
  * g_binding_get_source:
  * @binding: a #GBinding
  *
- * Retrieves the #GObject instance used as the source of the binding
+ * Retrieves the #GObject instance used as the source of the binding.
  *
  * Returns: (transfer none): the source #GObject
  * Since: 2.26
@@ -759,7 +735,7 @@
  * @binding: a #GBinding
  *
  * Retrieves the name of the property of #GBinding:source used as the source
- * of the binding
+ * of the binding.
  *
  * Returns: the name of the source property
  * Since: 2.26
@@ -770,7 +746,7 @@
  * g_binding_get_target:
  * @binding: a #GBinding
  *
- * Retrieves the #GObject instance used as the target of the binding
+ * Retrieves the #GObject instance used as the target of the binding.
  *
  * Returns: (transfer none): the target #GObject
  * Since: 2.26
@@ -782,7 +758,7 @@
  * @binding: a #GBinding
  *
  * Retrieves the name of the property of #GBinding:target used as the target
- * of the binding
+ * of the binding.
  *
  * Returns: the name of the target property
  * Since: 2.26
@@ -796,10 +772,10 @@
  * Explicitly releases the binding between the source and the target
  * property expressed by @binding.
  *
- * <note>This function will release the reference that is being held on
+ * This function will release the reference that is being held on
  * the @binding instance; if you want to hold on to the #GBinding instance
  * after calling g_binding_unbind(), you will need to hold a reference
- * to it.</note>
+ * to it.
  *
  * Since: 2.38
  */
@@ -850,7 +826,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter
+ * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter
  * denotes a flags type.
  */
 
@@ -866,7 +842,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)</literal>.
+ * `gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)`.
  *
  * Since: 2.26
  */
@@ -890,7 +866,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>.
+ * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.
  */
 
 
@@ -905,7 +881,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.
  */
 
 
@@ -920,7 +896,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.
  */
 
 
@@ -935,7 +911,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.
  */
 
 
@@ -950,7 +926,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.
  */
 
 
@@ -965,7 +941,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type..
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type..
  */
 
 
@@ -980,7 +956,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type.
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type.
  */
 
 
@@ -995,7 +971,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.
  */
 
 
@@ -1010,7 +986,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.
  */
 
 
@@ -1025,7 +1001,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.
  */
 
 
@@ -1040,7 +1016,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.
  */
 
 
@@ -1055,7 +1031,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.
  */
 
 
@@ -1070,7 +1046,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.
  */
 
 
@@ -1085,7 +1061,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.
  */
 
 
@@ -1100,7 +1076,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.
  */
 
 
@@ -1115,7 +1091,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.
  */
 
 
@@ -1130,7 +1106,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.
  */
 
 
@@ -1145,7 +1121,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.
  */
 
 
@@ -1160,7 +1136,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.
  *
  * Since: 2.26
  */
@@ -1177,7 +1153,7 @@
  * @marshal_data: additional data specified when registering the marshaller
  *
  * A marshaller for a #GCClosure with a callback of type
- * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>.
+ * `void (*callback) (gpointer instance, gpointer user_data)`.
  */
 
 
@@ -1187,7 +1163,7 @@
  * @return_gvalue: A #GValue to store the return value. May be %NULL
  *   if the callback of closure doesn't return a value.
  * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValue<!-- -->s holding the arguments
+ * @param_values: An array of #GValues holding the arguments
  *   on which to invoke the callback of closure.
  * @invocation_hint: The invocation hint given as the last argument to
  *   g_closure_invoke().
@@ -1195,8 +1171,8 @@
  *   marshaller, see g_closure_set_marshal() and
  *   g_closure_set_meta_marshal()
  *
- * A generic marshaller function implemented via <ulink
- * url="http://sourceware.org/libffi/">libffi</ulink>.
+ * A generic marshaller function implemented via
+ * [libffi](http://sourceware.org/libffi/).
  *
  * Since: 2.30
  */
@@ -1351,7 +1327,7 @@
  *                doesn't return a value.
  * @n_param_values: the length of the @param_values array
  * @param_values: (array length=n_param_values): an array of
- *                #GValue<!-- -->s holding the arguments on which to
+ *                #GValues holding the arguments on which to
  *                invoke the callback of @closure
  * @invocation_hint: (allow-none): a context-dependent invocation hint
  *
@@ -1362,7 +1338,7 @@
 /**
  * g_closure_new_object:
  * @sizeof_closure: the size of the structure to allocate, must be at least
- *  <literal>sizeof (GClosure)</literal>
+ *  `sizeof (GClosure)`
  * @object: a #GObject pointer to store in the @data field of the newly
  *  allocated #GClosure
  *
@@ -1378,19 +1354,19 @@
 /**
  * g_closure_new_simple:
  * @sizeof_closure: the size of the structure to allocate, must be at least
- *                  <literal>sizeof (GClosure)</literal>
+ *                  `sizeof (GClosure)`
  * @data: data to store in the @data field of the newly allocated #GClosure
  *
  * Allocates a struct of the given size and initializes the initial
  * part as a #GClosure. This function is mainly useful when
  * implementing new types of closures.
  *
- * |[
+ * |[<!-- language="C" -->
  * typedef struct _MyClosure MyClosure;
  * struct _MyClosure
  * {
  *   GClosure closure;
- *   // extra data goes here
+ *   /&ast; extra data goes here &ast;/
  * };
  *
  * static void
@@ -1399,7 +1375,7 @@
  * {
  *   MyClosure *my_closure = (MyClosure *)closure;
  *
- *   // free extra data here
+ *   /&ast; free extra data here &ast;/
  * }
  *
  * MyClosure *my_closure_new (gpointer data)
@@ -1410,7 +1386,7 @@
  *   closure = g_closure_new_simple (sizeof (MyClosure), data);
  *   my_closure = (MyClosure *) closure;
  *
- *   // initialize extra data here
+ *   /&ast; initialize extra data here &ast;/
  *
  *   g_closure_add_finalize_notifier (closure, notify_data,
  *                                    my_closure_finalize);
@@ -1464,7 +1440,7 @@
  * @closure: a #GClosure
  * @marshal: a #GClosureMarshal function
  *
- * Sets the marshaller of @closure. The <literal>marshal_data</literal>
+ * Sets the marshaller of @closure. The `marshal_data`
  * of @marshal provides a way for a meta marshaller to provide additional
  * information to the marshaller. (See g_closure_set_meta_marshal().) For
  * GObject's C predefined marshallers (the g_cclosure_marshal_*()
@@ -1503,27 +1479,27 @@
  *           still being held
  *
  * Takes over the initial ownership of a closure.  Each closure is
- * initially created in a <firstterm>floating</firstterm> state, which
- * means that the initial reference count is not owned by any caller.
- * g_closure_sink() checks to see if the object is still floating, and
- * if so, unsets the floating state and decreases the reference
- * count. If the closure is not floating, g_closure_sink() does
- * nothing. The reason for the existence of the floating state is to
- * prevent cumbersome code sequences like:
- * |[
+ * initially created in a "floating" state, which means that the initial
+ * reference count is not owned by any caller. g_closure_sink() checks
+ * to see if the object is still floating, and if so, unsets the
+ * floating state and decreases the reference count. If the closure
+ * is not floating, g_closure_sink() does nothing. The reason for the
+ * existence of the floating state is to prevent cumbersome code
+ * sequences like:
+ * |[<!-- language="C" -->
  * closure = g_cclosure_new (cb_func, cb_data);
  * g_source_set_closure (source, closure);
- * g_closure_unref (closure); // XXX GObject doesn't really need this
+ * g_closure_unref (closure); /&ast; GObject doesn't really need this &ast;/
  * ]|
  * Because g_source_set_closure() (and similar functions) take ownership of the
  * initial reference count, if it is unowned, we instead can write:
- * |[
+ * |[<!-- language="C" -->
  * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
  * ]|
  *
  * Generally, this function is used together with g_closure_ref(). Ane example
  * of storing a closure for later notification looks like:
- * |[
+ * |[<!-- language="C" -->
  * static GClosure *notify_closure = NULL;
  * void
  * foo_notify_set_closure (GClosure *closure)
@@ -1563,11 +1539,11 @@
  *  enumeration values. The array is terminated by a struct with all
  *  members being 0.
  *
- * This function is meant to be called from the <literal>complete_type_info</literal>
+ * This function is meant to be called from the `complete_type_info`
  * function of a #GTypePlugin implementation, as in the following
  * example:
  *
- * |[
+ * |[<!-- language="C" -->
  * static void
  * my_enum_complete_type_info (GTypePlugin     *plugin,
  *                             GType            g_type,
@@ -1735,8 +1711,8 @@
  * to the proxy object, but when there are other references held to
  * @object, a strong reference is held. The @notify callback is called
  * when the reference from @object to the proxy object should be
- * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref
- * true) or weak to strong (@is_last_ref false).
+ * "toggled" from strong to weak (@is_last_ref true) or weak to strong
+ * (@is_last_ref false).
  *
  * Since a (normal) reference must be held to the object before
  * calling g_object_add_toggle_ref(), the initial state of the reverse
@@ -1801,8 +1777,8 @@
  * A #GObject can have multiple bindings.
  *
  * Returns: (transfer none): the #GBinding instance representing the
- *   binding between the two #GObject instances. The binding is released
- *   whenever the #GBinding reference count reaches zero.
+ *     binding between the two #GObject instances. The binding is released
+ *     whenever the #GBinding reference count reaches zero.
  * Since: 2.26
  */
 
@@ -1815,13 +1791,13 @@
  * @target_property: the property on @target to bind
  * @flags: flags to pass to #GBinding
  * @transform_to: (scope notified) (allow-none): the transformation function
- *   from the @source to the @target, or %NULL to use the default
+ *     from the @source to the @target, or %NULL to use the default
  * @transform_from: (scope notified) (allow-none): the transformation function
- *   from the @target to the @source, or %NULL to use the default
+ *     from the @target to the @source, or %NULL to use the default
  * @user_data: custom data to be passed to the transformation functions,
- *   or %NULL
+ *     or %NULL
  * @notify: function to be called when disposing the binding, to free the
- *   resources used by the transformation functions
+ *     resources used by the transformation functions
  *
  * Complete version of g_object_bind_property().
  *
@@ -1841,15 +1817,15 @@
  *
  * A #GObject can have multiple bindings.
  *
- * <note>The same @user_data parameter will be used for both @transform_to
+ * The same @user_data parameter will be used for both @transform_to
  * and @transform_from transformation functions; the @notify function will
  * be called once, when the binding is removed. If you need different data
  * for each transformation function, please use
- * g_object_bind_property_with_closures() instead.</note>
+ * g_object_bind_property_with_closures() instead.
  *
  * Returns: (transfer none): the #GBinding instance representing the
- *   binding between the two #GObject instances. The binding is released
- *   whenever the #GBinding reference count reaches zero.
+ *     binding between the two #GObject instances. The binding is released
+ *     whenever the #GBinding reference count reaches zero.
  * Since: 2.26
  */
 
@@ -1862,21 +1838,21 @@
  * @target_property: the property on @target to bind
  * @flags: flags to pass to #GBinding
  * @transform_to: a #GClosure wrapping the transformation function
- *   from the @source to the @target, or %NULL to use the default
+ *     from the @source to the @target, or %NULL to use the default
  * @transform_from: a #GClosure wrapping the transformation function
- *   from the @target to the @source, or %NULL to use the default
+ *     from the @target to the @source, or %NULL to use the default
  *
  * Creates a binding between @source_property on @source and @target_property
  * on @target, allowing you to set the transformation functions to be used by
  * the binding.
  *
  * This function is the language bindings friendly version of
- * g_object_bind_property_full(), using #GClosure<!-- -->s instead of
+ * g_object_bind_property_full(), using #GClosures instead of
  * function pointers.
  *
  * Returns: (transfer none): the #GBinding instance representing the
- *   binding between the two #GObject instances. The binding is released
- *   whenever the #GBinding reference count reaches zero.
+ *     binding between the two #GObject instances. The binding is released
+ *     whenever the #GBinding reference count reaches zero.
  * Since: 2.26
  */
 
@@ -1896,11 +1872,11 @@
 /**
  * g_object_class_install_properties:
  * @oclass: a #GObjectClass
- * @n_pspecs: the length of the #GParamSpec<!-- -->s array
- * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array
+ * @n_pspecs: the length of the #GParamSpecs array
+ * @pspecs: (array length=n_pspecs): the #GParamSpecs array
  *   defining the new properties
  *
- * Installs new properties from an array of #GParamSpec<!-- -->s. This is
+ * Installs new properties from an array of #GParamSpecs. This is
  * usually done in the class initializer.
  *
  * The property id of each property is the index of each #GParamSpec in
@@ -1910,10 +1886,10 @@
  * be used to store a #GParamSpec.
  *
  * This function should be used if you plan to use a static array of
- * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this
+ * #GParamSpecs and g_object_notify_by_pspec(). For instance, this
  * class initialization:
  *
- * |[
+ * |[<!-- language="C" -->
  * enum {
  *   PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES
  * };
@@ -1946,7 +1922,7 @@
  *
  * allows calling g_object_notify_by_pspec() to notify of property changes:
  *
- * |[
+ * |[<!-- language="C" -->
  * void
  * my_object_set_foo (MyObject *self, gint foo)
  * {
@@ -1995,13 +1971,12 @@
  * @name: the name of a property registered in a parent class or
  *  in an interface of this class.
  *
- * Registers @property_id as referring to a property with the
- * name @name in a parent class or in an interface implemented
- * by @oclass. This allows this class to <firstterm>override</firstterm>
- * a property implementation in a parent class or to provide
- * the implementation of a property from an interface.
+ * Registers @property_id as referring to a property with the name
+ * @name in a parent class or in an interface implemented by @oclass.
+ * This allows this class to "override" a property implementation in
+ * a parent class or to provide the implementation of a property from
+ * an interface.
  *
- * <note>
  * Internally, overriding is implemented by creating a property of type
  * #GParamSpecOverride; generally operations that query the properties of
  * the object class, such as g_object_class_find_property() or
@@ -2012,7 +1987,6 @@
  * correct.  For virtually all uses, this makes no difference. If you
  * need to get the overridden property, you can call
  * g_param_spec_get_redirect_target().
- * </note>
  *
  * Since: 2.4
  */
@@ -2030,72 +2004,23 @@
  *
  * The signal specs expected by this function have the form
  * "modifier::signal_name", where modifier can be one of the following:
- * <variablelist>
- * <varlistentry>
- * <term>signal</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_data (..., NULL, 0)</literal>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>object_signal</term>
- * <term>object-signal</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_object (..., 0)</literal>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>swapped_signal</term>
- * <term>swapped-signal</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)</literal>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>swapped_object_signal</term>
- * <term>swapped-object-signal</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>signal_after</term>
- * <term>signal-after</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_AFTER)</literal>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>object_signal_after</term>
- * <term>object-signal-after</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>swapped_signal_after</term>
- * <term>swapped-signal-after</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>swapped_object_signal_after</term>
- * <term>swapped-object-signal-after</term>
- * <listitem><para>
- * equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
- * </para></listitem>
- * </varlistentry>
- * </variablelist>
- *
- * |[
+ * * - signal: equivalent to g_signal_connect_data (..., NULL, 0)
+ * - object-signal, object_signal: equivalent to g_signal_connect_object (..., 0)
+ * - swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED)
+ * - swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED)
+ * - signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER)
+ * - object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER)
+ * - swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER)
+ * - swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)
+ *
+ * |[<!-- language="C" -->
  *   menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
  * 						   "type", GTK_WINDOW_POPUP,
  * 						   "child", menu,
  * 						   NULL),
  * 				     "signal::event", gtk_menu_window_event, menu,
  * 				     "signal::size_request", gtk_menu_window_size_request, menu,
- * 				     "signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel,
+ * 				     "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
  * 				     NULL);
  * ]|
  *
@@ -2187,7 +2112,7 @@
  * This function is intended for #GObject implementations to re-enforce a
  * <link linkend="floating-ref">floating</link> object reference.
  * Doing this is seldom required: all
- * #GInitiallyUnowned<!-- -->s are created with a floating reference which
+ * #GInitiallyUnowneds are created with a floating reference which
  * usually just needs to be sunken by calling g_object_ref_sink().
  *
  * Since: 2.10
@@ -2223,12 +2148,9 @@
  * is responsible for freeing the memory in the appropriate manner for
  * the type, for instance by calling g_free() or g_object_unref().
  *
- * <example>
- * <title>Using g_object_get(<!-- -->)</title>
- * An example of using g_object_get() to get the contents
- * of three properties - one of type #G_TYPE_INT,
- * one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
- * <programlisting>
+ * Here is an example of using g_object_get() to get the contents
+ * of three properties: an integer, a string and an object:
+ * |[<!-- language="C" -->
  *  gint intval;
  *  gchar *strval;
  *  GObject *objval;
@@ -2239,12 +2161,11 @@
  *                "obj-property", &objval,
  *                NULL);
  *
- *  // Do something with intval, strval, objval
+ *  /&ast; Do something with intval, strval, objval &ast;/
  *
  *  g_free (strval);
  *  g_object_unref (objval);
- * </programlisting>
- * </example>
+ *  ]|
  */
 
 
@@ -2463,7 +2384,7 @@
  * instead, is to store the GParamSpec used with
  * g_object_class_install_property() inside a static array, e.g.:
  *
- * |[
+ * |[<!-- language="C" -->
  *   enum
  *   {
  *     PROP_0,
@@ -2488,7 +2409,7 @@
  *
  * and then notify a change on the "foo" property with:
  *
- * |[
+ * |[<!-- language="C" -->
  *   g_object_notify_by_pspec (self, properties[PROP_FOO]);
  * ]|
  *
@@ -2741,7 +2662,7 @@
  * set).
  * Usually, calling this function is only required to update
  * user data pointers with a destroy notifier, for example:
- * |[
+ * |[<!-- language="C" -->
  * void
  * object_add_to_user_list (GObject     *object,
  *                          const gchar *new_string)
@@ -3119,7 +3040,7 @@
  * efficient and in fact required when using property names as detail
  * strings for signals.
  *
- * Beyond the name, #GParamSpec<!-- -->s have two more descriptive
+ * Beyond the name, #GParamSpecs have two more descriptive
  * strings associated with them, the @nick, which should be suitable
  * for use as a label for the property in a property editor, and the
  * @blurb, which should be a somewhat longer description, suitable for
@@ -3226,7 +3147,7 @@
  * @owner_type: the owner to look for
  * @n_pspecs_p: (out): return location for the length of the returned array
  *
- * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
+ * Gets an array of all #GParamSpecs owned by @owner_type in
  * the pool.
  *
  * Returns: (array length=n_pspecs_p) (transfer container): a newly
@@ -3240,12 +3161,12 @@
  * @pool: a #GParamSpecPool
  * @owner_type: the owner to look for
  *
- * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
+ * Gets an #GList of all #GParamSpecs owned by @owner_type in
  * the pool.
  *
  * Returns: (transfer container) (element-type GObject.ParamSpec): a
- *          #GList of all #GParamSpec<!-- -->s owned by @owner_type in
- *          the pool#GParamSpec<!-- -->s.
+ *          #GList of all #GParamSpecs owned by @owner_type in
+ *          the pool#GParamSpecs.
  */
 
 
@@ -3333,7 +3254,7 @@
  *  be freed
  *
  * This function works like g_param_spec_set_qdata(), but in addition,
- * a <literal>void (*destroy) (gpointer)</literal> function may be
+ * a `void (*destroy) (gpointer)` function may be
  * specified which is called with @data as argument when the @pspec is
  * finalized, or the data is being overwritten by a call to
  * g_param_spec_set_qdata() with the same @quark.
@@ -3347,8 +3268,8 @@
  * The initial reference count of a newly created #GParamSpec is 1,
  * even though no one has explicitly called g_param_spec_ref() on it
  * yet. So the initial reference count is flagged as "floating", until
- * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink
- * (pspec);</literal> in sequence on it, taking over the initial
+ * someone calls `g_param_spec_ref (pspec); g_param_spec_sink
+ * (pspec);` in sequence on it, taking over the initial
  * reference count (thus ending up with a @pspec that has a reference
  * count of 1 still, but is not flagged "floating" anymore).
  */
@@ -3655,8 +3576,8 @@
  * that a return of %TRUE stops the signal emission: no further
  * callbacks will be invoked, while a return of %FALSE allows
  * the emission to continue. The idea here is that a %TRUE return
- * indicates that the callback <emphasis>handled</emphasis> the signal,
- * and no further handling is needed.
+ * indicates that the callback handled the signal, and no further
+ * handling is needed.
  *
  * Since: 2.4
  * Returns: standard #GSignalAccumulator result
@@ -3750,8 +3671,8 @@
  * Connects a #GCallback function to a signal for a particular object. Similar
  * to g_signal_connect(), but allows to provide a #GClosureNotify for the data
  * which will be called when the signal handler is disconnected and no longer
- * used. Specify @connect_flags if you need <literal>..._after()</literal> or
- * <literal>..._swapped()</literal> variants of this function.
+ * used. Specify @connect_flags if you need `..._after()` or
+ * `..._swapped()` variants of this function.
  *
  * Returns: the handler id (always greater than 0 for successful connections)
  */
@@ -4104,9 +4025,8 @@
  * be used, but they cannot be mixed.
  *
  * If 0 is used for @class_offset subclasses cannot override the class handler
- * in their <code>class_init</code> method by doing
- * <code>super_class->signal_handler = my_signal_handler</code>. Instead they
- * will have to use g_signal_override_class_handler().
+ * in their class_init method by doing super_class->signal_handler = my_signal_handler.
+ * Instead they will have to use g_signal_override_class_handler().
  *
  * If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as
  * the marshaller for this signal.
@@ -4397,8 +4317,8 @@
 
 /**
  * g_type_add_class_private:
- * @class_type: GType of an classed type.
- * @private_size: size of private structure.
+ * @class_type: GType of an classed type
+ * @private_size: size of private structure
  *
  * Registers a private class structure for a classed type;
  * when the class is allocated, the private structures for
@@ -4417,14 +4337,14 @@
  * g_type_add_interface_check: (skip)
  * @check_data: data to pass to @check_func
  * @check_func: function to be called after each interface
- *              is initialized.
+ *     is initialized
  *
  * Adds a function to be called after an interface vtable is
- * initialized for any class (i.e. after the @interface_init member of
- * #GInterfaceInfo has been called).
+ * initialized for any class (i.e. after the @interface_init
+ * member of #GInterfaceInfo has been called).
  *
- * This function is useful when you want to check an invariant that
- * depends on the interfaces of a class. For instance, the
+ * This function is useful when you want to check an invariant
+ * that depends on the interfaces of a class. For instance, the
  * implementation of #GObject uses this facility to check that an
  * object implements all of the properties that are defined on its
  * interfaces.
@@ -4435,9 +4355,9 @@
 
 /**
  * g_type_add_interface_dynamic:
- * @instance_type: the #GType value of an instantiable type.
- * @interface_type: the #GType value of an interface type.
- * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from.
+ * @instance_type: #GType value of an instantiable type
+ * @interface_type: #GType value of an interface type
+ * @plugin: #GTypePlugin structure to retrieve the #GInterfaceInfo from
  *
  * Adds the dynamic @interface_type to @instantiable_type. The information
  * contained in the #GTypePlugin structure pointed to by @plugin
@@ -4447,46 +4367,46 @@
 
 /**
  * g_type_add_interface_static:
- * @instance_type: #GType value of an instantiable type.
- * @interface_type: #GType value of an interface type.
- * @info: The #GInterfaceInfo structure for this
- *        (@instance_type, @interface_type) combination.
+ * @instance_type: #GType value of an instantiable type
+ * @interface_type: #GType value of an interface type
+ * @info: #GInterfaceInfo structure for this
+ *        (@instance_type, @interface_type) combination
  *
- * Adds the static @interface_type to @instantiable_type.  The
- * information contained in the #GInterfaceInfo structure pointed to by
- * @info is used to manage the relationship.
+ * Adds the static @interface_type to @instantiable_type.
+ * The information contained in the #GInterfaceInfo structure
+ * pointed to by @info is used to manage the relationship.
  */
 
 
 /**
  * g_type_check_instance:
- * @instance: A valid #GTypeInstance structure.
+ * @instance: a valid #GTypeInstance structure
  *
- * Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE()
- * macro.
+ * Private helper function to aid implementation of the
+ * G_TYPE_CHECK_INSTANCE() macro.
  *
- * Returns: %TRUE if @instance is valid, %FALSE otherwise.
+ * Returns: %TRUE if @instance is valid, %FALSE otherwise
  */
 
 
 /**
  * g_type_children:
- * @type: The parent type.
- * @n_children: (out) (allow-none): Optional #guint pointer to contain
- *              the number of child types.
+ * @type: the parent type
+ * @n_children: (out) (allow-none): location to store the length of
+ *     the returned array, or %NULL
  *
- * Return a newly allocated and 0-terminated array of type IDs, listing the
- * child types of @type. The return value has to be g_free()ed after use.
+ * Return a newly allocated and 0-terminated array of type IDs, listing
+ * the child types of @type.
  *
  * Returns: (array length=n_children) (transfer full): Newly allocated
- *          and 0-terminated array of child types.
+ *     and 0-terminated array of child types, free with g_free()
  */
 
 
 /**
  * g_type_class_add_private:
  * @g_class: class structure for an instantiatable type
- * @private_size: size of private structure.
+ * @private_size: size of private structure
  *
  * Registers a private structure for an instantiatable type.
  *
@@ -4503,14 +4423,13 @@
  * G_TYPE_INSTANCE_GET_PRIVATE() macro.
  *
  * The following example shows attaching a private structure
- * <structname>MyObjectPrivate</structname> to an object
- * <structname>MyObject</structname> defined in the standard GObject
- * fashion.
- * type's class_init() function.
+ * MyObjectPrivate to an object MyObject defined in the standard
+ * GObject fashion in the type's class_init() function.
+ *
  * Note the use of a structure member "priv" to avoid the overhead
  * of repeatedly calling MY_OBJECT_GET_PRIVATE().
  *
- * |[
+ * |[<!-- language="C" -->
  * typedef struct _MyObject        MyObject;
  * typedef struct _MyObjectPrivate MyObjectPrivate;
  *
@@ -4575,71 +4494,69 @@
 
 /**
  * g_type_class_peek:
- * @type: Type ID of a classed type.
+ * @type: type ID of a classed type
  *
- * This function is essentially the same as g_type_class_ref(), except that
- * the classes reference count isn't incremented. As a consequence, this function
- * may return %NULL if the class of the type passed in does not currently
- * exist (hasn't been referenced before).
+ * This function is essentially the same as g_type_class_ref(),
+ * except that the classes reference count isn't incremented.
+ * As a consequence, this function may return %NULL if the class
+ * of the type passed in does not currently exist (hasn't been
+ * referenced before).
  *
- * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
- *  structure for the given type ID or %NULL if the class does not
- *  currently exist.
+ * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass
+ *     structure for the given type ID or %NULL if the class does not
+ *     currently exist
  */
 
 
 /**
  * g_type_class_peek_parent:
- * @g_class: (type GObject.TypeClass): The #GTypeClass structure to
- *  retrieve the parent class for.
+ * @g_class: (type GObject.TypeClass): the #GTypeClass structure to
+ *     retrieve the parent class for
  *
  * This is a convenience function often needed in class initializers.
  * It returns the class structure of the immediate parent type of the
  * class passed in.  Since derived classes hold a reference count on
  * their parent classes as long as they are instantiated, the returned
- * class will always exist. This function is essentially equivalent
- * to:
+ * class will always exist.
  *
- * <programlisting>
- * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
- * </programlisting>
+ * This function is essentially equivalent to:
+ * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)))
  *
- * Returns: (type GObject.TypeClass) (transfer none): The parent class
- *  of @g_class.
+ * Returns: (type GObject.TypeClass) (transfer none): the parent class
+ *     of @g_class
  */
 
 
 /**
  * g_type_class_peek_static:
- * @type: Type ID of a classed type.
+ * @type: type ID of a classed type
  *
  * A more efficient version of g_type_class_peek() which works only for
  * static types.
  *
+ * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass
+ *     structure for the given type ID or %NULL if the class does not
+ *     currently exist or is dynamically loaded
  * Since: 2.4
- * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
- *  structure for the given type ID or %NULL if the class does not
- *  currently exist or is dynamically loaded.
  */
 
 
 /**
  * g_type_class_ref:
- * @type: Type ID of a classed type.
+ * @type: type ID of a classed type
  *
  * Increments the reference count of the class structure belonging to
  * @type. This function will demand-create the class if it doesn't
  * exist already.
  *
- * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
- *  structure for the given type ID.
+ * Returns: (type GObject.TypeClass) (transfer none): the #GTypeClass
+ *     structure for the given type ID
  */
 
 
 /**
  * g_type_class_unref:
- * @g_class: (type GObject.TypeClass): The #GTypeClass structure to
- *  unreference.
+ * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref
  *
  * Decrements the reference count of the class structure being passed in.
  * Once the last reference count of a class has been released, classes
@@ -4650,19 +4567,18 @@
 
 /**
  * g_type_class_unref_uncached: (skip)
- * @g_class: (type GObject.TypeClass): The #GTypeClass structure to
- *  unreference.
+ * @g_class: (type GObject.TypeClass): a #GTypeClass structure to unref
  *
  * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc
  * implementations. It unreferences a class without consulting the chain
- * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur
+ * of #GTypeClassCacheFuncs, avoiding the recursion which would occur
  * otherwise.
  */
 
 
 /**
  * g_type_create_instance: (skip)
- * @type: An instantiatable type to create an instance for.
+ * @type: an instantiatable type to create an instance for
  *
  * Creates and initializes an instance of @type if @type is valid and
  * can be instantiated. The type system only performs basic allocation
@@ -4670,16 +4586,16 @@
  * happen through functions supplied by the type's fundamental type
  * implementation.  So use of g_type_create_instance() is reserved for
  * implementators of fundamental types only. E.g. instances of the
- * #GObject hierarchy should be created via g_object_new() and
- * <emphasis>never</emphasis> directly through
- * g_type_create_instance() which doesn't handle things like singleton
- * objects or object construction.  Note: Do <emphasis>not</emphasis>
- * use this function, unless you're implementing a fundamental
- * type. Also language bindings should <emphasis>not</emphasis> use
- * this function but g_object_new() instead.
+ * #GObject hierarchy should be created via g_object_new() and never
+ * directly through g_type_create_instance() which doesn't handle things
+ * like singleton objects or object construction.
+ *
+ * Note: Do not use this function, unless you're implementing a
+ * fundamental type. Also language bindings should not use this
+ * function, but g_object_new() instead.
  *
- * Returns: An allocated and initialized instance, subject to further
- *  treatment by the fundamental type implementation.
+ * Returns: an allocated and initialized instance, subject to further
+ *     treatment by the fundamental type implementation
  */
 
 
@@ -4692,8 +4608,8 @@
  *
  * Since: 2.4
  * Returns: (type GObject.TypeInterface) (transfer none): the default
- *  vtable for the interface, or %NULL if the type is not currently in
- *  use.
+ *     vtable for the interface, or %NULL if the type is not currently
+ *     in use
  */
 
 
@@ -4707,31 +4623,28 @@
  * If the type is not currently in use, then the default vtable
  * for the type will be created and initalized by calling
  * the base interface init and default vtable init functions for
- * the type (the @<structfield>base_init</structfield>
- * and <structfield>class_init</structfield> members of #GTypeInfo).
+ * the type (the @base_init and @class_init members of #GTypeInfo).
  * Calling g_type_default_interface_ref() is useful when you
  * want to make sure that signals and properties for an interface
  * have been installed.
  *
  * Since: 2.4
  * Returns: (type GObject.TypeInterface) (transfer none): the default
- *  vtable for the interface; call g_type_default_interface_unref()
- *  when you are done using the interface.
+ *     vtable for the interface; call g_type_default_interface_unref()
+ *     when you are done using the interface.
  */
 
 
 /**
  * g_type_default_interface_unref:
  * @g_iface: (type GObject.TypeInterface): the default vtable
- *  structure for a interface, as returned by
- *  g_type_default_interface_ref()
+ *     structure for a interface, as returned by g_type_default_interface_ref()
  *
  * Decrements the reference count for the type corresponding to the
  * interface default vtable @g_iface. If the type is dynamic, then
  * when no one is using the interface and all references have
  * been released, the finalize function for the interface's default
- * vtable (the <structfield>class_finalize</structfield> member of
- * #GTypeInfo) will be called.
+ * vtable (the @class_finalize member of #GTypeInfo) will be called.
  *
  * Since: 2.4
  */
@@ -4739,18 +4652,18 @@
 
 /**
  * g_type_depth:
- * @type: A #GType value.
+ * @type: a #GType
  *
  * Returns the length of the ancestry of the passed in type. This
  * includes the type itself, so that e.g. a fundamental type has depth 1.
  *
- * Returns: The depth of @type.
+ * Returns: the depth of @type
  */
 
 
 /**
  * g_type_ensure:
- * @type: a #GType.
+ * @type: a #GType
  *
  * Ensures that the indicated @type has been registered with the
  * type system, and its _class_init() method has been run.
@@ -4771,7 +4684,7 @@
 
 /**
  * g_type_free_instance:
- * @instance: an instance of a type.
+ * @instance: an instance of a type
  *
  * Frees an instance of a type, returning it to the instance pool for
  * the type, if there is one.
@@ -4783,14 +4696,14 @@
 
 /**
  * g_type_from_name:
- * @name: Type name to lookup.
+ * @name: type name to lookup
  *
  * Lookup the type ID from a given type name, returning 0 if no type
  * has been registered under this name (this is the preferred method
  * to find out by name whether a specific type has been registered
  * yet).
  *
- * Returns: Corresponding type ID or 0.
+ * Returns: corresponding type ID or 0
  */
 
 
@@ -4799,7 +4712,7 @@
  * @type_id: valid type ID
  *
  * Internal function, used to extract the fundamental type ID portion.
- * use G_TYPE_FUNDAMENTAL() instead.
+ * Use G_TYPE_FUNDAMENTAL() instead.
  *
  * Returns: fundamental type ID
  */
@@ -4813,20 +4726,19 @@
  * The returned type ID represents the highest currently registered
  * fundamental type identifier.
  *
- * Returns: The nextmost fundamental type ID to be registered,
- *          or 0 if the type system ran out of fundamental type IDs.
+ * Returns: the next available fundamental type ID to be registered,
+ *     or 0 if the type system ran out of fundamental type IDs
  */
 
 
 /**
  * g_type_get_plugin:
- * @type: The #GType to retrieve the plugin for.
+ * @type: #GType to retrieve the plugin for
  *
- * Returns the #GTypePlugin structure for @type or
- * %NULL if @type does not have a #GTypePlugin structure.
+ * Returns the #GTypePlugin structure for @type.
  *
- * Returns: (transfer none): The corresponding plugin if @type is a
- *          dynamic type, %NULL otherwise.
+ * Returns: (transfer none): the corresponding plugin
+ *     if @type is a dynamic type, %NULL otherwise
  */
 
 
@@ -4849,14 +4761,14 @@
 /**
  * g_type_get_type_registration_serial:
  *
- * Returns an opaque serial number that represents the state of the set of
- * registered types. Any time a type is registered this serial changes,
+ * Returns an opaque serial number that represents the state of the set
+ * of registered types. Any time a type is registered this serial changes,
  * which means you can cache information based on type lookups (such as
  * g_type_from_name()) and know if the cache is still valid at a later
  * time by comparing the current serial with the one at the type lookup.
  *
  * Since: 2.36
- * Returns: An unsigned int, representing the state of type registrations.
+ * Returns: An unsigned int, representing the state of type registrations
  */
 
 
@@ -4873,8 +4785,8 @@
 
 /**
  * g_type_init_with_debug_flags:
- * @debug_flags: Bitwise combination of #GTypeDebugFlags values for
- *               debugging purposes.
+ * @debug_flags: bitwise combination of #GTypeDebugFlags values for
+ *     debugging purposes
  *
  * This function used to initialise the type system with debugging
  * flags.  Since GLib 2.36, the type system is initialised automatically
@@ -4889,8 +4801,8 @@
 
 /**
  * g_type_interface_add_prerequisite:
- * @interface_type: #GType value of an interface type.
- * @prerequisite_type: #GType value of an interface or instantiatable type.
+ * @interface_type: #GType value of an interface type
+ * @prerequisite_type: #GType value of an interface or instantiatable type
  *
  * Adds @prerequisite_type to the list of prerequisites of @interface_type.
  * This means that any type implementing @interface_type must also implement
@@ -4902,46 +4814,46 @@
 
 /**
  * g_type_interface_get_plugin:
- * @instance_type: the #GType value of an instantiatable type.
- * @interface_type: the #GType value of an interface type.
+ * @instance_type: #GType of an instantiatable type
+ * @interface_type: #GType of an interface type
  *
  * Returns the #GTypePlugin structure for the dynamic interface
- * @interface_type which has been added to @instance_type, or %NULL if
- * @interface_type has not been added to @instance_type or does not
- * have a #GTypePlugin structure. See g_type_add_interface_dynamic().
+ * @interface_type which has been added to @instance_type, or %NULL
+ * if @interface_type has not been added to @instance_type or does
+ * not have a #GTypePlugin structure. See g_type_add_interface_dynamic().
  *
  * Returns: (transfer none): the #GTypePlugin for the dynamic
- *          interface @interface_type of @instance_type.
+ *     interface @interface_type of @instance_type
  */
 
 
 /**
  * g_type_interface_peek:
- * @instance_class: (type GObject.TypeClass): A #GTypeClass structure.
- * @iface_type: An interface ID which this class conforms to.
+ * @instance_class: (type GObject.TypeClass): a #GTypeClass structure
+ * @iface_type: an interface ID which this class conforms to
  *
  * Returns the #GTypeInterface structure of an interface to which the
  * passed in class conforms.
  *
- * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface
- *  structure of iface_type if implemented by @instance_class, %NULL
- *  otherwise
+ * Returns: (type GObject.TypeInterface) (transfer none): the #GTypeInterface
+ *     structure of @iface_type if implemented by @instance_class, %NULL
+ *     otherwise
  */
 
 
 /**
  * g_type_interface_peek_parent:
- * @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure.
+ * @g_iface: (type GObject.TypeInterface): a #GTypeInterface structure
  *
  * Returns the corresponding #GTypeInterface structure of the parent type
  * of the instance type to which @g_iface belongs. This is useful when
  * deriving the implementation of an interface from the parent type and
  * then possibly overriding some methods.
  *
- * Returns: (transfer none) (type GObject.TypeInterface): The
- *  corresponding #GTypeInterface structure of the parent type of the
- *  instance type to which @g_iface belongs, or %NULL if the parent
- *  type doesn't conform to the interface.
+ * Returns: (transfer none) (type GObject.TypeInterface): the
+ *     corresponding #GTypeInterface structure of the parent type of the
+ *     instance type to which @g_iface belongs, or %NULL if the parent
+ *     type doesn't conform to the interface
  */
 
 
@@ -4949,42 +4861,42 @@
  * g_type_interface_prerequisites:
  * @interface_type: an interface type
  * @n_prerequisites: (out) (allow-none): location to return the number
- *                   of prerequisites, or %NULL
+ *     of prerequisites, or %NULL
  *
  * Returns the prerequisites of an interfaces type.
  *
  * Since: 2.2
  * Returns: (array length=n_prerequisites) (transfer full): a
- *          newly-allocated zero-terminated array of #GType containing
- *          the prerequisites of @interface_type
+ *     newly-allocated zero-terminated array of #GType containing
+ *     the prerequisites of @interface_type
  */
 
 
 /**
  * g_type_interfaces:
- * @type: The type to list interface types for.
- * @n_interfaces: (out) (allow-none): Optional #guint pointer to
- *                contain the number of interface types.
+ * @type: the type to list interface types for
+ * @n_interfaces: (out) (allow-none): location to store the length of
+ *     the returned array, or %NULL
  *
- * Return a newly allocated and 0-terminated array of type IDs, listing the
- * interface types that @type conforms to. The return value has to be
- * g_free()ed after use.
+ * Return a newly allocated and 0-terminated array of type IDs, listing
+ * the interface types that @type conforms to.
  *
- * Returns: (array length=n_interfaces) (transfer full): Newly
- *          allocated and 0-terminated array of interface types.
+ * Returns: (array length=n_interfaces) (transfer full): Newly allocated
+ *     and 0-terminated array of interface types, free with g_free()
  */
 
 
 /**
  * g_type_is_a:
- * @type: Type to check anchestry for.
- * @is_a_type: Possible anchestor of @type or interface @type could conform to.
+ * @type: type to check anchestry for
+ * @is_a_type: possible anchestor of @type or interface that @type
+ *     could conform to
  *
  * If @is_a_type is a derivable type, check whether @type is a
- * descendant of @is_a_type.  If @is_a_type is an interface, check
+ * descendant of @is_a_type. If @is_a_type is an interface, check
  * whether @type conforms to it.
  *
- * Returns: %TRUE if @type is_a @is_a_type holds true.
+ * Returns: %TRUE if @type is a @is_a_type
  */
 
 
@@ -5109,7 +5021,7 @@
 
 /**
  * g_type_name:
- * @type: Type to return name for.
+ * @type: type to return name for
  *
  * Get the unique name that is assigned to a type ID.  Note that this
  * function (like all other GType API) cannot cope with invalid type
@@ -5117,35 +5029,35 @@
  * other validly registered type ID, but randomized type IDs should
  * not be passed in and will most likely lead to a crash.
  *
- * Returns: Static type name or %NULL.
+ * Returns: static type name or %NULL
  */
 
 
 /**
  * g_type_next_base:
- * @leaf_type: Descendant of @root_type and the type to be returned.
- * @root_type: Immediate parent of the returned type.
+ * @leaf_type: descendant of @root_type and the type to be returned
+ * @root_type: immediate parent of the returned type
  *
  * Given a @leaf_type and a @root_type which is contained in its
  * anchestry, return the type that @root_type is the immediate parent
- * of.  In other words, this function determines the type that is
+ * of. In other words, this function determines the type that is
  * derived directly from @root_type which is also a base class of
  * @leaf_type.  Given a root type and a leaf type, this function can
  * be used to determine the types and order in which the leaf type is
  * descended from the root type.
  *
- * Returns: Immediate child of @root_type and anchestor of @leaf_type.
+ * Returns: immediate child of @root_type and anchestor of @leaf_type
  */
 
 
 /**
  * g_type_parent:
- * @type: The derived type.
+ * @type: the derived type
  *
- * Return the direct parent type of the passed in type.  If the passed
+ * Return the direct parent type of the passed in type. If the passed
  * in type has no parent, i.e. is a fundamental type, 0 is returned.
  *
- * Returns: The parent type.
+ * Returns: the parent type
  */
 
 
@@ -5198,19 +5110,19 @@
 
 /**
  * g_type_qname:
- * @type: Type to return quark of type name for.
+ * @type: type to return quark of type name for
  *
  * Get the corresponding quark of the type IDs name.
  *
- * Returns: The type names quark or 0.
+ * Returns: the type names quark or 0
  */
 
 
 /**
  * g_type_query:
- * @type: the #GType value of a static, classed type.
- * @query: (out caller-allocates): A user provided structure that is
- *         filled in with constant values upon success.
+ * @type: #GType of a static, classed type
+ * @query: (out caller-allocates): a user provided structure that is
+ *     filled in with constant values upon success
  *
  * Queries the type system for information about a specific type.
  * This function will fill in a user-provided structure to hold
@@ -5223,10 +5135,10 @@
 
 /**
  * g_type_register_dynamic:
- * @parent_type: Type from which this type will be derived.
- * @type_name: 0-terminated string used as the name of the new type.
- * @plugin: The #GTypePlugin structure to retrieve the #GTypeInfo from.
- * @flags: Bitwise combination of #GTypeFlags values.
+ * @parent_type: type from which this type will be derived
+ * @type_name: 0-terminated string used as the name of the new type
+ * @plugin: #GTypePlugin structure to retrieve the #GTypeInfo from
+ * @flags: bitwise combination of #GTypeFlags values
  *
  * Registers @type_name as the name of a new dynamic type derived from
  * @parent_type.  The type system uses the information contained in the
@@ -5234,56 +5146,56 @@
  * instances (if not abstract).  The value of @flags determines the nature
  * (e.g. abstract or not) of the type.
  *
- * Returns: The new type identifier or #G_TYPE_INVALID if registration failed.
+ * Returns: the new type identifier or #G_TYPE_INVALID if registration failed
  */
 
 
 /**
  * g_type_register_fundamental:
- * @type_id: A predefined type identifier.
- * @type_name: 0-terminated string used as the name of the new type.
- * @info: The #GTypeInfo structure for this type.
- * @finfo: The #GTypeFundamentalInfo structure for this type.
- * @flags: Bitwise combination of #GTypeFlags values.
+ * @type_id: a predefined type identifier
+ * @type_name: 0-terminated string used as the name of the new type
+ * @info: #GTypeInfo structure for this type
+ * @finfo: #GTypeFundamentalInfo structure for this type
+ * @flags: bitwise combination of #GTypeFlags values
  *
  * Registers @type_id as the predefined identifier and @type_name as the
- * name of a fundamental type. If @type_id is already registered, or a type
- * named @type_name is already registered, the behaviour is undefined. The type
- * system uses the information contained in the #GTypeInfo structure pointed to
- * by @info and the #GTypeFundamentalInfo structure pointed to by @finfo to
- * manage the type and its instances. The value of @flags determines additional
- * characteristics of the fundamental type.
+ * name of a fundamental type. If @type_id is already registered, or a
+ * type named @type_name is already registered, the behaviour is undefined.
+ * The type system uses the information contained in the #GTypeInfo structure
+ * pointed to by @info and the #GTypeFundamentalInfo structure pointed to by
+ * @finfo to manage the type and its instances. The value of @flags determines
+ * additional characteristics of the fundamental type.
  *
- * Returns: The predefined type identifier.
+ * Returns: the predefined type identifier
  */
 
 
 /**
  * g_type_register_static:
- * @parent_type: Type from which this type will be derived.
- * @type_name: 0-terminated string used as the name of the new type.
- * @info: The #GTypeInfo structure for this type.
- * @flags: Bitwise combination of #GTypeFlags values.
+ * @parent_type: type from which this type will be derived
+ * @type_name: 0-terminated string used as the name of the new type
+ * @info: #GTypeInfo structure for this type
+ * @flags: bitwise combination of #GTypeFlags values
  *
  * Registers @type_name as the name of a new static type derived from
- * @parent_type.  The type system uses the information contained in the
+ * @parent_type. The type system uses the information contained in the
  * #GTypeInfo structure pointed to by @info to manage the type and its
- * instances (if not abstract).  The value of @flags determines the nature
+ * instances (if not abstract). The value of @flags determines the nature
  * (e.g. abstract or not) of the type.
  *
- * Returns: The new type identifier.
+ * Returns: the new type identifier
  */
 
 
 /**
  * g_type_register_static_simple: (skip)
- * @parent_type: Type from which this type will be derived.
- * @type_name: 0-terminated string used as the name of the new type.
- * @class_size: Size of the class structure (see #GTypeInfo)
- * @class_init: Location of the class initialization function (see #GTypeInfo)
- * @instance_size: Size of the instance structure (see #GTypeInfo)
- * @instance_init: Location of the instance initialization function (see #GTypeInfo)
- * @flags: Bitwise combination of #GTypeFlags values.
+ * @parent_type: type from which this type will be derived
+ * @type_name: 0-terminated string used as the name of the new type
+ * @class_size: size of the class structure (see #GTypeInfo)
+ * @class_init: location of the class initialization function (see #GTypeInfo)
+ * @instance_size: size of the instance structure (see #GTypeInfo)
+ * @instance_init: location of the instance initialization function (see #GTypeInfo)
+ * @flags: bitwise combination of #GTypeFlags values
  *
  * Registers @type_name as the name of a new static type derived from
  * @parent_type.  The value of @flags determines the nature (e.g.
@@ -5291,7 +5203,7 @@
  * struct and calling g_type_register_static().
  *
  * Since: 2.12
- * Returns: The new type identifier.
+ * Returns: the new type identifier
  */
 
 
@@ -5330,15 +5242,16 @@
 
 /**
  * g_type_value_table_peek: (skip)
- * @type: A #GType value.
+ * @type: a #GType
  *
  * Returns the location of the #GTypeValueTable associated with @type.
- * <emphasis>Note that this function should only be used from source code
+ *
+ * Note that this function should only be used from source code
  * that implements or has internal knowledge of the implementation of
- * @type.</emphasis>
+ * @type.
  *
- * Returns: Location of the #GTypeValueTable associated with @type or
- *  %NULL if there is no #GTypeValueTable associated with @type.
+ * Returns: location of the #GTypeValueTable associated with @type or
+ *     %NULL if there is no #GTypeValueTable associated with @type
  */
 
 
@@ -5433,8 +5346,7 @@
  * g_value_array_remove:
  * @value_array: #GValueArray to remove an element from
  * @index_: position of value to remove, which must be less than
- *          <code>value_array-><link
- *          linkend="GValueArray.n-values">n_values</link></code>
+ *     @value_array->n_values
  *
  * Remove the value at position @index_ from @value_array.
  *