From b63f85310b357cb9e3c8775c9bd833bef6e80420 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Sat, 8 Feb 2014 10:33:30 +0100 Subject: 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 d19178b2..d3f9c581 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -218,6 +218,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 --gapplication-service 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 @@ -297,8 +353,8 @@ /** * GApplicationCommandLineClass: * - * The GApplicationCommandLineClass 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 - * after 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 */ + * |[ + * /* 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. DBUS_COOKIE_SHA1. + * @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 - * - * - * 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. - * - * + * + * - 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 raise(SIGTERM)) 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. polkit_authority_check_authorization_sync() - * with the POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION 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 - * PropertiesChanged D-Bus signal on the - * org.freedesktop.DBus.Properties 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 expected interface. + * said to be the "expected interface". * * The checks performed are: - * - * - * 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 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(). - * - * + * - 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 struct - * sockaddr_in or struct sockaddr_in6. + * An IPv4 or IPv6 socket address, corresponding to a struct + * sockaddr_in or struct sockaddr_in6. */ /** * GInetSocketAddress:flowinfo: * - * The sin6_flowinfo field, for IPv6 addresses. + * The `sin6_flowinfo` field, for IPv6 addresses. * * Since: 2.32 */ @@ -1510,7 +1556,7 @@ /** * GInetSocketAddress:scope_id: * - * The sin6_scope_id 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 - * 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 + * 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 #GQuarks 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 'change-state' handler - * + * An example of a 'change-state' handler: + * |[ * 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); * } - * - * + * ]| * - * 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 - * "socks://", #GSimpleProxyResolver will treat - * it as referring to all three of the socks5, - * socks4a, and socks4 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: * - * - * - * 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. - * - * + * - 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 - * 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. + * 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 struct sockaddr + * 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: * - * - * - * %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). - * - * - * + * - %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, not when it calls - * a g_task_return_ 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 - * |[ + * |[ * { * "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 openssl rsa + * 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 ("BEGIN RSA PRIVATE - * KEY") or unencrypted PKCS#8 format ("BEGIN - * PRIVATE KEY"). 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 openssl rsa + * 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 - * struct sockaddr_un. + * 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. * - * |[ + * |[ * GIOExtensionPoint *ep; * * /* Register an extension point */ @@ -3522,7 +3509,7 @@ * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); * ]| * - * |[ + * |[ * /* 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 GIO_EXTRA_MODULES 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 - * PATH. 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 set() 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 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 + * 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: * - * + * |[ * 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); - * + * ]| * - * 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. + * 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 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. + * 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 primary instance; 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 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. + * 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 - * DBus bus name. + * [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: - * - * via 'Activate' (i.e. just starting the application) - * via 'Open' (i.e. opening some files) - * by handling a command-line - * via activating an action - * + * + * - 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 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(), + * 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 @@ * * * - * A GApplication with menus - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * - * * Using extra D-Bus hooks with a GApplication * * @@ -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 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 + * 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. * - * Handling commandline arguments with GApplication - * - * 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. - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * 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. + * |[ + * static int + * command_line (GApplication *application, + * GApplicationCommandLine *cmdline) + * { + * gchar **argv; + * gint argc; + * gint i; * - * Split commandline handling - * - * An 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 + * 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. + * |[ + * 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. - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * * - * Deferred commandline handling - * - * 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. - * - * - * 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. - * - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * 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. + * |[ + * 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: * - * |[ + * |[ * 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: - * |[ + * |[ * 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. * - * I/O - * 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 + * ## 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. + * %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 mime type 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 struct ucred - * - see the - * unix7 - * 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 struct cmsgcred. This corresponds + * credential type is a struct cmsgcred. This corresponds * to %G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED. * - * On OpenBSD, the native credential type is a struct sockpeercred. + * 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 ucred_t. 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 - * - * This is so that g_bus_get() and g_bus_get_sync() can safely return the - * same #GDBusConnection when called from any thread. - * - * . + * 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: - * Error Registration - * /* foo-bar-error.h: */ + * |[ + * /* 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; * } - * + * ]| * 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 org.project.Foo.Bar.Error.AnotherError. + * 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 - * org.project.Foo.Bar.Error.AnotherError 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 - * D-Bus specification. + * [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 org.freedesktop.DBus.ObjectManager + * 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 org.freedesktop.DBus.ObjectManager + * 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. :1.42) 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 - * 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. + * 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 org.freedesktop.DBus.ObjectManager + * 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 * for how this can easily be done using the - * gdbus-codegen - * tool. + * gdbus-codegen 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 <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. + * 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 @@ * g_file_eject_mountable_with_operation() to eject a mountable file. * * - * entity tag + * ## 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 - * specification + * 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. - * */ @@ -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 - * \xnn. + * 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 <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. + * 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 #GFiles, + * #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 #GFileInfos, 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 * - * - * As of GLib 2.36, the g_io_scheduler methods - * are deprecated in favor of #GThreadPool and #GTask. - * + * 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 * . * - * + * ## An example menu # {#menu-example} + * + * ![](menu-example.png) * * There are 8 "menus" visible in the screenshot: one menubar, two * submenus and 5 sections: - * - * 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) - * + * + * - 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) * * 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. * - * + * ## A menu example # {#menu-model} + * + * ![](menu-model.png) * * Notice that the separators visible in * appear nowhere in . 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: - * - * 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 - * + * - 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 * - * Stateless - * * A stateless action typically corresponds to an ordinary menu item. - * - * + * * Selecting such a menu item will activate the action (with no parameter). - * - * * - * Boolean State - * + * ## 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. - * - * + * * Selecting a toggle menu item will activate the action. The menu item should * be rendered as "checked" when the state is true. - * - * * - * String Parameter and State - * + * ## 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. - * - * + * * 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. - * - * */ @@ -5968,7 +5998,7 @@ * @short_description: System networking includes * @include: gio/gnetworking.h * - * The gnetworking.h 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 _GNU_SOURCE before - * including them. Note that this symbol must be defined before - * including any 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 _full 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 - * _full 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 $datadir/appname, 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 glib-compile-resources 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 - * preprocess 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: * - * xml-stripblanks which will use xmllint 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. + * `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. * - * to-pixdata which will use gdk-pixbuf-pixdata 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 GDK_PIXBUF_PIXDATA 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 resource description - * * * @@ -6329,14 +6360,14 @@ * menumarkup.xml * * - * ]]> + * ]| * * This will create a resource bundle with the following files: - * + * ]| * * 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 - * gettext-domain attribute of the - * schemalist or schema - * elements and the category that is specified in the l10n attribute of the - * key 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 glib-compile-schemas - * utility. The input is a schema description in an XML format that can be - * described by the following DTD: - * |[FIXME: MISSING XINCLUDE CONTENT]| - * - * glib-compile-schemas 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 + * 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 glib-compile-schemas + * 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 * . 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. * - * Default values - * * * @@ -6492,10 +6523,10 @@ * * * - * ]]> + * ]| * - * Ranges, choices and enumerated types - * * * @@ -6538,51 +6569,42 @@ * * * - * ]]> - * - * - * 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, - * glib-compile-schemas reads - * so-called 'vendor override' files. These are keyfiles in the same - * directory as the XML schema sources which can override default values. - * The schema id serves as the group name in the key file, and the values - * are expected in serialized GVariant form, as in the following example: - * + * ]| + * + * ## 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, + * glib-compile-schemas reads + * so-called 'vendor override' files. These are keyfiles in the same + * directory as the XML schema sources which can override default values. + * The schema id serves 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 - * - * - * - * 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. - * - * + * ]| + * + * 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. * - * - * 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 - * gio/gsettingsbackend.h - * + * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including + * `gio/gsettingsbackend.h`. */ @@ -6646,7 +6666,7 @@ * * Consider the following example: * - * |[ + * |[ * typedef struct * { * ... @@ -6703,7 +6723,7 @@ * ships a gschemas.compiled file as part of itself, and then simply do * the following: * - * |[ + * |[ * { * 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 * - * - * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of - * #GTask, which provides a simpler API. - * + * As of GLib 2.36, #GSimpleAsyncResult is deprecated in favor of + * #GTask, which provides a simpler API. * * #GSimpleAsyncResult implements #GAsyncResult. * - * GSimpleAsyncResult handles #GAsyncReadyCallbacks, 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 #GThreads. + * 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 * 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. * - * #GSockets 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 struct sockaddr - * 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. * - * |[ + * |[ * 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 #GSrvTargets + * 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 subprocess.py + * 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 - * communicate() method of - * subprocess.py. 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 * - * - * 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. - * - * GTask as a GAsyncResult - * + * 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: + * |[ * typedef struct { * CakeFrostingType frosting; * char *message; @@ -7463,25 +7477,23 @@ * * return g_task_propagate_pointer (G_TASK (result), error); * } - * - * - * - * - * 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 I/O priority 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). - * - * Chained asynchronous operations - * + * ]| + * + * ## 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 I/O priority 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: + * |[ * typedef struct { * Cake *cake; * CakeFrostingType frosting; @@ -7606,19 +7618,17 @@ * * return g_task_propagate_pointer (G_TASK (result), error); * } - * - * - * - * - * 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. - * - * g_task_run_in_thread() - * + * ]| + * + * ## 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: + * |[ * typedef struct { * guint radius; * CakeFlavor flavor; @@ -7685,26 +7695,24 @@ * * return g_task_propagate_pointer (G_TASK (result), error); * } - * - * - * - * - * 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. - * - * g_task_set_return_on_cancel() - * + * ]| + * + * ## 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: + * |[ * static void * bake_cake_thread (GTask *task, * gpointer source_object, @@ -7793,81 +7801,63 @@ * g_object_unref (task); * return cake; * } - * - * - * - * - * Porting from <literal>GSimpleAsyncResult</literal> - * - * #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 - * priority, #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()). - * - * - * + * ]| + * + * ## 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 + * priority, #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. * - * - * 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. - * + * ## 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 - * - * 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: - * + * ]| + * 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"\" - * - * - * + * ]| * 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. - * - * Test Fixture for D-Bus services - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * - * - * - * 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: - * + * 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 - * - * - * + * ]| */ @@ -8210,9 +8187,9 @@ * It contains functions to do some of the UNIX socket specific * functionality like passing file descriptors. * - * 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. + * 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 <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. + * 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 <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. + * 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 <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. + * 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 <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. + * 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 <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. + * 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 <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. + * 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. * - * + * ## 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. /dev/sda2), - * 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. - * + * 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 <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. + * 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 <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. + * 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. * - * - * Using g_action_map_add_action_entries() - * + * |[ * static void * activate_quit (GSimpleAction *simple, * GVariant *parameter, @@ -10466,8 +10441,7 @@ * * return G_ACTION_GROUP (group); * } - * - * + * ]| * * 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 - * freedesktop.org Desktop - * Entry Specification 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 - * #GAppInfos 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 #GAppInfos 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 - * NoDisplay=true set or are excluded from - * display by means of OnlyShowIn or - * NotShowIn. 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 Hidden key set. + * the `Hidden` key set. * - * Returns: (element-type GAppInfo) (transfer full): a newly allocated #GList of references to #GAppInfos. + * 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 GIO_LAUNCHED_DESKTOP_FILE + * On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` * environment variable with the path of the launched desktop file and - * 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. + * `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 DISPLAY 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 KEY=VALUE. + * 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 - * DESKTOP_STARTUP_ID for the launched operation, - * if supported. + * `DESKTOP_STARTUP_ID` for the launched operation, if supported. * - * Startup notification IDs are defined in the - * FreeDesktop.Org Startup Notifications standard. + * 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. @@ -11156,6 +11126,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 --display= + * or --gdk-debug= 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 @@ -11263,6 +11322,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: - * - * 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. - * + * + * - 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 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 --version, 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 - * _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. + * 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: - * - * - * @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). - * - * + * + * - @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 shared-mime-info + * 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 shared-mime-info + * (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 - * - * g_list_free_full (list, g_free); - * + * 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 not 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 not 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 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. + * 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 /run/bus-for-:0, - * this function would return /run/bus-for-%3A0, + * 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 - * unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0. + * "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. DBUS_COOKIE_SHA1. + * @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.: - * |[ + * |[ * 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.: - * |[ + * |[ * 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 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 thread-default main * loop 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 org.freedesktop.DBus.Error.InvalidArgs + * 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 - * org.freedesktop.DBus.Error.UnknownMethod resp. - * org.freedesktop.DBus.Error.InvalidArgs 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 can 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 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 dynamic 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 fallback handler - * 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 thread-default main * loop 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 - * org.gtk.GDBus.UnmappedGError.Quark._ESCAPED_QUARK_NAME.Code_ERROR_CODE + * `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 - * #GErrors 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 - * #GErrors 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 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). + * %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. * - * 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. + * 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 - * org.freedesktop.DBus.Introspectable.Introspect + * `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 - * org.freedesktop.DBus.Properties::PropertiesChanged + * `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: - * - * 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) - * + * ]| * or - * - * 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 - * + * ]| * * 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 - * org.gtk.GDBus.UnmappedGError.Quark... 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, - * always 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 org.freedesktop.DBus.Introspectable.Introspect 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 - * node element. + * <node> element. * * Note that this routine is using a * GMarkup-based @@ -17476,10 +17552,9 @@ * @object: An object. * * Like g_dbus_object_manager_server_export() but appends a string of - * 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. + * 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.: - * |[ + * |[ * 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.: - * |[ + * |[ * 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. - * |[ + * |[ * 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 - * 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. + * 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 - * 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). + * `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 - * OnlyShowIn and NotShowIn 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 - * OnlyShowIn and NotShowIn 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 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 + * 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 - * /usr/share/applications/kde/foo.desktop). + * `/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 - * OnlyShowIn and NotShowIn + * `OnlyShowIn` and `NotShowIn` * desktop entry fields. * - * The Desktop - * Menu specification recognizes the following: - * - * GNOME - * KDE - * ROX - * XFCE - * LXDE - * Unity - * Old - * + * 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. #GFileAttributeMatchers 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: - * |[ + * |[ * 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: - * + * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * + * ]| * 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 'du' 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. * - * 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. + * 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 * - * - * - * 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). - * - * + * - 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 sin6_flowinfo 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 sin6_scope_id 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 - * #GIOExtensions. 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). * - * |[ + * |[ * /* 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: - * - * *
* @@ -25587,7 +25654,7 @@ * *
* - * ]]> + * ]| * * 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). - * - * * * @@ -25612,7 +25678,7 @@ * * * - * ]]> + * ]| * * 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 shared-mime-info + * 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 shared-mime-info + * 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 gphoto2://[usb:001,002]/store1/ - * and gphoto2://[usb:001,002]/store2/. When the + * activation URIs `gphoto2://[usb:001,002]/store1/` + * and `gphoto2://[usb:001,002]/store2/`. When the * underlying mount (with root - * gphoto2://[usb:001,002]/) 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(). * - * 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. + * 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 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. + * 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 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. + * 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 <protocol>://[user[:password]@]host:port - * or direct://, 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 none 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). * - * direct:// 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 do not - * 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 GSETTINGS_BACKEND - * 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 not - * 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 - * base-path/@name, where - * base-path 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 child 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 (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. + * 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 '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 `'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 'enum' 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 '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']. + * 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 'range' 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 XDG_DATA_DIRS and - * GSETTINGS_SCHEMA_DIR. 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 - * gschemas.compiled as produced by - * glib-compile-schemas. + * The directory should contain a file called `gschemas.compiled` as + * produced by the + * glib-compile-schemas tool. * - * 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 @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: child or extends) - * 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 "socks://", + * If @default_proxy starts with "socks://", * #GSimpleProxyResolver will treat it as referring to all three of - * the socks5, socks4a, and - * socks4 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 - * "socks://", #GSimpleProxyResolver will treat it - * as referring to all three of the socks5, - * socks4a, and socks4 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 struct sockaddr. + * 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 struct sockaddr 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 struct sockaddr + * @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 - * struct sockaddr @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 - * struct sockaddr. + * 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 struct - * sockaddr, 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 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.) + * 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 #GProxyAddresses 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, SOL_SOCKET) - * @optname: the "name" of the option (eg, SO_BROADCAST) + * @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 - * getsockopt (). (If you need to fetch a - * non-integer-valued option, you will need to call - * getsockopt () directly.) + * getsockopt(). (If you need to fetch a non-integer-valued option, + * you will need to call getsockopt() directly.) * - * The <gio/gnetworking.h> + * The `<gio/gnetworking.h>` * 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 (errno or - * WSAGetLastError ()) will still be set to the - * result of the getsockopt () 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 - * #GOutputVectors 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, SOL_SOCKET) - * @optname: the "name" of the option (eg, SO_BROADCAST) + * @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 - * setsockopt (). (If you need to set a - * non-integer-valued option, you will need to call - * setsockopt () directly.) + * setsockopt(). (If you need to set a non-integer-valued option, + * you will need to call setsockopt() directly.) * - * The <gio/gnetworking.h> + * The `<gio/gnetworking.h>` * 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 (errno or - * WSAGetLastError ()) will still be set to the - * result of the setsockopt () 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 #GSrvTargets 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 priority, and sets @source's callback - * to @callback, with @task as the callback's - * user_data. + * 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 task_data. + * Gets @task's `task_data`. * - * Returns: (transfer none): @task's task_data. + * 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 - * callback, 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 that doing so invalidates the hash computed by prior calls * to g_icon_hash(). - * */ @@ -35343,7 +35392,7 @@ * that can be created by shortening @iconname at '-' characters. * * In the following example, @icon1 and @icon2 are equivalent: - * |[ + * |[ * 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 that doing so invalidates the hash computed by prior calls * to g_icon_hash(). - * * * 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 #GTlsCertificates 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 renegotiation_info 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 - * 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. + * 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. /media/disk - * or /usr + * @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 struct sockaddr_un, 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 * - * + * |[ * 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 */ - * - * + * volume_activation_root = g_volume_get_activation_root (volume); /* assume not NULL */ + * ]| * then the expression - * - * + * |[ * (g_file_has_prefix (volume_activation_root, mount_root) || * g_file_equal (volume_activation_root, mount_root)) - * - * + * ]| * will always be %TRUE. * * Activation roots are typically used in #GVolumeMonitor @@ -37926,26 +37968,26 @@ * g_mount_is_shadowed() for more details. * * Returns: (transfer full): the activation root of @volume or %NULL. Use - * g_object_unref() to free. + * g_object_unref() to free. * Since: 2.18 */ /** * g_volume_get_drive: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the drive for the @volume. * - * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. - * The returned object should be unreffed with g_object_unref() - * when no longer needed. + * Returns: (transfer full): a #GDrive or %NULL if @volume is not + * associated with a drive. The returned object should be unreffed + * with g_object_unref() when no longer needed. */ /** * g_volume_get_icon: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the icon for @volume. * @@ -37965,14 +38007,14 @@ * for more information about volume identifiers. * * Returns: a newly allocated string containing the - * requested identfier, or %NULL if the #GVolume - * doesn't have this kind of identifier + * requested identfier, or %NULL if the #GVolume + * doesn't have this kind of identifier */ /** * g_volume_get_mount: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the mount for the @volume. * @@ -37984,29 +38026,29 @@ /** * g_volume_get_name: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the name of @volume. * * Returns: the name for the given @volume. The returned string should - * be freed with g_free() when no longer needed. + * be freed with g_free() when no longer needed. */ /** * g_volume_get_sort_key: - * @volume: A #GVolume. + * @volume: a #GVolume * * Gets the sort key for @volume, if any. * - * Returns: Sorting key for @volume or %NULL if no such key is available. + * Returns: Sorting key for @volume or %NULL if no such key is available * Since: 2.32 */ /** * g_volume_get_symbolic_icon: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the symbolic icon for @volume. * @@ -38019,7 +38061,7 @@ /** * g_volume_get_uuid: - * @volume: a #GVolume. + * @volume: a #GVolume * * Gets the UUID for the @volume. The reference is typically based on * the file system UUID for the volume in question and should be @@ -38150,11 +38192,11 @@ /** * g_volume_mount: (virtual mount_fn) - * @volume: a #GVolume. + * @volume: a #GVolume * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL * @user_data: user data that gets passed to @callback * * Mounts a volume. This is an asynchronous operation, and is @@ -38177,7 +38219,7 @@ * function; there's no need to listen for the 'mount-added' signal on * #GVolumeMonitor. * - * Returns: %TRUE, %FALSE if operation failed. + * Returns: %TRUE, %FALSE if operation failed */ @@ -38187,7 +38229,7 @@ * * Returns whether the volume should be automatically mounted. * - * Returns: %TRUE if the volume should be automatically mounted. + * Returns: %TRUE if the volume should be automatically mounted */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index bb403b15..a68339e5 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -44,15 +44,14 @@ * used as a context. This is mainly useful for short strings which * may need different translations, depending on the context in which * they are used. - * |[ + * |[ * label1 = C_("Navigation", "Back"); * label2 = C_("Body part", "Back"); * ]| * - * If you are using the C_() macro, you need to make sure - * that you pass to xgettext when - * extracting messages. Note that this only works with GNU - * gettext >= 0.15. + * 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 Array. + * 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 - * g_async_queue_* 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 GByteArray struct allows access to the - * public fields of a GByteArray. + * 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. * - * - * - * Using GCond to block a thread until a condition is satisfied - * - * + * Here is an example for using GCond to block a thread until a condition + * is satisfied: + * |[ * gpointer current_data = NULL; * GMutex data_mutex; * GCond data_cond; @@ -206,21 +202,19 @@ * * return data; * } - * - * - * + * ]| * 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 current_data by the - * while loop in pop_data and waiting. - * Specifically, another thread could set pop_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. + * 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 g_cond_ - * 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 - * GDate 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 GINT_TO_POINTER (n) (or similar macros). + * of the form `GINT_TO_POINTER (n)` (or similar macros). * * 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 Algorithmic Complexity Attacks. + * 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 GHook 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 GHookList 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 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. + * 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 O_APPEND - * (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 - * O_NONBLOCK/O_NDELAY - * (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. - * - * - * Checking the version of the GLib library - * - * if (!GLIB_CHECK_VERSION (1, 2, 0)) - * g_error ("GLib version 1.2.0 or above is needed"); - * - * - * - * 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. * - * - * A function which will not work in a threaded environment - * + * Take for example the following function: + * |[ * 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; * } - * - * - * + * ]| * 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: - * - * - * Using GMutex to protected a shared variable - * + * |[ * 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; * } - * - * - * + * ]| * 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 g_mutex_ - * 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 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. + * 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 GPatternSpec 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 g_private_ 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()). * - * - * An array with access functions - * + * Here is an example for an array with access functions: + * |[ * 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); * } - * - * - * 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 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. - * - * + * ]| + * 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 - * g_rw_lock_ 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 g_rand_* 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 - * g_rec_mutex_ 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 - * token = ch 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 - * token = v_symbol 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 - * DIST_EXTRA or dist_schema_DATA + * `DIST_EXTRA` or `dist_schema_DATA` * sense, in which case they will always be in the srcdir) or built (in - * the BUILT_SOURCES 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 /dev/null. + * 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 - * /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(). + * `/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 - * /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(). + * `/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 /dev/null 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 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. + * 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 GTime is defined to always be a 32bit integer, - * unlike time_t which may be 64bit 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: - * |[ + * 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: + * |[ * 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 struct timeval 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 sizeof (gpointer) + * 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 GTrashStack*. + * is cast to a GTrashStack*. */ @@ -2300,10 +2268,9 @@ /** * GTree: * - * The GTree struct is an opaque data - * structure representing a Balanced Binary Tree. It - * should be accessed only by using the following functions. + * The GTree struct is an opaque data structure representing a Balanced Binary Tree. + * It should be accessed only by using the following functions. */ @@ -2644,6 +2611,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. + * + * + * Using stack-allocated #GVariantDict + * + * 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); + * } + * + * + * + * + * Using heap-allocated #GVariantDict + * + * 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; + * } + * + * + * + * Since: 2.40 + */ + + /** * GVariantIter: (skip) * @@ -2685,10 +2751,10 @@ * on systems with 64bit IEEE-compatible doubles. * * The typical usage would be something like: - * |[ + * |[ * 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 extern "C" + * compiler in use is a C++ compiler, adds extern "C" * around the header. */ @@ -2736,19 +2802,17 @@ /** * G_CONST_RETURN: * - * If G_DISABLE_CONST_RETURNS is defined, this macro expands - * to nothing. By default, the macro expands to const. - * The macro should 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. + * 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 - * const 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 extern "C" + * 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. * - * |[ + * |[ * 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"; - * |[ + * |[ * 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. * - * - * 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. - * */ @@ -2981,11 +3044,9 @@ * for scanning and printing values of type #gint64 or #guint64. * It is a string literal. * - * - * 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. - * * * 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 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. + * 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 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. + * 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 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. + * 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 -Wdeprecated-declarations - * 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 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. + * 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. * - * * A function that has pointer arguments and examines the data pointed to - * 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. - * + * 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 deprecated attribute if the - * compiler is gcc. It can be used to mark typedefs, - * variables and functions as deprecated. When called with the - * 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 gcc 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 - * gcc 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 __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 - * 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 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). + * 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. * - * |[ + * |[ * 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 - * __FUNCTION__ on gcc 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 __attribute__((visibility("hidden"))). - * When using the Sun Studio compiler, it expands to __hidden. + * 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. * - * |[ + * |[ * 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 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). + * 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 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. + * 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 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. + * 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 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 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 sentinel function attribute - * if the compiler is gcc, 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 - * __PRETTY_FUNCTION__ on gcc - * 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 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. + * 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. * - * |[ + * |[ * gint g_snprintf (gchar *string, * gulong n, * gchar const *format, @@ -3334,11 +3382,11 @@ /** * G_GNUC_PURE: * - * 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. + * 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 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. + * 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 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. + * 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. * - * |[ + * |[ * 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 warn_unused_result function - * attribute if the compiler is gcc, 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. * - * - * 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. - * */ @@ -3520,7 +3565,7 @@ * G_HOOK: * @hook: a pointer * - * Casts a pointer to a GHook*. + * 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. - * 1 << G_HOOK_FLAG_USER_SHIFT 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 G_IMPLEMENTS_INLINES + * 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. @@ -3623,17 +3668,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 - * Desktop - * Entry Specification. 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 Application 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 Application 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 Startup - * Notification Protocol Specification. + * 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 - * Application 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 Application 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 Link 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. * - * |[ + * |[ * if (G_LIKELY (random () != 1)) * g_print ("not one"); * ]| @@ -3959,19 +3992,17 @@ * G_LOCK_DEFINE: * @name: the name of the lock * - * The G_LOCK_* 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 - * give_me_next_number() example using the - * G_LOCK_* macros: + * give_me_next_number() example using the #G_LOCK macros: * - * - * Using the <literal>G_LOCK_*</literal> convenience macros - * + * Here is an example for using the #G_LOCK convenience macros: + * |[ * G_LOCK_DEFINE (current_number); * * int @@ -3986,8 +4017,7 @@ * * return ret_val; * } - * - * + * ]| */ @@ -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. * - * |[ + * |[ * GOnce my_once = G_ONCE_INIT; * ]| * @@ -4326,10 +4356,10 @@ * @identifier2: an identifier * * Yields a new preprocessor pasted identifier - * identifier1identifier2 from its expanded + * @identifier1identifier2 from its expanded * arguments @identifier1 and @identifier2. For example, * the following code: - * |[ + * |[ * #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: - * |[ + * |[ * 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. * - * |[ + * |[ * 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 typedef is valid. + * any place where a typedef is valid. * - * - * 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. - * + * 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 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. + * 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. * - * |[ + * |[ * #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: * - * |[ + * |[ * #define AGE 27 * const gchar *greeting = G_STRINGIFY (AGE) " today!"; * ]| * * is transformed by the preprocessor into (code equivalent to): * - * |[ + * |[ * const gchar *greeting = "27 today!"; * ]| */ @@ -4587,8 +4612,8 @@ /** * G_STRUCT_OFFSET: - * @struct_type: a structure type, e.g. GtkWidget - * @member: a field in the structure, e.g. window + * @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. * - * |[ + * |[ * if (G_UNLIKELY (random () == 1)) * g_print ("a random one"); * ]| @@ -4679,15 +4704,14 @@ /** * G_VA_COPY: - * @ap1: the va_list variable to place a copy of @ap2 in - * @ap2: a va_list + * @ap1: the va_list variable to place a copy of @ap2 in + * @ap2: a va_list * - * Portable way to copy va_list variables. + * Portable way to copy va_list variables. * - * 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. + * 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 windows.h. 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. * - * |[ + * |[ * { * 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); * ... * } * ]| * - * If you are using the NC_() macro, you need to make sure - * that you pass 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. - * + * 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. - * |[ + * |[ * { * 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. * - * If you are using the Q_() macro, you need to make sure - * that you pass to xgettext when extracting - * messages. If you are using GNU gettext >= 0.15, you can also use - * to let xgettext split the context - * string off into a msgctxt line in the po file. + * 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(). * - * - * Using a #GArray to store #gint values - * + * Here is an example that stores integers in a #GArray: + * |[ * 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); - * - * + * ]| */ @@ -4926,17 +4948,16 @@ * * To free a #GByteArray, use g_byte_array_free(). * - * - * Using a #GByteArray - * + * An example for using a #GByteArray: + * |[ * 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); - * - * + * ]| * * 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. * - * 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. + * 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(). * - * - * Using a #GPtrArray - * - * GPtrArray *gparray; + * An example using a #GPtrArray: + * |[ + * 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); - * - * + * 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 RFC - * 1421 or RFC - * 2045. 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 - * Desktop Bookmark - * Specification. + * [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 XML Bookmark Exchange Language + * 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 - * 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. - * |[FIXME: MISSING XINCLUDE CONTENT]| + * <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. - * - * - * 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, - * - * + * 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, + * * 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 * - * * However, if the application use UTF-8, the actual file name on * disk would look like this: - * * * 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 * - * - * 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 - * 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(2) or fopen(3). - * - * + * 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 G_FILENAME_ENCODING - * environment variable. For example, if your installation uses - * ISO-8859-1 for file names, you can put this in your - * ~/.profile: - * + * linkend="G_FILENAME_ENCODING">`G_FILENAME_ENCODING` + * environment variable. For example, if your installation uses + * ISO-8859-1 for file names, you can put this in your `~/.profile` * * export G_FILENAME_ENCODING=ISO-8859-1 * - * * 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 - * G_FILENAME_ENCODING 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. * illustrates how * these functions are used to convert between UTF-8 and the * encoding for file names in the file system. - * - *
- * Conversion between File Name Encodings - * - *
- * - * Checklist for Application Writers - * + * + * ## Conversion between file name encodings # {#file-name-encodings-diagram) + * + * ![](file-name-encodings.png) + * + * ## Checklist for Application Writers + * * This section is a practical summary of the detailed - * description above. You can use this as a checklist of + * * things to do to make sure your applications process file * name encodings correctly. - * - * - * - * 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. - * - * - * 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. - * - * - * 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 G_FILENAME_ENCODING is set to - * ISO-8859-1, for example. - * - * - * - * + * + * 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 day. + * 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 - * 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 + * 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. * - * It is very important to use the API to access the #GDate - * struct. 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 data type (the #GError - * object) 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.) + * 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: - * |[ + * |[ * gboolean g_file_get_contents (const gchar *filename, * gchar **contents, * gsize *length, * GError **error); * ]| - * 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: - * |[ + * 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: + * |[ * 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 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. + * 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 error - * argument: - * |[ - * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */ + * an error message, you can pass %NULL for the @error argument: + * |[ + * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */ * /* no error occurred */ ; * else * /* error */ ; * ]| * - * 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 + * 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 - * error->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, - * error->message 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: - * |[ + * |[ * 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: - * |[ + * |[ * 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. - * |[ + * |[ * 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: - * |[ + * |[ * 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 @@ * } * } * ]| - * 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. + * @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(): - * |[ + * |[ * 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 - * 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. + * 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: - * - * - * The error domain is called - * <NAMESPACE>_<MODULE>_ERROR, + * + * - 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 () + * |[ + * #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"); + * } * ]| - * - * - * The quark function for the error domain is called - * <namespace>_<module>_error_quark, + * + * - The quark function for the error domain is called + * <namespace>_<module>_error_quark, * for example g_spawn_error_quark() or g_thread_error_quark(). - * - * - * The error codes are in an enumeration called - * <Namespace><Module>Error; + * + * - The error codes are in an enumeration called + * <Namespace><Module>Error; * for example,#GThreadError or #GSpawnError. - * - * - * Members of the error code enumeration are called - * <NAMESPACE>_<MODULE>_ERROR_<CODE>, + * + * - Members of the error code enumeration are called + * <NAMESPACE>_<MODULE>_ERROR_<CODE>, * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. - * - * - * 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 <NAMESPACE>_<MODULE>_ERROR_FAILED, + * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED, * for example %G_SPAWN_ERROR_FAILED. - * - * * * Summary of rules for use of #GError: - * - * - * Do not report programming errors via #GError. - * - * - * 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 "...". - * - * - * 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. - * - * - * 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. - * - * - * 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 + * + * - 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. - * - * - * 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. - * - * - * "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. - * - * - * 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 must be set to a non-%NULL - * value. - * - * - * 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. - * - * - * 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. - * g_return_if_fail (error == NULL || *error == NULL);). - * - * + * `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 - * G_FILENAME_ENCODING 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 Internationalized Domain - * Names for Applications (IDNA) 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: * - * The g_regex_*() 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 - * man:pcreapi(3) 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 PCRE 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 - * RFC 3986. 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. * - * - * 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 32bit 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 32bit 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 32bit 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. - * - * - * + * ## 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 DBus - * specification, 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 "m" 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 "*", "?" and - * "r" 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: - * - * - * 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: - * + * ## 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: * * * @@ -6376,7 +6283,7 @@ * * * - * b + * b * * * @@ -6388,7 +6295,7 @@ * * * - * y + * y * * * @@ -6400,7 +6307,7 @@ * * * - * n + * n * * * @@ -6413,7 +6320,7 @@ * * * - * q + * q * * * @@ -6426,7 +6333,7 @@ * * * - * i + * i * * * @@ -6439,7 +6346,7 @@ * * * - * u + * u * * * @@ -6452,7 +6359,7 @@ * * * - * x + * x * * * @@ -6465,7 +6372,7 @@ * * * - * t + * t * * * @@ -6478,7 +6385,7 @@ * * * - * h + * h * * * @@ -6492,7 +6399,7 @@ * * * - * d + * d * * * @@ -6505,7 +6412,7 @@ * * * - * s + * s * * * @@ -6517,7 +6424,7 @@ * * * - * o + * o * * * @@ -6530,7 +6437,7 @@ * * * - * g + * g * * * @@ -6543,7 +6450,7 @@ * * * - * ? + * ? * * * @@ -6556,7 +6463,7 @@ * * * - * v + * v * * * @@ -6569,51 +6476,50 @@ * * * - * a + * a * * * * * used as a prefix on another type string to mean an array of - * that type; the type string "ai", 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. * * * * * * - * m + * m * * * * * used as a prefix on another type string to mean a "maybe", or - * "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. + * "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. * * * * * * - * () + * () * * * * * used to enclose zero or more other concatenated type strings - * to create a tuple type; the type string - * "(is)", 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. * * * * * * - * r + * r * * * @@ -6627,7 +6533,7 @@ * * * - * {} + * {} * * * @@ -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 "a{sd}", 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. * * * 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. * @@ -6650,14 +6555,14 @@ * * * - * * + * * * * * * * 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". * * @@ -6665,24 +6570,20 @@ * * * - * - * 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. - * - * + * + * 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. HMAC + * 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 - * 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: - * |[ - * #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: + * |[ + * #define GETTEXT_PACKAGE "gtk20" + * #include * ]| * 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: - * g_io_add_watch(), g_io_add_watch_full(), - * g_source_remove() Convenience - * functions for creating #GIOChannel instances and adding - * them to the main - * event loop. - * + * @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 key files for - * lack of a better name. Several freedesktop.org specifications use - * key files now, e.g the - * Desktop - * Entry Specification and the - * Icon - * Theme Specification. + * 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 - * Desktop - * Entry Specification, 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 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. + * 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: - * - * .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. - * + * + * - .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 - * Desktop - * Entry Specification, 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: - * |[ + * |[ * 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: - * |[ + * |[ * 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(). * - * Creating new source types - * 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 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 + * 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. - * 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(). - * - * Customizing the main loop iteration - * 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(). - * The operation of these functions can best be seen in terms - * of a state diagram, as shown in . - *
States of a Main Context - * - *
- * - * - * On Unix, the GLib mainloop is incompatible with fork(). Any program + * g_main_context_check() and g_main_context_dispatch(). + * + * ## State of a Main Context # {#mainloop-states} + * + * The operation of these functions can best be seen in terms + * of a state diagram, as shown in this image. + * + * ![](mainloop-states.gif) + * + * On UNIX, the GLib mainloop is incompatible with fork(). Any program * using the mainloop must either exec() or exit() from the child * without returning to the mainloop. */ @@ -7175,10 +7074,8 @@ /** * SECTION:markup - * @Title: Simple XML Subset Parser - * @Short_description: parses a subset of XML - * @See_also: XML - * Specification + * @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-formedBeing wellformed is a weaker condition than being - * valid. See the XML - * specification for definitions of these terms. - * 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: - * - * 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. - * + * + * - 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: - * - * Elements - * Attributes - * 5 standard entities: - * &amp; &lt; &gt; &quot; &apos; - * - * Character references - * Sections marked as CDATA - * + * + * - 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. * - * * 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. - * * - * - * 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(). - * + * 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 - * - * [Bonwick94] 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 - * [Bonwick01] Bonwick and Jonathan Adams, Magazines and vmem: Extending the - * slab allocator to many cpu's and arbitrary resources. USENIX 2001 - * . + * [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 g_slice 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. * - * - * Using the slice allocator - * + * Here is an example for using the slice allocator: + * |[ * 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]); - * } - * + * for (i = 0; i < 10000; i++) + * g_slice_free1 (50, mem[i]); + * ]| * - * - * Using the slice allocator with data structures - * + * And here is an example for using the using the slice allocator + * with data structures: + * |[ * 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); - * + * ]| */ @@ -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 - * IEEE 754-2008 + * [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: * - * testtreemodel -r 1 --max-size 20 --rand --display=:1.0 -vb -- file1 file2 + * `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 - * - * 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 + * 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. - * - * Non-option arguments are returned to the application as rest arguments. - * - * 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. - * * * 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 , , - * and - * 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. - * - * + * 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 - * + * ]| * - * GOption groups options in #GOptionGroups, 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. - * - * + * |[ * static gint repeats = 2; * static gint max_size = 8; * static gboolean verbose = FALSE; @@ -7475,7 +7366,7 @@ * /* ... */ * * } - * + * ]| * * 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: * - * |[ + * |[ * int * main (int argc, char **argv) * { @@ -7536,16 +7427,14 @@ * @short_description: matches strings against patterns containing '*' * (wildcard) and '?' (joker) * - * The g_pattern_match* 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 - * can be matched by the wildcards, there are no - * '[...]' character ranges and '*' and '?' can - * not 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). * - * Do not use this API for cryptographic purposes such as key - * generation, nonces, salts or one-time pads. + * 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 - * /dev/random 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 - * 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 + * 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 - * GRand and GRandom. - * 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. + * 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 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. + * 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, * or simply pointers to any type of data. * - * 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 + * 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 point 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 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 + * 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. * - * 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. - * + * ## 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. * - * - * - * 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. - * - * + * - 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 - * |[ + * |[ * 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 - * - * - * 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. - * - * + * + * - 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 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. + * 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: - * |[ + * |[ * 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: - * |[ + * |[ * gpointer p; * int i; * p = (void*) 42; * i = (int) p; * ]| - * Again, that example was not 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: - * |[ + * |[ * 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. * - * 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. - * + * 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 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. + * 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 - * www.unicode.org. + * [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 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. + * 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. * - * 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. + * 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. * - * If array elements contain dynamically-allocated memory, - * they should be freed separately. + * 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. * - * - * Getting a pointer to an element in a #GArray - * + * This example gets a pointer to an element in a #GArray: + * |[ * EDayViewEvent *event; - * /* This gets a pointer to the 4th element - * in the array of EDayViewEvent structs. */ - * event = &g_array_index (events, EDayViewEvent, 3); - * - * + * /* 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. * - * 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. + * 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. * - * 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 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. + * 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 errno 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 ERANGE is stored in errno. + * is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and - * EINVAL is stored in errno. 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 ERANGE is stored in errno. + * is returned, and `ERANGE` is stored in `errno`. * If the base is outside the valid range, zero is returned, and - * EINVAL is stored in errno. + * `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 EOF 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 EOF 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 - * G_DISABLE_ASSERT 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 g_assert_cmpfloat (n1, op, n2) is - * the same as g_assert_true (n1 op n2). 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 g_assert_cmpint (n1, op, n2) is - * the same as g_assert_true (n1 op n2). 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 g_assert_cmpstr (s1, op, s2) is - * the same as g_assert_true (g_strcmp0 (s1, s2) op 0). + * 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. * - * |[ + * |[ * g_assert_cmpstr (mystring, ==, "fubar"); * ]| * @@ -9199,8 +9054,8 @@ * * Debugging macro to compare two unsigned integers. * - * The effect of g_assert_cmpuint (n1, op, n2) is - * the same as g_assert_true (n1 op n2). 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 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 + * 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 - * g_assert (err != NULL) + * `g_assert (err != NULL)` * * Since: 2.20 */ @@ -9253,8 +9108,8 @@ * * Debugging macro to check that a #GError is not set. * - * The effect of g_assert_no_error (err) is - * the same as g_assert_true (err == NULL). 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 - * G_DISABLE_ASSERT 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 - * g_async_queue_*_unlocked() 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: - * |[ + * |[ * 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 - * { tmp = *atomic; *@atomic += @val; return tmp; } + * `{ 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 - * { tmp = *atomic; *@atomic &= @val; return tmp; } + * `{ 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 - * { if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; } + * `{ 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 - * { *@atomic -= 1; return (*@atomic == 0); } + * `{ *@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 - * { *@atomic += 1; } + * 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 - * { tmp = *atomic; *@atomic |= @val; return tmp; } + * `{ 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 - * { tmp = *atomic; *@atomic ^= @val; return tmp; } + * `{ 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 - * { tmp = *atomic; *@atomic += @val; return tmp; } + * `{ 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 - * { tmp = *atomic; *@atomic &= @val; return tmp; } + * `{ 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 - * { if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; } + * `{ 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 - * { tmp = *atomic; *@atomic |= @val; return tmp; } + * `{ 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 - * { tmp = *atomic; *@atomic ^= @val; return tmp; } + * `{ 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 LF - * characters, not CR LF 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 g_build_path - * (G_DIR_SEPARATOR_S, first_element, ....). + * 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 - * (\ 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. + * (`\` 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 ABA, ABABA - * 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 - * g_spawn... 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 waitpid 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): * - * |[ + * |[ * 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 - * - * Note that some encodings may allow nul bytes to - * occur inside strings. In that case, using -1 for - * the @len parameter is 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. * @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. + * 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. + * 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. + * 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. + * 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 - * + * 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 - * 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.) - * - * . + * 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 G_DEBUG environment variable (see - * Running GLib Applications). + * 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. - * 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. + * + * 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: time_t 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: - * |[ + * |[ * g_date_set_time_t (date, time (NULL)); * ]| * @@ -13293,266 +13154,81 @@ * * The following format specifiers are supported: * - * - * - * \%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 representation 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 - * - * + * - \%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: - * - * - * 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. - * - * - * + * + * - 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 struct tm from - * @tm: struct tm to fill + * @date: a #GDate to set the struct tm from + * @tm: struct tm to fill * - * Fills in the date-related bits of a struct tm - * 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 LC_MESSAGES. 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: - * - * @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_") - * + * + * - @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 errno 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 GINT_TO_POINTER (n). + * 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 GINT_TO_POINTER (n). + * 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 EEXIST this function returns - * #G_FILE_ERROR_EXIST. Unlike errno 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: - * - * - * 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 + * + * - 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. - * - * - * 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. - * - * * * 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, (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. + * %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! - * |[ + * |[ * /* 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 PATHEXT 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. + * 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 PATHEXT 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 PATH 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 FILE struct, the - * FILE 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 - * FILE 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 FILE 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 FILE 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 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 current - * locale. 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 + * 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 current + * locale. 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 - * G_FILENAME_ENCODING 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 - * 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. - * + * `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 LANGUAGE, - * LC_ALL, LC_MESSAGES and LANG - * 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 current locale, + * 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 CLOCK_MONOTONIC 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 CLOCK_MONOTONIC 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 not - * 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 argv[0].) + * 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 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 + * 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 - * XDG Base Directory Specification. - * 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 - * XDG Base Directory Specification + * 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 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 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 TEMP 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 - * XDG Base Directory Specification. + * 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 - * XDG Base Directory Specification. - * 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 - * XDG Base Directory Specification. - * 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 - * XDG Base Directory Specification. This is the directory - * specified in the XDG_RUNTIME_DIR 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 $HOME/Desktop 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. - * |[ + * |[ * 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 sizeof (GHook) + * 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 - * GINT_TO_POINTER (n), 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 - * GINT_TO_POINTER (n), 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 errno error number, e.g. EINVAL + * @en: an `errno` error number, e.g. `EINVAL` * - * Converts an errno 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: - * - * - * 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 + * + * - 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 not guarantee that the encoding can - * be changed. - * - * + * 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. * - * 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. + * 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. * - * |[ + * |[ * /* 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: - * |[ + * |[ * list = g_list_remove_link (list, llink); * list = g_list_concat (llink, list); * ]| @@ -18497,12 +18154,10 @@ * * Copies a #GList. * - * * 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. - * * * 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: - * |[ + * |[ * another_list = g_list_copy_deep (list, (GCopyFunc) g_object_ref, NULL); * ]| * * And, to entirely free the new list, you could do: - * |[ + * |[ * 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. * - * - * If list elements contain dynamically-allocated memory, - * you should either use g_list_free_full() or free them manually - * first. - * + * 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. * - * * 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() - * + * 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. * - * * 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() - * + * 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. * - * * This function iterates over the whole list to count its elements. - * Use a GQueue instead - * of a GList if you regularly need the number of items. - * + * 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. * - * |[ + * |[ * /* Notice that it is initialized to the empty list. */ * GList *list = NULL; * @@ -18840,10 +18486,8 @@ * list = g_list_prepend (list, "first"); * ]| * - * - * 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. - * + * 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: - * |[ + * |[ * 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. + * 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. + * 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: - * - * - * 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. - * - * - * + * + * - `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 G_DEBUG environment variable (see - * Running GLib Applications). + * 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. * - * - * Adding a log handler for all warning messages in the default - * (application) domain - * + * Here is an example for adding a log handler for all warning messages + * in the default domain: + * |[ * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * - * + * ]| * - * - * Adding a log handler for all critical messages from GTK+ - * + * This example adds a log handler for all critical messages from GTK+: + * |[ * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * - * + * ]| * - * - * Adding a log handler for <emphasis>all</emphasis> messages from - * GLib - * + * This example adds a log handler for all messages from GLib: + * |[ * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * | G_LOG_FLAG_RECURSION, my_log_handler, NULL); - * - * + * ]| * * 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 stat 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 #GSources 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(), not 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: * - * |[ + * |[ * #define NUM_TASKS 10 * static volatile gint tasks_remaining = NUM_TASKS; * ... @@ -19670,7 +19301,7 @@ * ]| * * Then in a thread: - * |[ + * |[ * 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. * - * |[ + * |[ * 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() * - * |[ + * |[ * gpointer * allocate_memory (gsize size) * { @@ -19785,23 +19416,14 @@ * many things that the user could do. Instead, you can use the * following techniques: * - * - * - * - * Use gtk_widget_set_sensitive() or modal dialogs to prevent - * the user from interacting with elements while the main - * loop is recursing. - * - * - * - * - * 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. - * - * - * + * 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. * - * |[ + * |[ * 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: * - * |[ + * |[ * void * start_counting (GMarkupParseContext *context) * { @@ -20393,7 +20015,7 @@ * * The subparser would then be used as follows: * - * |[ + * |[ * 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"; + * |[ + * 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 ("" + * "%s" + * "%s" + * "", * 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 man:pcrepartial 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 G_DEBUG environment variable - * includes the key gc-friendly. + * 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. This function must be called - * before using any other GLib functions. 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. * - * |[ + * |[ * typedef struct { * GMutex m; * ... @@ -21065,10 +20691,10 @@ * current thread will block until @mutex is unlocked by the other * thread. * - * #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). + * (including but not limited to deadlocks). */ @@ -21080,11 +20706,10 @@ * it immediately returns %FALSE. Otherwise it locks @mutex and returns * %TRUE. * - * #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). - * * * Returns: %TRUE if @mutex could be locked */ @@ -21448,19 +21073,19 @@ /** * g_on_error_query: - * @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) + * @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 - * [E]xit, [H]alt, show [S]tack trace or [P]roceed. + * `[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> + * |[ + * #include * * 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 _exit(0). + * 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 gdb, 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 gdb - * for the [S]tack trace option. + * @prg_name: the program name, needed by gdb for the "[S]tack trace" + * option * - * 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(). + * 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. * - * |[ + * |[ * gpointer * get_debug_flags (void) * { @@ -21564,17 +21189,17 @@ * blocked until initialization completed. To be used in constructs * like this: * - * |[ + * |[ * 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 #GOptionEntrys + * @entries: a %NULL-terminated array of #GOptionEntrys * @translation_domain: (allow-none): a translation domain to use for translating - * the 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 , call - * g_option_context_get_help (context, TRUE, NULL). - * To obtain the text produced by , call - * g_option_context_get_help (context, FALSE, NULL). + * 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 - * g_option_context_get_help (context, FALSE, group). + * `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 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 output, after the - * usage summary - * programname [OPTION...] + * 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 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 exit (0). + * call `exit (0)`. * * Note that function depends on the * current locale for @@ -21853,12 +21478,11 @@ /** * g_option_context_set_description: * @context: a #GOptionContext - * @description: (allow-none): a string to be shown in 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 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 , %FALSE to disable it + * @help_enabled: %TRUE to enable `--help`, %FALSE to disable it * - * Enables or disables automatic generation of - * output. By default, g_option_context_parse() recognizes - * , , - * , - * and groupname 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 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 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 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 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 #GOptionEntrys + * @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 not - * 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 @name + * help for the options in this group with `--help-`@name * @description: a description for this group to be shown in - * . 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 @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 output. Different - * groups can use different #GTranslateFuncs. 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 #GDebugKeys 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 "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 "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 "help", 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(), - * not 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 - * not 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 - * #GPollFDs 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. * - * 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. + * 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. * - * - * This does not perform bounds checking on the given @index_, so you are - * responsible for checking it against the array length. + * 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). * - * 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. + * 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. * - * 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. + * 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 always 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 must 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. * - * - * If queue elements contain dynamically-allocated memory, - * you should either use g_queue_free_full() or free them manually - * first. - * + * 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 must 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 must 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, not 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, not 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 must 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 /dev/urandom (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 g_random_* 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. * - * |[ + * |[ * 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(). * - * |[ + * |[ * 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(). * - * |[ + * |[ * 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: * - * - * \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 - * - * - * + * - \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: - * |[ + * |[ * 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. * - * |[ + * |[ * 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. * - * * 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. - * * * 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. * - * * 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. - * * * 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 exactly 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(). * - * * 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. - * * * 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(). * - * * 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. - * * * 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 not - * 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. * - * - * 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). - * + * 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. - * * * 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 1 * sizeof (void*), + * 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 sizeof (@type) + * 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 sizeof (type) + * It calls g_slice_free1() using `sizeof (type)` * as the block size. * Note that the exact release behaviour can be changed with the * G_DEBUG=gc-friendly environment @@ -25813,11 +25397,11 @@ * A convenience macro to allocate a block of memory from the * slice allocator. * - * 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 G_SLICE=always-malloc + * 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 + * G_SLICE=always-malloc * 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 sizeof (@type) + * 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. * - * * The return value is the new start of the list, which may * have changed, so make sure you store the new value. - * * - * * 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. - * * - * |[ + * |[ * /* Notice that these are initialized to the empty list. */ * GSList *list = NULL, *number_list = NULL; * @@ -25909,12 +25489,10 @@ * * Copies a #GSList. * - * * 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. - * * * Returns: a copy of @list */ @@ -25936,12 +25514,12 @@ * one argument. * * For instance, if @list holds a list of GObjects, you can do: - * |[ + * |[ * another_list = g_slist_copy_deep (list, (GCopyFunc) g_object_ref, NULL); * ]| * * And, to entirely free the new list, you could do: - * |[ + * |[ * 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. * - * 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. + * 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. * - * * If list elements contain dynamically-allocated memory, * you should either use g_slist_free_full() or free them manually * first. - * */ @@ -26133,9 +25709,7 @@ * * Gets the last element in a #GSList. * - * * This function iterates over the whole list. - * * * 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. * - * * This function iterates over the whole list to * count its elements. - * * * Returns: the number of elements in the #GSList */ @@ -26211,12 +25783,10 @@ * * Adds a new element on to the start of the list. * - * * The return value is the new start of the list, which * may have changed, so make sure you store the new value. - * * - * |[ + * |[ * /* 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. * - * 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. + * 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. * - * |[ + * |[ * 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. * - * |[ + * |[ * 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 - * sizeof (GSource). + * `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. * - * - * 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. - * + * 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 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. - * + * 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 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. + * 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 - * 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 + * 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 KEY=VALUE. 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 SIGCHLD 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 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 + * 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 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. + * 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 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 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(). * - * * 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. - * * * 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 - * waitpid(2) 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. + * 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 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 @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 - * 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. + * 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 stat 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 - * 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". + * 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: hash = hash * 33 + c. 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 + * |[ * 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. * - * The variable argument list must end - * with %NULL. If you forget the %NULL, g_strconcat() will start appending - * random memory junk to your string. - * * 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 - * |[ + * |[ * 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). * - * Caveat: this is supposedly a more secure alternative to - * strcat() or strncat(), but for real security g_strconcat() is harder - * to mess up. + * 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 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. + * 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. * - * 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. + * 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. * - * - * To copy a number of characters from a UTF-8 encoded string, use - * g_utf8_strncpy() instead. - * + * 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, - * g_strreverse ("abcdef") 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 signal - * 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 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 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: * - * |[ + * |[ * /* 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 "no_g_set_prgname", 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: - * - * - * - * - * List test cases available in a test executable. - * - * - * - * - * - * Provide a random seed to reproduce test runs using random numbers. - * - * - * - * - * Run tests verbosely. - * - * - * , - * Run tests quietly. - * - * - * - * - * Execute all tests matching TESTPATH. - * This can also be used to force a test to run that would otherwise - * be skipped (ie, a test whose name contains "/subprocess"). - * - * - * - * - * - * 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 test logging output. - * - * + * + * - `-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 testpath) 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 g_test_add_* + * 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 testpath) - * 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. * - * |[ + * |[ * 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 "/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. + * @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 main () 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 - * my_object_new(1000000) will abort with an error + * `my_object_new(1000000)` will abort with an error * message. * - * |[ + * |[ * 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 g_thread_exit (retval) 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(). * - * - * 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. - * + * 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 - * RFC 3339, and - * to either of the two most-precise formats defined by - * the W3C Note - * "Date and Time Formats". 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 - * TZ 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 "Z" (for UTC) or - * "±hh:mm". ISO 8601 additionally specifies - * "±hhmm" and "±hh". 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 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 + * 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 - * 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 + * `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 RFC3339 - * §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 for an explanation of the possible - * values of the TZ environment variable. See - * Microsoft Time Zone Index Values 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 - * TZ 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 gunichar2 - * 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 UAX#15 + * 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 UAX#15 + * 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 UAX#15 + * 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 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. + * 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 - * Unicode Standard - * Annex #11 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 Codes for the - * representation of names of scripts 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 Codes for the - * representation of names of scripts 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 - * FD_CLOEXEC. If for example you want to configure - * O_NONBLOCK, 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(). * - * This function does *not* take O_CLOEXEC, it takes - * FD_CLOEXEC as if for fcntl(); these are - * different on Linux/glibc. + * 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 O_NONBLOCK, but - * on some older ones may use O_NDELAY. + * 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 - * SIGHUP, SIGINT, - * SIGTERM can be monitored. In GLib 2.36, - * SIGUSR1 and SIGUSR2 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 SIGTERM + * 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. * - * - * 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). - * + * 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. - * * * 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: - * + * |[ * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ] - * + * ]| * 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 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. + * @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 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. + * @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. * - * - * 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. - * * * 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 gunichar2 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 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. + * 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 GVariant varargs documentation. + * * This function might be used as follows: * - * |[ + * |[ * 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 GVariant varargs documentation. + * * This function might be used as follows: * - * |[ + * |[ * GVariant * * make_pointless_dictionary (void) * { @@ -32974,6 +32460,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 + * GVariant Format Strings. + * + * 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 @@ -33313,8 +33017,8 @@ * Memory. * * In particular, arrays of these fixed-sized types can be interpreted - * as an array of the given C type, with @element_size set to - * sizeof the appropriate type: + * as an array of the given C type, with @element_size set to the size + * the appropriate type: * * * @@ -33331,16 +33035,16 @@ * * * - * 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. + * 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 GVariant - * Format Strings. - * - * - * Memory management with g_variant_iter_loop() - * - * /* Iterates a dictionary of type 'a{sv}' */ + * Here is an example for memory management with g_variant_iter_loop(): + * |[ + * /* 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 + * */ * } * } - * - * + * ]| * * 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 * GVariant Format Strings. * * 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 GVariant - * Format Strings. - * - * - * Memory management with g_variant_iter_next() - * - * /* Iterates a dictionary of type 'a{sv}' */ + * Here is an example for memory management with g_variant_iter_next(): + * |[ + * /* 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); * } * } - * - * + * ]| * * 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 * GVariant Format Strings. * * 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. * - * - * Iterating with g_variant_iter_next_value() - * - * /* recursively iterate a container */ + * Here is an example for iterating with g_variant_iter_next_value(): + * |[ + * /* recursively iterate a container */ * void * iterate_container_recursive (GVariant *container) * { @@ -34014,8 +33710,7 @@ * g_variant_unref (child); * } * } - * - * + * ]| * * Returns: (allow-none) (transfer full): a #GVariant, or %NULL * Since: 2.24 @@ -34041,6 +33736,9 @@ * see the section on * GVariant Format Strings. * + * 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 - * a{s*} (and equally well with type - * a{o*}, 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 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 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 GVariant varargs documentation. + * + * + * 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); + * + * * 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 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. + * @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 GVariant varargs documentation. * - * + * Consider this simple example: + * |[ * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three"); - * + * ]| * * 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 [('one', 1), ('two', 2), ('three', 3)]. + * result of + * |[ + * [('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 GVariant varargs documentation. + * * 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 GVariant varargs documentation. + * * 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. @@ -34753,6 +34480,13 @@ */ +/** + * g_variant_parser_get_error_quark: + * + * Deprecated: Use g_variant_parse_error_quark() instead. + */ + + /** * g_variant_print: * @value: a #GVariant @@ -34804,7 +34538,7 @@ * @value: a #GVariant * * #GVariant uses a floating reference count system. All functions with - * names starting with g_variant_new_ 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 - * G_DEBUG environment variable (see - * Running GLib Applications). + * 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 - * GETTEXT_PACKAGE in software configured using GNU + * `GETTEXT_PACKAGE` in software configured using GNU * autotools. The function first looks in the Windows Registry for the - * value #InstallationDirectory in the key - * #HKLM\Software\@package, 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 char type. + * Corresponds to the standard C char type. */ @@ -35851,7 +35585,7 @@ /** * gdouble: * - * Corresponds to the standard C double 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 float 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 int 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 intptr_t, + * 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 long 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 off64_t. + * 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 void*. + * #gpointer looks better and is easier to use than void*. */ /** * gshort: * - * Corresponds to the standard C short 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 size_t 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 - * ssize_t 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 unsigned char type. + * Corresponds to the standard C unsigned char type. */ /** * guint: * - * Corresponds to the standard C unsigned int 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 uintptr_t, + * 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 unsigned long 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 unsigned short type. + * Corresponds to the standard C unsigned short type. * Values of this type can range from 0 to #G_MAXUSHORT. */ diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c index ccfbccaa..83fd6a92 100644 --- a/gir/gmodule-2.0.c +++ b/gir/gmodule-2.0.c @@ -16,7 +16,6 @@ * @module: the #GModule corresponding to the module which has just been loaded * * Specifies the type of the module initialization function. - * g_module_check_init * 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 * - * g_module_unload * 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 - * pkg-config --libs gmodule-2.0. + * 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 - * g_quark_from_static_string ("my-module-stuff"), + * `g_quark_from_static_string ("my-module-stuff")`, * it must ensure that it is never unloaded, by calling g_module_make_resident(). * - * - * Calling a function defined in a <structname>GModule</structname> - * + * Example: Calling a function defined in a GModule + * |[ * /* 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; * } - * - * + * ]| */ /** * 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 /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. + * @directory of `/lib` and a @module_name of "mylibrary" will return + * `/lib/libmylibrary.so`. On a Windows system, using `\Windows` as the + * directory it will return `\Windows\mylibrary.dll`. * * Returns: the complete path of the module, including the standard library * prefix and suffix. This should be freed when no longer needed diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index ab618f62..b25b8d0b 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -63,7 +63,7 @@ * This signal is typically used to obtain change notification for a * single property, by specifying the property name as a detail in the * g_signal_connect() call, like this: - * |[ + * |[ * 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 #GParamSpecs 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 #GWeakRefs taken + * references to the object being held, any #GWeakRefs taken * before it was disposed will continue to point to %NULL. If - * #GWeakRefs 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: * - * |[ + * |[ * g_object_bind_property (object1, "property-a", * object2, "property-b", * G_BINDING_DEFAULT); * ]| * - * will cause object2:property-b to be updated every - * time g_object_set() or the specific accessor changes the value of - * object1:property-a. + * 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: * - * |[ + * |[ * 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: * - * |[ + * |[ * g_object_bind_property_full (adjustment1, "value", * adjustment2, "value", * G_BINDING_BIDIRECTIONAL, @@ -182,15 +182,15 @@ * NULL, NULL); * ]| * - * will keep the value property of the two adjustments - * in sync; the celsius_to_fahrenheit function will be - * called whenever the adjustment1:value property changes - * and will transform the current value of the property before applying it - * to the adjustment2:value property; vice versa, the - * fahrenheit_to_celsius function will be called whenever - * the adjustment2:value property changes, and will - * transform the current value of the property before applying it to the - * adjustment1:value. + * 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. * - * 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. + * 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 #GValues 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 #GValues 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: - * - * - * 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. - * - * + * + * - 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> + * |[ + * #include * * 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. * - * - * 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. - * + * 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: - * - * #GTypePlugin - * The abstract type loader interface. - * - * - * #GModule - * Portable mechanism for dynamically loaded modules. - * - * + * @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: - * - * - * - * 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 new_type_plugin is an implementation of the - * #GTypePlugin interface. - * - * - * 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: + * |[ + * 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 new_type_id. - * - * - * 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. - * - * - * 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). - * - * - * 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. - * - * - * Things may repeat from the second step. - * - * + * 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 . * - * + * ## 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 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: - * |[ + * 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: + * |[ * container = create_container (); * container_add_child (container, create_child()); * ]| - * If container_add_child() will g_object_ref_sink() 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: - * |[ + * 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: + * |[ * 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. - * * * 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: * - * |[ + * |[ * /* 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 - * 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 - * 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. - * - * 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: - * - * - * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * - * - * 2 - Invocation of normal user-provided signal handlers (after flag %FALSE) - * - * - * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * - * - * 4 - Invocation of user provided signal handlers, connected with an after flag of %TRUE - * - * - * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * - * + * + * 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 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. + * + * 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: * - * |[ + * |[ * GValueArray *array = g_value_array_new (10); * ]| * * can be replaced by: * - * |[ + * |[ * 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. * - * 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. + * 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 - * gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data) 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 - * gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data). + * `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 - * gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gboolean arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gchar arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gdouble arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gint arg1, gpointer user_data) 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 - * void (*callback) (gpointer instance, gint arg1, gpointer user_data) 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 - * void (*callback) (gpointer instance, gfloat arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gint arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, glong arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, GObject *arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gpointer arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, guchar arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, guint arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gulong arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data). + * `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 - * void (*callback) (gpointer instance, gpointer user_data). + * `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 #GValues 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 libffi. + * 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 - * #GValues 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 - * sizeof (GClosure) + * `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 - * sizeof (GClosure) + * `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. * - * |[ + * |[ * 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 marshal_data + * 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 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: - * |[ + * 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: + * |[ * 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: - * |[ + * |[ * 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: - * |[ + * |[ * 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 complete_type_info + * This function is meant to be called from the `complete_type_info` * function of a #GTypePlugin implementation, as in the following * example: * - * |[ + * |[ * 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 - * toggled 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. * - * 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. + * 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 #GClosures 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 #GParamSpecs array - * @pspecs: (array length=n_pspecs): the #GParamSpecs 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 #GParamSpecs. 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 - * #GParamSpecs and g_object_notify_by_pspec(). For instance, this + * #GParamSpecs and g_object_notify_by_pspec(). For instance, this * class initialization: * - * |[ + * |[ * 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: * - * |[ + * |[ * 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 override - * 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. * - * * 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(). - * * * 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: - * - * - * 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) - * - * - * - * - * |[ + * * - 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) + * + * |[ * 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 * floating object reference. * Doing this is seldom required: all - * #GInitiallyUnowneds 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(). * - * - * Using g_object_get(<!-- -->) - * 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: - * + * Here is an example of using g_object_get() to get the contents + * of three properties: an integer, a string and an object: + * |[ * 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); - * - * + * ]| */ @@ -2463,7 +2384,7 @@ * instead, is to store the GParamSpec used with * g_object_class_install_property() inside a static array, e.g.: * - * |[ + * |[ * enum * { * PROP_0, @@ -2488,7 +2409,7 @@ * * and then notify a change on the "foo" property with: * - * |[ + * |[ * 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: - * |[ + * |[ * 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, #GParamSpecs 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 #GParamSpecs 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 #GParamSpecs 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 #GParamSpecs owned by @owner_type in - * the pool#GParamSpecs. + * #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 void (*destroy) (gpointer) 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 g_param_spec_ref (pspec); g_param_spec_sink - * (pspec); 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 handled 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 ..._after() or - * ..._swapped() 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 class_init method by doing - * super_class->signal_handler = my_signal_handler. 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 - * MyObjectPrivate to an object - * MyObject 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(). * - * |[ + * |[ * 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. * - * - * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); - * + * 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 #GTypeClassCacheFuncs, 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 - * 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. + * #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 @base_init - * and class_init 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 class_finalize 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. - * 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. + * @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 - * value_array->n_values + * @value_array->n_values * * Remove the value at position @index_ from @value_array. * -- cgit v1.2.1