[gobject-introspection] Update glib annotations from git master
- From: Rico Tzschichholz <ricotz src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Update glib annotations from git master
- Date: Sun, 16 Feb 2014 20:16:54 +0000 (UTC)
commit d9e22053063d573c2a968a2468d829c0f6191fd0
Author: Rico Tzschichholz <ricotz ubuntu com>
Date: Sun Feb 16 21:16:34 2014 +0100
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 d3f9c58..0cc13e8 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 <literal>--gapplication-service</literal> 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:
* |[<!-- language="C" -->
- * /* 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
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * [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
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * [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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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: <link linkend="extending-gio">Extending GIO</link>
+ * @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 @@
* |[<!-- language="C" -->
* 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);
* ]|
*
* |[<!-- language="C" -->
- * /* 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 <link linkend="gio-querymodules">gio-querymodules</link>.
+ * 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.
*
- * <example id="gapplication-example-open"><title>Opening files with a GApplication</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gapplication-example-open.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * 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).
*
- * <example id="gapplication-example-actions"><title>A GApplication with actions</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gapplication-example-actions.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * 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).
*
- * <example id="gapplication-example-dbushooks"><title>Using extra D-Bus hooks with a GApplication</title>
- * <programlisting>
- * <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gapplication-example-dbushooks.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
- * </xi:include>
- * </programlisting>
- * </example>
+ * 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
- * <xref linkend="gapplication-example-cmdline3"/> 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: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
+ * @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 <link
linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses";>D-Bus specification</link>.
+ * 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:
- * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
+ *
+ * |[
* static gboolean
* on_authorize_authenticated_peer (GDBusAuthObserver *observer,
* GIOStream *stream,
@@ -4507,7 +4494,7 @@
*
* return authorized;
* }
- * </programlisting></example>
+ * ]|
*/
@@ -4546,13 +4533,25 @@
* #GError, the only valid thing you can do with that #GDBusConnection is to
* free it with g_object_unref().
*
- * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * ## 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}
*
- * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * 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)
*
- * <example id="gdbus-unix-fd-client"><title>D-Bus UNIX File Descriptor
example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-unix-fd-client.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
*
- * <example id="gdbus-export"><title>Exporting a GObject</title><programlisting><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-export.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * 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:
* |[<!-- language="C" -->
- * /* 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: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
+ * @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.
*
- * <example id="gdbus-owning-names"><title>Simple application owning a
name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-own-name.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * 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.
*
- * <example id="gdbus-watching-names"><title>Simple application watching a
name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-watch-name.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * 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
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * [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 <xref linkend="gdbus-example-gdbus-codegen"/>
- * for how this can easily be done using the
- * <link linkend="gdbus-codegen">gdbus-codegen</link> 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
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * [thread-default main context][g-main-context-push-thread-default]
* of the thread where the instance was constructed.
*
- * <example id="gdbus-wellknown-proxy"><title>GDBusProxy for a
well-known-name</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-watch-proxy.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * 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().
*
- * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text"
href="../../../../gio/tests/gdbus-example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE
CONTENT</xi:fallback></xi:include></programlisting></example>
+ * 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 `<gio/gdesktopappinfo.h>` belongs to the UNIX-specific
* GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*/
@@ -5055,13 +5057,11 @@
* (see #GInputStream and #GOutputStream).
*
* To construct a #GFile, you can use:
- * <simplelist>
- * <member>g_file_new_for_path() if you have a path.</member>
- * <member>g_file_new_for_uri() if you have a URI.</member>
- * <member>g_file_new_for_commandline_arg() for a command line argument.</member>
- * <member>g_file_new_tmp() to create a temporary file from a template.</member>
- * <member>g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().</member>
- * </simplelist>
+ * - 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:
- * <simplelist>
- * <member>g_file_mount_mountable() to mount a mountable file.</member>
- * <member>g_file_unmount_mountable_with_operation() to unmount a mountable file.</member>
- * <member>g_file_eject_mountable_with_operation() to eject a mountable file.</member>
- * </simplelist>
+ * - 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).
*
- * <para>
- * <table>
- * <title>GFileAttributes Default Namespaces</title>
- * <tgroup cols='2' align='left'><thead>
- * <row><entry>Namspace</entry><entry>Description</entry></row>
- * </thead>
- * <tbody>
- * <row><entry>"standard"</entry><entry>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.</entry></row>
- * <row><entry>"etag"</entry><entry>The <link linkend="gfile-etag">"Entity Tag"</link>
- * namespace. Currently, the only key in this namespace is "value", which contains
- * the value of the current entity tag.</entry></row>
- * <row><entry>"id"</entry><entry>The "Identification" namespace. This
- * namespace is used by file managers and applications that list directories
- * to check for loops and to uniquely identify files.</entry></row>
- * <row><entry>"access"</entry><entry>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.</entry></row>
- * <row><entry>"mountable"</entry><entry>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.</entry></row>
- * <row><entry>"time"</entry><entry>The "Time" namespace. Includes file
- * access, changed, created times. </entry></row>
- * <row><entry>"unix"</entry><entry>The "Unix" namespace. Includes UNIX-specific
- * information and may not be available for all files. Examples include
- * the UNIX "UID", "GID", etc.</entry></row>
- * <row><entry>"dos"</entry><entry>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.</entry></row>
- * <row><entry>"owner"</entry><entry>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.</entry></row>
- * <row><entry>"thumbnail"</entry><entry>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.</entry></row>
- * <row><entry>"filesystem"</entry><entry>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.</entry></row>
- * <row><entry>"gvfs"</entry><entry>The "GVFS" namespace. Keys in this namespace
- * contain information about the current GVFS backend in use. </entry></row>
- * <row><entry>"xattr"</entry><entry>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.</entry></row>
- * <row><entry>"xattr-sys"</entry><entry>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.</entry></row>
- * <row><entry>"selinux"</entry><entry>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.</entry></row>
- * </tbody>
- * </tgroup>
- * </table>
- * </para>
+ * ## 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 @@
* <!-- TODO: Implementation note about using extended attributes on supported
* file systems -->
*
- * <para><table>
- * <title>GFileAttributes Built-in Keys and Value Types</title>
- * <tgroup cols='3' align='left'><thead>
- * <row><entry>Enum Value</entry><entry>Namespace::Key</entry><entry>Value Type</entry></row>
- * </thead><tbody>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_TYPE</entry><entry>standard::type</entry><entry>uint32
(#GFileType)</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN</entry><entry>standard::is-hidden</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP</entry><entry>standard::is-backup</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK</entry><entry>standard::is-symlink</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL</entry><entry>standard::is-virtual</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_NAME</entry><entry>standard::name</entry><entry>byte
string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME</entry><entry>standard::display-name</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME</entry><entry>standard::edit-name</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_STANDARD_ICON</entry><entry>standard::icon</entry><entry>object
(#GIcon)</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE</entry><entry>standard::content-type</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE</entry><entry>standard::fast-content-type</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_SIZE</entry><entry>standard::size</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE</entry><entry>standard::allocated-size</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET</entry><entry>standard::symlink-target</entry><entry>byte
string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_TARGET_URI</entry><entry>standard::target-uri</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER</entry><entry>standard::sort-order</entry><entry>int32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ETAG_VALUE</entry><entry>etag::value</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_ID_FILE</entry><entry>id::file</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_ID_FILESYSTEM</entry><entry>id::filesystem</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_READ</entry><entry>access::can-read</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE</entry><entry>access::can-write</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE</entry><entry>access::can-execute</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE</entry><entry>access::can-delete</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH</entry><entry>access::can-trash</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME</entry><entry>access::can-rename</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT</entry><entry>mountable::can-mount</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT</entry><entry>mountable::can-unmount</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT</entry><entry>mountable::can-eject</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE</entry><entry>mountable::unix-device</entry><entry>uint32</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE</entry><entry>mountable::unix-device-file</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI</entry><entry>mountable::hal-udi</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED</entry><entry>time::modified</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC</entry><entry>time::modified-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS</entry><entry>time::access</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC</entry><entry>time::access-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED</entry><entry>time::changed</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_TIME_CHANGED_USEC</entry><entry>time::changed-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED</entry><entry>time::created</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_TIME_CREATED_USEC</entry><entry>time::created-usec</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_DEVICE</entry><entry>unix::device</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_INODE</entry><entry>unix::inode</entry><entry>uint64</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_MODE</entry><entry>unix::mode</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_NLINK</entry><entry>unix::nlink</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_UID</entry><entry>unix::uid</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_GID</entry><entry>unix::gid</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_RDEV</entry><entry>unix::rdev</entry><entry>uint32</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE</entry><entry>unix::block-size</entry><entry>uint32</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_UNIX_BLOCKS</entry><entry>unix::blocks</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT</entry><entry>unix::is-mountpoint</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE</entry><entry>dos::is-archive</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_DOS_IS_SYSTEM</entry><entry>dos::is-system</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_OWNER_USER</entry><entry>owner::user</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_OWNER_USER_REAL</entry><entry>owner::user-real</entry><entry>string</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_OWNER_GROUP</entry><entry>owner::group</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_PATH</entry><entry>thumbnail::path</entry><entry>bytestring</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_THUMBNAILING_FAILED</entry><entry>thumbnail::failed</entry><entry>boolean</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID</entry><entry>thumbnail::is-valid</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_PREVIEW_ICON</entry><entry>preview::icon</entry><entry>object
(#GIcon)</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_SIZE</entry><entry>filesystem::size</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_FREE</entry><entry>filesystem::free</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_USED</entry><entry>filesystem::used</entry><entry>uint64</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_TYPE</entry><entry>filesystem::type</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_FILESYSTEM_READONLY</entry><entry>filesystem::readonly</entry><entry>boolean</entry></row>
- * <row><entry>%G_FILE_ATTRIBUTE_GVFS_BACKEND</entry><entry>gvfs::backend</entry><entry>string</entry></row>
- *
<row><entry>%G_FILE_ATTRIBUTE_SELINUX_CONTEXT</entry><entry>selinux::context</entry><entry>string</entry></row>
- * </tbody></tgroup></table></para>
+ * ## 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 `<gio/gfiledescriptorbased.h>` belongs to the UNIX-specific
* GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*
@@ -5378,14 +5300,14 @@
* SECTION:gfileinfo
* @short_description: File Information and Attributes
* @include: gio/gio.h
- * @see_also: #GFile, <link linkend="gio-GFileAttribute">GFileAttribute</link>
+ * @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 <link linkend="gio-GFileAttribute">GFileAttribute</link> 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link> 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
- * <xref linkend="menu-example"/>.
+ * 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)
*
- * <xref linkend="menu-model"/> 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 @@
*
* 
*
- * Notice that the separators visible in <xref linkend="menu-example"/>
- * appear nowhere in <xref linkend="menu-model"/>. 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
- * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
- * and the
- * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
- * 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 `<gio/gnetworking.h>` header can be included to get
* various low-level networking-related system headers, automatically
* taking care of certain portability issues for you.
*
@@ -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
- * <em>is</em> 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 <link linkend="glib-compile-resources">glib-compile-resources</link> 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 <link linkend="glib-compile-resources">glib-compile-resources</link>
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 <link linkend="glib-compile-resources">glib-compile-resources</link> 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 <schemalist> or <schema>
* elements and the category that is specified in the l10n attribute of
- * the <key> element.
+ * the <key> element.
*
* GSettings uses schemas in a compact binary form that is created
- * by the <link linkend="glib-compile-schemas">glib-compile-schemas</link>
+ * 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 <link linkend="glib-compile-schemas">glib-compile-schemas</link>
- * 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 <schema> element). The convention for schema
* ids is to use a dotted name, similar in style to a D-Bus bus name,
* e.g. "org.gnome.SessionManager". In particular, if the settings are
* for a specific service that owns a D-Bus bus name, the D-Bus bus name
@@ -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
- * <xref linkend="schema-enumerated"/>. The underlying type of
- * such a key is string, but you can use g_settings_get_enum(),
- * g_settings_set_enum(), g_settings_get_flags(), g_settings_set_flags()
- * access the numeric values corresponding to the string value of enum
- * and flags keys.
+ * enumerated types. These can be described by a <choice>,
+ * <enum> or <flags> 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,
- * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
- * so-called 'vendor override' files. These are keyfiles in the same
- * directory as the XML schema sources which can override default values.
- * The schema id serves as the group name in the key file, and the values
- * are expected in serialized GVariant form, as in the following example:
+ * [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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link>. 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, <link linkend="gio-gnetworking.h">gnetworking.h</link>
+ * @see_also: #GInitable, [<gnetworking.h>][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 <link
- * linkend="g-main-context-push-thread-default-context">thread-default
- * context</link> 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 <link
- * linkend="io-priority">I/O priority</link> when starting a new
- * subtask, so you don't have to keep track of them yourself.
- * g_task_attach_source() simplifies the case of waiting for a
- * source to fire (automatically using the correct #GMainContext
- * and priority).
+ * 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:
* |[<!-- language="C" -->
@@ -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
- * <link linkend="io-priority">priority</link>, #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 `<gio/gunixconnection.h>` belongs to the UNIX-specific
* GIO interfaces, thus you have to use the `gio-unix-2.0.pc`
* pkg-config file when using it.
*
@@ -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 `<gio/gunixfdlist.h>` belongs to the UNIX-specific GIO
* interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*/
@@ -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 `<gio/gunixfdmessage.h>` belongs to the UNIX-specific GIO
* interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*/
@@ -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 `<gio/gunixinputstream.h>` belongs to the UNIX-specific GIO
* interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*/
@@ -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 `<gio/gunixmounts.h>` belongs to the UNIX-specific GIO
* interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config
* file when using it.
*/
@@ -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 `<gio/gunixoutputstream.h>` belongs to the UNIX-specific GIO
* interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
* when using it.
*/
@@ -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 `<gio/gunixsocketaddress.h>` belongs to the UNIX-specific GIO
* interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file
* when using it.
*/
@@ -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 <link
- * linkend="g-main-context-push-thread-default">thread-default-context
- * aware</link>, 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 `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO
* interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
* when using it.
*/
@@ -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 `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO
* interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file
* when using it.
*/
@@ -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 <literal>--display=</literal>
- * or <literal>--gdk-debug=</literal> 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 <literal>--version</literal>, where an immediate reply from
- * the local process is desired (instead of communicating with an
- * already-running instance). A #GApplication::handle-local-options
- * handler can stop further processing by returning a non-negative
- * value, which then becomes the exit status of the process.
+ * 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
- * <xref linkend="gapplication-example-cmdline2"/> 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <xref linkend="gdbus-owning-names"/>.
+ * 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <xref
- * linkend="gdbus-watching-names"/>. 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <link linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <xref linkend="gdbus-server"/> 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <xref linkend="gdbus-subtree-server"/> 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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> 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 <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * 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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> 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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> 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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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:
- * <table frame='all'>
- * <title>#GValue / #GVariant conversion rules</title>
- * <tgroup cols='2' align='left' colsep='1' rowsep='1'>
- * <thead>
- * <row>
- * <entry>If the #GType for @gvalue is...</entry>
- * <entry>... then @type must be</entry>
- * </row>
- * </thead>
- * <tbody>
- * <row>
- * <entry>#G_TYPE_STRING</entry>
- * <entry><link linkend="G-VARIANT-TYPE-STRING:CAPS">'s'</link>, <link
linkend="G-VARIANT-TYPE-OBJECT-PATH:CAPS">'o'</link>, <link
linkend="G-VARIANT-TYPE-SIGNATURE:CAPS">'g'</link> or <link
linkend="G-VARIANT-TYPE-BYTESTRING:CAPS">'ay'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_STRV</entry>
- * <entry><link linkend="G-VARIANT-TYPE-STRING-ARRAY:CAPS">'as'</link>, <link
linkend="G-VARIANT-TYPE-OBJECT-PATH-ARRAY:CAPS">'ao'</link> or <link
linkend="G-VARIANT-TYPE-BYTESTRING-ARRAY:CAPS">'aay'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_BOOLEAN</entry>
- * <entry><link linkend="G-VARIANT-TYPE-BOOLEAN:CAPS">'b'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_UCHAR</entry>
- * <entry><link linkend="G-VARIANT-TYPE-BYTE:CAPS">'y'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_INT</entry>
- * <entry><link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link> or <link
linkend="G-VARIANT-TYPE-INT16:CAPS">'n'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_UINT</entry>
- * <entry><link linkend="G-VARIANT-TYPE-UINT32:CAPS">'u'</link> or <link
linkend="G-VARIANT-TYPE-UINT16:CAPS">'q'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_INT64</entry>
- * <entry><link linkend="G-VARIANT-TYPE-INT64:CAPS">'x'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_UINT64</entry>
- * <entry><link linkend="G-VARIANT-TYPE-UINT64:CAPS">'t'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_DOUBLE</entry>
- * <entry><link linkend="G-VARIANT-TYPE-DOUBLE:CAPS">'d'</link></entry>
- * </row>
- * <row>
- * <entry>#G_TYPE_VARIANT</entry>
- * <entry>Any #GVariantType</entry>
- * </row>
- * </tbody>
- * </tgroup>
- * </table>
+ *
+ * - #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 <link linkend="G-VARIANT-TYPE-INT32:CAPS">'i'</link>. 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 <link linkend="G-VARIANT-TYPE-VARDICT:CAPS">'a{sv}'</link>.
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 <xref linkend="gdbus-server"/> and <xref
- * linkend="gdbus-unix-fd-client"/> 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.
+ * <node> element.
*
* Note that this routine is using a
- * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-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
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * [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
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * [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
- * <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
+ * [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 <xref linkend="gdbus-wellknown-proxy"/> 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 <xref linkend="gdbus-wellknown-proxy"/> 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 <xref linkend="gdbus-wellknown-proxy"/> 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 <xref linkend="gdbus-wellknown-proxy"/> 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 <xref linkend="gdbus-peer-to-peer"/> 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 <link linkend="io-priority">I/O priority</link>
- * 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:
- * <table>
- * <title>File Attribute Matcher strings and results</title>
- * <tgroup cols='2' align='left'><thead>
- * <row><entry> Matcher String </entry><entry> Matches </entry></row></thead>
- * <tbody>
- * <row><entry>"*"</entry><entry>matches all attributes.</entry></row>
- * <row><entry>"standard::is-hidden"</entry><entry>matches only the key is-hidden in the standard
namespace.</entry></row>
- * <row><entry>"standard::type,unix::*"</entry><entry>matches the type key in the standard namespace and
- * all keys in the unix namespace.</entry></row>
- * </tbody></tgroup>
- * </table>
+ * ## 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">io priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="gio-GFileAttribute">GFileAttribute</link>s
+ * 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 <link linkend="gfile-etag">entity tag</link> 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 <link linkend="gio-GContentType">GContentType</link>.
+ * @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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="gio-GIOScheduler">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link>).
+ * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="gio-GIOScheduler">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="gfile-etag">entity tag</link>
+ * @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 <link linkend="gfile-etag">entity tag</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="gfile-etag">entity tag</link>
- * 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 <link linkend="gfile-etag">entity tag</link>
+ * @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 <link linkend="gfile-etag">entity tag</link> 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 <link linkend="gfile-etag">entity tag</link> 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 <link linkend="gfile-etag">entity tag</link>
+ * @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 <link linkend="gfile-etag">entity tag</link>
+ * @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 <link linkend="gfile-etag">entity tag</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link
- * linkend="g-main-context-push-thread-default-context">thread-default
- * contexts</link>. 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 <link linkend="io-priority">I/O priority</link>
- * 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`).
@@ -23945,6 +23782,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 "<literal>%</literal>").
+ *
+ * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be
+ * parsed.
+ * Since: 2.40
+ */
+
+
+/**
* g_initable_init:
* @initable: a #GInitable.
* @cancellable: optional #GCancellable object, %NULL to ignore.
@@ -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 <xref linkend="ginitable"/> 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
+ * @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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
+ * @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).
*
* |[<!-- language="C" -->
- * /* 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 `<protocol>://[user[:password] ]host:port` or
+ * `direct://`, where <protocol> could be http, rtsp, socks
* or other proxying protocol.
*
* If you don't know what network protocol is being used on the
@@ -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 <child> 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
- * <link linkend="glib-compile-schemas">glib-compile-schemas</link> 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * loop</link> 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 <link linkend="gio-gnetworking.h">`<gio/gnetworking.h>`</link>
+ * The [<gio/gnetworking.h>][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 <link linkend="gio-gnetworking.h">`<gio/gnetworking.h>`</link>
+ * The [<gio/gnetworking.h>][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
- * <link linkend="glib-compile-resources">glib-compile-resources</link>
+ * [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
- * <link linkend="glib-compile-resources">glib-compile-resources</link>
+ * [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
- * <link linkend="glib-compile-resources">glib-compile-resources</link>
+ * [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 <link
- * linkend="io-priority">priority</link>, 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link> 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 <link
- * linkend="g-main-context-push-thread-default">thread-default main
- * context</link>.
+ * 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 <link linkend="io-priority">priority</link>
- * 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 <link linkend="io-priority">I/O priority</link>
- * 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 <link linkend="volume-identifier">identifiers</link>
- * 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
* |[<!-- language="C" -->
@@ -38003,8 +37852,8 @@
* @kind: the kind of identifier to return
*
* Gets the identifier of the given kind for @volume.
- * See the <link linkend="volume-identifier">introduction</link>
- * 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 a68339e..31029d8 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 <link
- * linkend="glib-Keyed-Data-Lists">Keyed Data List</link>. 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
- * <link linkend="glib-Hash-Tables">Hash Table</link>. 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 <link
- * linkend="glib-Type-Conversion-Macros">Type Conversion
- * Macros</link>.
+ * 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
- * <link linkend="glib-N-ary-Trees">N-ary Tree</link>. 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 <link
- * linkend="glib-Type-Conversion-Macros">Type Conversion
- * Macros</link>.
+ * 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
- * <link linkend="glib-Sequences">Sequence</link> 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.
- * <informalfigure>
- * <mediaobject>
- * <imageobject>
- * <imagedata align="right" fileref="Sorted_binary_tree_inorder.svg" format="SVG"/>
- * </imageobject>
- * <caption>In order: A, B, C, D, E, F, G, H, I</caption>
- * </mediaobject>
- * </informalfigure>
* @G_PRE_ORDER: visits a node, then its children.
- * <informalfigure>
- * <mediaobject>
- * <imageobject>
- * <imagedata align="right" fileref="Sorted_binary_tree_preorder.svg" format="SVG"/>
- * </imageobject>
- * <caption>Pre order: F, B, A, D, C, E, G, I, H</caption>
- * </mediaobject>
- * </informalfigure>
* @G_POST_ORDER: visits the node's children, then the node itself.
- * <informalfigure>
- * <mediaobject>
- * <imageobject>
- * <imagedata align="right" fileref="Sorted_binary_tree_postorder.svg" format="SVG"/>
- * </imageobject>
- * <caption>Post order: A, C, E, D, B, H, I, G, F</caption>
- * </mediaobject>
- * </informalfigure>
- * @G_LEVEL_ORDER: is not implemented for <link
- * linkend="glib-Balanced-Binary-Trees">Balanced Binary
- * Trees</link>. For <link
- * linkend="glib-N-ary-Trees">N-ary Trees</link>, 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.
- * <informalfigure>
- * <mediaobject>
- * <imageobject>
- * <imagedata align="right" fileref="Sorted_binary_tree_breadth-first_traversal.svg"
format="SVG"/>
- * </imageobject>
- * <caption>Level order: F, B, G, A, D, I, C, E, H</caption>
- * </mediaobject>
- * </informalfigure>
+ * @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
+ * 
+ * - Pre order: F, B, A, D, C, E, G, I, H
+ * 
+ * - Post order: A, C, E, D, B, H, I, G, F
+ * 
+ * - Level order: F, B, G, A, D, I, C, E, H
+ * 
*/
/**
* GTree:
*
- * The GTree struct is an opaque data structure representing a <link
- * linkend="glib-Balanced-Binary-Trees">Balanced Binary Tree</link>.
- * It should be accessed only by using the following functions.
+ * 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.
*
- * <example>
- * <title>Using stack-allocated #GVariantDict</title>
- * <programlisting>
+ * ## 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);
* }
- * </programlisting>
- * </example>
+ * ]|
+ *
+ * ## Using heap-allocated GVariantDict
*
- * <example>
- * <title>Using heap-allocated #GVariantDict</title>
- * <programlisting>
+ * |[
* 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;
* }
- * </programlisting>
- * </example>
+ * ]|
*
* 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 @@
* |[<!-- language="C" -->
* static GPrivate name_key = G_PRIVATE_INIT (g_free);
*
- * /* return value should not be freed */
+ * // return value should not be freed
* const gchar *
* get_local_name (void)
* {
@@ -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 @@
* |[<!-- language="C" -->
* GArray *garray;
* gint i;
- * /* We create a new array to store gint values.
- * * We don't want it zero-terminated or cleared to 0's.
- * */
+ * // We create a new array to store gint values.
+ * // We don't want it zero-terminated or cleared to 0's.
* garray = g_array_new (FALSE, FALSE, sizeof (gint));
* for (i = 0; i < 10000; i++)
* 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
+ * <xbel> root element; each bookmark is stored inside a
+ * <bookmark> element, using its URI: no relative paths can
* be used inside a bookmark file. The bookmark may have a user defined
* title and description, to be used instead of the URI. Under the
- * <metadata> element, with its owner attribute set to
+ * <metadata> element, with its owner attribute set to
* `http://freedesktop.org`, is stored the meta-data about a resource
* pointed by its URI. The meta-data consists of the resource's MIME
* type; the applications that have registered a bookmark; the groups
@@ -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,
- * <programlisting>
+ * |[
* Character: P r e s e n t a c i ó n . s x i
* Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
- * </programlisting>
+ * ]|
* However, if the application use UTF-8, the actual file name on
* disk would look like this:
- * <programlisting id="filename-utf-8">
+ * |[
* Character: P r e s e n t a c i ó n . s x i
* Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
- * </programlisting>
+ * ]|
* 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 <link
- * linkend="G_FILENAME_ENCODING">`G_FILENAME_ENCODING`</link>
+ * 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`
- * <programlisting>
+ * |[
* export G_FILENAME_ENCODING=ISO-8859-1
- * </programlisting>
+ * ]|
* 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.
- * <xref linkend="file-name-encodings-diagram"/> 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:
* |[<!-- language="C" -->
- * 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 <NAMESPACE>_<MODULE>_ERROR,
* for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
* |[<!-- language="C" -->
* #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,
+ * <namespace>_<module>_error_quark,
* for example g_spawn_error_quark() or g_thread_error_quark().
*
* - The error codes are in an enumeration called
- * <Namespace><Module>Error;
- * for example,#GThreadError or #GSpawnError.
+ * <Namespace><Module>Error;
+ * for example, #GThreadError or #GSpawnError.
*
* - Members of the error code enumeration are called
- * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
+ * <NAMESPACE>_<MODULE>_ERROR_<CODE>,
* for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
*
* - If there's a "generic" or "unknown" error code for unrecoverable
* errors it doesn't make sense to distinguish with specific codes,
- * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
+ * it should be called <NAMESPACE>_<MODULE>_ERROR_FAILED,
* for example %G_SPAWN_ERROR_FAILED.
*
* Summary of rules for use of #GError:
@@ -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.
+ * <footnote><para>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.
+ * </para></footnote>
+ * If %FALSE is
* returned, the error must be set to a non-%NULL value.
+ * <footnote><para>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.</para></footnote>
*
* - 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: <xref linkend="glib-regex-syntax"/>
+ * @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:
- * <informaltable>
- * <tgroup cols='2'>
- * <tbody>
- * <row>
- * <entry>
- * <para>
- * <emphasis role='strong'>Character</emphasis>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * <emphasis role='strong'>Meaning</emphasis>
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * b
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * y
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BYTE; a byte.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * n
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * q
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * i
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * u
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * x
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * t
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * h
- * </para>
- * </entry>
- * <entry>
- * <para>
- * 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.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * d
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
- * floating point value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * s
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_STRING; a string.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * o
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_OBJECT_PATH; a string in
- * the form of a D-Bus object path.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * g
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_STRING; a string in the
- * form of a D-Bus type signature.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * ?
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BASIC; an indefinite type
- * that is a supertype of any of the basic types.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * v
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_VARIANT; a container type
- * that contain any other type of value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * a
- * </para>
- * </entry>
- * <entry>
- * <para>
- * 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.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * m
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used as a prefix on another type string to mean a "maybe", or
- * "nullable", version of that type; the type string "ms", for example,
- * is the type of a value that maybe contains a string, or maybe
- * contains nothing.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * ()
- * </para>
- * </entry>
- * <entry>
- * <para>
- * 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.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * r
- * </para>
- * </entry>
- * <entry>
- * <para>
- * 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.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * {}
- * </para>
- * </entry>
- * <entry>
- * <para>
- * 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.
- * </para>
- * <para>
- * The first type (the basic type) is the key type and the second
- * type is the value type. The reason that the first type is
- * restricted to being a basic type is so that it can easily be
- * hashed.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * *
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_ANY; the indefinite type
- * that is a supertype of all types. Note that, as with all type
- * strings, this character represents exactly one type. It
- * cannot be used inside of tuples to mean "any number of items".
- * </para>
- * </entry>
- * </row>
- * </tbody>
- * </tgroup>
- * </informaltable>
+ * - `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>`
+ * `<glib/gi18n.h>`. For use in a library, you must include
+ * `<glib/gi18n-lib.h>`
* after defining the %GETTEXT_PACKAGE macro suitably for your library:
* |[<!-- language="C" -->
* #define GETTEXT_PACKAGE "gtk20"
@@ -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 <link linkend="glib-The-Main-Event-Loop">main event
- * loop</link>. 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 <link
- * linkend="glib-The-Main-Event-Loop">main event loop</link> 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 <link
- * linkend="glib-Singly-Linked-Lists">#GSList</link> 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
- * <link linkend="glib-Double-ended-Queues">GQueue</link> instead.
+ * [GQueue][glib-Double-ended-Queues] instead.
*
* The data contained in each element can be either integer values, by
- * using one of the <link linkend="glib-Type-Conversion-Macros">Type
- * Conversion Macros</link>, 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 <link
- * linkend="glib-Memory-Slices">slice allocator</link>, 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 <link
- * linkend="glib-Doubly-Linked-Lists">Doubly-Linked Lists</link> 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 <link linkend="glib-Type-Conversion-Macros">Type
- * Conversion Macros</link>, 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 <link
- * linkend="glib-Memory-Slices">slice allocator</link>, 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 @@
* |[<!-- language="C" -->
* 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 <link
- * linkend="glib-Datasets">Datasets</link> and <link
- * linkend="glib-Keyed-Data-Lists">Keyed Data Lists</link>.
+ * 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 <link linkend="glib-Type-Conversion-Macros">Type
- * Conversion Macros</link>, 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 <link
- * linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
- * 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 `<glib/gprintf.h>` 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: <link linkend="gtester">gtester</link>,
- * <link linkend="gtester-report">gtester-report</link>
+ * @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:
* |[<!-- language="C" -->
* 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 <link linkend="setlocale">current locale</link>
- * 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
- * <link linkend="setlocale">locale</link>-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!
* |[<!-- language="C" -->
- * /* 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
- * <link linkend="setlocale">current locale</link>.
+ * [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 <link linkend="setlocale">current locale</link>.
+ * 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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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 <link linkend="setlocale">current
- * locale</link>; 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 <link linkend="setlocale">current
- * locale</link>. If `G_FILENAME_ENCODING` is not set, but
- * `G_BROKEN_FILENAMES` is, the character set of the current locale
- * is taken as the filename encoding. If neither environment variable
- * is set, UTF-8 is taken as the filename encoding, but the character
- * set of the current locale is also put in the list of encodings.
+ * 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.
*
* |[<!-- language="C" -->
- * /* 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.
*
* |[<!-- language="C" -->
- * /* 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 <link linkend="setlocale">current locale</link>. 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 <link linkend="setlocale">current locale</link> 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 <link linkend="gio">gio</link>-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 "(?P<X>a)?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 "(?P<X>a)?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
- * <link linkend="setlocale">current locale</link> 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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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>".
+ * "<a> <b> <c>" against the pattern "<.*>"
+ * you get "<a> <b> <c>".
*
* 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>".
+ * "<a> <b> <c>" against the pattern "<.*>;"
+ * you would obtain three matches: "<a> <b> <c>",
+ * "<a> <b>" and "<a>".
*
* 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<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 '\\'.
*
* 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 <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+ * 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
- * <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+ * 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 <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+ * 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
- * <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
- * variable, also see <link linkend="G_SLICE">G_SLICE</link> 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
- * <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
- * variable, also see <link linkend="G_SLICE">G_SLICE</link> 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
- * <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
- * variable, also see <link linkend="G_SLICE">G_SLICE</link> 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
- * <link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment
- * variable, also see <link linkend="G_SLICE">G_SLICE</link> 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
- * <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+ * 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 <link linkend="G_SLICE">G_SLICE=always-malloc</link>
+ * 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.
*
* |[<!-- language="C" -->
- * /* 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.
*
* |[<!-- language="C" -->
- * /* 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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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
- * <link linkend="string-precision">string precision pitfalls</link>
+ * [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
- * <link linkend="string-precision">string precision pitfalls</link>
+ * [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 (<code>)".
*/
@@ -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 (<signum>)".
*/
@@ -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
- * <link linkend="glib-Glob-style-pattern-matching">pattern</link>
+ * @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:
*
* |[<!-- language="C" -->
- * /* 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
- * <link linkend="glib-Glob-style-pattern-matching">pattern</link>
+ * @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
- * <link linkend="glib-Glob-style-pattern-matching">pattern</link>
+ * @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
- * <link linkend="glib-Glob-style-pattern-matching">pattern</link>
+ * @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
- * <link linkend="glib-Glob-style-pattern-matching">pattern</link>
+ * @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
- * <link linkend="glib-N-ary-Trees">N-ary Tree</link>.
+ * 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 <link linkend="setlocale">current locale</link>.
+ * 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
- * <link linkend="setlocale">current locale</link>.
+ * 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
- * <link linkend="setlocale">current locale</link>.
+ * 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 <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ * 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 <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ * 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
- * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ * @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 <link
- * linkend='gvariant-format-strings'>GVariant Format Strings</link>.
+ * 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
- * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ * [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
- * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ * [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
- * <link linkend='gvariant-serialised-data-memory'>Serialised Data
- * Memory</link>.
+ * [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:
- *
- * <informaltable>
- * <tgroup cols='2'>
- * <thead><row><entry>element type</entry> <entry>C type</entry></row></thead>
- * <tbody>
- * <row><entry>%G_VARIANT_TYPE_INT16 (etc.)</entry>
- * <entry>#gint16 (etc.)</entry></row>
- * <row><entry>%G_VARIANT_TYPE_BOOLEAN</entry>
- * <entry>#guchar (not #gboolean!)</entry></row>
- * <row><entry>%G_VARIANT_TYPE_BYTE</entry> <entry>#guchar</entry></row>
- * <row><entry>%G_VARIANT_TYPE_HANDLE</entry> <entry>#guint32</entry></row>
- * <row><entry>%G_VARIANT_TYPE_DOUBLE</entry> <entry>#gdouble</entry></row>
- * </tbody>
- * </tgroup>
- * </informaltable>
+ * - %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
- * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ * [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():
* |[<!-- language="C" -->
- * /* 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
- * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ * [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():
* |[<!-- language="C" -->
- * /* 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
- * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ * [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():
* |[<!-- language="C" -->
- * /* 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
- * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>.
+ * [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 <link linkend='gvariant-format-strings'>GVariant Format
- * Strings</link>. 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 <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ * the [GVariant varargs documentation][gvariant-varargs].
*
- * <programlisting>
+ * |[
* 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);
- * </programlisting>
+ * ]|
*
* 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 <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ * the [GVariant varargs documentation][gvariant-varargs].
*
* Consider this simple example:
* |[<!-- language="C" -->
@@ -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 <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ * 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 <link linkend='gvariant-varargs'>GVariant varargs documentation</link>.
+ * 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 <link linkend='gvariant-text'>here</link>.
+ * 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 <link linkend='gvariant-text'>here</link>.
+ * 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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * 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
- * <link linkend="string-precision">string precision pitfalls</link>.
+ * [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 83fd6a9..c1a66a5 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
- * <link linkend="glib-Dynamic-Loading-of-Modules">Dynamically-Loaded
- * Module</link>. 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
* |[<!-- language="C" -->
- * /* 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 b25b8d0..ea1dbc1 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
- * <link linkend="canonical-parameter-name">canonical</link> 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 <link
- * linkend="glib-mkenums">glib-mkenums</link> 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 <link
- * linkend="glib-genmarshal">glib-genmarshal</link> 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 <link
- * linkend="gobject-Standard-Parameter-and-Value-Types">Standard
- * Values API</link> 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 <xref
- * linkend="gobject-Signals"/>.
+ * support. Signals are described in detail [here][gobject-Signals].
*
* ## Floating references # {#floating-ref}
*
@@ -580,16 +577,18 @@
* the following sequence can be used:
*
* |[<!-- language="C" -->
- * /* 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 <link
- * linkend="glib-genmarshal">glib-genmarshal</link>) 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 @@
* |[<!-- language="C" -->
* 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 <link
- * linkend="glib-mkenums">glib-mkenums</link> 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 <link
- * linkend="glib-mkenums">glib-mkenums</link> 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
- * <link linkend="floating-ref">floating</link> 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 <link linkend="floating-ref">floating</link>
- * 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
- * <link linkend="floating-ref">floating</link> 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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
