[gobject-introspection] Update glib annotations from git master
- From: Rico Tzschichholz <ricotz src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Update glib annotations from git master
- Date: Sat, 8 Feb 2014 09:35:47 +0000 (UTC)
commit b63f85310b357cb9e3c8775c9bd833bef6e80420
Author: Rico Tzschichholz <ricotz ubuntu com>
Date: Sat Feb 8 10:33:30 2014 +0100
Update glib annotations from git master
gir/gio-2.0.c | 3212 ++++++++++++++--------------
gir/glib-2.0.c | 6059 +++++++++++++++++++++++++----------------------------
gir/gmodule-2.0.c | 38 +-
gir/gobject-2.0.c | 996 ++++-----
4 files changed, 4993 insertions(+), 5312 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index d19178b..d3f9c58 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" -->
+ * /* Make sure we don't do unnecessary work if already cancelled */
* 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 *<!-- -->/
+ * /* Set up all the data needed to be able to
+ * * handle cancellation of the operation
+ * */
* my_data = my_data_new (...);
*
* id = 0;
@@ -356,12 +411,13 @@
* G_CALLBACK (cancelled_handler)
* data, NULL);
*
- * /<!-- -->* cancellable operation here... *<!-- -->/
+ * /* cancellable operation here... */
*
* g_cancellable_disconnect (cancellable, id);
*
- * /<!-- -->* cancelled_handler is never called after this, it
- * * is now safe to free the data *<!-- -->/
+ * /* cancelled_handler is never called after this,
+ * * it is now safe to free the data
+ * */
* 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
+ * /* Volume only goes from 0 to 10 */
* 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;
*
* /* Register an extension point */
@@ -3522,7 +3509,7 @@
* g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
* ]|
*
- * |[
+ * |[<!-- language="C" -->
* /* Implement an extension point */
* 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
- * %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
+ * %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
+ * /* do something special with uri */
* }
* 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;
+ *
+ * /* do the heavy lifting in an idle */
+ *
+ * g_application_command_line_set_exit_status (cmdline, 0);
+ * g_object_unref (cmdline); /* this releases the application */
+ *
+ * return G_SOURCE_REMOVE;
+ * }
+ *
+ * static int
+ * command_line (GApplication *application,
+ * GApplicationCommandLine *cmdline)
+ * {
+ * /* keep the application running until we are done with this commandline */
+ * 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" -->
+ * /* foo-bar-error.h: */
*
* #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 /*< skip >*/
* } FooBarError;
*
- * /<!-- -->* foo-bar-error.c: *<!-- -->/
+ * /* foo-bar-error.c: */
*
* 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 *<!-- -->/
+ * /* Ensure that every error code has an associated D-Bus error name */
* 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><gio/gdesktopappinfo.h></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 `<gio/gdesktopappinfo.h>` 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><gio/gfiledescriptorbased.h></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 `<gio/gfiledescriptorbased.h>` 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}
+ *
+ * 
*
* 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}
+ *
+ * 
*
* 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 `<gio/gnetworking.h>` 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 <schemalist> or <schema>
+ * elements and the category that is specified in the l10n attribute of
+ * the <key> 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 <schema> 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 <choice>,
+ * <enum> or <flags> 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).
- * *<!-- -->/
+ * /* 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).
+ * */
* 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.
- * *<!-- -->/
+ * /* We couldn't connect to the first address, but we succeeded
+ * * in connecting to a later address.
+ * */
* g_error_free (conn_error);
* }
* return conn;
* }
* else if (error)
* {
- * /<!-- -->* Either the initial lookup failed, or else the caller
- * * cancelled us.
- * *<!-- -->/
+ * /* Either the initial lookup failed, or else the caller
+ * * cancelled us.
+ * */
* 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><gio/gunixconnection.h></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 `<gio/gunixconnection.h>` 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><gio/gunixfdlist.h></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 `<gio/gunixfdlist.h>` 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><gio/gunixfdmessage.h></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 `<gio/gunixfdmessage.h>` 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><gio/gunixinputstream.h></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 `<gio/gunixinputstream.h>` 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><gio/gunixmounts.h></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 `<gio/gunixmounts.h>` 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><gio/gunixoutputstream.h></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 `<gio/gunixoutputstream.h>` 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><gio/gunixsocketaddress.h></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 `<gio/gunixsocketaddress.h>` 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><gio/gwin32inputstream.h></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 `<gio/gwin32inputstream.h>` 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><gio/gwin32outputstream.h></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 `<gio/gwin32outputstream.h>` 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,
- * &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: method-call
- * Flags: none
- * Version: 0
- * Serial: 4
- * Headers:
+ * |[
+ * Flags: none
+ * Version: 0
+ * Serial: 4
+ * Headers:
* path -> objectpath '/org/gtk/GDBus/TestObject'
* interface -> 'org.gtk.GDBus.TestInterface'
* member -> 'GimmeStdout'
* destination -> ':1.146'
- * Body: ()
+ * Body: ()
* UNIX File Descriptors:
* (none)
- * </programlisting>
+ * ]|
* or
- * <programlisting>
- * Type: method-return
- * Flags: no-reply-expected
- * Version: 0
- * Serial: 477
- * Headers:
+ * |[
+ * 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: ()
- * UNIX File Descriptors:
+ * 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.
+ * <node> 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,
- * &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,
- * &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%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%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" -->
* /* a stream that can grow */
* 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><protocol>://[user[:password] ]host:port</literal>
- * or <literal>direct://</literal>, where <protocol> 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 `<protocol>://[user[:password] ]host:port` or
+ * `direct://`, where <protocol> 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 <child> 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><gio/gnetworking.h></literal></link>
+ * The <link linkend="gio-gnetworking.h">`<gio/gnetworking.h>`</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><gio/gnetworking.h></literal></link>
+ * The <link linkend="gio-gnetworking.h">`<gio/gnetworking.h>`</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); /* mounted, so never NULL */
* mount_root = g_mount_get_root (mount);
- * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
- * </programlisting>
- *
+ * volume_activation_root = g_volume_get_activation_root (volume); /* assume not NULL */
+ * ]|
* 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 bb403b1..a68339e 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
- * *<!-- -->/
+ * /* now do a very complicated calculation to calculate the new
+ * * number, this might for example be a random number generator
+ * */
* 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 (&mutex);
+ * g_mutex_lock (&mutex);
* ret_val = current_number = calc_next_number (current_number);
- * g_mutex_unlock (&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 (&lock);
- * if (index < array->len)
+ * g_rw_lock_reader_lock (&lock);
+ * if (index < array->len)
* retval = g_ptr_array_index (array, index);
- * g_rw_lock_reader_unlock (&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 (&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 (&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 (&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 (&dict, orig);
+ * if (!g_variant_dict_lookup (&dict, "count", "u", &count))
+ * {
+ * g_set_error (...);
+ * g_variant_dict_clear (&dict);
+ * return NULL;
+ * }
+ *
+ * g_variant_dict_insert (&dict, "count", "u", count + 1);
+ *
+ * return g_variant_dict_end (&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", &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=%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, &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 << G_HOOK_FLAG_USER_SHIFT</literal> is the first
+ * `1 << 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
+ * /* return value should not be freed */
* const gchar *
* get_local_name (void)
* {
@@ -4412,7 +4442,7 @@
* }
*
*
- * static GPrivate count_key; // no free function
+ * static GPrivate count_key; /* no free function */
*
* 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 > 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. *<!-- -->/
+ * /* We create a new array to store gint values.
+ * * We don't want it zero-terminated or cleared to 0's.
+ * */
* garray = g_array_new (FALSE, FALSE, sizeof (gint));
- * for (i = 0; i < 10000; i++)
+ * for (i = 0; i < 10000; i++)
* g_array_append_val (garray, i);
- * for (i = 0; i < 10000; i++)
+ * for (i = 0; i < 10000; i++)
* if (g_array_index (garray, gint, i) != i)
- * g_print ("ERROR: got %d instead of %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 < 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 < 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 %p instead of %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>]|
+ * <xbel> root element; each bookmark is stored inside a
+ * <bookmark> 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
+ * <metadata> 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ó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ó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 ó 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 ó 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)
+ *
+ * 
+ *
+ * ## 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) — 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", &contents, NULL, &err);
- * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
+ *
+ * g_file_get_contents ("foo.txt", &contents, NULL, &err);
+ * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
* if (err != NULL)
* {
* /* Report error to user, and free error */
* g_assert (contents == NULL);
- * fprintf (stderr, "Unable to read file: %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", &contents, NULL, NULL)) /* ignore errors */
+ * an error message, you can pass %NULL for the @error argument:
+ * |[<!-- language="C" -->
+ * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */
* /* no error occurred */ ;
* else
* /* error */ ;
* ]|
*
- * 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->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->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 < 0)
+ * if (fd < 0)
* {
* g_set_error (error,
* FOO_ERROR, /* error domain */
* FOO_ERROR_BLAH, /* error code */
- * "Failed to open file: %s", /* error message format string */
+ * "Failed to open file: %s", /* error message format string */
* 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 (&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 (&tmp_error);
- * other_function_that_can_fail (&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); /* ignore errors */
*
* tmp_error = NULL;
- * other_function_that_can_fail (&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><NAMESPACE>_<MODULE>_ERROR</literal>,
+ *
+ * - The error domain is called <NAMESPACE>_<MODULE>_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><namespace>_<module>_error_quark</literal>,
+ *
+ * - The quark function for the error domain is called
+ * <namespace>_<module>_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><Namespace><Module>Error</literal>;
+ *
+ * - The error codes are in an enumeration called
+ * <Namespace><Module>Error;
* for example,#GThreadError or #GSpawnError.
- * </para></listitem>
- * <listitem><para>
- * Members of the error code enumeration are called
- * <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>,
+ *
+ * - Members of the error code enumeration are called
+ * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
* 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><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>,
+ * it should be called <NAMESPACE>_<MODULE>_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:
- * |[
- * #define GETTEXT_PACKAGE "gtk20"
- * #include <glib/gi18n-lib.h>
+ * `<glib/gi18n.h>`. For use in a library, you must include
+ * `<glib/gi18n-lib.h>`
+ * 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.
+ *
+ * 
+ *
+ * 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; &lt; &gt; &quot; &apos;</literal>
- * </listitem>
- * <listitem>Character references</listitem>
- * <listitem>Sections marked as CDATA</listitem>
- * </itemizedlist>
+ *
+ * - Elements
+ *
+ * - Attributes
+ *
+ * - 5 standard entities: &amp; &lt; &gt; &quot; &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;
*
* /* Allocate 10000 blocks. */
- * for (i = 0; i < 10000; i++)
+ * for (i = 0; i < 10000; i++)
* {
* mem[i] = g_slice_alloc (50);
*
* /* Fill in the memory with some junk. */
- * for (j = 0; j < 50; j++)
+ * for (j = 0; j < 50; j++)
* mem[i][j] = i * j;
* }
*
* /* Now free all of the blocks. */
- * for (i = 0; i < 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;
*
* /* Allocate one block, using the g_slice_new() macro. */
@@ -7320,7 +7215,7 @@
*
* /* We can free the block, so it can be reused. */
* 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 @@
* /* ... */
*
* }
- * </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()%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()%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><glib/gprintf.h></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 `<glib/gprintf.h>` 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>%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>%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>%Ns</literal>. If your intention is
- * to format strings for a certain number of columns, then
- * <literal>%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 %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 %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 %Ns. If your intention is to format strings for a
+ * certain number of columns, then %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 = &g_array_index (events, EDayViewEvent, 3);
- * </programlisting>
- * </example>
+ * /* This gets a pointer to the 4th element
+ * * in the array of EDayViewEvent structs.
+ * */
+ * 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 < @s2,
- * or a positive value if @s1 > @s2.
+ * or a positive value if @s1 > @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 < @s2,
- * or a positive value if @s1 > @s2.
+ * or a positive value if @s1 > @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 && err->domain
- * == dom && 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 && err->domain
+ * == dom && 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.
+ * /* timeout has passed. */
* g_mutex_unlock (&data_mutex);
* return NULL;
* }
*
- * // there is data for us
+ * /* there is data for us */
* 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" -->
* /* DON'T DO THIS */
* 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 "@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 "@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" -->
* /* Notice that these are initialized to the empty list. */
* 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" -->
* /* Notice that it is initialized to the empty list. */
* 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 & Mason";
+ * |[<!-- language="C" -->
+ * const char *store = "Fortnum & Mason";
* const char *item = "Tea";
* char *output;
- *
- * output = g_markup_printf_escaped ("<purchase>"
- * "<store>%s</store>"
- * "<item>%s</item>"
- * "</purchase>",
+ *
+ * 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.
*
- * |[
- * #include <glib.h>
+ * |[<!-- language="C" -->
+ * #include <glib.h>
*
* static void
* log_handler (const gchar *log_domain,
@@ -21482,17 +21107,17 @@
* G_LOG_LEVEL_CRITICAL,
* log_handler,
* NULL);
- * /* ... */
+ * ...
* ]|
*
- * 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 (&initialization_value))
+ * if (g_once_init_enter (&initialization_value))
* {
- * gsize setup_value = 42; /** initialization code here **/
+ * gsize setup_value = 42; /* initialization code here */
*
- * g_once_init_leave (&initialization_value, setup_value);
+ * g_once_init_leave (&initialization_value, setup_value);
* }
*
- * /** use initialization_value here **/
+ * /* use initialization_value here */
* ]|
*
* 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)
* {
* /* Print all uppercase-only words. */
* GRegex *regex;
* GMatchInfo *match_info;
- *
+ *
* regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- * g_regex_match (regex, string, 0, &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;
- *
+ *
* regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &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, &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" -->
* /* Notice that these are initialized to the empty list. */
* 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" -->
* /* Notice that it is initialized to the empty list. */
* 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 ();
+ * /* do stuff with self */
* 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 *<!-- -->/
+ * /* do stuff with self */
* }
* 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 < @s2,
- * or a positive value if @s1 > @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 > @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 < @s2,
- * or a positive value if @s1 > @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 > @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" -->
* /* g_main_context_push_thread_default() should fail if the
* * context is already owned by another thread.
* */
@@ -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" -->
+ * /* Iterates a dictionary of type 'a{sv}' */
* 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 *<!-- -->/
+ * /* no need to free 'key' and 'value' here
+ * * unless breaking out of this loop
+ * */
* }
* }
- * </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" -->
+ * /* Iterates a dictionary of type 'a{sv}' */
* 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 *<!-- -->/
+ * /* must free data for ourselves */
* 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" -->
+ * /* recursively iterate a container */
* 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>#InstallationDirectory</literal> in the key
- * <literal>#HKLM\Software\ package</literal>, and if that value
+ * value `#InstallationDirectory` in the key
+ * `#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 ccfbcca..83fd6a9 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" -->
* /* the function signature for 'say_hello' */
* typedef void (* SayHelloFunc) (const char *message);
*
@@ -128,16 +124,16 @@
* if (!module)
* {
* g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
- * "%s", g_module_error ());
+ * "%s", g_module_error ());
* return FALSE;
* }
*
- * if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
+ * if (!g_module_symbol (module, "say_hello", (gpointer *)&say_hello))
* {
* g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
- * "%s: %s", filename, g_module_error ());
+ * "%s: %s", filename, g_module_error ());
* if (!g_module_close (module))
- * g_warning ("%s: %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 ("%s: %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 ("%s: %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 ab618f6..b25b8d0 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 <glib-object.h>
+ * |[<!-- language="C" -->
+ * #include <glib-object.h>
*
* static void
* int2string (const GValue *src_value,
@@ -341,34 +336,34 @@
* const gchar *message;
*
* /* The GValue starts empty */
- * g_assert (!G_VALUE_HOLDS_STRING (&a));
+ * g_assert (!G_VALUE_HOLDS_STRING (&a));
*
* /* Put a string in it */
- * 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));
+ * 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));
*
* /* Reset it to its pristine state */
- * g_value_unset (&a);
+ * g_value_unset (&a);
*
* /* It can then be reused for another type */
- * g_value_init (&a, G_TYPE_INT);
- * g_value_set_int (&a, 42);
+ * g_value_init (&a, G_TYPE_INT);
+ * g_value_set_int (&a, 42);
*
* /* Attempt to transform it into a GValue of type STRING */
- * g_value_init (&b, G_TYPE_STRING);
+ * g_value_init (&b, G_TYPE_STRING);
*
* /* An INT is transformable to a STRING */
* g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
*
- * g_value_transform (&a, &b);
- * g_printf ("%s\n", g_value_get_string (&b));
+ * g_value_transform (&a, &b);
+ * g_printf ("%s\n", g_value_get_string (&b));
*
* /* Attempt to transform it again using a custom transform function */
* g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
- * g_value_transform (&a, &b);
- * g_printf ("%s\n", g_value_get_string (&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" -->
* /* save floating state */
* 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
+ * /* extra data goes here */
* };
*
* static void
@@ -1399,7 +1375,7 @@
* {
* MyClosure *my_closure = (MyClosure *)closure;
*
- * // free extra data here
+ * /* free extra data here */
* }
*
* 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
+ * /* initialize extra data here */
*
* 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); /* GObject doesn't really need this */
* ]|
* 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, &menu->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
+ * /* Do something with intval, strval, objval */
*
* 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.
*
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
