From d9e22053063d573c2a968a2468d829c0f6191fd0 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Sun, 16 Feb 2014 21:16:34 +0100 Subject: Update glib annotations from git master --- gir/gio-2.0.c | 1121 +++++++++++++++++++++++------------------------------ gir/glib-2.0.c | 1118 +++++++++++++++++++--------------------------------- gir/gmodule-2.0.c | 8 +- gir/gobject-2.0.c | 95 +++-- 4 files changed, 939 insertions(+), 1403 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index d3f9c581..0cc13e84 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -259,8 +259,8 @@ * 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). + * the `--gapplication-service` switch works properly (i.e. 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 @@ -396,13 +396,12 @@ * * An example of how to us this: * |[ - * /* Make sure we don't do 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; @@ -411,13 +410,12 @@ * 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); * ]| * @@ -857,7 +855,7 @@ * connect signals to all interface proxies managed by @manager. * * This signal is emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * that @manager was constructed in. * * Since: 2.30 @@ -879,7 +877,7 @@ * connect signals to all interface proxies managed by @manager. * * This signal is emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * that @manager was constructed in. * * Since: 2.30 @@ -1218,9 +1216,9 @@ * * If #GDBusServer:flags contains %G_DBUS_SERVER_FLAGS_RUN_IN_THREAD * then the signal is emitted in a new thread dedicated to the - * connection. Otherwise the signal is emitted in the thread-default main - * loop of the thread that @server was constructed in. + * connection. Otherwise the signal is emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @server was constructed in. * * You are guaranteed that signal handlers for this signal runs * before incoming messages on @connection are processed. This means @@ -2364,7 +2362,7 @@ * * 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); * } @@ -3484,7 +3482,7 @@ * SECTION:extensionpoints * @short_description: Extension Points * @include: gio.h - * @see_also: Extending GIO + * @see_also: [Extending GIO][extending-gio] * * #GIOExtensionPoint provides a mechanism for modules to extend the * functionality of the library or application that loaded it in an @@ -3504,13 +3502,13 @@ * |[ * GIOExtensionPoint *ep; * - * /* Register an extension point */ + * // Register an extension point * ep = g_io_extension_point_register ("my-extension-point"); * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE); * ]| * * |[ - * /* Implement an extension point */ + * // Implement an extension point * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE); * g_io_extension_point_implement ("my-extension-point", * my_example_impl_get_type (), @@ -3526,7 +3524,7 @@ * * To avoid opening all modules just to find out what extension * points they implement, GIO makes use of a caching mechanism, - * see gio-querymodules. + * see [gio-querymodules][gio-querymodules]. * You are expected to run this command after installing a * GIO module. * @@ -3682,7 +3680,7 @@ * (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 + * \%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 @@ -3712,7 +3710,7 @@ * * if (g_file_has_uri_scheme (file, "cdda")) * { - * /* do something special with uri */ + * // do something special with uri * } * g_object_unref (file); * ]| @@ -3863,29 +3861,14 @@ * vfunc, to parse them in either the primary instance or the local instance, * respectively. * - * Opening files with a GApplication - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * For an example of opening files with a GApplication, see + * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). * - * A GApplication with actions - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * For an example of using actions with GApplication, see + * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). * - * Using extra D-Bus hooks with a GApplication - * - * - * FIXME: MISSING XINCLUDE CONTENT - * - * - * + * For an example of using extra D-Bus hooks with GApplication, see + * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c). */ @@ -3909,7 +3892,8 @@ * The GApplicationCommandLine object can provide the @argc and @argv * parameters for use with the #GOptionContext command-line parsing API, * with the g_application_command_line_get_arguments() function. See - * for an example. + * [gapplication-example-cmdline3.c][gapplication-example-cmdline3] + * for an example. * * The exit status of the originally-invoked process may be set and * messages can be printed to stdout or stderr of that process. The @@ -4016,10 +4000,10 @@ * { * GApplicationCommandLine *cmdline = data; * - * /* do the heavy lifting in an idle */ + * // do the heavy lifting in an idle * * g_application_command_line_set_exit_status (cmdline, 0); - * g_object_unref (cmdline); /* this releases the application */ + * g_object_unref (cmdline); // this releases the application * * return G_SOURCE_REMOVE; * } @@ -4028,7 +4012,7 @@ * command_line (GApplication *application, * GApplicationCommandLine *cmdline) * { - * /* keep the application running until we are done with this commandline */ + * // keep the application running until we are done with this commandline * g_application_hold (application); * * g_object_set_data_full (G_OBJECT (cmdline), @@ -4452,7 +4436,7 @@ * @title: GDBusActionGroup * @short_description: A D-Bus GActionGroup implementation * @include: gio/gio.h - * @see_also: GActionGroup exporter + * @see_also: [GActionGroup exporter][gio-GActionGroup-exporter] * * #GDBusActionGroup is an implementation of the #GActionGroup * interface that can be used as a proxy for an action group @@ -4468,7 +4452,7 @@ * * Routines for working with D-Bus addresses. A D-Bus address is a string * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses - * is explained in detail in the D-Bus specification. + * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses). */ @@ -4483,10 +4467,13 @@ * signals you are interested in. Note that new signals may be added * in the future * + * ## Controlling Authentication # {#auth-observer} + * * For example, if you only want to allow D-Bus connections from * processes owned by the same uid as the server, you would use a * signal handler like the following: - * Controlling Authentication + * + * |[ * static gboolean * on_authorize_authenticated_peer (GDBusAuthObserver *observer, * GIOStream *stream, @@ -4507,7 +4494,7 @@ * * return authorized; * } - * + * ]| */ @@ -4546,13 +4533,25 @@ * #GError, the only valid thing you can do with that #GDBusConnection is to * free it with g_object_unref(). * - * D-Bus server exampleFIXME: MISSING XINCLUDE CONTENT + * ## An example D-Bus server # {#gdbus-server} + * + * Here is an example for a D-Bus server: + * [gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c) + * + * ## An example for exporting a subtree # {#gdbus-subtree-server} * - * D-Bus subtree exampleFIXME: MISSING XINCLUDE CONTENT + * Here is an example for exporting a subtree: + * [gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c) * - * D-Bus UNIX File Descriptor exampleFIXME: MISSING XINCLUDE CONTENT + * ## An example for file descriptor passing # {#gdbus-unix-fd-client} * - * Exporting a GObjectFIXME: MISSING XINCLUDE CONTENT + * Here is an example for passing UNIX file descriptors: + * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-unix-fd-client.c) + * + * ## An example for exporting a GObject # {#gdbus-export} + * + * Here is an example for exporting a #GObject: + * [gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c) */ @@ -4581,7 +4580,7 @@ * is typically done in the function returning the #GQuark for the * error domain: * |[ - * /* foo-bar-error.h: */ + * // foo-bar-error.h: * * #define FOO_BAR_ERROR (foo_bar_error_quark ()) * GQuark foo_bar_error_quark (void); @@ -4591,10 +4590,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[] = * { @@ -4603,7 +4602,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 @@ -4673,7 +4672,7 @@ * @title: GDBusMenuModel * @short_description: A D-Bus GMenuModel implementation * @include: gio/gio.h - * @see_also: GMenuModel Exporter + * @see_also: [GMenuModel Exporter][gio-GMenuModel-exporter] * * #GDBusMenuModel is an implementation of #GMenuModel that can be used * as a proxy for a menu model that is exported over D-Bus with @@ -4714,7 +4713,8 @@ * * Convenience API for owning bus names. * - * Simple application owning a nameFIXME: MISSING XINCLUDE CONTENT + * A simple example for owning a name can be found in + * [gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c) */ @@ -4726,7 +4726,8 @@ * * Convenience API for watching bus names. * - * Simple application watching a nameFIXME: MISSING XINCLUDE CONTENT + * A simple example for watching a name can be found in + * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c) */ @@ -4831,7 +4832,7 @@ * #GDBusObjectManagerClient::interface-proxy-signal. * * Note that all callbacks and signals are emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * that the #GDBusObjectManagerClient object was constructed * in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects * originating from the #GDBusObjectManagerClient object will be created in @@ -4917,20 +4918,20 @@ * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). * * The generic #GDBusProxy::g-properties-changed and - * #GDBusProxy::g-signal signals are not very convenient to work - * with. Therefore, the recommended way of working with proxies is to - * 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. + * #GDBusProxy::g-signal signals are not very convenient to work with. + * Therefore, the recommended way of working with proxies is to subclass + * #GDBusProxy, and have more natural properties and signals in your derived + * class. This [example][gdbus-example-gdbus-codegen] shows how this can + * easily be done using the [gdbus-codegen][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 * and #GObject::notify) are emitted in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread where the instance was constructed. * - * GDBusProxy for a well-known-nameFIXME: MISSING XINCLUDE CONTENT + * An example using a proxy for a well-known name can be found in + * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c) */ @@ -4948,7 +4949,8 @@ * To just export an object on a well-known name on a message bus, such as the * session or system bus, you should instead use g_bus_own_name(). * - * D-Bus peer-to-peer exampleFIXME: MISSING XINCLUDE CONTENT + * An example of peer-to-peer communication with G-DBus can be found + * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c). */ @@ -4971,7 +4973,7 @@ * #GDesktopAppInfo is an implementation of #GAppInfo based on * desktop files. * - * Note that `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific + * Note that `` belongs to the UNIX-specific * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config * file when using it. */ @@ -5055,13 +5057,11 @@ * (see #GInputStream and #GOutputStream). * * To construct a #GFile, you can use: - * - * g_file_new_for_path() if you have a path. - * g_file_new_for_uri() if you have a URI. - * g_file_new_for_commandline_arg() for a command line argument. - * g_file_new_tmp() to create a temporary file from a template. - * g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). - * + * - g_file_new_for_path() if you have a path. + * - g_file_new_for_uri() if you have a URI. + * - g_file_new_for_commandline_arg() for a command line argument. + * - g_file_new_tmp() to create a temporary file from a template. + * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). * * One way to think of a #GFile is as an abstraction of a pathname. For * normal files the system pathname is what is stored internally, but as @@ -5110,11 +5110,9 @@ * Some #GFile operations do not have synchronous analogs, as they may * take a very long time to finish, and blocking may leave an application * unusable. Notable cases include: - * - * g_file_mount_mountable() to mount a mountable file. - * g_file_unmount_mountable_with_operation() to unmount a mountable file. - * g_file_eject_mountable_with_operation() to eject a mountable file. - * + * - g_file_mount_mountable() to mount a mountable file. + * - g_file_unmount_mountable_with_operation() to unmount a mountable file. + * - g_file_eject_mountable_with_operation() to eject a mountable file. * * ## Entity Tags # {#gfile-etag} * @@ -5156,71 +5154,62 @@ * and other possible implementation details (e.g., on a UNIX system, a file * attribute key will be registered for the user id for a given file). * - * - * - * GFileAttributes Default Namespaces - * - * NamspaceDescription - * - * - * "standard"The "Standard" namespace. General file - * information that any application may need should be put in this namespace. - * Examples include the file's name, type, and size. - * "etag"The "Entity Tag" - * namespace. Currently, the only key in this namespace is "value", which contains - * the value of the current entity tag. - * "id"The "Identification" namespace. This - * namespace is used by file managers and applications that list directories - * to check for loops and to uniquely identify files. - * "access"The "Access" namespace. Used to check - * if a user has the proper privilidges to access files and perform - * file operations. Keys in this namespace are made to be generic - * and easily understood, e.g. the "can_read" key is %TRUE if - * the current user has permission to read the file. UNIX permissions and - * NTFS ACLs in Windows should be mapped to these values. - * "mountable"The "Mountable" namespace. Includes - * simple boolean keys for checking if a file or path supports mount operations, e.g. - * mount, unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. - * "time"The "Time" namespace. Includes file - * access, changed, created times. - * "unix"The "Unix" namespace. Includes UNIX-specific - * information and may not be available for all files. Examples include - * the UNIX "UID", "GID", etc. - * "dos"The "DOS" namespace. Includes DOS-specific - * information and may not be available for all files. Examples include - * "is_system" for checking if a file is marked as a system file, and "is_archive" - * for checking if a file is marked as an archive file. - * "owner"The "Owner" namespace. Includes information - * about who owns a file. May not be available for all file systems. Examples include - * "user" for getting the user name of the file owner. This information is often mapped from - * some backend specific data such as a unix UID. - * "thumbnail"The "Thumbnail" namespace. Includes - * information about file thumbnails and their location within the file system. Examples of - * keys in this namespace include "path" to get the location of a thumbnail, "failed" - * to check if thumbnailing of the file failed, and "is-valid" to check if the thumbnail is - * outdated. - * "filesystem"The "Filesystem" namespace. Gets information - * about the file system where a file is located, such as its type, how much - * space is left available, and the overall size of the file system. - * "gvfs"The "GVFS" namespace. Keys in this namespace - * contain information about the current GVFS backend in use. - * "xattr"The "xattr" namespace. Gets information - * about extended user attributes. See attr(5). The "user." prefix of the - * extended user attribute name is stripped away when constructing keys in - * this namespace, e.g. "xattr::mime_type" for the extended attribute with - * the name "user.mime_type". Note that this information is only available - * if GLib has been built with extended attribute support. - * "xattr-sys"The "xattr-sys" namespace. - * Gets information about extended attributes which are not user-specific. - * See attr(5). Note that this information is only available if GLib - * has been built with extended attribute support. - * "selinux"The "SELinux" namespace. Includes - * information about the SELinux context of files. Note that this information - * is only available if GLib has been built with SELinux support. - * - * - *
- * + * ## Default Namespaces + * + * - `"standard"`: The "Standard" namespace. General file information that + * any application may need should be put in this namespace. Examples + * include the file's name, type, and size. + * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key + * in this namespace is "value", which contains the value of the current + * entity tag. + * - `"id"`: The "Identification" namespace. This namespace is used by file + * managers and applications that list directories to check for loops and + * to uniquely identify files. + * - `"access"`: The "Access" namespace. Used to check if a user has the + * proper privileges to access files and perform file operations. Keys in + * this namespace are made to be generic and easily understood, e.g. the + * "can_read" key is %TRUE if the current user has permission to read the + * file. UNIX permissions and NTFS ACLs in Windows should be mapped to + * these values. + * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys + * for checking if a file or path supports mount operations, e.g. mount, + * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. + * - `"time"`: The "Time" namespace. Includes file access, changed, created + * times. + * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and + * may not be available for all files. Examples include the UNIX "UID", + * "GID", etc. + * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may + * not be available for all files. Examples include "is_system" for checking + * if a file is marked as a system file, and "is_archive" for checking if a + * file is marked as an archive file. + * - `"owner"`: The "Owner" namespace. Includes information about who owns a + * file. May not be available for all file systems. Examples include "user" + * for getting the user name of the file owner. This information is often + * mapped from some backend specific data such as a UNIX UID. + * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file + * thumbnails and their location within the file system. Examples of keys in + * this namespace include "path" to get the location of a thumbnail, "failed" + * to check if thumbnailing of the file failed, and "is-valid" to check if + * the thumbnail is outdated. + * - `"filesystem"`: The "Filesystem" namespace. Gets information about the + * file system where a file is located, such as its type, how much space is + * left available, and the overall size of the file system. + * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information + * about the current GVFS backend in use. + * - `"xattr"`: The "xattr" namespace. Gets information about extended + * user attributes. See attr(5). The "user." prefix of the extended user + * attribute name is stripped away when constructing keys in this namespace, + * e.g. "xattr::mime_type" for the extended attribute with the name + * "user.mime_type". Note that this information is only available if + * GLib has been built with extended attribute support. + * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about + * extended attributes which are not user-specific. See attr(5). Note + * that this information is only available if GLib has been built with + * extended attribute support. + * - `"selinux"`: The "SELinux" namespace. Includes information about the + * SELinux context of files. Note that this information is only available + * if GLib has been built with SELinux support. * * Please note that these are not all of the possible namespaces. * More namespaces can be added from GIO modules or by individual applications. @@ -5229,77 +5218,10 @@ * * - * - * GFileAttributes Built-in Keys and Value Types - * - * Enum ValueNamespace::KeyValue Type - * - * %G_FILE_ATTRIBUTE_STANDARD_TYPEstandard::typeuint32 (#GFileType) - * %G_FILE_ATTRIBUTE_STANDARD_IS_HIDDENstandard::is-hiddenboolean - * %G_FILE_ATTRIBUTE_STANDARD_IS_BACKUPstandard::is-backupboolean - * %G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINKstandard::is-symlinkboolean - * %G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUALstandard::is-virtualboolean - * %G_FILE_ATTRIBUTE_STANDARD_NAMEstandard::namebyte string - * %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAMEstandard::display-namestring - * %G_FILE_ATTRIBUTE_STANDARD_EDIT_NAMEstandard::edit-namestring - * %G_FILE_ATTRIBUTE_STANDARD_ICONstandard::iconobject (#GIcon) - * %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPEstandard::content-typestring - * %G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPEstandard::fast-content-typestring - * %G_FILE_ATTRIBUTE_STANDARD_SIZEstandard::sizeuint64 - * %G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZEstandard::allocated-sizeuint64 - * %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGETstandard::symlink-targetbyte string - * %G_FILE_ATTRIBUTE_STANDARD_TARGET_URIstandard::target-uristring - * %G_FILE_ATTRIBUTE_STANDARD_SORT_ORDERstandard::sort-orderint32 - * %G_FILE_ATTRIBUTE_ETAG_VALUEetag::valuestring - * %G_FILE_ATTRIBUTE_ID_FILEid::filestring - * %G_FILE_ATTRIBUTE_ID_FILESYSTEMid::filesystemstring - * %G_FILE_ATTRIBUTE_ACCESS_CAN_READaccess::can-readboolean - * %G_FILE_ATTRIBUTE_ACCESS_CAN_WRITEaccess::can-writeboolean - * %G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTEaccess::can-executeboolean - * %G_FILE_ATTRIBUTE_ACCESS_CAN_DELETEaccess::can-deleteboolean - * %G_FILE_ATTRIBUTE_ACCESS_CAN_TRASHaccess::can-trashboolean - * %G_FILE_ATTRIBUTE_ACCESS_CAN_RENAMEaccess::can-renameboolean - * %G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNTmountable::can-mountboolean - * %G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNTmountable::can-unmountboolean - * %G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECTmountable::can-ejectboolean - * %G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICEmountable::unix-deviceuint32 - * %G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILEmountable::unix-device-filestring - * %G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDImountable::hal-udistring - * %G_FILE_ATTRIBUTE_TIME_MODIFIEDtime::modifieduint64 - * %G_FILE_ATTRIBUTE_TIME_MODIFIED_USECtime::modified-usecuint32 - * %G_FILE_ATTRIBUTE_TIME_ACCESStime::accessuint64 - * %G_FILE_ATTRIBUTE_TIME_ACCESS_USECtime::access-usecuint32 - * %G_FILE_ATTRIBUTE_TIME_CHANGEDtime::changeduint64 - * %G_FILE_ATTRIBUTE_TIME_CHANGED_USECtime::changed-usecuint32 - * %G_FILE_ATTRIBUTE_TIME_CREATEDtime::createduint64 - * %G_FILE_ATTRIBUTE_TIME_CREATED_USECtime::created-usecuint32 - * %G_FILE_ATTRIBUTE_UNIX_DEVICEunix::deviceuint32 - * %G_FILE_ATTRIBUTE_UNIX_INODEunix::inodeuint64 - * %G_FILE_ATTRIBUTE_UNIX_MODEunix::modeuint32 - * %G_FILE_ATTRIBUTE_UNIX_NLINKunix::nlinkuint32 - * %G_FILE_ATTRIBUTE_UNIX_UIDunix::uiduint32 - * %G_FILE_ATTRIBUTE_UNIX_GIDunix::giduint32 - * %G_FILE_ATTRIBUTE_UNIX_RDEVunix::rdevuint32 - * %G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZEunix::block-sizeuint32 - * %G_FILE_ATTRIBUTE_UNIX_BLOCKSunix::blocksuint64 - * %G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINTunix::is-mountpointboolean - * %G_FILE_ATTRIBUTE_DOS_IS_ARCHIVEdos::is-archiveboolean - * %G_FILE_ATTRIBUTE_DOS_IS_SYSTEMdos::is-systemboolean - * %G_FILE_ATTRIBUTE_OWNER_USERowner::userstring - * %G_FILE_ATTRIBUTE_OWNER_USER_REALowner::user-realstring - * %G_FILE_ATTRIBUTE_OWNER_GROUPowner::groupstring - * %G_FILE_ATTRIBUTE_THUMBNAIL_PATHthumbnail::pathbytestring - * %G_FILE_ATTRIBUTE_THUMBNAILING_FAILEDthumbnail::failedboolean - * %G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALIDthumbnail::is-validboolean - * %G_FILE_ATTRIBUTE_PREVIEW_ICONpreview::iconobject (#GIcon) - * %G_FILE_ATTRIBUTE_FILESYSTEM_SIZEfilesystem::sizeuint64 - * %G_FILE_ATTRIBUTE_FILESYSTEM_FREEfilesystem::freeuint64 - * %G_FILE_ATTRIBUTE_FILESYSTEM_USEDfilesystem::useduint64 - * %G_FILE_ATTRIBUTE_FILESYSTEM_TYPEfilesystem::typestring - * %G_FILE_ATTRIBUTE_FILESYSTEM_READONLYfilesystem::readonlyboolean - * %G_FILE_ATTRIBUTE_GVFS_BACKENDgvfs::backendstring - * %G_FILE_ATTRIBUTE_SELINUX_CONTEXTselinux::contextstring - *
+ * ## Default Keys + * + * For a list of the built-in keys and their types, see the + * [GFileInfo][GFileInfo] documentation. * * Note that there are no predefined keys in the "xattr" and "xattr-sys" * namespaces. Keys for the "xattr" namespace are constructed by stripping @@ -5321,7 +5243,7 @@ * #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 + * Note that `` belongs to the UNIX-specific * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config * file when using it. * @@ -5378,14 +5300,14 @@ * SECTION:gfileinfo * @short_description: File Information and Attributes * @include: gio/gio.h - * @see_also: #GFile, GFileAttribute + * @see_also: #GFile, [GFileAttribute][gio-GFileAttribute] * * Functionality for manipulating basic metadata for files. #GFileInfo * implements methods for getting information that all files should * contain, and allows for manipulation of extended attributes. * - * See GFileAttribute for more - * information on how GIO handles file attributes. + * See [GFileAttribute][gio-GFileAttribute for more information on how + * GIO handles file attributes. * * To obtain a #GFileInfo for a #GFile, use g_file_query_info() (or its * async variant). To obtain a #GFileInfo for a file input or output @@ -5469,9 +5391,9 @@ * * To get informed about changes to the file or directory you are * monitoring, connect to the #GFileMonitor::changed signal. The - * signal will be emitted in the thread-default main - * context of the thread that the monitor was created in + * signal will be emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that the monitor was created in * (though if the global default main context is blocked, this may * cause notifications to be blocked even if the thread-default * context is still running). @@ -5721,9 +5643,9 @@ * To close a stream use g_io_stream_close() which will close the common * stream object and also the individual substreams. You can also close * the substreams themselves. In most cases this only marks the - * substream as closed, so further I/O on it fails. However, some streams - * may support "half-closed" states where one direction of the stream - * is actually shut down. + * substream as closed, so further I/O on it fails but common state in the + * #GIOStream may still be open. However, some streams may support + * "half-closed" states where one direction of the stream is actually shut down. * * Since: 2.22 */ @@ -5823,8 +5745,7 @@ * it (or, in the case of the 'root' menu, is defined by the context * in which it is used). * - * As an example, consider the visible portions of the menu in - * . + * As an example, consider the visible portions of this menu: * * ## An example menu # {#menu-example} * @@ -5842,7 +5763,7 @@ * - the Sources section (containing 2 items) * - the Markup section (containing 2 items) * - * illustrates the conceptual connection between + * The [example][menu-model] illustrates the conceptual connection between * these 8 menus. Each large block in the figure represents a menu and the * smaller blocks within the large block represent items in that menu. Some * items contain references to other menus. @@ -5851,8 +5772,8 @@ * * ![](menu-model.png) * - * Notice that the separators visible in - * appear nowhere in . This is because + * Notice that the separators visible in the [example][menu-example] + * appear nowhere in the [menu model][menu-model]. This is because * separators are not explicitly represented in the menu model. Instead, * a separator is inserted between any two non-empty sections of a menu. * Section items can have labels just like any other item. In that case, @@ -5863,12 +5784,10 @@ * outside the application. Examples include global menus, jumplists, * dash boards, etc. To support such uses, it is necessary to 'export' * information about actions and their representation in menus, which - * is exactly what the - * GActionGroup exporter - * and the - * GMenuModel exporter - * do for #GActionGroup and #GMenuModel. The client-side counterparts - * to make use of the exported information are #GDBusActionGroup and + * is exactly what the [GActionGroup exporter][gio-GActionGroup-exporter] + * and the [GMenuModel exporter][gio-GMenuModel-exporter] do for + * #GActionGroup and #GMenuModel. The client-side counterparts to + * make use of the exported information are #GDBusActionGroup and * #GDBusMenuModel. * * The API of #GMenuModel is very generic, with iterators for the @@ -5998,7 +5917,7 @@ * @short_description: System networking includes * @include: gio/gnetworking.h * - * The `<gio/gnetworking.h>` header can be included to get + * The `` header can be included to get * various low-level networking-related system headers, automatically * taking care of certain portability issues for you. * @@ -6195,10 +6114,9 @@ * the property. * * The general idea here is to reduce the number of locations where a - * particular piece of state is kept (and therefore has to be - * synchronised between). #GPropertyAction does not have a separate - * state that is kept in sync with the property value -- its state - * is the property value. + * particular piece of state is kept (and therefore has to be synchronised + * between). #GPropertyAction does not have a separate state that is kept + * in sync with the property value -- its state is the property value. * * For example, it might be useful to create a #GAction corresponding to * the "visible-child-name" property of a #GtkStack so that the current @@ -6317,7 +6235,7 @@ * 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 + * The #GResource API and the [glib-compile-resources][glib-compile-resources] program * provide a convenient and efficient alternative to this which has some nice properties. You * maintain the files as normal files, so its easy to edit them, but during the build the files * are combined into a binary bundle that is linked into the executable. This means that loading @@ -6346,7 +6264,7 @@ * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will * abort. * - * Resource bundles are created by the glib-compile-resources program + * Resource bundles are created by the [glib-compile-resources][glib-compile-resources] program * 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. * @@ -6372,7 +6290,7 @@ * 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. * - * You can then use glib-compile-resources to compile the xml to a + * You can then use [glib-compile-resources][glib-compile-resources] to compile the xml to a * binary bundle that you can load with g_resource_load(). However, its more common to use the --generate-source and * --generate-header arguments to create a source file and header to link directly into your application. * @@ -6472,22 +6390,22 @@ * Similar to GConf, the default values in GSettings schemas can be * localized, but the localized values are stored in gettext catalogs * and looked up with the domain that is specified in the - * gettext-domain attribute of the <schemalist> or <schema> + * gettext-domain attribute of the or * elements and the category that is specified in the l10n attribute of - * the <key> element. + * the element. * * GSettings uses schemas in a compact binary form that is created - * by the glib-compile-schemas + * by the [glib-compile-schemas][glib-compile-schemas] * 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`. + * The [glib-compile-schemas][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 + * id attribute of the element). The convention for schema * ids is to use a dotted name, similar in style to a D-Bus bus name, * e.g. "org.gnome.SessionManager". In particular, if the settings are * for a specific service that owns a D-Bus bus name, the D-Bus bus name @@ -6496,13 +6414,12 @@ * 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. + * enumerated types. These can be described by a , + * or element, as seen in the + * [example][schema-enumerated]. The underlying type of such a key + * is string, but you can use g_settings_get_enum(), g_settings_set_enum(), + * g_settings_get_flags(), g_settings_set_flags() access the numeric values + * corresponding to the string value of enum and flags keys. * * An example for default value: * |[ @@ -6577,11 +6494,11 @@ * 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: + * [glib-compile-schemas][glib-compile-schemas] reads so-called vendor + * override' files. These are keyfiles in the same directory as the XML + * schema sources which can override default values. The schema id serves + * 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' @@ -6820,9 +6737,9 @@ * 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 thread-default main - * context. g_simple_async_result_run_in_thread() will run the + * will finish it from an idle handler in the + * [thread-default main context][g-main-context-push-thread-default] + * . g_simple_async_result_run_in_thread() will run the * job in a separate thread and then deliver the result to the * thread-default main context. * @@ -6849,9 +6766,8 @@ * baked_cb (Cake *cake, * gpointer user_data) * { - * /* In this example, this callback is not given a reference to the cake, so - * * the GSimpleAsyncResult has to take a reference to it. - * */ + * // In this example, this callback is not given a reference to the cake, + * // so the GSimpleAsyncResult has to take a reference to it. * GSimpleAsyncResult *result = user_data; * * if (cake == NULL) @@ -6865,12 +6781,11 @@ * g_object_unref); * * - * /* In this example, we assume that baked_cb is called as a callback from - * * the mainloop, so it's safe to complete the operation synchronously here. - * * If, however, _baker_prepare_cake () might call its callback without - * * first returning to the mainloop — inadvisable, but some APIs do so — - * * we would need to use g_simple_async_result_complete_in_idle(). - * */ + * // In this example, we assume that baked_cb is called as a callback from + * // the mainloop, so it's safe to complete the operation synchronously here. + * // If, however, _baker_prepare_cake () might call its callback without + * // first returning to the mainloop — inadvisable, but some APIs do so — + * // we would need to use g_simple_async_result_complete_in_idle(). * g_simple_async_result_complete (result); * g_object_unref (result); * } @@ -6909,9 +6824,8 @@ * g_object_unref); * g_simple_async_result_complete_in_idle (simple); * g_object_unref (simple); - * /* Drop the reference returned by _baker_get_cached_cake(); the - * * GSimpleAsyncResult has taken its own reference. - * */ + * // Drop the reference returned by _baker_get_cached_cake(); + * // the GSimpleAsyncResult has taken its own reference. * g_object_unref (cake); * return; * } @@ -6981,7 +6895,7 @@ * SECTION:gsocket * @short_description: Low-level socket object * @include: gio/gio.h - * @see_also: #GInitable, gnetworking.h + * @see_also: #GInitable, [][gio-gnetworking.h] * * A #GSocket is a low-level networking primitive. It is a more or less * direct mapping of the BSD socket API in a portable GObject based API. @@ -7098,10 +7012,9 @@ * 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); @@ -7113,18 +7026,15 @@ * { * 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 initial lookup failed, or else the caller cancelled us. * if (conn_error) * g_error_free (conn_error); * return NULL; @@ -7158,6 +7068,10 @@ * custom socket connection types for specific combination of socket * family/type/protocol using g_socket_connection_factory_register_type(). * + * To close a #GSocketConnection, use g_io_stream_close(). Closing both + * substreams of the #GIOStream separately will not close the underlying + * #GSocket. + * * Since: 2.22 */ @@ -7240,9 +7154,9 @@ * If you are interested in writing connection handlers that contain * blocking code then see #GThreadedSocketService. * - * The socket service runs on the main loop of the thread-default - * context of the thread it is created in, and is not + * The socket service runs on the main loop of the + * [thread-default context][g-main-context-push-thread-default-context] + * of the thread it is created in, and is not * threadsafe in general. However, the calls to start and stop the * service are thread-safe so these can be used from threads that * handle incoming clients. @@ -7330,8 +7244,8 @@ * change of working directory, child setup functions, etc). * * A typical use of #GSubprocess will involve calling - * g_subprocess_new(), followed by g_subprocess_wait() or - * g_subprocess_wait_sync(). After the process exits, the status can be + * g_subprocess_new(), followed by g_subprocess_wait_async() or + * g_subprocess_wait(). After the process exits, the status can be * checked using functions such as g_subprocess_get_if_exited() (which * are similar to the familiar WIFEXITED-style POSIX macros). * @@ -7417,7 +7331,7 @@ * if (!cake_decorate (cake, decoration->frosting, decoration->message, &error)) * { * g_object_unref (cake); - * /* g_task_return_error() takes ownership of error */ + * // g_task_return_error() takes ownership of error * g_task_return_error (task, error); * g_object_unref (task); * return; @@ -7454,7 +7368,7 @@ * cake = _baker_get_cached_cake (self, radius, flavor, frosting, message); * if (cake != NULL) * { - * /* _baker_get_cached_cake() returns a reffed cake */ + * // _baker_get_cached_cake() returns a reffed cake * g_task_return_pointer (task, cake, g_object_unref); * g_object_unref (task); * return; @@ -7483,14 +7397,13 @@ * * #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). + * 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][io-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: * |[ @@ -7525,9 +7438,8 @@ * return; * } * - * /* baking_data_free() will drop its ref on the cake, so - * * we have to take another here to give to the caller. - * */ + * // baking_data_free() will drop its ref on the cake, so we have to + * // take another here to give to the caller. * g_task_return_pointer (result, g_object_ref (cake), g_object_unref); * g_object_unref (task); * } @@ -7561,7 +7473,7 @@ * * bd->cake = cake; * - * /* Bail out now if the user has already cancelled */ + * // Bail out now if the user has already cancelled * if (g_task_return_error_if_cancelled (task)) * { * g_object_unref (task); @@ -7575,9 +7487,8 @@ * GSource *source; * * source = cake_decorator_wait_source_new (cake); - * /* Attach @source to @task's GMainContext and have it call - * * decorator_ready() when it is ready. - * */ + * // Attach @source to @task's GMainContext and have it call + * // decorator_ready() when it is ready. * g_task_attach_source (task, source, * G_CALLBACK (decorator_ready)); * g_source_unref (source); @@ -7733,22 +7644,20 @@ * return; * } * - * /* If the task has already been cancelled, then we don't - * * want to add the cake to the cake cache. Likewise, we don't - * * want to have the task get cancelled in the middle of - * * updating the cache. g_task_set_return_on_cancel() will - * * return %TRUE here if it managed to disable return-on-cancel, - * * or %FALSE if the task was cancelled before it could. - * */ + * // If the task has already been cancelled, then we don't want to add + * // the cake to the cake cache. Likewise, we don't want to have the + * // task get cancelled in the middle of updating the cache. + * // g_task_set_return_on_cancel() will return %TRUE here if it managed + * // to disable return-on-cancel, or %FALSE if the task was cancelled + * // before it could. * if (g_task_set_return_on_cancel (task, FALSE)) * { - * /* If the caller cancels at this point, their - * * GAsyncReadyCallback won't be invoked until we return, - * * so we don't have to worry that this code will run at - * * the same time as that code does. But if there were - * * other functions that might look at the cake cache, - * * then we'd probably need a GMutex here as well. - * */ + * // If the caller cancels at this point, their + * // GAsyncReadyCallback won't be invoked until we return, + * // so we don't have to worry that this code will run at + * // the same time as that code does. But if there were + * // other functions that might look at the cake cache, + * // then we'd probably need a GMutex here as well. * baker_add_cake_to_cache (baker, cake); * g_task_return_pointer (task, cake, g_object_unref); * } @@ -7768,7 +7677,8 @@ * GTask *task; * * cake_data = g_slice_new (CakeData); - * /* ... */ + * + * ... * * task = g_task_new (self, cancellable, callback, user_data); * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); @@ -7790,7 +7700,8 @@ * Cake *cake; * * cake_data = g_slice_new (CakeData); - * /* ... */ + * + * ... * * task = g_task_new (self, cancellable, NULL, NULL); * g_task_set_task_data (task, cake_data, (GDestroyNotify) cake_data_free); @@ -7812,7 +7723,7 @@ * 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 + * [priority][io-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. @@ -8187,7 +8098,7 @@ * 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 + * Note that `` belongs to the UNIX-specific * GIO interfaces, thus you have to use the `gio-unix-2.0.pc` * pkg-config file when using it. * @@ -8230,7 +8141,7 @@ * 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 + * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config * file when using it. */ @@ -8253,7 +8164,7 @@ * 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 + * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config * file when using it. */ @@ -8271,7 +8182,7 @@ * 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 + * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config * file when using it. */ @@ -8284,7 +8195,7 @@ * * Routines for managing mounted UNIX mount points and paths. * - * Note that `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO + * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config * file when using it. */ @@ -8302,7 +8213,7 @@ * 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 + * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file * when using it. */ @@ -8324,7 +8235,7 @@ * 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 + * Note that `` belongs to the UNIX-specific GIO * interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file * when using it. */ @@ -8398,10 +8309,10 @@ * on the computer. In other words, what a file selector or file manager * would show in a sidebar. * - * #GVolumeMonitor is not thread-default-context - * aware, and so should not be used other than from the main - * thread, with no thread-default-context active. + * #GVolumeMonitor is not + * [thread-default-context aware][g-main-context-push-thread-default], + * and so should not be used other than from the main thread, with no + * thread-default-context active. */ @@ -8414,7 +8325,7 @@ * #GWin32InputStream implements #GInputStream for reading from a * Windows file handle. * - * Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO + * Note that `` belongs to the Windows-specific GIO * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file * when using it. */ @@ -8429,7 +8340,7 @@ * #GWin32OutputStream implements #GOutputStream for writing to a * Windows file handle. * - * Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO + * Note that `` belongs to the Windows-specific GIO * interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file * when using it. */ @@ -11202,9 +11113,8 @@ * * 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. + * 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 @@ -11803,11 +11713,11 @@ * 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. + * 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 @@ -11824,7 +11734,8 @@ * and override local_command_line(). In this case, you most likely want * to return %TRUE from your local_command_line() implementation to * suppress the default handling. See - * for an example. + * [gapplication-example-cmdline2.c][gapplication-example-cmdline2] + * for an example. * * If, after the above is done, the use count of the application is zero * then the exit status is returned immediately. If the use count is @@ -12029,8 +11940,7 @@ /** * g_async_initable_init_async: * @initable: a #GAsyncInitable. - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -12092,8 +12002,7 @@ /** * g_async_initable_new_async: * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the initialization is * finished @@ -12135,8 +12044,7 @@ * @first_property_name: the name of the first property, followed by * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the initialization is * finished @@ -12159,8 +12067,7 @@ * @object_type: a #GType supporting #GAsyncInitable. * @n_parameters: the number of parameters in @parameters * @parameters: the parameters to use to construct the object - * @io_priority: the I/O priority - * of the operation. + * @io_priority: the [I/O priority][io-priority] of the operation * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the initialization is * finished @@ -12275,8 +12182,7 @@ * g_buffered_input_stream_fill_async: * @stream: a #GBufferedInputStream * @count: the number of bytes that will be read from the stream - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer @@ -12556,9 +12462,9 @@ * * Starts acquiring @name on the bus specified by @bus_type and calls * @name_acquired_handler and @name_lost_handler when the name is - * acquired respectively lost. Callbacks will be invoked in the thread-default main - * loop of the thread you are calling this function from. + * acquired respectively lost. Callbacks will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this function from. * * 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 @@ -12600,7 +12506,7 @@ * before @name is requested from the bus. * * This behavior makes it very simple to write applications that wants - * to own names and export objects, see . + * to [own names][gdbus-owning-names] and export objects. * Simply register objects to be exported in @bus_acquired_handler and * unregister the objects (if any) in @name_lost_handler. * @@ -12702,9 +12608,9 @@ * Starts watching @name on the bus specified by @bus_type and calls * @name_appeared_handler and @name_vanished_handler when the name is * known to have a owner respectively known to lose its - * owner. Callbacks will be invoked in the thread-default main - * loop of the thread you are calling this function from. + * owner. Callbacks will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this function from. * * You are guaranteed that one of the handlers will be invoked after * calling this function. When you are done watching the name, just @@ -12723,11 +12629,11 @@ * guaranteed that the next time one of the handlers is invoked, it * will be @name_vanished_handler. The reverse is also true. * - * This behavior makes it very simple to write applications that wants - * to take action when a certain name exists, see . Basically, the application - * should create object proxies in @name_appeared_handler and destroy - * them again (if any) in @name_vanished_handler. + * This behavior makes it very simple to write applications that want + * to take action when a certain [name exists][gdbus-watching-names]. + * Basically, the application should create object proxies in + * @name_appeared_handler and destroy them again (if any) in + * @name_vanished_handler. * * Returns: An identifier (never 0) that an be used with * g_bus_unwatch_name() to stop watching the name. @@ -13698,8 +13604,7 @@ /** * g_data_input_stream_read_line_async: * @stream: a given #GDataInputStream. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -13867,8 +13772,7 @@ * g_data_input_stream_read_until_async: * @stream: a given #GDataInputStream. * @stop_chars: characters to terminate the read. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -13946,8 +13850,7 @@ * @stop_chars: characters to terminate the read * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is * nul-terminated - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -14448,8 +14351,9 @@ * NULL); * ]| * - * This is an asynchronous method. When the operation is finished, @callback will be invoked - * in the thread-default main loop + * This is an asynchronous method. When the operation is finished, + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can then call * g_dbus_connection_call_finish() to get the result of the operation. * See g_dbus_connection_call_sync() for the synchronous version of this @@ -14631,14 +14535,14 @@ * %G_IO_ERROR_CLOSED. * * When @connection has been closed, the #GDBusConnection::closed - * signal is emitted in the thread-default main - * loop of the thread that @connection was constructed in. + * signal is emitted in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @connection was constructed in. * * 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 + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * 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 * version. @@ -14775,9 +14679,9 @@ * 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 + * @callback will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * 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 * version. @@ -15101,9 +15005,10 @@ * Registers callbacks for exported objects at @object_path with the * D-Bus interface that is described in @interface_info. * - * Calls to functions in @vtable (and @user_data_free_func) will - * happen in the thread-default main - * loop of the thread you are calling this method from. + * Calls to functions in @vtable (and @user_data_free_func) will happen + * in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * Note that all #GVariant values passed to functions in @vtable will match * the signature given in @interface_info - if a remote caller passes @@ -15134,7 +15039,7 @@ * reference count is -1, see g_dbus_interface_info_ref()) for as long * as the object is exported. Also note that @vtable will be copied. * - * See for an example of how to use this method. + * See this [server][gdbus-server] for an example of how to use this method. * * Returns: 0 if @error is set, otherwise a registration id (never 0) * that can be used with g_dbus_connection_unregister_object() @@ -15168,9 +15073,9 @@ * #gpointer will be used to call into the interface vtable for processing * the request. * - * All calls into user-provided code will be invoked in the thread-default main - * loop of the thread you are calling this method from. + * All calls into user-provided code will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * If an existing subtree is already registered at @object_path or * then @error is set to #G_IO_ERROR_EXISTS. @@ -15185,7 +15090,8 @@ * Note that @vtable will be copied so you cannot change it after * registration. * - * See for an example of how to use this method. + * See this [server][gdbus-subtree-server] for an example of how to use + * this method. * * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) * that can be used with g_dbus_connection_unregister_subtree() . @@ -15226,9 +15132,9 @@ * %G_IO_ERROR_CLOSED. If @message is not well-formed, * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. @@ -15267,8 +15173,9 @@ * fail with %G_IO_ERROR_CANCELLED. If @message is not well-formed, * the operation fails with %G_IO_ERROR_INVALID_ARGUMENT. * - * This is an asynchronous method. When the operation is finished, @callback will be invoked - * in the thread-default main loop + * This is an asynchronous method. When the operation is finished, @callback + * will be invoked in the + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can then call * g_dbus_connection_send_message_with_reply_finish() to get the result of the operation. * See g_dbus_connection_send_message_with_reply_sync() for the synchronous version. @@ -15276,9 +15183,9 @@ * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Since: 2.26 */ @@ -15298,9 +15205,9 @@ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use * g_dbus_message_to_gerror() to transcode this to a #GError. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][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 * Since: 2.26 @@ -15341,9 +15248,9 @@ * be of type %G_DBUS_MESSAGE_TYPE_ERROR. Use * g_dbus_message_to_gerror() to transcode this to a #GError. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. @@ -15394,11 +15301,10 @@ * @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. + * 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 context][g-main-context-push-thread-default] + * of the thread you are calling this method from. * * If @connection is not a message bus connection, @sender must be * %NULL. @@ -15697,69 +15603,29 @@ /** * g_dbus_gvalue_to_gvariant: - * @gvalue: A #GValue to convert to a #GVariant. - * @type: A #GVariantType. + * @gvalue: A #GValue to convert to a #GVariant + * @type: A #GVariantType * - * Converts a #GValue to a #GVariant of the type indicated by the @type parameter. + * Converts a #GValue to a #GVariant of the type indicated by the @type + * parameter. * * The conversion is using the following rules: - * - * #GValue / #GVariant conversion rules - * - * - * - * If the #GType for @gvalue is... - * ... then @type must be - * - * - * - * - * #G_TYPE_STRING - * 's', 'o', 'g' or 'ay' - * - * - * #G_TYPE_STRV - * 'as', 'ao' or 'aay' - * - * - * #G_TYPE_BOOLEAN - * 'b' - * - * - * #G_TYPE_UCHAR - * 'y' - * - * - * #G_TYPE_INT - * 'i' or 'n' - * - * - * #G_TYPE_UINT - * 'u' or 'q' - * - * - * #G_TYPE_INT64 - * 'x' - * - * - * #G_TYPE_UINT64 - * 't' - * - * - * #G_TYPE_DOUBLE - * 'd' - * - * - * #G_TYPE_VARIANT - * Any #GVariantType - * - * - * - *
+ * + * - #G_TYPE_STRING: 's', 'o', 'g' or 'ay' + * - #G_TYPE_STRV: 'as', 'ao' or 'aay' + * - #G_TYPE_BOOLEAN: 'b' + * - #G_TYPE_UCHAR: 'y' + * - #G_TYPE_INT: 'i', 'n' + * - #G_TYPE_UINT: 'u', 'q' + * - #G_TYPE_INT64 'x' + * - #G_TYPE_UINT64: 't' + * - #G_TYPE_DOUBLE: 'd' + * - #G_TYPE_VARIANT: Any #GVariantType + * * This can fail if e.g. @gvalue is of type #G_TYPE_STRING and @type - * is 'i'. It will - * also fail for any #GType (including e.g. #G_TYPE_OBJECT and - * #G_TYPE_BOXED derived-types) not in the table above. + * is ['i'][G-VARIANT-TYPE-INT32:CAPS]. It will also fail for any #GType + * (including e.g. #G_TYPE_OBJECT and #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 @@ -15769,9 +15635,9 @@ * See the g_dbus_gvariant_to_gvalue() function for how to convert a * #GVariant to a #GValue. * - * Returns: A #GVariant (never floating) of #GVariantType - * @type holding the data from @gvalue or %NULL in case of - * failure. Free with g_variant_unref(). + * Returns: A #GVariant (never floating) of #GVariantType @type holding + * the data from @gvalue or %NULL in case of failure. Free with + * g_variant_unref(). * Since: 2.30 */ @@ -16069,7 +15935,9 @@ * * Gets all D-Bus properties for @interface_. * - * Returns: (transfer full): A #GVariant of type 'a{sv}'. Free with g_variant_unref(). + * Returns: (transfer full): A #GVariant of type + * ['a{sv}'][G-VARIANT-TYPE-VARDICT:CAPS]. + * Free with g_variant_unref(). * Since: 2.30 */ @@ -16943,9 +16811,9 @@ * descriptor passing, that cannot be properly expressed in the * #GVariant API. * - * See and for an example of how to use this - * low-level API to send and receive UNIX file descriptors. + * See this [server][gdbus-server] and [client][gdbus-unix-fd-client] + * for an example of how to use this low-level API to send and receive + * UNIX file descriptors. * * Returns: (transfer none): #GDBusMessage. Do not free, it is owned by @invocation. * Since: 2.26 @@ -17215,10 +17083,10 @@ * Parses @xml_data and returns a #GDBusNodeInfo representing the data. * * The introspection XML must contain exactly one top-level - * <node> element. + * element. * * Note that this routine is using a - * GMarkup-based + * [GMarkup][glib-Simple-XML-Subset-Parser.description]-based * parser that only accepts a subset of valid XML documents. * * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free @@ -17358,7 +17226,7 @@ * * This is an asynchronous failable constructor. When the result is * ready, @callback will be invoked in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. You can * then call g_dbus_object_manager_client_new_finish() to get the result. See * g_dbus_object_manager_client_new_sync() for the synchronous version. @@ -17399,7 +17267,7 @@ * * This is an asynchronous failable constructor. When the result is * ready, @callback will be invoked in the - * thread-default main loop + * [thread-default main loop][g-main-context-push-thread-default] * of the thread you are calling this method from. You can * then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See * g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. @@ -17800,7 +17668,7 @@ * * This is an asynchronous method. When the operation is finished, * @callback will be invoked in the - * thread-default main loop + * [thread-default main context][g-main-context-push-thread-default] * of the thread you are calling this method from. * You can then call g_dbus_proxy_call_finish() to get the result of * the operation. See g_dbus_proxy_call_sync() for the synchronous @@ -18105,7 +17973,7 @@ * * See g_dbus_proxy_new_sync() and for a synchronous version of this constructor. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -18137,7 +18005,7 @@ * * Like g_dbus_proxy_new() but takes a #GBusType instead of a #GDBusConnection. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Since: 2.26 */ @@ -18169,7 +18037,7 @@ * * Like g_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 @@ -18204,7 +18072,7 @@ * This is a synchronous failable constructor. See g_dbus_proxy_new() * and g_dbus_proxy_new_finish() for the asynchronous version. * - * See for an example of how #GDBusProxy can be used. + * #GDBusProxy is used in this [example][gdbus-wellknown-proxy]. * * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref(). * Since: 2.26 @@ -18350,8 +18218,7 @@ * The returned #GDBusServer isn't active - you have to start it with * g_dbus_server_start(). * - * See for how #GDBusServer can - * be used. + * #GDBusServer is used in this [example][gdbus-peer-to-peer]. * * This is a synchronous failable constructor. See * g_dbus_server_new() for the asynchronous version. @@ -19240,8 +19107,7 @@ * g_file_append_to_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -19405,20 +19271,15 @@ * The wildcard "*" may be used to match all keys and namespaces, or * "namespace::*" will match all keys in a given namespace. * - * Examples of strings to use: - * - * File Attribute Matcher strings and results - * - * Matcher String Matches - * - * "*"matches all attributes. - * "standard::is-hidden"matches only the key is-hidden in the standard namespace. - * "standard::type,unix::*"matches the type key in the standard namespace and - * all keys in the unix namespace. - * - *
+ * ## Examples of file attribute matcher strings and results * - * Returns: a #GFileAttributeMatcher. + * - `"*"`: matches all attributes. + * - `"standard::is-hidden"`: matches only the key is-hidden in the + * standard namespace. + * - `"standard::type,unix::*"`: matches the type key in the standard + * namespace and all keys in the unix namespace. + * + * Returns: a #GFileAttributeMatcher */ @@ -19533,8 +19394,7 @@ * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @progress_callback: (allow-none): function to callback with progress @@ -19628,8 +19488,7 @@ * g_file_create_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -19705,8 +19564,7 @@ * g_file_create_readwrite_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -19763,8 +19621,7 @@ /** * g_file_delete_async: (virtual delete_file_async) * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -19940,8 +19797,7 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call when the @@ -19996,8 +19852,7 @@ /** * g_file_enumerator_close_async: * @enumerator: a #GFileEnumerator. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -20113,8 +19968,7 @@ * g_file_enumerator_next_files_async: * @enumerator: a #GFileEnumerator. * @num_files: the number of file info objects to request - * @io_priority: the io priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -20209,8 +20063,7 @@ /** * g_file_find_enclosing_mount_async: * @file: a #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -20512,7 +20365,7 @@ * @src_info: source to copy attributes from. * @dest_info: destination to copy attributes to. * - * Copies all of the GFileAttributes + * Copies all of the [GFileAttribute][gio-GFileAttribute] * from @src_info to @dest_info. */ @@ -20744,7 +20597,7 @@ * g_file_info_get_etag: * @info: a #GFileInfo. * - * Gets the entity tag for a given + * Gets the [entity tag][gfile-etag] for a given * #GFileInfo. See %G_FILE_ATTRIBUTE_ETAG_VALUE. * * Returns: a string containing the value of the "etag:value" attribute. @@ -21064,7 +20917,7 @@ /** * g_file_info_set_content_type: * @info: a #GFileInfo. - * @content_type: a content type. See GContentType. + * @content_type: a content type. See [GContentType][gio-GContentType] * * Sets the content type attribute for a given #GFileInfo. * See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. @@ -21224,8 +21077,7 @@ * g_file_input_stream_query_info_async: * @stream: a #GFileInputStream. * @attributes: a file attribute query string. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21304,8 +21156,7 @@ * g_file_io_stream_query_info_async: * @stream: a #GFileIOStream. * @attributes: a file attribute query string. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -21499,8 +21350,7 @@ /** * g_file_make_directory_async: (virtual make_directory_async) * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -21614,8 +21464,7 @@ * g_file_measure_disk_usage_async: * @file: a #GFile * @flags: #GFileMeasureFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable * @progress_callback: (allow-none): a #GFileMeasureProgressCallback * @progress_data: user_data for @progress_callback @@ -21720,9 +21569,8 @@ * has taken place. Should be called from file monitor * implementations only. * - * The signal will be emitted from an idle handler (in the thread-default main - * context). + * The signal will be emitted from an idle handler (in the + * [thread-default main context][g-main-context-push-thread-default]). */ @@ -22042,8 +21890,7 @@ /** * g_file_open_readwrite_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -22123,8 +21970,7 @@ * g_file_output_stream_query_info_async: * @stream: a #GFileOutputStream. * @attributes: a file attribute query string. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][gio-GIOScheduler] of the request * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -22318,8 +22164,7 @@ * g_file_query_filesystem_info_async: * @file: input #GFile * @attributes: an attribute query string - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -22405,8 +22250,7 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call when the @@ -22511,8 +22355,7 @@ /** * g_file_read_async: * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -22547,7 +22390,7 @@ /** * g_file_replace: * @file: input #GFile - * @etag: (allow-none): an optional entity tag + * @etag: (allow-none): an optional [entity tag][gfile-etag] * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -22605,12 +22448,11 @@ /** * g_file_replace_async: * @file: input #GFile - * @etag: (allow-none): an entity tag - * for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -22634,11 +22476,11 @@ * @file: input #GFile * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @length: the length of @contents in bytes - * @etag: (allow-none): the old entity tag - * for the document, or %NULL + * @etag: (allow-none): the old [entity-tag][gfile-etag] for the document, + * or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @new_etag: (allow-none) (out): a location to a new entity tag + * @new_etag: (allow-none) (out): a location to a new [entity tag][gfile-etag] * for the document. This should be freed with g_free() when no longer * needed, or %NULL * @cancellable: optional #GCancellable object, %NULL to ignore @@ -22669,7 +22511,7 @@ * @file: input #GFile * @contents: (element-type guint8) (array length=length): string of contents to replace the file with * @length: the length of @contents in bytes - * @etag: (allow-none): a new entity tag for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -22702,7 +22544,7 @@ * g_file_replace_contents_bytes_async: * @file: input #GFile * @contents: a #GBytes - * @etag: (allow-none): a new entity tag for the @file, or %NULL + * @etag: (allow-none): a new [entity tag][gfile-etag] for the @file, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags * @cancellable: optional #GCancellable object, %NULL to ignore @@ -22726,7 +22568,7 @@ * g_file_replace_contents_finish: * @file: input #GFile * @res: a #GAsyncResult - * @new_etag: (out) (allow-none): a location of a new entity tag + * @new_etag: (out) (allow-none): a location of a new [entity tag][gfile-etag] * for the document. This should be freed with g_free() when it is no * longer needed, or %NULL * @error: a #GError, or %NULL @@ -22756,7 +22598,7 @@ /** * g_file_replace_readwrite: * @file: a #GFile - * @etag: (allow-none): an optional entity tag + * @etag: (allow-none): an optional [entity tag][gfile-etag] * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags @@ -22784,12 +22626,11 @@ /** * g_file_replace_readwrite_async: * @file: input #GFile - * @etag: (allow-none): an entity tag - * for the current #GFile, or NULL to ignore + * @etag: (allow-none): an [entity tag][gfile-etag] for the current #GFile, + * or %NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -23002,8 +22843,7 @@ * @file: input #GFile * @info: a #GFileInfo * @flags: a #GFileQueryInfoFlags - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback @@ -23093,8 +22933,7 @@ * g_file_set_display_name_async: * @file: input #GFile * @display_name: a string - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback to call @@ -23215,11 +23054,10 @@ * g_file_supports_thread_contexts: * @file: a #GFile * - * Checks if @file supports thread-default - * contexts. If this returns %FALSE, you cannot perform - * asynchronous operations on @file in a thread that has a - * thread-default context. + * Checks if @file supports + * [thread-default contexts][g-main-context-push-thread-default-context]. + * If this returns %FALSE, you cannot perform asynchronous operations on + * @file in a thread that has a thread-default context. * * Returns: Whether or not @file supports thread-default contexts. * Since: 2.22 @@ -23249,8 +23087,7 @@ /** * g_file_trash_async: (virtual trash_async) * @file: input #GFile - * @io_priority: the I/O priority - * of the request + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, * %NULL to ignore * @callback: a #GAsyncReadyCallback to call @@ -23549,7 +23386,7 @@ * (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`). + * (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`). @@ -23944,6 +23781,22 @@ */ +/** + * g_inet_socket_address_new_from_string: + * @address: the string form of an IP address + * @port: a port number + * + * Creates a new #GInetSocketAddress for @address and @port. + * + * If @address is an IPv6 address, it can also contain a scope ID + * (separated from the address by a "%"). + * + * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be + * parsed. + * Since: 2.40 + */ + + /** * g_initable_init: * @initable: a #GInitable. @@ -23966,8 +23819,7 @@ * If the object is not initialized, or initialization returns with an * error, then all operations on the object except g_object_ref() and * g_object_unref() are considered to be invalid, and have undefined - * behaviour. See the section introduction - * for more details. + * behaviour. See the [introduction][ginitable] for more details. * * Implementations of this method must be idempotent, i.e. multiple calls * to this function with the same argument should return the same results. @@ -24096,8 +23948,7 @@ /** * g_input_stream_close_async: * @stream: A #GInputStream. - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional cancellable object * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -24214,7 +24065,7 @@ * @buffer: (array length=count) (element-type guint8): a buffer to * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream - * @io_priority: the I/O priority + * @io_priority: the [I/O priority][io-priority] * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied @@ -24286,8 +24137,7 @@ * g_input_stream_read_bytes_async: * @stream: A #GInputStream. * @count: the number of bytes that will be read from the stream - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -24385,8 +24235,7 @@ * g_input_stream_skip_async: * @stream: A #GInputStream. * @count: the number of bytes that will be skipped from the stream - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -24779,7 +24628,7 @@ * @job_func: a #GIOSchedulerJobFunc. * @user_data: data to pass to @job_func * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the I/O priority + * @io_priority: the [I/O priority][io-priority] * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @@ -25241,13 +25090,13 @@ * allocation for itself). * * |[ - * /* a stream that can grow */ + * // a stream that can grow * stream = g_memory_output_stream_new (NULL, 0, realloc, free); * - * /* another stream that can grow */ + * // another stream that can grow * stream2 = g_memory_output_stream_new (NULL, 0, g_realloc, g_free); * - * /* a fixed-size stream */ + * // a fixed-size stream * data = malloc (200); * stream3 = g_memory_output_stream_new (data, 200, NULL, free); * ]| @@ -26042,7 +25891,7 @@ * g_variant_get(), followed by a g_variant_unref(). As such, * @format_string must make a complete copy of the data (since the * #GVariant may go away after the call to g_variant_unref()). In - * particular, no '&' characters are allowed in @format_string. + * particular, no '&' characters are allowed in @format_string. * * Returns: %TRUE if the named attribute was found with the expected * type @@ -28508,8 +28357,8 @@ * * 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 + * the form `://[user[:password]@]host:port` or + * `direct://`, where could be http, rtsp, socks * or other proxying protocol. * * If you don't know what network protocol is being used on the @@ -29665,7 +29514,7 @@ * @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 element. * * Returns: (transfer full): a 'child' settings object * Since: 2.26 @@ -30484,8 +30333,7 @@ * may be useful to authors of plugin management systems. * * The directory should contain a file called `gschemas.compiled` as - * produced by the - * glib-compile-schemas tool. + * produced by the [glib-compile-schemas][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 @@ -30978,9 +30826,9 @@ * g_simple_async_result_complete_in_idle: * @simple: a #GSimpleAsyncResult. * - * Completes an asynchronous function in an idle handler in the thread-default main - * loop of the thread that @simple was initially created in + * Completes an asynchronous function in an idle handler in the + * [thread-default main context][g-main-context-push-thread-default] + * of the thread that @simple was initially created in * (and re-pushes that context around the invocation of the callback). * * Calling this function takes a reference to @simple for as long as @@ -31032,8 +30880,8 @@ /** * g_simple_async_result_is_valid: * @result: the #GAsyncResult passed to the _finish function. - * @source: the #GObject passed to the _finish function. - * @source_tag: the asynchronous function. + * @source: (allow-none): the #GObject passed to the _finish function. + * @source_tag: (allow-none): the asynchronous function. * * Ensures that the data passed to the _finish function of an async * operation is consistent. Three checks are performed. @@ -31041,12 +30889,12 @@ * First, @result is checked to ensure that it is really a * #GSimpleAsyncResult. Second, @source is checked to ensure that it * matches the source object of @result. Third, @source_tag is - * checked to ensure that it is either %NULL (as it is when the result was - * created by g_simple_async_report_error_in_idle() or - * g_simple_async_report_gerror_in_idle()) or equal to the - * @source_tag argument given to g_simple_async_result_new() (which, by - * convention, is a pointer to the _async function corresponding to the - * _finish function from which this function is called). + * checked to ensure that it is equal to the @source_tag argument given + * to g_simple_async_result_new() (which, by convention, is a pointer + * to the _async function corresponding to the _finish function from + * which this function is called). (Alternatively, if either + * @source_tag or @result's source tag is %NULL, then the source tag + * check is skipped.) * * Returns: #TRUE if all checks passed or #FALSE if any failed. * Since: 2.20 @@ -32711,7 +32559,7 @@ * 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 @@ -33514,6 +33362,12 @@ * This call is thread-safe, so it may be called from a thread * handling an incoming client request. * + * Note that this only stops accepting new connections; it does not + * close the listening sockets, and you can call + * g_socket_service_start() again later to begin listening again. To + * close the listening sockets, call g_socket_listener_close(). (This + * will happen automatically when the #GSocketService is finalized.) + * * Since: 2.22 */ @@ -33630,7 +33484,7 @@ * 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 @@ -33837,7 +33691,7 @@ * Finalized a GResource initialized by g_static_resource_init(). * * This is normally used by code generated by - * glib-compile-resources + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Since: 2.32 @@ -33851,7 +33705,7 @@ * Gets the GResource that was registered by a call to g_static_resource_init(). * * This is normally used by code generated by - * glib-compile-resources + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Returns: (transfer none): a #GResource @@ -33867,7 +33721,7 @@ * GStaticResource. * * This is normally used by code generated by - * glib-compile-resources + * [glib-compile-resources][glib-compile-resources] * and is not typically used by other code. * * Since: 2.32 @@ -34669,9 +34523,8 @@ * * A utility function for dealing with async operations where you need * 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`. + * #GMainContext with @task's [priority][io-priority], and sets @source's + * callback to @callback, with @task as the callback's `user_data`. * * This takes a reference on @task until @source is destroyed. * @@ -34706,9 +34559,9 @@ * @task: a #GTask * * Gets the #GMainContext that @task will return its result in (that - * is, the context that was the thread-default main - * context at the point when @task was created). + * is, the context that was the + * [thread-default main context][g-main-context-push-thread-default] + * at the point when @task was created). * * This will always return a non-%NULL value, even if the task's * context is the default #GMainContext. @@ -34810,9 +34663,8 @@ * @callback_data: (closure): user data passed to @callback. * * Creates a #GTask acting on @source_object, which will eventually be - * used to invoke @callback in the current thread-default main - * context. + * used to invoke @callback in the current + * [thread-default main context][g-main-context-push-thread-default]. * * Call this in the "start" method of your asynchronous method, and * pass the #GTask around throughout the asynchronous operation. You @@ -35108,8 +34960,7 @@ /** * g_task_set_priority: * @task: the #GTask - * @priority: the priority - * of the request. + * @priority: the [priority][io-priority] of the request * * Sets @task's priority. If you do not call this, it will default to * %G_PRIORITY_DEFAULT. @@ -35912,8 +35763,7 @@ /** * g_tls_connection_handshake_async: * @conn: a #GTlsConnection - * @io_priority: the I/O priority - * of the request. + * @io_priority: the [I/O priority][io-priority] of the request * @cancellable: (allow-none): a #GCancellable, or %NULL * @callback: callback to call when the handshake is complete * @user_data: the data to pass to the callback function @@ -37927,9 +37777,8 @@ * g_volume_enumerate_identifiers: * @volume: a #GVolume * - * Gets the kinds of identifiers - * that @volume has. Use g_volume_get_identifier() to obtain - * the identifiers themselves. + * Gets the kinds of [identifiers][volume-identifier] that @volume has. + * Use g_volume_get_identifier() to obtain the identifiers themselves. * * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array * of strings containing kinds of identifiers. Use g_strfreev() to free. @@ -37952,9 +37801,9 @@ * GFile *mount_root * GFile *volume_activation_root; * - * mount = g_volume_get_mount (volume); /* mounted, so never NULL */ + * 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 * |[ @@ -38003,8 +37852,8 @@ * @kind: the kind of identifier to return * * Gets the identifier of the given kind for @volume. - * See the introduction - * for more information about volume identifiers. + * See the [introduction][volume-identifier] for more + * information about volume identifiers. * * Returns: a newly allocated string containing the * requested identfier, or %NULL if the #GVolume diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index a68339e5..31029d81 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -138,7 +138,7 @@ * value comes before the second, 0 if they are equal, or a positive * integer if the first value comes after the second. * - * Returns: negative value if @a < @b; zero if @a = @b; positive + * Returns: negative value if @a < @b; zero if @a = @b; positive * value if @a > @b */ @@ -153,7 +153,7 @@ * value comes before the second, 0 if they are equal, or a positive * integer if the first value comes after the second. * - * Returns: negative value if @a < @b; zero if @a = @b; positive + * Returns: negative value if @a < @b; zero if @a = @b; positive * value if @a > @b */ @@ -232,9 +232,9 @@ /** * GData: * - * The #GData struct is an opaque data structure to represent a Keyed Data List. It should - * only be accessed via the following functions. + * The #GData struct is an opaque data structure to represent a + * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be + * accessed via the following functions. */ @@ -618,8 +618,8 @@ * GHashTable: * * The #GHashTable struct is an opaque data structure to represent a - * Hash Table. It should only be - * accessed via the following functions. + * [Hash Table][glib-Hash-Tables]. It should only be accessed via the + * following functions. */ @@ -681,7 +681,7 @@ * Defines the type of function used to compare #GHook elements in * g_hook_insert_sorted(). * - * Returns: a value <= 0 if @new_hook should be before @sibling + * Returns: a value <= 0 if @new_hook should be before @sibling */ @@ -1203,9 +1203,8 @@ /** * GList: * @data: holds the element's data, which can be a pointer to any kind - * of data, or any integer value using the Type Conversion - * Macros. + * of data, or any integer value using the + * [Type Conversion Macros][glib-Type-Conversion-Macros] * @next: contains the link to the next element in the list * @prev: contains the link to the previous element in the list * @@ -1309,9 +1308,8 @@ * { * 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; @@ -1358,8 +1356,7 @@ * children are accessed by using the @next pointer of each * child. * - * The #GNode struct represents one node in a - * N-ary Tree. fields + * The #GNode struct represents one node in a [n-ary tree][glib-N-ary-Trees]. */ @@ -1642,9 +1639,8 @@ /** * GSList: * @data: holds the element's data, which can be a pointer to any kind - * of data, or any integer value using the Type Conversion - * Macros. + * of data, or any integer value using the + * [Type Conversion Macros][glib-Type-Conversion-Macros] * @next: contains the link to the next element in the list. * * The #GSList struct is used for each element in the singly-linked @@ -1818,7 +1814,7 @@ * GSequence: * * The #GSequence struct is an opaque data type representing a - * Sequence data type. + * [sequence][glib-Sequences] data type. */ @@ -2218,59 +2214,35 @@ * then its right child. This is the one to use if you * want the output sorted according to the compare * function. - * - * - * - * - * - * In order: A, B, C, D, E, F, G, H, I - * - * * @G_PRE_ORDER: visits a node, then its children. - * - * - * - * - * - * Pre order: F, B, A, D, C, E, G, I, H - * - * * @G_POST_ORDER: visits the node's children, then the node itself. - * - * - * - * - * - * Post order: A, C, E, D, B, H, I, G, F - * - * - * @G_LEVEL_ORDER: is not implemented for Balanced Binary - * Trees. For N-ary Trees, it - * vists the root node first, then its children, then - * its grandchildren, and so on. Note that this is less - * efficient than the other orders. - * - * - * - * - * - * Level order: F, B, G, A, D, I, C, E, H - * - * + * @G_LEVEL_ORDER: is not implemented for + * [balanced binary trees][glib-Balanced-Binary-Trees]. + * For [n-ary trees][glib-N-ary-Trees], it + * vists the root node first, then its children, then + * its grandchildren, and so on. Note that this is less + * efficient than the other orders. * * Specifies the type of traveral performed by g_tree_traverse(), - * g_node_traverse() and g_node_find(). + * g_node_traverse() and g_node_find(). The different orders are + * illustrated here: + * - In order: A, B, C, D, E, F, G, H, I + * ![](Sorted_binary_tree_inorder.svg) + * - Pre order: F, B, A, D, C, E, G, I, H + * ![](Sorted_binary_tree_preorder.svg) + * - Post order: A, C, E, D, B, H, I, G, F + * ![](Sorted_binary_tree_postorder.svg) + * - Level order: F, B, G, A, D, I, C, E, H + * ![](Sorted_binary_tree_breadth-first_traversal.svg) */ /** * 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][glib-Balanced-Binary-Trees]. It should be + * accessed only by using the following functions. */ @@ -2650,9 +2622,9 @@ * key is not found. Each returns the new dictionary as a floating * #GVariant. * - * - * Using stack-allocated #GVariantDict - * + * ## Using a stack-allocated GVariantDict + * + * |[ * GVariant * * add_to_count (GVariant *orig, * GError **error) @@ -2660,24 +2632,23 @@ * GVariantDict dict; * guint32 count; * - * g_variant_dict_init (&dict, orig); - * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) + * g_variant_dict_init (&dict, orig); + * if (!g_variant_dict_lookup (&dict, "count", "u", &count)) * { * g_set_error (...); - * g_variant_dict_clear (&dict); + * g_variant_dict_clear (&dict); * return NULL; * } * - * g_variant_dict_insert (&dict, "count", "u", count + 1); + * g_variant_dict_insert (&dict, "count", "u", count + 1); * - * return g_variant_dict_end (&dict); + * return g_variant_dict_end (&dict); * } - * - * + * ]| + * + * ## Using heap-allocated GVariantDict * - * - * Using heap-allocated #GVariantDict - * + * |[ * GVariant * * add_to_count (GVariant *orig, * GError **error) @@ -2688,7 +2659,7 @@ * * dict = g_variant_dict_new (orig); * - * if (g_variant_dict_lookup (dict, "count", "u", &count)) + * if (g_variant_dict_lookup (dict, "count", "u", &count)) * { * g_variant_dict_insert (dict, "count", "u", count + 1); * result = g_variant_dict_end (dict); @@ -2703,8 +2674,7 @@ * * return result; * } - * - * + * ]| * * Since: 2.40 */ @@ -3593,7 +3563,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. */ @@ -4338,7 +4308,7 @@ * G_OS_UNIX: * * This macro is defined only on UNIX. So you can bracket - * UNIX-specific code in "#ifdef G_OS_UNIX". + * UNIX-specific code in "\#ifdef G_OS_UNIX". */ @@ -4346,7 +4316,7 @@ * G_OS_WIN32: * * This macro is defined only on Windows. So you can bracket - * Windows-specific code in "#ifdef G_OS_WIN32". + * Windows-specific code in "\#ifdef G_OS_WIN32". */ @@ -4428,7 +4398,7 @@ * |[ * 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) * { @@ -4442,7 +4412,7 @@ * } * * - * static GPrivate count_key; /* no free function */ + * static GPrivate count_key; // no free function * * gint * get_local_count (void) @@ -4918,9 +4888,8 @@ * |[ * 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++) * g_array_append_val (garray, i); @@ -5153,11 +5122,11 @@ * 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 + * root element; each bookmark is stored inside a + * 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 + * 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 @@ -5260,16 +5229,16 @@ * 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() or from g_dir_read_name(), and you wish @@ -5286,21 +5255,20 @@ * encoding for their strings, and that is also what they use for * 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 - * encoding for file names in the `G_FILENAME_ENCODING` + * 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 encoding for + * file names in the [`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. - * illustrates how + * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This + * [diagram][file-name-encodings-diagram] illustrates how * these functions are used to convert between UTF-8 and the * encoding for file names in the file system. * @@ -5547,14 +5515,14 @@ * g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL)); * if (err != NULL) * { - * /* Report error to user, and free error */ + * // Report error to user, and free error * g_assert (contents == NULL); * fprintf (stderr, "Unable to read file: %s\n", err->message); * g_error_free (err); * } * else * { - * /* Use file contents */ + * // Use file contents * g_assert (contents != NULL); * } * ]| @@ -5567,10 +5535,12 @@ * 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 */ - * /* no error occurred */ ; + * if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) // ignore errors + * // no error occurred + * ; * else - * /* error */ ; + * // error + * ; * ]| * * The #GError object contains three fields: @domain indicates the module @@ -5603,9 +5573,9 @@ * 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 */ + * FOO_ERROR, // error domain + * FOO_ERROR_BLAH, // error code + * "Failed to open file: %s", // error message format string * g_strerror (errno)); * return -1; * } @@ -5626,12 +5596,12 @@ * * if (!sub_function_that_can_fail (err)) * { - * /* assert that error was set by the sub-function */ + * // assert that error was set by the sub-function * g_assert (err == NULL || *err != NULL); * return FALSE; * } * - * /* otherwise continue, no error occurred */ + * // otherwise continue, no error occurred * g_assert (err == NULL || *err == NULL); * } * ]| @@ -5653,14 +5623,13 @@ * * if (tmp_error != NULL) * { - * /* store tmp_error in err, if err != NULL, - * * otherwise call g_error_free() on tmp_error - * */ + * // store tmp_error in err, if err != NULL, + * // otherwise call g_error_free() on tmp_error * g_propagate_error (err, tmp_error); * return FALSE; * } * - * /* otherwise continue, no error occurred */ + * // otherwise continue, no error occurred * } * ]| * @@ -5700,7 +5669,7 @@ * * g_return_val_if_fail (err == NULL || *err == NULL, FALSE); * - * sub_function_that_can_fail (NULL); /* ignore errors */ + * sub_function_that_can_fail (NULL); // ignore errors * * tmp_error = NULL; * other_function_that_can_fail (&tmp_error); @@ -5721,7 +5690,7 @@ * * Error domains and codes are conventionally named as follows: * - * - The error domain is called <NAMESPACE>_<MODULE>_ERROR, + * - The error domain is called __ERROR, * for example %G_SPAWN_ERROR or %G_THREAD_ERROR: * |[ * #define G_SPAWN_ERROR g_spawn_error_quark () @@ -5734,20 +5703,20 @@ * ]| * * - The quark function for the error domain is called - * <namespace>_<module>_error_quark, + * __error_quark, * for example g_spawn_error_quark() or g_thread_error_quark(). * * - The error codes are in an enumeration called - * <Namespace><Module>Error; - * for example,#GThreadError or #GSpawnError. + * Error; + * for example, #GThreadError or #GSpawnError. * * - Members of the error code enumeration are called - * <NAMESPACE>_<MODULE>_ERROR_<CODE>, + * __ERROR_, * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN. * * - 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 __ERROR_FAILED, * for example %G_SPAWN_ERROR_FAILED. * * Summary of rules for use of #GError: @@ -5787,8 +5756,22 @@ * g_set_error() will complain if you pile up errors. * * - By convention, if you return a boolean value indicating success - * then %TRUE means success and %FALSE means failure. If %FALSE is + * then %TRUE means success and %FALSE means failure. + * Avoid creating functions which have a boolean + * return value and a GError parameter, but where the boolean does + * something other than signal whether the GError is set. Among other + * problems, it requires C callers to allocate a temporary error. Instead, + * provide a "gboolean *" out parameter. There are functions in GLib + * itself such as g_key_file_has_key() that are deprecated because of this. + * + * If %FALSE is * returned, the error must be set to a non-%NULL value. + * One exception to this is that in situations that are + * already considered to be undefined behaviour (such as when a + * g_return_val_if_fail() check fails), the error need not be set. + * Instead of checking separately whether the error is set, callers + * should ensure that they do not provoke undefined behaviour, then + * assume that the error will be set on failure. * * - A %NULL return value is also frequently used to mean that an error * occurred. You should make clear in your documentation whether %NULL @@ -5855,7 +5838,7 @@ * SECTION:gregex * @title: Perl-compatible regular expressions * @short_description: matches strings against regular expressions - * @see_also: + * @see_also: [Regular expression syntax][glib-regex-syntax] * * The g_regex_*() functions implement regular * expression pattern matching using syntax and semantics similar to @@ -6076,9 +6059,10 @@ * 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. + * 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 * @@ -6265,311 +6249,53 @@ * "a(aa(ui)(qna{ya(yd)}))". * * The meaning of each of the characters is as follows: - * - * - * - * - * - * - * Character - * - * - * - * - * Meaning - * - * - * - * - * - * - * b - * - * - * - * - * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. - * - * - * - * - * - * - * y - * - * - * - * - * the type string of %G_VARIANT_TYPE_BYTE; a byte. - * - * - * - * - * - * - * n - * - * - * - * - * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit - * integer. - * - * - * - * - * - * - * q - * - * - * - * - * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit - * integer. - * - * - * - * - * - * - * i - * - * - * - * - * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit - * integer. - * - * - * - * - * - * - * u - * - * - * - * - * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit - * integer. - * - * - * - * - * - * - * x - * - * - * - * - * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit - * integer. - * - * - * - * - * - * - * t - * - * - * - * - * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit - * integer. - * - * - * - * - * - * - * h - * - * - * - * - * the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit - * value that, by convention, is used as an index into an array - * of file descriptors that are sent alongside a D-Bus message. - * - * - * - * - * - * - * d - * - * - * - * - * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision - * floating point value. - * - * - * - * - * - * - * s - * - * - * - * - * the type string of %G_VARIANT_TYPE_STRING; a string. - * - * - * - * - * - * - * o - * - * - * - * - * the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in - * the form of a D-Bus object path. - * - * - * - * - * - * - * g - * - * - * - * - * the type string of %G_VARIANT_TYPE_STRING; a string in the - * form of a D-Bus type signature. - * - * - * - * - * - * - * ? - * - * - * - * - * the type string of %G_VARIANT_TYPE_BASIC; an indefinite type - * that is a supertype of any of the basic types. - * - * - * - * - * - * - * v - * - * - * - * - * the type string of %G_VARIANT_TYPE_VARIANT; a container type - * that contain any other type of value. - * - * - * - * - * - * - * 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 signed 32-bit integers. - * - * - * - * - * - * - * 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. - * - * - * - * - * - * - * () - * - * - * - * - * 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. - * - * - * - * - * - * - * r - * - * - * - * - * the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type - * that is a supertype of any tuple type, regardless of the - * number of items. - * - * - * - * - * - * - * {} - * - * - * - * - * 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. - * - * - * 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 - * restricted to being a basic type is so that it can easily be - * hashed. - * - * - * - * - * - * - * * - * - * - * - * - * 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 - * cannot be used inside of tuples to mean "any number of items". - * - * - * - * - * - * + * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. + * - `y`: the type string of %G_VARIANT_TYPE_BYTE; a byte. + * - `n`: the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit integer. + * - `q`: the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit integer. + * - `i`: the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit integer. + * - `u`: the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit integer. + * - `x`: the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit integer. + * - `t`: the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit integer. + * - `h`: the type string of %G_VARIANT_TYPE_HANDLE; a signed 32 bit value + * that, by convention, is used as an index into an array of file + * descriptors that are sent alongside a D-Bus message. + * - `d`: the type string of %G_VARIANT_TYPE_DOUBLE; a double precision + * floating point value. + * - `s`: the type string of %G_VARIANT_TYPE_STRING; a string. + * - `o`: the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in the form + * of a D-Bus object path. + * - `g`: the type string of %G_VARIANT_TYPE_STRING; a string in the form of + * a D-Bus type signature. + * - `?`: the type string of %G_VARIANT_TYPE_BASIC; an indefinite type that + * is a supertype of any of the basic types. + * - `v`: the type string of %G_VARIANT_TYPE_VARIANT; a container type that + * contain any other type of value. + * - `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 + * signed 32-bit integers. + * - `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. + * - `()`: 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. + * - `r`: the type string of %G_VARIANT_TYPE_TUPLE; an indefinite type that is + * a supertype of any tuple type, regardless of the number of items. + * - `{}`: 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. + * + * 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 restricted to being a + * basic type is so that it can easily be hashed. + * - `*`: 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 cannot be used inside of tuples + * to mean "any number of items". * * Any type string of a container that contains an indefinite type is, * itself, an indefinite type. For example, the type string "a*" @@ -6682,8 +6408,8 @@ * 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>` + * ``. For use in a library, you must include + * `` * after defining the %GETTEXT_PACKAGE macro suitably for your library: * |[ * #define GETTEXT_PACKAGE "gtk20" @@ -6712,9 +6438,9 @@ * * The #GIOChannel data type aims to provide a portable method for * using file descriptors, pipes, and sockets, and integrating them - * into the main event - * loop. Currently full support is available on UNIX platforms, - * support for Windows is only partially complete. + * into the [main event loop][glib-The-Main-Event-Loop]. Currently, + * full support is available on UNIX platforms, support for Windows + * is only partially complete. * * To create a new #GIOChannel on UNIX systems use * g_io_channel_unix_new(). This works for plain file descriptors, @@ -6726,9 +6452,8 @@ * g_io_channel_write_chars(), g_io_channel_seek_position(), and * g_io_channel_shutdown(). * - * To add a #GIOChannel to the main event loop use - * g_io_add_watch() or g_io_add_watch_full(). Here you specify which + * To add a #GIOChannel to the [main event loop][glib-The-Main-Event-Loop], + * use g_io_add_watch() or g_io_add_watch_full(). Here you specify which * events you are interested in on the #GIOChannel, and provide a * function to be called whenever these events occur. * @@ -6848,23 +6573,21 @@ * Each element in the list contains a piece of data, together with * pointers which link to the previous and next elements in the list. * Using these pointers it is possible to move through the list in both - * directions (unlike the singly-linked #GSList which - * only allows movement through the list in the forward direction). + * directions (unlike the singly-linked [GSList][glib-Singly-Linked-Lists], + * which only allows movement through the list in the forward direction). * * The double linked list does not keep track of the number of items * and does not keep track of both the start and end of the list. If * you want fast access to both the start and the end of the list, * and/or the number of items in the list, use a - * GQueue instead. + * [GQueue][glib-Double-ended-Queues] instead. * * The data contained in each element can be either integer values, by - * using one of the Type - * Conversion Macros, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * - * List elements are allocated from the slice allocator, which is more - * efficient than allocating elements individually. + * List elements are allocated from the [slice allocator][glib-Memory-Slices], + * which is more efficient than allocating elements individually. * * Note that most of the #GList functions expect to be passed a pointer * to the first element in the list. The functions which insert @@ -6882,7 +6605,7 @@ * GList *l; * for (l = list; l != NULL; l = l->next) * { - * /* do something with l->data */ + * // do something with l->data * } * ]| * @@ -6897,7 +6620,7 @@ * GList *next = l->next; * if (should_be_removed (l)) * { - * /* possibly free l->data */ + * // possibly free l->data * list = g_list_delete_link (list, l); * } * l = next; @@ -6930,17 +6653,15 @@ * Each element in the list contains a piece of data, together with a * pointer which links to the next element in the list. Using this * pointer it is possible to move through the list in one direction - * only (unlike the Doubly-Linked Lists which - * allow movement in both directions). + * only (unlike the [double-linked lists][glib-Doubly-Linked-Lists], + * which allow movement in both directions). * * The data contained in each element can be either integer values, by - * using one of the Type - * Conversion Macros, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * - * List elements are allocated from the slice allocator, which is more - * efficient than allocating elements individually. + * List elements are allocated from the [slice allocator][glib-Memory-Slices], + * which is more efficient than allocating elements individually. * * Note that most of the #GSList functions expect to be passed a * pointer to the first element in the list. The functions which insert @@ -7112,7 +6833,7 @@ * * - Attributes * - * - 5 standard entities: &amp; &lt; &gt; &quot; &apos; + * - 5 standard entities: & < > " ' * * - Character references * @@ -7182,17 +6903,17 @@ * gchar *mem[10000]; * gint i; * - * /* Allocate 10000 blocks. */ + * // Allocate 10000 blocks. * for (i = 0; i < 10000; i++) * { * mem[i] = g_slice_alloc (50); * - * /* Fill in the memory with some junk. */ + * // Fill in the memory with some junk. * for (j = 0; j < 50; j++) * mem[i][j] = i * j; * } * - * /* Now free all of the blocks. */ + * // Now free all of the blocks. * for (i = 0; i < 10000; i++) * g_slice_free1 (50, mem[i]); * ]| @@ -7202,10 +6923,10 @@ * |[ * GRealArray *array; * - * /* Allocate one block, using the g_slice_new() macro. */ + * // Allocate one block, using the g_slice_new() macro. * array = g_slice_new (GRealArray); * - * /* We can now use array just like a normal pointer to a structure. */ + * // We can now use array just like a normal pointer to a structure. * array->data = NULL; * array->len = 0; * array->alloc = 0; @@ -7213,7 +6934,7 @@ * array->clear = (clear ? 1 : 0); * array->elt_size = elt_size; * - * /* We can free the block, so it can be reused. */ + * // We can free the block, so it can be reused. * g_slice_free (GRealArray, array); * ]| */ @@ -7363,7 +7084,7 @@ * exit (1); * } * - * /* ... */ + * ... * * } * ]| @@ -7404,18 +7125,18 @@ * args = g_strdupv (argv); * #endif * - * /* ... setup context ... */ + * // set up context * * if (!g_option_context_parse_strv (context, &args, &error)) * { - * /* ... error ... */ + * // error happened * } * - * /* ... */ + * ... * * g_strfreev (args); * - * /* ... */ + * ... * } * ]| */ @@ -7454,9 +7175,8 @@ * Given either the string or the #GQuark identifier it is possible to * retrieve the other. * - * Quarks are used for both Datasets and Keyed Data Lists. + * Quarks are used for both [datasets][glib-Datasets] and + * [keyed data lists][glib-Keyed-Data-Lists]. * * To create a new quark from a string, use g_quark_from_string() or * g_quark_from_static_string(). @@ -7486,8 +7206,8 @@ * as #GList to store elements. * * The data contained in each element can be either integer values, by - * using one of the Type - * Conversion Macros, or simply pointers to any type of data. + * using one of the [Type Conversion Macros][glib-Type-Conversion-Macros], + * or simply pointers to any type of data. * * To create a new GQueue, use g_queue_new(). * @@ -7537,7 +7257,7 @@ * * The g_rand*_range functions will return high quality equally * distributed random numbers, whereas for example the - * `(g_random_int()%max)` approach often + * `(g_random_int()\%max)` approach often * doesn't yield equally distributed numbers. * * GLib changed the seeding algorithm for the pseudo-random number @@ -7572,11 +7292,10 @@ * * The #GSequence data structure has the API of a list, but is * implemented internally with a balanced binary tree. This means that - * it is possible to maintain a sorted list of n elements in time O(n - * log n). The data contained in each element can be either integer - * values, by using of the Type Conversion Macros, - * or simply pointers to any type of data. + * it is possible to maintain a sorted list of n elements in time O(n log n). + * The data contained in each element can be either integer values, by using + * of the [Type Conversion Macros][glib-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 @@ -7663,21 +7382,21 @@ * 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 + * explicitly include `` in order to use the GLib * printf() functions. * * ## 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 + * 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 + * "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 + * 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. */ @@ -7707,8 +7426,7 @@ * SECTION:testing * @title: Testing * @short_description: a test framework - * @see_also: gtester, - * gtester-report + * @see_also: [gtester][gtester], [gtester-report][gtester-report] * * GLib provides a framework for writing and maintaining unit tests * in parallel to the code they are testing. The API is designed according @@ -7834,31 +7552,31 @@ * 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 + * - The functions 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 + * - The setlocale() function 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 + * - The fork() function 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. + * - The daemon() function 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 @@ -8266,9 +7984,8 @@ * 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. - * */ + * // This gets a pointer to the 4th element in the array of + * // EDayViewEvent structs. * event = &g_array_index (events, EDayViewEvent, 3); * ]| * @@ -8754,8 +8471,8 @@ * * 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. + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. */ @@ -8790,8 +8507,8 @@ * function only on strings known to be in encodings where bytes * 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. + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. */ @@ -8972,7 +8689,7 @@ * g_assert_cmpfloat: * @n1: an floating point number * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of ==, !=, <, >, <=, >=. * @n2: another floating point number * * Debugging macro to compare two floating point numbers. @@ -8990,7 +8707,7 @@ * g_assert_cmphex: * @n1: an unsigned integer * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * * Debugging macro to compare to unsigned integers. @@ -9006,7 +8723,7 @@ * g_assert_cmpint: * @n1: an integer * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of ==, !=, <, >, <=, >=. * @n2: another integer * * Debugging macro to compare two integers. @@ -9024,7 +8741,7 @@ * g_assert_cmpstr: * @s1: a string (may be %NULL) * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of ==, !=, <, >, <=, >=. * @s2: another string (may be %NULL) * * Debugging macro to compare two strings. If the comparison fails, @@ -9049,7 +8766,7 @@ * g_assert_cmpuint: * @n1: an unsigned integer * @cmp: The comparison operator to use. - * One of ==, !=, <, >, <=, >=. + * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * * Debugging macro to compare two unsigned integers. @@ -9073,8 +8790,8 @@ * 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 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. * @@ -9605,7 +9322,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. * @@ -9628,7 +9345,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 @@ -9647,7 +9364,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. * @@ -9663,7 +9380,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. * @@ -9707,7 +9424,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. * @@ -9724,7 +9441,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. * @@ -9756,7 +9473,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. * @@ -9773,7 +9490,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. * @@ -9791,7 +9508,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. * @@ -9812,7 +9529,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. * @@ -9844,7 +9561,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. * @@ -9876,7 +9593,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. * @@ -11479,8 +11196,9 @@ /** * g_child_watch_add: - * @pid: process id to watch. On POSIX the pid of a child process. On - * Windows a handle for a process (which doesn't have to be a child). + * @pid: process id to watch. On POSIX the positive pid of a child + * process. On Windows a handle for a process (which doesn't have to be + * a child). * @function: function to call * @data: data to pass to @function * @@ -11512,7 +11230,7 @@ * g_child_watch_add_full: (rename-to g_child_watch_add) * @priority: the priority of the idle source. Typically this will be in the * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. - * @pid: process to watch. On POSIX the pid of a child process. On + * @pid: process to watch. On POSIX the positive pid of a child process. On * Windows a handle for a process (which doesn't have to be a child). * @function: function to call * @data: data to pass to @function @@ -11548,7 +11266,7 @@ /** * g_child_watch_source_new: - * @pid: process to watch. On POSIX the pid of a child process. On + * @pid: process to watch. On POSIX the positive pid of a child process. On * Windows a handle for a process (which doesn't have to be a child). * * Creates a new child_watch source. @@ -11570,6 +11288,10 @@ * argument in the application. Calling waitpid() for individual * pids will still work fine. * + * Similarly, on POSIX platforms, the @pid passed to this function must + * be greater than 0 (i.e. this function must wait for a specific child, + * and cannot wait for one of many children by using a nonpositive argument). + * * Returns: the newly-created child watch source * Since: 2.4 */ @@ -11848,12 +11570,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; * @@ -12830,10 +12552,10 @@ * @str: string to parse * * Parses a user-inputted string @str, and try to figure out what date it - * represents, taking the current locale - * into account. If the string is successfully parsed, the date will be - * valid after the call. Otherwise, it will be invalid. You should check - * using g_date_valid() to see whether the parsing succeeded. + * represents, taking the [current locale][setlocale] into account. If the + * string is successfully parsed, the date will be valid after the call. + * Otherwise, it will be invalid. You should check using g_date_valid() + * to see whether the parsing succeeded. * * This function is not appropriate for file formats and the like; it * isn't very precise, and its exact behavior varies with the locale. @@ -12906,7 +12628,7 @@ * @date: valid #GDate * * Generates a printed representation of the date, in a - * locale-specific way. + * [locale][setlocale]-specific way. * Works just like the platform's C library strftime() function, * but only accepts date-related formats; time-related formats * give undefined results. Date must be valid. Unlike strftime() @@ -14518,11 +14240,11 @@ * 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 */ + * // DON'T DO THIS * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK)) * { * fd = g_open (filename, O_WRONLY); - * /* write to fd */ + * // write to fd * } * ]| * @@ -14634,7 +14356,7 @@ * Converts a string from UTF-8 to the encoding GLib uses for * filenames. Note that on Windows GLib uses UTF-8 for filenames; * on other platforms, this function indirectly depends on the - * current locale. + * [current locale][setlocale]. * * Returns: (array length=bytes_written) (element-type guint8) (transfer full): * The converted string, or %NULL on an error. @@ -14681,7 +14403,7 @@ * Converts a string which is in the encoding used by GLib for * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 * for filenames; on other platforms, this function indirectly depends on - * the current locale. + * the [current locale][setlocale]. * * Returns: The converted string, or %NULL on an error. */ @@ -14800,7 +14522,7 @@ * g_fprintf: * @file: the stream to write to. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -14857,11 +14579,10 @@ * g_get_charset: * @charset: return location for character set name * - * Obtains the character set for the current - * locale; you might use this character set as an argument to - * g_convert(), to convert from the current locale's encoding to some - * other encoding. (Frequently g_locale_to_utf8() and g_locale_from_utf8() - * are nice shortcuts, though.) + * Obtains the character set for the [current locale][setlocale]; you + * might use this character set as an argument to g_convert(), to convert + * from the current locale's encoding to some other encoding. (Frequently + * g_locale_to_utf8() and g_locale_from_utf8() are nice shortcuts, though.) * * On Windows the character set returned by this function is the * so-called system default ANSI code-page. That is the character set @@ -14953,12 +14674,12 @@ * * `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. + * to mean the character set for the [current locale][setlocale]. + * 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. * @@ -15609,7 +15330,7 @@ * g_hash_table_iter_init (&iter, hash_table); * while (g_hash_table_iter_next (&iter, &key, &value)) * { - * /* do something with key and value */ + * // do something with key and value * } * ]| * @@ -16019,7 +15740,7 @@ * Compares the ids of two #GHook elements, returning a negative value * if the second id is greater than the first. * - * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook + * Returns: a value <= 0 if the id of @sibling is >= the id of @new_hook */ @@ -18111,14 +17832,14 @@ * the list with g_list_reverse() when all elements have been added. * * |[ - * /* Notice that these are initialized to the empty list. */ + * // Notice that these are initialized to the empty list. * GList *string_list = NULL, *number_list = NULL; * - * /* This is a list of strings. */ + * // This is a list of strings. * string_list = g_list_append (string_list, "first"); * string_list = g_list_append (string_list, "second"); * - * /* This is a list of integers. */ + * // This is a list of integers. * number_list = g_list_append (number_list, GINT_TO_POINTER (27)); * number_list = g_list_append (number_list, GINT_TO_POINTER (14)); * ]| @@ -18479,7 +18200,7 @@ * which will have changed, so make sure you store the new value. * * |[ - * /* Notice that it is initialized to the empty list. */ + * // Notice that it is initialized to the empty list. * GList *list = NULL; * * list = g_list_prepend (list, "last"); @@ -18636,8 +18357,8 @@ * * Converts a string from UTF-8 to the encoding used for strings by * the C runtime (usually the same as that used by the operating - * system) in the current locale. On - * Windows this means the system codepage. + * system) in the [current locale][setlocale]. On Windows this means + * the system codepage. * * Returns: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. @@ -18667,8 +18388,7 @@ * * Converts a string which is in the encoding used for strings by * the C runtime (usually the same as that used by the operating - * system) in the current locale into a - * UTF-8 string. + * system) in the [current locale][setlocale] into a UTF-8 string. * * Returns: A newly-allocated buffer containing the converted string, * or %NULL on an error, and error will be set. @@ -19140,7 +18860,7 @@ * * Acquires @context and sets it as the thread-default context for the * current thread. This will cause certain asynchronous operations - * (such as most gio-based I/O) which are + * (such as most [gio][gio]-based I/O) which are * 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 @@ -19748,7 +19468,7 @@ * of line endings and attribute values. * * Note also that this function will produce character references in - * the range of &#x1; ... &#x1f; for all control sequences + * the range of  ...  for all control sequences * except for tabstop, newline and carriage return. The character * references in this range are not valid XML 1.0, but they are * valid XML 1.1 and will be accepted by the GMarkup parser. @@ -20021,7 +19741,7 @@ * if (strcmp (element_name, "count-these") == 0) * start_counting (context); * - * /* else, handle other tags... */ + * // else, handle other tags... * } * * static void end_element (context, element_name, ...) @@ -20029,7 +19749,7 @@ * if (strcmp (element_name, "count-these") == 0) * g_print ("Counted %d tags\n", end_counting (context)); * - * /* else, handle other tags... */ + * // else, handle other tags... * } * ]| * @@ -20197,7 +19917,7 @@ * Retrieves the text matching the capturing parentheses named @name. * * If @name is a valid sub pattern name but it didn't match anything - * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") + * (e.g. sub pattern "X", matching "b" against "(?Pa)?b") * then an empty string is returned. * * The string is fetched from the string passed to the match function, @@ -20221,7 +19941,7 @@ * Retrieves the position in bytes of the capturing parentheses named @name. * * If @name is a valid sub pattern name but it didn't match anything - * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") + * (e.g. sub pattern "X", matching "b" against "(?Pa)?b") * then @start_pos and @end_pos are set to -1 and %TRUE is returned. * * Returns: %TRUE if the position was fetched, %FALSE otherwise. @@ -21194,12 +20914,12 @@ * * 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); * } * - * /* use initialization_value here */ + * // use initialization_value here * ]| * * Returns: %TRUE if the initialization section should be entered, @@ -21434,8 +21154,7 @@ * this function will produce help output to stdout and * call `exit (0)`. * - * Note that function depends on the - * current locale for + * Note that function depends on the [current locale][setlocale] for * automatic character set conversion of string and filename * arguments. * @@ -22014,7 +21733,7 @@ /** * g_printf: * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard printf() function which supports @@ -23462,7 +23181,7 @@ * static void * print_uppercase_words (const gchar *string) * { - * /* Print all uppercase-only words. */ + * // Print all uppercase-only words. * GRegex *regex; * GMatchInfo *match_info; * @@ -23531,15 +23250,15 @@ * Using the standard algorithm for regular expression matching only * the longest match in the string is retrieved, it is not possible * to obtain all the available matches. For instance matching - * "<a> <b> <c>" against the pattern "<.*>" - * you get "<a> <b> <c>". + * " " against the pattern "<.*>" + * you get " ". * * This function uses a different algorithm (called DFA, i.e. deterministic * finite automaton), so it can retrieve all the possible matches, all * starting at the same point in the string. For instance matching - * "<a> <b> <c>" against the pattern "<.*>" - * you would obtain three matches: "<a> <b> <c>", - * "<a> <b>" and "<a>". + * " " against the pattern "<.*>;" + * you would obtain three matches: " ", + * " " and "". * * The number of matched strings is retrieved using * g_match_info_get_match_count(). To obtain the matched strings and @@ -23607,7 +23326,7 @@ * static void * print_uppercase_words (const gchar *string) * { - * /* Print all uppercase-only words. */ + * // Print all uppercase-only words. * GRegex *regex; * GMatchInfo *match_info; * GError *error = NULL; @@ -23698,11 +23417,12 @@ * * Replaces all occurrences of the pattern in @regex with the * replacement text. Backreferences of the form '\number' or - * '\g<number>' in the replacement text are interpolated by the - * number-th captured subexpression of the match, '\g<name>' refers - * 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 '\\'. + * '\g' in the replacement text are interpolated by the + * number-th captured subexpression of the match, '\g' refers + * 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: * @@ -23764,7 +23484,7 @@ * return FALSE; * } * - * /* ... */ + * ... * * GRegex *reg; * GHashTable *h; @@ -23781,7 +23501,7 @@ * res = g_regex_replace_eval (reg, text, -1, 0, 0, eval_cb, h, NULL); * g_hash_table_destroy (h); * - * /* ... */ + * ... * ]| * * Returns: a newly allocated string containing the replacements @@ -25255,7 +24975,7 @@ * if a malloc() fallback implementation is used instead, * the alignment may be reduced in a libc dependent fashion. * Note that the underlying slice allocation mechanism can - * be changed with the G_SLICE=always-malloc + * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated memory block @@ -25269,8 +24989,7 @@ * * Allocates a block of memory via g_slice_alloc() and initializes * the returned memory to 0. Note that the underlying slice allocation - * mechanism can be changed with the - * G_SLICE=always-malloc + * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block @@ -25303,7 +25022,7 @@ * 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 + * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block, cast to a pointer to @type @@ -25322,9 +25041,8 @@ * 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 - * variable, also see G_SLICE for - * related debugging options. + * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see + * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ @@ -25340,10 +25058,8 @@ * The memory must have been allocated via g_slice_alloc() or * g_slice_alloc0() and the @block_size has to match the size * specified upon allocation. Note that the exact release behaviour - * can be changed with the - * G_DEBUG=gc-friendly environment - * variable, also see G_SLICE for - * related debugging options. + * can be changed with the [`G_DEBUG=gc-friendly`][G_DEBUG] environment + * variable, also see [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ @@ -25361,9 +25077,8 @@ * a @next pointer (similar to #GSList). The name of the * @next field in @type is passed as third argument. * Note that the exact release behaviour can be changed with the - * G_DEBUG=gc-friendly environment - * variable, also see G_SLICE for - * related debugging options. + * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see + * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ @@ -25382,9 +25097,8 @@ * @next pointer (similar to #GSList). The offset of the @next * field in each block is passed as third argument. * Note that the exact release behaviour can be changed with the - * G_DEBUG=gc-friendly environment - * variable, also see G_SLICE for - * related debugging options. + * [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see + * [`G_SLICE`][G_SLICE] for related debugging options. * * Since: 2.10 */ @@ -25400,8 +25114,7 @@ * 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 + * mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Returns: a pointer to the allocated block, cast to a pointer to @type @@ -25420,7 +25133,7 @@ * 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 + * be changed with the [`G_SLICE=always-malloc`][G_SLICE] * environment variable. * * Since: 2.10 @@ -25454,14 +25167,14 @@ * the elements and reverse the list when all elements have been added. * * |[ - * /* Notice that these are initialized to the empty list. */ + * // Notice that these are initialized to the empty list. * GSList *list = NULL, *number_list = NULL; * - * /* This is a list of strings. */ + * // This is a list of strings. * list = g_slist_append (list, "first"); * list = g_slist_append (list, "second"); * - * /* This is a list of integers. */ + * // This is a list of integers. * number_list = g_slist_append (number_list, GINT_TO_POINTER (27)); * number_list = g_slist_append (number_list, GINT_TO_POINTER (14)); * ]| @@ -25787,7 +25500,7 @@ * may have changed, so make sure you store the new value. * * |[ - * /* Notice that it is initialized to the empty list. */ + * // Notice that it is initialized to the empty list. * GSList *list = NULL; * list = g_slist_prepend (list, "last"); * list = g_slist_prepend (list, "first"); @@ -25887,7 +25600,7 @@ * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * A safer form of the standard sprintf() function. The output is guaranteed @@ -26127,7 +25840,7 @@ * SomeWidget *self = data; * * GDK_THREADS_ENTER (); - * /* do stuff with self */ + * // do stuff with self * self->idle_id = 0; * GDK_THREADS_LEAVE (); * @@ -26167,7 +25880,7 @@ * GDK_THREADS_ENTER (); * if (!g_source_is_destroyed (g_main_current_source ())) * { - * /* do stuff with self */ + * // do stuff with self * } * GDK_THREADS_LEAVE (); * @@ -26848,7 +26561,7 @@ * is up to the caller to ensure that the allocated buffer is large * enough to hold the formatted result * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @...: the arguments to insert in the output. * * An implementation of the standard sprintf() function which supports @@ -27073,8 +26786,8 @@ * 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. + * 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. */ @@ -27211,7 +26924,7 @@ /** * g_strdup_printf: * @format: a standard printf() format string, but notice - * string precision pitfalls + * [string precision pitfalls][string-precision] * @...: the parameters to insert into the format string * * Similar to the standard C sprintf() function but safer, since it @@ -27226,7 +26939,7 @@ /** * g_strdup_vprintf: * @format: a standard printf() format string, but notice - * string precision pitfalls + * [string precision pitfalls][string-precision] * @args: the list of parameters to insert into the format string * * Similar to the standard C vsprintf() function but safer, since it @@ -27265,7 +26978,7 @@ * not all platforms support the strerror() function. * * Returns: a UTF-8 string describing the error code. If the error code - * is unknown, it returns "unknown error (<code>)". + * is unknown, it returns "unknown error ()". */ @@ -28006,8 +27719,8 @@ * 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. + * 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 @@ -28109,7 +27822,7 @@ * the strsignal() function. * * Returns: a UTF-8 string describing the signal. If the signal is unknown, - * it returns "unknown signal (<signum>)". + * it returns "unknown signal ()". */ @@ -28445,8 +28158,7 @@ * g_test_expect_message: * @log_domain: (allow-none): the log domain of the message * @log_level: the log level of the message - * @pattern: a glob-style - * pattern + * @pattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Indicates that a message with the given @log_domain and @log_level, * with text matching @pattern, is expected to be logged. When this @@ -28463,9 +28175,8 @@ * For example: * * |[ - * /* g_main_context_push_thread_default() should fail if the - * * context is already owned by another thread. - * */ + * // g_main_context_push_thread_default() should fail if the + * // context is already owned by another thread. * g_test_expect_message (G_LOG_DOMAIN, * G_LOG_LEVEL_CRITICAL, * "assertion*acquired_context*failed"); @@ -28915,8 +28626,11 @@ * particular code runs before or after a given test case, use * g_test_add(), which lets you specify setup and teardown functions. * + * If all tests are skipped, this function will return 0 if + * producing TAP output, or 77 (treated as "skip test" by Automake) otherwise. + * * Returns: 0 on success, 1 on failure (assuming it returns at all), - * 77 if all tests were skipped with g_test_skip(). + * 0 or 77 if all tests were skipped with g_test_skip() * Since: 2.16 */ @@ -29090,8 +28804,7 @@ /** * g_test_trap_assert_stderr: - * @serrpattern: a glob-style - * pattern + * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stderr output of the last test subprocess * matches @serrpattern. See g_test_trap_subprocess(). @@ -29109,8 +28822,7 @@ /** * g_test_trap_assert_stderr_unmatched: - * @serrpattern: a glob-style - * pattern + * @serrpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stderr output of the last test subprocess * does not match @serrpattern. See g_test_trap_subprocess(). @@ -29121,8 +28833,7 @@ /** * g_test_trap_assert_stdout: - * @soutpattern: a glob-style - * pattern + * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stdout output of the last test subprocess matches * @soutpattern. See g_test_trap_subprocess(). @@ -29133,8 +28844,7 @@ /** * g_test_trap_assert_stdout_unmatched: - * @soutpattern: a glob-style - * pattern + * @soutpattern: a glob-style [pattern][glib-Glob-style-pattern-matching] * * Assert that the stdout output of the last test subprocess * does not match @soutpattern. See g_test_trap_subprocess(). @@ -29169,7 +28879,7 @@ * { * g_print ("some stdout text: somagic17\n"); * g_printerr ("some stderr text: semagic43\n"); - * exit (0); /* successful test run */ + * exit (0); // successful test run * } * g_test_trap_assert_passed (); * g_test_trap_assert_stdout ("*somagic17*"); @@ -29256,7 +28966,7 @@ * return; * } * - * /* Reruns this same test in a subprocess */ + * // Reruns this same test in a subprocess * g_test_trap_subprocess (NULL, 0, 0); * g_test_trap_assert_failed (); * g_test_trap_assert_stderr ("*ERROR*too large*"); @@ -30545,8 +30255,7 @@ * Deprecated: 2.2: The order of a balanced tree is somewhat arbitrary. * If you just want to visit all nodes in sorted order, use * g_tree_foreach() instead. If you really need to visit nodes in - * a different order, consider using an - * N-ary Tree. + * a different order, consider using an [n-ary tree][glib-N-ary-Trees]. */ @@ -31644,14 +31353,14 @@ * @str2: a UTF-8 encoded string * * Compares two strings for ordering using the linguistically - * correct rules for the current locale. + * correct rules for the [current locale][setlocale]. * When sorting a large number of strings, it will be significantly * faster to obtain collation keys with g_utf8_collate_key() and * compare the keys with strcmp() when sorting instead of sorting * the original strings. * - * Returns: < 0 if @str1 compares before @str2, - * 0 if they compare equal, > 0 if @str1 compares after @str2. + * Returns: < 0 if @str1 compares before @str2, + * 0 if they compare equal, > 0 if @str1 compares after @str2. */ @@ -31668,8 +31377,7 @@ * with strcmp() will always be the same as comparing the two * original keys with g_utf8_collate(). * - * Note that this function depends on the - * current locale. + * Note that this function depends on the [current locale][setlocale]. * * Returns: a newly allocated string. This string should * be freed with g_free() when you are done with it. @@ -31691,8 +31399,7 @@ * would like to treat numbers intelligently so that "file1" "file10" "file5" * is sorted as "file1" "file5" "file10". * - * Note that this function depends on the - * current locale. + * Note that this function depends on the [current locale][setlocale]. * * Returns: a newly allocated string. This string should * be freed with g_free() when you are done with it. @@ -32119,7 +31826,7 @@ * * 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. + * the [GVariant varargs documentation][gvariant-varargs]. * * This function might be used as follows: * @@ -32161,7 +31868,7 @@ * * 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. + * the [GVariant varargs documentation][gvariant-varargs]. * * This function might be used as follows: * @@ -32453,9 +32160,9 @@ * If you only require an equality comparison, g_variant_equal() is more * general. * - * Returns: negative value if a < b; + * Returns: negative value if a < b; * zero if a = b; - * positive value if a > b. + * positive value if a > b. * Since: 2.26 */ @@ -32582,10 +32289,9 @@ * 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. + * @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][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked * Since: 2.40 @@ -32803,15 +32509,15 @@ * The arguments that are expected by this function are entirely * determined by @format_string. @format_string also restricts the * permissible types of @value. It is an error to give a value with - * an incompatible type. See the section on GVariant Format Strings. + * an incompatible type. See the section on + * [GVariant format strings][gvariant-format-strings]. * Please note that the syntax of the format string is very likely to be * extended in the future. * * @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. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 */ @@ -32907,7 +32613,7 @@ * @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. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 */ @@ -33013,27 +32719,16 @@ * * @element_size must be the size of a single element in the array, * as given by the section on - * Serialised Data - * Memory. + * [serialized data memory][gvariant-serialised-data-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 the size * the appropriate type: - * - * - * - * element type C type - * - * %G_VARIANT_TYPE_INT16 (etc.) - * #gint16 (etc.) - * %G_VARIANT_TYPE_BOOLEAN - * #guchar (not #gboolean!) - * %G_VARIANT_TYPE_BYTE #guchar - * %G_VARIANT_TYPE_HANDLE #guint32 - * %G_VARIANT_TYPE_DOUBLE #gdouble - * - * - * + * - %G_VARIANT_TYPE_INT16 (etc.): #gint16 (etc.) + * - %G_VARIANT_TYPE_BOOLEAN: #guchar (not #gboolean!) + * - %G_VARIANT_TYPE_BYTE: #guchar + * - %G_VARIANT_TYPE_HANDLE: #guint32 + * - %G_VARIANT_TYPE_DOUBLE: #gdouble * * 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 @@ -33336,7 +33031,7 @@ * @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. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Since: 2.24 */ @@ -33550,7 +33245,7 @@ * * Here is an example for memory management with g_variant_iter_loop(): * |[ - * /* Iterates a dictionary of type 'a{sv}' */ + * // Iterates a dictionary of type 'a{sv}' * void * iterate_dictionary (GVariant *dictionary) * { @@ -33564,9 +33259,8 @@ * 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 * } * } * ]| @@ -33586,7 +33280,7 @@ * the values and also determines if the values are copied or borrowed. * * See the section on - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked, or %FALSE if there was no * value @@ -33645,7 +33339,7 @@ * * Here is an example for memory management with g_variant_iter_next(): * |[ - * /* Iterates a dictionary of type 'a{sv}' */ + * // Iterates a dictionary of type 'a{sv}' * void * iterate_dictionary (GVariant *dictionary) * { @@ -33659,7 +33353,7 @@ * 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); * } @@ -33673,7 +33367,7 @@ * the values and also determines if the values are copied or borrowed. * * See the section on - * GVariant Format Strings. + * [GVariant format strings][gvariant-format-strings-pointers]. * * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value * Since: 2.24 @@ -33692,7 +33386,7 @@ * * Here is an example for iterating with g_variant_iter_next_value(): * |[ - * /* recursively iterate a container */ + * // recursively iterate a container * void * iterate_container_recursive (GVariant *container) * { @@ -33734,7 +33428,7 @@ * @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. + * [GVariant format strings][gvariant-format-strings-pointers]. * * This function is currently implemented with a linear scan. If you * plan to do many lookups then #GVariantDict may be more efficient. @@ -33807,11 +33501,11 @@ * * Think of this function as an analogue to g_strdup_printf(). * - * The type of the created instance and the arguments that are - * expected by this function are determined by @format_string. See the - * section on GVariant Format - * Strings. Please note that the syntax of the format string is - * very likely to be extended in the future. + * The type of the created instance and the arguments that are expected + * by this function are determined by @format_string. See the section on + * [GVariant format strings][gvariant-format-strings]. Please note that + * the syntax of the format string is very likely to be extended in the + * future. * * The first character of the format string must not be '*' '?' '@' or * 'r'; in essence, a new #GVariant must always be constructed by this @@ -33819,9 +33513,9 @@ * * 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. + * the [GVariant varargs documentation][gvariant-varargs]. * - * + * |[ * MyFlags some_flags = FLAG_ONE | FLAG_TWO; * const gchar *some_strings[] = { "a", "b", "c", NULL }; * GVariant *new_variant; @@ -33830,7 +33524,7 @@ * /* This cast is required. */ * (guint64) some_flags, * some_strings); - * + * ]| * * Returns: a new floating #GVariant instance * Since: 2.24 @@ -34144,7 +33838,7 @@ * * 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. + * the [GVariant varargs documentation][gvariant-varargs]. * * Consider this simple example: * |[ @@ -34189,7 +33883,7 @@ * * 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. + * the [GVariant varargs documentation][gvariant-varargs]. * * In order to behave correctly in all cases it is necessary for the * calling function to g_variant_ref_sink() the return result before @@ -34356,9 +34050,9 @@ * @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. + * 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][gvariant-varargs. * * These two generalisations allow mixing of multiple calls to * g_variant_new_va() and g_variant_get_va() within a single actual @@ -34409,7 +34103,7 @@ * * A single #GVariant is parsed from the content of @text. * - * The format is described here. + * The format is described [here][gvariant-text]. * * The memory at @limit will never be accessed and the parser behaves as * if the character at @limit is the nul terminator. This has the @@ -34495,7 +34189,7 @@ * * Pretty-prints @value in the format understood by g_variant_parse(). * - * The format is described here. + * The format is described [here][gvariant-text]. * * If @type_annotate is %TRUE, then type information is included in * the output. @@ -35140,7 +34834,7 @@ * g_vasprintf: * @string: the return location for the newly-allocated string. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the GNU vasprintf() function which supports @@ -35158,7 +34852,7 @@ * g_vfprintf: * @file: the stream to write to. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -35172,7 +34866,7 @@ /** * g_vprintf: * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vprintf() function which supports @@ -35189,7 +34883,7 @@ * @n: the maximum number of bytes to produce (including the * terminating nul character). * @format: a standard printf() format string, but notice - * string precision pitfalls. + * string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * A safer form of the standard vsprintf() function. The output is guaranteed @@ -35219,7 +34913,7 @@ * g_vsprintf: * @string: the buffer to hold the output. * @format: a standard printf() format string, but notice - * string precision pitfalls. + * [string precision pitfalls][string-precision] * @args: the list of arguments to insert in the output. * * An implementation of the standard vsprintf() function which supports @@ -35387,8 +35081,8 @@ * the package, typically the same identifier as used for * `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 diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c index 83fd6a92..c1a66a55 100644 --- a/gir/gmodule-2.0.c +++ b/gir/gmodule-2.0.c @@ -6,8 +6,8 @@ * GModule: * * The #GModule struct is an opaque data structure to represent a - * Dynamically-Loaded - * Module. It should only be accessed via the following functions. + * [dynamically-loaded module][glib-Dynamic-Loading-of-Modules]. + * It should only be accessed via the following functions. */ @@ -111,7 +111,7 @@ * * Example: Calling a function defined in a GModule * |[ - * /* the function signature for 'say_hello' */ + * // the function signature for 'say_hello' * typedef void (* SayHelloFunc) (const char *message); * * gboolean @@ -146,7 +146,7 @@ * return FALSE; * } * - * /* call our function in the module */ + * // call our function in the module * say_hello ("Hello world!"); * * if (!g_module_close (module)) diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index b25b8d0b..ea1dbc16 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -69,7 +69,7 @@ * text_view) * ]| * It is important to note that you must use - * canonical parameter names as + * [canonical][canonical-parameter-name] parameter names as * detail strings for the notify signal. */ @@ -128,9 +128,8 @@ * GLib type system, it can be used as value type for object * properties, using g_param_spec_enum() or g_param_spec_flags(). * - * GObject ships with a utility called glib-mkenums that can construct - * suitable type registration functions from C enumeration + * GObject ships with a utility called [glib-mkenums][glib-mkenums], + * that can construct suitable type registration functions from C enumeration * definitions. */ @@ -263,9 +262,8 @@ * marshaller for any closure which is connected to this * signal. GObject provides a number of C marshallers for this * purpose, see the g_cclosure_marshal_*() functions. Additional C - * marshallers can be generated with the glib-genmarshal utility. Closures - * can be explicitly connected to signals with + * marshallers can be generated with the [glib-genmarshal][glib-genmarshal] + * utility. Closures can be explicitly connected to signals with * g_signal_connect_closure(), but it usually more convenient to let * GObject create a closure automatically by using one of the * g_signal_connect_*() functions which take a callback function/user @@ -293,9 +291,9 @@ * other type * @see_also: The fundamental types which all support #GValue * operations and thus can be used as a type initializer for - * g_value_init() are defined by a separate interface. See the Standard - * Values API for details. + * g_value_init() are defined by a separate interface. See the + * [standard values API][gobject-Standard-Parameter-and-Value-Types] + * for details * @title: Generic values * * The #GValue structure is basically a variable container that consists @@ -330,37 +328,37 @@ * main (int argc, * char *argv[]) * { - * /* GValues must be initialized */ + * // GValues must be initialized * GValue a = G_VALUE_INIT; * GValue b = G_VALUE_INIT; * const gchar *message; * - * /* The GValue starts empty */ + * // The GValue starts empty * g_assert (!G_VALUE_HOLDS_STRING (&a)); * - * /* Put a string in it */ + * // 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)); * - * /* Reset it to its pristine state */ + * // Reset it to its pristine state * g_value_unset (&a); * - * /* It can then be reused for another type */ + * // It can then be reused for another type * g_value_init (&a, G_TYPE_INT); * g_value_set_int (&a, 42); * - * /* Attempt to transform it into a GValue of type STRING */ + * // Attempt to transform it into a GValue of type STRING * g_value_init (&b, G_TYPE_STRING); * - * /* An INT is transformable to a 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)); * - * /* Attempt to transform it again using a custom transform function */ + * // 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)); @@ -538,8 +536,7 @@ * methods for all object types in GTK+, Pango and other libraries * based on GObject. The GObject class provides methods for object * construction and destruction, property access methods, and signal - * support. Signals are described in detail in . + * support. Signals are described in detail [here][gobject-Signals]. * * ## Floating references # {#floating-ref} * @@ -580,16 +577,18 @@ * the following sequence can be used: * * |[ - * /* save floating state */ + * // save floating state * gboolean was_floating = g_object_is_floating (object); * g_object_ref_sink (object); - * /* protected code portion */ - * ...; - * /* restore floating state */ + * // protected code portion + * + * ... + * + * // restore floating state * if (was_floating) * g_object_force_floating (object); * else - * g_object_unref (object); /* release previously acquired reference */ + * g_object_unref (object); // release previously acquired reference * ]| */ @@ -1366,7 +1365,7 @@ * struct _MyClosure * { * GClosure closure; - * /* extra data goes here */ + * // extra data goes here * }; * * static void @@ -1375,7 +1374,7 @@ * { * MyClosure *my_closure = (MyClosure *)closure; * - * /* free extra data here */ + * // free extra data here * } * * MyClosure *my_closure_new (gpointer data) @@ -1386,7 +1385,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); @@ -1458,9 +1457,8 @@ * Sets the meta marshaller of @closure. A meta marshaller wraps * @closure->marshal and modifies the way it is called in some * fashion. The most common use of this facility is for C callbacks. - * The same marshallers (generated by glib-genmarshal) are used - * everywhere, but the way that we get the callback function + * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), + * are used everywhere, but the way that we get the callback function * differs. In most cases we want to use @closure->callback, but in * other cases we want to use some different technique to retrieve the * callback function. @@ -1489,7 +1487,7 @@ * |[ * closure = g_cclosure_new (cb_func, cb_data); * g_source_set_closure (source, closure); - * g_closure_unref (closure); /* 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: @@ -1610,10 +1608,9 @@ * * Registers a new static enumeration type with the name @name. * - * It is normally more convenient to let glib-mkenums generate a - * my_enum_get_type() function from a usual C enumeration definition - * than to write one yourself using g_enum_register_static(). + * It is normally more convenient to let [glib-mkenums][glib-mkenums], + * generate a my_enum_get_type() function from a usual C enumeration + * definition than to write one yourself using g_enum_register_static(). * * Returns: The new type identifier. */ @@ -1678,10 +1675,9 @@ * * Registers a new static flags type with the name @name. * - * It is normally more convenient to let glib-mkenums generate a - * my_flags_get_type() function from a usual C enumeration definition - * than to write one yourself using g_flags_register_static(). + * It is normally more convenient to let [glib-mkenums][glib-mkenums] + * generate a my_flags_get_type() function from a usual C enumeration + * definition than to write one yourself using g_flags_register_static(). * * Returns: The new type identifier. */ @@ -2109,11 +2105,10 @@ * g_object_force_floating: * @object: a #GObject * - * 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 - * usually just needs to be sunken by calling g_object_ref_sink(). + * This function is intended for #GObject implementations to re-enforce + * a [floating][floating-ref] object reference. Doing this is seldom + * required: all #GInitiallyUnowneds are created with a floating reference + * which usually just needs to be sunken by calling g_object_ref_sink(). * * Since: 2.10 */ @@ -2161,7 +2156,7 @@ * "obj-property", &objval, * NULL); * - * /* Do something with intval, strval, objval */ + * // Do something with intval, strval, objval * * g_free (strval); * g_object_unref (objval); @@ -2295,8 +2290,7 @@ * g_object_is_floating: * @object: (type GObject.Object): a #GObject * - * Checks whether @object has a floating - * reference. + * Checks whether @object has a [floating][floating-ref] reference. * * Since: 2.10 * Returns: %TRUE if @object has a floating reference @@ -2432,8 +2426,7 @@ * @object: (type GObject.Object): a #GObject * * Increase the reference count of @object, and possibly remove the - * floating reference, if @object - * has a floating reference. + * [floating][floating-ref] reference, if @object has a floating reference. * * In other words, if the object is floating, then this call "assumes * ownership" of the floating reference, converting it to a normal @@ -5305,7 +5298,7 @@ /** * g_value_array_insert: * @value_array: #GValueArray to add an element to - * @index_: insertion position, must be <= value_array->n_values + * @index_: insertion position, must be <= value_array->n_values * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * * Insert a copy of @value at specified position into @value_array. If @value -- cgit v1.2.1