[gobject-introspection] Update GLib annotations, using the improved annotation parser.
- From: Johan Dahlin <johan src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gobject-introspection] Update GLib annotations, using the improved annotation parser.
- Date: Thu, 5 Apr 2012 14:26:20 +0000 (UTC)
commit 5ab6a478f5fe7642090032e3345f8c884e15f5b7
Author: Dieter Verfaillie <dieterv optionexplicit be>
Date: Wed Apr 4 17:10:40 2012 +0200
Update GLib annotations, using the improved annotation parser.
https://bugzilla.gnome.org/show_bug.cgi?id=672254
gir/gio-2.0.c | 3700 +++++++++++++----------------------
gir/glib-2.0.c | 5572 +++++++++++++++++++++++------------------------------
gir/gobject-2.0.c | 1017 +++++------
3 files changed, 4209 insertions(+), 6080 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 16e1476..3a00434 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -261,9 +261,7 @@
* a commandline is not handled locally. See g_application_run() and
* the #GApplicationCommandLine documentation for more information.
*
- * process. See g_application_command_line_set_exit_status().
- *
- * Returns: An integer that is set as the exit status for the calling
+ * Returns: An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status().
*/
@@ -472,9 +470,7 @@
* from @source_value into the target property of @target
* using @target_value.
*
- * otherwise
- *
- * Returns: %TRUE if the transformation was successful, and %FALSE
+ * Returns: %TRUE if the transformation was successful, and %FALSE otherwise
* Since: 2.26
*/
@@ -691,27 +687,27 @@
*
* An example of how to us this:
* |[
- * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
- * if (g_cancellable_set_error_if_cancelled (cancellable))
- * return;
+ * /<!-- -->* Make sure we don't do any unnecessary work if already cancelled *<!-- -->/
+ * if (g_cancellable_set_error_if_cancelled (cancellable))
+ * return;
*
- * /<!-- -->* Set up all the data needed to be able to
- * * handle cancellation of the operation *<!-- -->/
- * my_data = my_data_new (...);
+ * /<!-- -->* Set up all the data needed to be able to
+ * * handle cancellation of the operation *<!-- -->/
+ * my_data = my_data_new (...);
*
- * id = 0;
- * if (cancellable)
- * id = g_cancellable_connect (cancellable,
- * G_CALLBACK (cancelled_handler)
- * data, NULL);
+ * id = 0;
+ * if (cancellable)
+ * id = g_cancellable_connect (cancellable,
+ * G_CALLBACK (cancelled_handler)
+ * data, NULL);
*
- * /<!-- -->* cancellable operation here... *<!-- -->/
+ * /<!-- -->* cancellable operation here... *<!-- -->/
*
- * g_cancellable_disconnect (cancellable, id);
+ * g_cancellable_disconnect (cancellable, id);
*
- * /<!-- -->* cancelled_handler is never called after this, it
- * * is now safe to free the data *<!-- -->/
- * my_data_free (my_data);
+ * /<!-- -->* cancelled_handler is never called after this, it
+ * * is now safe to free the data *<!-- -->/
+ * my_data_free (my_data);
* ]|
*
* Note that the cancelled signal is emitted in the thread that
@@ -803,19 +799,19 @@
* The initialization process of a class involves:
* <itemizedlist>
* <listitem><para>
- * 1 - Copying common members from the parent class over to the
- * derived class structure.
+ * 1 - Copying common members from the parent class over to the
+ * derived class structure.
* </para></listitem>
* <listitem><para>
- * 2 - Zero initialization of the remaining members not copied
- * over from the parent class.
+ * 2 - Zero initialization of the remaining members not copied
+ * over from the parent class.
* </para></listitem>
* <listitem><para>
- * 3 - Invocation of the GBaseInitFunc() initializers of all parent
- * types and the class' type.
+ * 3 - Invocation of the GBaseInitFunc() initializers of all parent
+ * types and the class' type.
* </para></listitem>
* <listitem><para>
- * 4 - Invocation of the class' GClassInitFunc() initializer.
+ * 4 - Invocation of the class' GClassInitFunc() initializer.
* </para></listitem>
* </itemizedlist>
* Since derived classes are partially initialized through a memory copy
@@ -833,45 +829,45 @@
*
* |[
* typedef struct {
- * GObjectClass parent_class;
- * gint static_integer;
- * gchar *dynamic_string;
+ * GObjectClass parent_class;
+ * gint static_integer;
+ * gchar *dynamic_string;
* } TypeAClass;
* static void
* type_a_base_class_init (TypeAClass *class)
* {
- * class->dynamic_string = g_strdup ("some string");
+ * class->dynamic_string = g_strdup ("some string");
* }
* static void
* type_a_base_class_finalize (TypeAClass *class)
* {
- * g_free (class->dynamic_string);
+ * g_free (class->dynamic_string);
* }
* static void
* type_a_class_init (TypeAClass *class)
* {
- * class->static_integer = 42;
+ * class->static_integer = 42;
* }
*
* typedef struct {
- * TypeAClass parent_class;
- * gfloat static_float;
- * GString *dynamic_gstring;
+ * TypeAClass parent_class;
+ * gfloat static_float;
+ * GString *dynamic_gstring;
* } TypeBClass;
* static void
* type_b_base_class_init (TypeBClass *class)
* {
- * class->dynamic_gstring = g_string_new ("some other string");
+ * class->dynamic_gstring = g_string_new ("some other string");
* }
* static void
* type_b_base_class_finalize (TypeBClass *class)
* {
- * g_string_free (class->dynamic_gstring);
+ * g_string_free (class->dynamic_gstring);
* }
* static void
* type_b_class_init (TypeBClass *class)
* {
- * class->static_float = 3.14159265358979323846;
+ * class->static_float = 3.14159265358979323846;
* }
* ]|
* Initialization of TypeBClass will first cause initialization of
@@ -1176,17 +1172,17 @@
* The cause of this event can be
* <itemizedlist>
* <listitem><para>
- * If g_dbus_connection_close() is called. In this case
- * @remote_peer_vanished is set to %FALSE and @error is %NULL.
+ * If g_dbus_connection_close() is called. In this case
+ * @remote_peer_vanished is set to %FALSE and @error is %NULL.
* </para></listitem>
* <listitem><para>
- * If the remote peer closes the connection. In this case
- * @remote_peer_vanished is set to %TRUE and @error is set.
+ * If the remote peer closes the connection. In this case
+ * @remote_peer_vanished is set to %TRUE and @error is set.
* </para></listitem>
* <listitem><para>
- * If the remote peer sends invalid or malformed data. In this
- * case @remote_peer_vanished is set to %FALSE and @error
- * is set.
+ * If the remote peer sends invalid or malformed data. In this
+ * case @remote_peer_vanished is set to %FALSE and @error
+ * is set.
* </para></listitem>
* </itemizedlist>
*
@@ -1342,8 +1338,48 @@
/**
* GDBusError:
+ * @G_DBUS_ERROR_FAILED: A generic error; "something went wrong" - see the error message for more.
+ * @G_DBUS_ERROR_NO_MEMORY: There was not enough memory to complete an operation.
+ * @G_DBUS_ERROR_SERVICE_UNKNOWN: The bus doesn't know how to launch a service to supply the bus name you wanted.
+ * @G_DBUS_ERROR_NAME_HAS_NO_OWNER: The bus name you referenced doesn't exist (i.e. no application owns it).
+ * @G_DBUS_ERROR_NO_REPLY: No reply to a message expecting one, usually means a timeout occurred.
+ * @G_DBUS_ERROR_IO_ERROR: Something went wrong reading or writing to a socket, for example.
+ * @G_DBUS_ERROR_BAD_ADDRESS: A D-Bus bus address was malformed.
+ * @G_DBUS_ERROR_NOT_SUPPORTED: Requested operation isn't supported (like ENOSYS on UNIX).
+ * @G_DBUS_ERROR_LIMITS_EXCEEDED: Some limited resource is exhausted.
+ * @G_DBUS_ERROR_ACCESS_DENIED: Security restrictions don't allow doing what you're trying to do.
+ * @G_DBUS_ERROR_AUTH_FAILED: Authentication didn't work.
+ * @G_DBUS_ERROR_NO_SERVER: Unable to connect to server (probably caused by ECONNREFUSED on a socket).
+ * @G_DBUS_ERROR_TIMEOUT: Certain timeout errors, possibly ETIMEDOUT on a socket. Note that %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also exists. We can't fix it for compatibility reasons so just be careful.
+ * @G_DBUS_ERROR_NO_NETWORK: No network access (probably ENETUNREACH on a socket).
+ * @G_DBUS_ERROR_ADDRESS_IN_USE: Can't bind a socket since its address is in use (i.e. EADDRINUSE).
+ * @G_DBUS_ERROR_DISCONNECTED: The connection is disconnected and you're trying to use it.
+ * @G_DBUS_ERROR_INVALID_ARGS: Invalid arguments passed to a method call.
+ * @G_DBUS_ERROR_FILE_NOT_FOUND: Missing file.
+ * @G_DBUS_ERROR_FILE_EXISTS: Existing file and the operation you're using does not silently overwrite.
+ * @G_DBUS_ERROR_UNKNOWN_METHOD: Method name you invoked isn't known by the object you invoked it on.
+ * @G_DBUS_ERROR_TIMED_OUT: Certain timeout errors, e.g. while starting a service. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We can't fix it for compatibility reasons so just be careful.
+ * @G_DBUS_ERROR_MATCH_RULE_NOT_FOUND: Tried to remove or modify a match rule that didn't exist.
+ * @G_DBUS_ERROR_MATCH_RULE_INVALID: The match rule isn't syntactically valid.
+ * @G_DBUS_ERROR_SPAWN_EXEC_FAILED: While starting a new process, the exec() call failed.
+ * @G_DBUS_ERROR_SPAWN_FORK_FAILED: While starting a new process, the fork() call failed.
+ * @G_DBUS_ERROR_SPAWN_CHILD_EXITED: While starting a new process, the child exited with a status code.
+ * @G_DBUS_ERROR_SPAWN_CHILD_SIGNALED: While starting a new process, the child exited on a signal.
+ * @G_DBUS_ERROR_SPAWN_FAILED: While starting a new process, something went wrong.
+ * @G_DBUS_ERROR_SPAWN_SETUP_FAILED: We failed to setup the environment correctly.
+ * @G_DBUS_ERROR_SPAWN_CONFIG_INVALID: We failed to setup the config parser correctly.
+ * @G_DBUS_ERROR_SPAWN_SERVICE_INVALID: Bus name was not valid.
+ * @G_DBUS_ERROR_SPAWN_SERVICE_NOT_FOUND: Service file not found in system-services directory.
+ * @G_DBUS_ERROR_SPAWN_PERMISSIONS_INVALID: Permissions are incorrect on the setuid helper.
+ * @G_DBUS_ERROR_SPAWN_FILE_INVALID: Service file invalid (Name, User or Exec missing).
+ * @G_DBUS_ERROR_SPAWN_NO_MEMORY: Tried to get a UNIX process ID and it wasn't available.
+ * @G_DBUS_ERROR_UNIX_PROCESS_ID_UNKNOWN: Tried to get a UNIX process ID and it wasn't available.
+ * @G_DBUS_ERROR_INVALID_SIGNATURE: A type signature is not valid.
+ * @G_DBUS_ERROR_INVALID_FILE_CONTENT: A file contains invalid syntax or is otherwise broken.
+ * @G_DBUS_ERROR_SELINUX_SECURITY_CONTEXT_UNKNOWN: Asked for SELinux security context and it wasn't available.
+ * @G_DBUS_ERROR_ADT_AUDIT_DATA_UNKNOWN: Asked for ADT audit data and it wasn't available.
+ * @G_DBUS_ERROR_OBJECT_PATH_IN_USE: There's already an object with the requested object path.
*
- * Certain timeout errors, e.g. while starting a service. Warning: this is
* Error codes for the %G_DBUS_ERROR error domain.
*
* Since: 2.26
@@ -1382,10 +1418,7 @@
*
* The type of the @get_property function in #GDBusInterfaceVTable.
*
- * @error is set. If the returned #GVariant is floating, it is
- * consumed - otherwise its reference count is decreased by one.
- *
- * Returns: A #GVariant with the value for @property_name or %NULL if
+ * Returns: A #GVariant with the value for @property_name or %NULL if @error is set. If the returned #GVariant is floating, it is consumed - otherwise its reference count is decreased by one.
* Since: 2.26
*/
@@ -1605,49 +1638,49 @@
* |[
* static GDBusMessage *
* passive_filter (GDBusConnection *connection
- * GDBusMessage *message,
- * gboolean incoming,
- * gpointer user_data)
+ * GDBusMessage *message,
+ * gboolean incoming,
+ * gpointer user_data)
* {
- * /<!-- -->* inspect @message *<!-- -->/
- * return message;
+ * /<!-- -->* inspect @message *<!-- -->/
+ * return message;
* }
* ]|
* Filter functions that wants to drop a message can simply return %NULL:
* |[
* static GDBusMessage *
* drop_filter (GDBusConnection *connection
- * GDBusMessage *message,
- * gboolean incoming,
- * gpointer user_data)
- * {
- * if (should_drop_message)
+ * GDBusMessage *message,
+ * gboolean incoming,
+ * gpointer user_data)
* {
- * g_object_unref (message);
- * message = NULL;
- * }
- * return message;
+ * if (should_drop_message)
+ * {
+ * g_object_unref (message);
+ * message = NULL;
+ * }
+ * return message;
* }
* ]|
* Finally, a filter function may modify a message by copying it:
* |[
* static GDBusMessage *
* modifying_filter (GDBusConnection *connection
- * GDBusMessage *message,
- * gboolean incoming,
- * gpointer user_data)
+ * GDBusMessage *message,
+ * gboolean incoming,
+ * gpointer user_data)
* {
- * GDBusMessage *copy;
- * GError *error;
+ * GDBusMessage *copy;
+ * GError *error;
*
- * error = NULL;
- * copy = g_dbus_message_copy (message, &error);
- * /<!-- -->* handle @error being is set *<!-- -->/
- * g_object_unref (message);
+ * error = NULL;
+ * copy = g_dbus_message_copy (message, &error);
+ * /<!-- -->* handle @error being is set *<!-- -->/
+ * g_object_unref (message);
*
- * /<!-- -->* modify @copy *<!-- -->/
+ * /<!-- -->* modify @copy *<!-- -->/
*
- * return copy;
+ * return copy;
* }
* ]|
* If the returned #GDBusMessage is different from @message and cannot
@@ -1657,10 +1690,7 @@
* check this ahead of time using g_dbus_message_to_blob() passing a
* #GDBusCapabilityFlags value obtained from @connection.
*
- * g_object_unref() or %NULL to drop the message. Passive filter
- * functions can simply return the passed @message object.
- *
- * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with
+ * Returns: (transfer full) (allow-none): A #GDBusMessage that will be freed with g_object_unref() or %NULL to drop the message. Passive filter functions can simply return the passed @message object.
* Since: 2.26
*/
@@ -2284,22 +2314,22 @@
*
* The checks performed are:
* <itemizedlist>
- * <listitem><para>
- * When completing a method call, if the type signature of
- * the reply message isn't what's expected, the reply is
- * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
- * </para></listitem>
- * <listitem><para>
- * Received signals that have a type signature mismatch are dropped and
- * a warning is logged via g_warning().
- * </para></listitem>
- * <listitem><para>
- * Properties received via the initial <literal>GetAll()</literal> call
- * or via the <literal>::PropertiesChanged</literal> signal (on the
- * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties";>org.freedesktop.DBus.Properties</ulink> interface) or
- * set using g_dbus_proxy_set_cached_property() with a type signature
- * mismatch are ignored and a warning is logged via g_warning().
- * </para></listitem>
+ * <listitem><para>
+ * When completing a method call, if the type signature of
+ * the reply message isn't what's expected, the reply is
+ * discarded and the #GError is set to %G_IO_ERROR_INVALID_ARGUMENT.
+ * </para></listitem>
+ * <listitem><para>
+ * Received signals that have a type signature mismatch are dropped and
+ * a warning is logged via g_warning().
+ * </para></listitem>
+ * <listitem><para>
+ * Properties received via the initial <literal>GetAll()</literal> call
+ * or via the <literal>::PropertiesChanged</literal> signal (on the
+ * <ulink url="http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties";>org.freedesktop.DBus.Properties</ulink> interface) or
+ * set using g_dbus_proxy_set_cached_property() with a type signature
+ * mismatch are ignored and a warning is logged via g_warning().
+ * </para></listitem>
* </itemizedlist>
* Note that these checks are never done on methods, signals and
* properties that are not referenced in the given
@@ -2388,10 +2418,7 @@
* <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
* that @manager was constructed in.
*
- * must be a #GDBusProxy<!-- -->- or #GDBusObjectProxy<!-- -->-derived
- * type.
- *
- * Returns: A #GType to use for the remote object. The returned type
+ * Returns: A #GType to use for the remote object. The returned type must be a #GDBusProxy<!-- -->- or #GDBusObjectProxy<!-- -->-derived type.
* Since: 2.30
*/
@@ -2444,9 +2471,7 @@
* that it's suitable to call g_dbus_connection_register_object() or
* similar from the signal handler.
*
- * run.
- *
- * Returns: %TRUE to claim @connection, %FALSE to let other handlers
+ * Returns: %TRUE to claim @connection, %FALSE to let other handlers run.
* Since: 2.26
*/
@@ -3515,9 +3540,7 @@
* Long-running jobs should periodically check the @cancellable
* to see if they have been cancelled.
*
- * complete the job, %FALSE if the job is complete (or cancelled)
- *
- * Returns: %TRUE if this function should be called again to
+ * Returns: %TRUE if this function should be called again to complete the job, %FALSE if the job is complete (or cancelled)
*/
@@ -3821,31 +3844,6 @@
/**
- * GLIB_CHECK_VERSION:
- * @major: the major version to check for
- * @minor: the minor version to check for
- * @micro: the micro version to check for
- *
- * Checks the version of the GLib library that is being compiled
- * against.
- *
- * <example>
- * <title>Checking the version of the GLib library</title>
- * <programlisting>
- * if (!GLIB_CHECK_VERSION (1, 2, 0))
- * g_error ("GLib version 1.2.0 or above is needed");
- * </programlisting>
- * </example>
- *
- * See glib_check_version() for a runtime check.
- *
- * is the same as or newer than the passed-in version.
- *
- * Returns: %TRUE if the version of the GLib header files
- */
-
-
-/**
* GLIB_VERSION_2_26:
*
* A macro that evaluates to the 2.26 version of GLib, in a format
@@ -4507,22 +4505,22 @@
*
* static GObject*
* my_singleton_constructor (GType type,
- * guint n_construct_params,
- * GObjectConstructParam *construct_params)
- * {
- * GObject *object;
- *
- * if (!the_singleton)
+ * guint n_construct_params,
+ * GObjectConstructParam *construct_params)
* {
- * object = G_OBJECT_CLASS (parent_class)->constructor (type,
- * n_construct_params,
- * construct_params);
- * the_singleton = MY_SINGLETON (object);
- * }
- * else
- * object = g_object_ref (G_OBJECT (the_singleton));
- *
- * return object;
+ * GObject *object;
+ *
+ * if (!the_singleton)
+ * {
+ * object = G_OBJECT_CLASS (parent_class)->constructor (type,
+ * n_construct_params,
+ * construct_params);
+ * the_singleton = MY_SINGLETON (object);
+ * }
+ * else
+ * object = g_object_ref (G_OBJECT (the_singleton));
+ *
+ * return object;
* }
* </programlisting></example>
*/
@@ -4599,9 +4597,7 @@
* The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
* options.
*
- * occurred, in which case @error should be set with g_set_error()
- *
- * Returns: %TRUE if the option was successfully parsed, %FALSE if an error
+ * Returns: %TRUE if the option was successfully parsed, %FALSE if an error occurred, in which case @error should be set with g_set_error()
*/
@@ -4687,9 +4683,7 @@
*
* The type of function that can be called before and after parsing.
*
- * occurred, in which case @error should be set with g_set_error()
- *
- * Returns: %TRUE if the function completed successfully, %FALSE if an error
+ * Returns: %TRUE if the function completed successfully, %FALSE if an error occurred, in which case @error should be set with g_set_error()
*/
@@ -4739,7 +4733,7 @@
* @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8
* @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
* @G_PARAM_PRIVATE: internal
- * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26
+ * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since 2.26
*
* Through the #GParamFlags flag values, certain aspects of parameters
* can be configured.
@@ -5132,9 +5126,7 @@
* Specifies the type of function passed to g_main_context_set_poll_func().
* The semantics of the function should match those of the poll() system call.
*
- * reported, or -1 if an error occurred.
- *
- * Returns: the number of #GPollFD elements which have events or errors
+ * Returns: the number of #GPollFD elements which have events or errors reported, or -1 if an error occurred.
*/
@@ -5269,7 +5261,9 @@
/**
* GProxyResolver:
*
- * Interface that can be used to resolve proxy address.
+ * A helper class to enumerate proxies base on URI.
+ *
+ * Since: 2.26
*/
@@ -5317,7 +5311,8 @@
* @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
* @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
* @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
+ * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
+ * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
* @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
* @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
* @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
@@ -5522,7 +5517,7 @@
/**
* GSettings::change-event:
* @settings: the object on which the signal was emitted
- * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL
+ * @keys: (array length=n_keys) (element-type GQuark) (allow-none): an array of #GQuark<!-- -->s for the changed keys, or %NULL
* @n_keys: the length of the @keys array, or 0
*
* The "change-event" signal is emitted once per change event that
@@ -5541,9 +5536,7 @@
* for each affected key. If any other connected handler returns
* %TRUE then this default functionality will be suppressed.
*
- * event. FALSE to propagate the event further.
- *
- * Returns: %TRUE to stop other handlers from being invoked for the
+ * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
*/
@@ -5586,9 +5579,7 @@
* connected handler returns %TRUE then this default functionality
* will be suppressed.
*
- * event. FALSE to propagate the event further.
- *
- * Returns: %TRUE to stop other handlers from being invoked for the
+ * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.
*/
@@ -5652,8 +5643,7 @@
* 'settings-schema' property if you wish to pass in a
* #GSettingsSchema.
*
- * Deprecated:2.32:Use the 'schema-id' property instead. In a future
- * version, this property may instead refer to a #GSettingsSchema.
+ * Deprecated: 2.32:Use the 'schema-id' property instead. In a future version, this property may instead refer to a #GSettingsSchema.
*/
@@ -5723,9 +5713,7 @@
* The type for the function that is used to convert an object property
* value to a #GVariant for storing it in #GSettings.
*
- * or %NULL in case of an error
- *
- * Returns: a new #GVariant holding the data from @value,
+ * Returns: a new #GVariant holding the data from @value, or %NULL in case of an error
*/
@@ -5782,10 +5770,7 @@
* values is performed. The return value of signal emissions is then the
* value returned by the last callback.
*
- * should be aborted. Returning %FALSE means to abort the
- * current emission and %TRUE is returned for continuation.
- *
- * Returns: The accumulator function returns whether the signal emission
+ * Returns: The accumulator function returns whether the signal emission should be aborted. Returning %FALSE means to abort the current emission and %TRUE is returned for continuation.
*/
@@ -5822,9 +5807,7 @@
*
* You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
*
- * hook is disconnected (and destroyed).
- *
- * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
+ * Returns: whether it wants to stay connected. If it returns %FALSE, the signal hook is disconnected (and destroyed).
*/
@@ -5923,16 +5906,16 @@
* <programlisting>
* static void
* change_volume_state (GSimpleAction *action,
- * GVariant *value,
- * gpointer user_data)
+ * GVariant *value,
+ * gpointer user_data)
* {
- * gint requested;
+ * gint requested;
*
- * requested = g_variant_get_int32 (value);
+ * requested = g_variant_get_int32 (value);
*
- * // Volume only goes from 0 to 10
- * if (0 <= requested && requested <= 10)
- * g_simple_action_set_state (action, value);
+ * // Volume only goes from 0 to 10
+ * if (0 <= requested && requested <= 10)
+ * g_simple_action_set_state (action, value);
* }
* </programlisting>
* </example>
@@ -6103,7 +6086,7 @@
/**
* GSocketClient:
*
- * A helper class for network servers to listen for and accept connections.
+ * A helper class for network clients to make connections.
*
* Since: 2.22
*/
@@ -6122,77 +6105,77 @@
* the different @event values are as follows:
*
* <variablelist>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_RESOLVING:</term>
- * <listitem><para>
- * @client is about to look up @connectable in DNS.
- * @connection will be %NULL.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_RESOLVED:</term>
- * <listitem><para>
- * @client has successfully resolved @connectable in DNS.
- * @connection will be %NULL.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_CONNECTING:</term>
- * <listitem><para>
- * @client is about to make a connection to a remote host;
- * either a proxy server or the destination server itself.
- * @connection is the #GSocketConnection, which is not yet
- * connected.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_CONNECTED:</term>
- * <listitem><para>
- * @client has successfully connected to a remote host.
- * @connection is the connected #GSocketConnection.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
- * <listitem><para>
- * @client is about to negotiate with a proxy to get it to
- * connect to @connectable. @connection is the
- * #GSocketConnection to the proxy server.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
- * <listitem><para>
- * @client has negotiated a connection to @connectable through
- * a proxy server. @connection is the stream returned from
- * g_proxy_connect(), which may or may not be a
- * #GSocketConnection.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
- * <listitem><para>
- * @client is about to begin a TLS handshake. @connection is a
- * #GTlsClientConnection.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
- * <listitem><para>
- * @client has successfully completed the TLS handshake.
- * @connection is a #GTlsClientConnection.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>%G_SOCKET_CLIENT_COMPLETE:</term>
- * <listitem><para>
- * @client has either successfully connected to @connectable
- * (in which case @connection is the #GSocketConnection that
- * it will be returning to the caller) or has failed (in which
- * case @connection is %NULL and the client is about to return
- * an error).
- * </para></listitem>
- * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_RESOLVING:</term>
+ * <listitem><para>
+ * @client is about to look up @connectable in DNS.
+ * @connection will be %NULL.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_RESOLVED:</term>
+ * <listitem><para>
+ * @client has successfully resolved @connectable in DNS.
+ * @connection will be %NULL.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_CONNECTING:</term>
+ * <listitem><para>
+ * @client is about to make a connection to a remote host;
+ * either a proxy server or the destination server itself.
+ * @connection is the #GSocketConnection, which is not yet
+ * connected.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_CONNECTED:</term>
+ * <listitem><para>
+ * @client has successfully connected to a remote host.
+ * @connection is the connected #GSocketConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATING:</term>
+ * <listitem><para>
+ * @client is about to negotiate with a proxy to get it to
+ * connect to @connectable. @connection is the
+ * #GSocketConnection to the proxy server.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_PROXY_NEGOTIATED:</term>
+ * <listitem><para>
+ * @client has negotiated a connection to @connectable through
+ * a proxy server. @connection is the stream returned from
+ * g_proxy_connect(), which may or may not be a
+ * #GSocketConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKING:</term>
+ * <listitem><para>
+ * @client is about to begin a TLS handshake. @connection is a
+ * #GTlsClientConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_TLS_HANDSHAKED:</term>
+ * <listitem><para>
+ * @client has successfully completed the TLS handshake.
+ * @connection is a #GTlsClientConnection.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%G_SOCKET_CLIENT_COMPLETE:</term>
+ * <listitem><para>
+ * @client has either successfully connected to @connectable
+ * (in which case @connection is the #GSocketConnection that
+ * it will be returning to the caller) or has failed (in which
+ * case @connection is %NULL and the client is about to return
+ * an error).
+ * </para></listitem>
+ * </varlistentry>
* </variablelist>
*
* Each event except %G_SOCKET_CLIENT_COMPLETE may be emitted
@@ -6293,6 +6276,15 @@
/**
+ * GSocketListener:
+ *
+ * A helper class for network servers to listen for and accept connections.
+ *
+ * Since: 2.22
+ */
+
+
+/**
* GSocketListenerClass:
* @changed: virtual method called when the set of socket listened to changes
*
@@ -6414,9 +6406,10 @@
* GSourceCallbackFuncs:
* @ref: Called when a reference is added to the callback object
* @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
- *
+ * @get: Called to extract the callback function and data from the callback object.
*
+ * The <structname>GSourceCallbackFuncs</structname> struct contains
+ * functions for managing callback objects.
*/
@@ -6566,7 +6559,7 @@
/**
* GTcpConnection:
*
- * A #GSocketConnection for UNIX domain socket connections.
+ * A #GSocketConnection for TCP/IP connections.
*
* Since: 2.22
*/
@@ -6618,11 +6611,11 @@
* would become
* |[
* {
- * "gnome-dev-cdrom-audio",
- * "gnome-dev-cdrom",
- * "gnome-dev",
- * "gnome",
- * NULL
+ * "gnome-dev-cdrom-audio",
+ * "gnome-dev-cdrom",
+ * "gnome-dev",
+ * "gnome",
+ * NULL
* };
* ]|
*/
@@ -6821,8 +6814,8 @@
/**
* GTlsClientConnection:
*
- * TLS client-side connection; the client-side implementation of a
- * #GTlsConnection
+ * Abstract base class for the backend-specific client connection
+ * type.
*
* Since: 2.28
*/
@@ -6893,8 +6886,8 @@
/**
* GTlsConnection:
*
- * TLS connection. This is an abstract type that will be subclassed by
- * a TLS-library-specific subtype.
+ * Abstract base class for the backend-specific #GTlsClientConnection
+ * and #GTlsServerConnection types.
*
* Since: 2.28
*/
@@ -6940,11 +6933,7 @@
* need to worry about this, and can simply block in the signal
* handler until the UI thread returns an answer.
*
- * immediately end the signal emission). %FALSE to allow the signal
- * emission to continue, which will cause the handshake to fail if
- * no one else overrides it.
- *
- * Returns: %TRUE to accept @peer_cert (which will also
+ * Returns: %TRUE to accept @peer_cert (which will also immediately end the signal emission). %FALSE to allow the signal emission to continue, which will cause the handshake to fail if no one else overrides it.
* Since: 2.28
*/
@@ -7253,9 +7242,7 @@
* The type of functions which are used to translate user-visible
* strings, for <option>--help</option> output.
*
- * The returned string is owned by GLib and must not be freed.
- *
- * Returns: a translation of the string for the current locale.
+ * Returns: a translation of the string for the current locale. The returned string is owned by GLib and must not be freed.
*/
@@ -7289,9 +7276,7 @@
* whether they actually want to cache the class of this type, since all
* classes are routed through the same #GTypeClassCacheFunc chain.
*
- * called, %FALSE to continue.
- *
- * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
+ * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being called, %FALSE to continue.
*/
@@ -7553,6 +7538,7 @@
/**
* GUnicodeScript:
+ * @G_UNICODE_SCRIPT_INVALID_CODE: a value never returned from g_unichar_get_script()
* @G_UNICODE_SCRIPT_COMMON: a character used by multiple different scripts
* @G_UNICODE_SCRIPT_INHERITED: a mark glyph that takes its script from the i base glyph to which it is attached
* @G_UNICODE_SCRIPT_ARABIC: Arabic
@@ -7592,7 +7578,8 @@
* @G_UNICODE_SCRIPT_TELUGU: Telugu
* @G_UNICODE_SCRIPT_THAANA: Thaana
* @G_UNICODE_SCRIPT_THAI: Thai
- * @G_UNICODE_SCRIPT_TIBETAN: Tibetan Canadian Aboriginal
+ * @G_UNICODE_SCRIPT_TIBETAN: Tibetan
+ * @G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL: Canadian Aboriginal
* @G_UNICODE_SCRIPT_YI: Yi
* @G_UNICODE_SCRIPT_TAGALOG: Tagalog
* @G_UNICODE_SCRIPT_HANUNOO: Hanunoo
@@ -7605,10 +7592,13 @@
* @G_UNICODE_SCRIPT_SHAVIAN: Shavian
* @G_UNICODE_SCRIPT_LINEAR_B: Linear B
* @G_UNICODE_SCRIPT_TAI_LE: Tai Le
- * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic New Tai Lue
+ * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic
+ * @G_UNICODE_SCRIPT_NEW_TAI_LUE: New Tai Lue
* @G_UNICODE_SCRIPT_BUGINESE: Buginese
* @G_UNICODE_SCRIPT_GLAGOLITIC: Glagolitic
- * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh Syloti Nagri Old Persian
+ * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh
+ * @G_UNICODE_SCRIPT_SYLOTI_NAGRI: Syloti Nagri
+ * @G_UNICODE_SCRIPT_OLD_PERSIAN: Old Persian
* @G_UNICODE_SCRIPT_KHAROSHTHI: Kharoshthi
* @G_UNICODE_SCRIPT_UNKNOWN: an unassigned code point
* @G_UNICODE_SCRIPT_BALINESE: Balinese
@@ -7628,10 +7618,16 @@
* @G_UNICODE_SCRIPT_LYCIAN: Lycian. Since 2.16.3
* @G_UNICODE_SCRIPT_LYDIAN: Lydian. Since 2.16.3
* @G_UNICODE_SCRIPT_AVESTAN: Avestan. Since 2.26
- * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26 Egyptian Hieroglpyhs. Since 2.26 Imperial Aramaic. Since 2.26 Inscriptional Pahlavi. Since 2.26 Inscriptional Parthian. Since 2.26
+ * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26
+ * @G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS: Egyptian Hieroglpyhs. Since 2.26
+ * @G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC: Imperial Aramaic. Since 2.26
+ * @G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI: Inscriptional Pahlavi. Since 2.26
+ * @G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN: Inscriptional Parthian. Since 2.26
* @G_UNICODE_SCRIPT_JAVANESE: Javanese. Since 2.26
* @G_UNICODE_SCRIPT_KAITHI: Kaithi. Since 2.26
- * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26 Meetei Mayek. Since 2.26 Old South Arabian. Since 2.26
+ * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26
+ * @G_UNICODE_SCRIPT_MEETEI_MAYEK: Meetei Mayek. Since 2.26
+ * @G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN: Old South Arabian. Since 2.26
* @G_UNICODE_SCRIPT_OLD_TURKIC: Old Turkic. Since 2.28
* @G_UNICODE_SCRIPT_SAMARITAN: Samaritan. Since 2.26
* @G_UNICODE_SCRIPT_TAI_THAM: Tai Tham. Since 2.26
@@ -7640,8 +7636,7 @@
* @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
* @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
* @G_UNICODE_SCRIPT_CHAKMA: Chakma. Since: 2.32
- * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32
- * @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32
+ * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32 @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32
* @G_UNICODE_SCRIPT_MIAO: Miao. Since: 2.32
* @G_UNICODE_SCRIPT_SHARADA: Sharada. Since: 2.32
* @G_UNICODE_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 2.32
@@ -7829,10 +7824,7 @@
*
* Whether or not this is an abstract address
*
- * distinguishes between zero-padded and non-zero-padded
- * abstract addresses.
- *
- * Deprecated: Use #GUnixSocketAddress:address-type, which
+ * Deprecated: Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses.
*/
@@ -8259,9 +8251,7 @@
*
* Check if the closure still needs a marshaller. See g_closure_set_marshal().
*
- * @closure.
- *
- * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
+ * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on @closure.
*/
@@ -8406,11 +8396,11 @@
*
* |[
* G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_THING,
- * 0,
- * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
+ * gtk_gadget,
+ * GTK_TYPE_THING,
+ * 0,
+ * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
* ]|
* expands to
* |[
@@ -8423,42 +8413,42 @@
*
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
*
* GType
* gtk_gadget_get_type (void)
* {
- * return gtk_gadget_type_id;
+ * return gtk_gadget_type_id;
* }
*
* static void
* gtk_gadget_register_type (GTypeModule *type_module)
* {
- * const GTypeInfo g_define_type_info = {
- * sizeof (GtkGadgetClass),
- * (GBaseInitFunc) NULL,
- * (GBaseFinalizeFunc) NULL,
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * (GClassFinalizeFunc) gtk_gadget_class_finalize,
- * NULL, // class_data
- * sizeof (GtkGadget),
- * 0, // n_preallocs
- * (GInstanceInitFunc) gtk_gadget_init,
- * NULL // value_table
- * };
- * gtk_gadget_type_id = g_type_module_register_type (type_module,
- * GTK_TYPE_THING,
- * GtkGadget,
- * &g_define_type_info,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
+ * const GTypeInfo g_define_type_info = {
+ * sizeof (GtkGadgetClass),
+ * (GBaseInitFunc) NULL,
+ * (GBaseFinalizeFunc) NULL,
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * (GClassFinalizeFunc) gtk_gadget_class_finalize,
+ * NULL, // class_data
+ * sizeof (GtkGadget),
+ * 0, // n_preallocs
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * NULL // value_table
+ * };
+ * gtk_gadget_type_id = g_type_module_register_type (type_module,
+ * GTK_TYPE_THING,
+ * GtkGadget,
+ * &g_define_type_info,
+ * (GTypeFlags) flags);
+ * {
+ * const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
* }
* ]|
*
@@ -8556,11 +8546,11 @@
*
* |[
* G_DEFINE_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_WIDGET,
- * 0,
- * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
+ * gtk_gadget,
+ * GTK_TYPE_WIDGET,
+ * 0,
+ * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
* ]|
* expands to
* |[
@@ -8569,33 +8559,33 @@
* static gpointer gtk_gadget_parent_class = NULL;
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
*
* GType
* gtk_gadget_get_type (void)
* {
- * static volatile gsize g_define_type_id__volatile = 0;
- * if (g_once_init_enter (&g_define_type_id__volatile))
- * {
- * GType g_define_type_id =
- * g_type_register_static_simple (GTK_TYPE_WIDGET,
- * g_intern_static_string ("GtkGadget"),
- * sizeof (GtkGadgetClass),
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * sizeof (GtkGadget),
- * (GInstanceInitFunc) gtk_gadget_init,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
- * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
- * }
- * return g_define_type_id__volatile;
+ * static volatile gsize g_define_type_id__volatile = 0;
+ * if (g_once_init_enter (&g_define_type_id__volatile))
+ * {
+ * GType g_define_type_id =
+ * g_type_register_static_simple (GTK_TYPE_WIDGET,
+ * g_intern_static_string ("GtkGadget"),
+ * sizeof (GtkGadgetClass),
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * sizeof (GtkGadget),
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * (GTypeFlags) flags);
+ * {
+ * const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
+ * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
+ * }
+ * return g_define_type_id__volatile;
* }
* ]|
* The only pieces which have to be manually provided are the definitions of
@@ -9840,9 +9830,7 @@
*
* Returns %TRUE if a #GNode is a leaf node.
*
- * (i.e. it has no children)
- *
- * Returns: %TRUE if the #GNode is a leaf node
+ * Returns: %TRUE if the #GNode is a leaf node (i.e. it has no children)
*/
@@ -9852,9 +9840,7 @@
*
* Returns %TRUE if a #GNode is the root of a tree.
*
- * (i.e. it has no parent or siblings)
- *
- * Returns: %TRUE if the #GNode is the root of a tree
+ * Returns: %TRUE if the #GNode is the root of a tree (i.e. it has no parent or siblings)
*/
@@ -9882,9 +9868,7 @@
*
* Return the name of a class structure's type.
*
- * should not be freed.
- *
- * Returns: Type name of @class. The string is owned by the type system and
+ * Returns: Type name of @class. The string is owned by the type system and should not be freed.
*/
@@ -9924,9 +9908,7 @@
*
* Get the name of an object's type.
*
- * should not be freed.
- *
- * Returns: Type name of @object. The string is owned by the type system and
+ * Returns: Type name of @object. The string is owned by the type system and should not be freed.
*/
@@ -10387,13 +10369,13 @@
* of g_signal_new().
* |[
* g_signal_new ("size_request",
- * G_TYPE_FROM_CLASS (gobject_class),
- * G_SIGNAL_RUN_FIRST,
- * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
- * NULL, NULL,
- * _gtk_marshal_VOID__BOXED,
- * G_TYPE_NONE, 1,
- * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
+ * G_TYPE_FROM_CLASS (gobject_class),
+ * G_SIGNAL_RUN_FIRST,
+ * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
+ * NULL, NULL,
+ * _gtk_marshal_VOID__BOXED,
+ * G_TYPE_NONE, 1,
+ * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
* ]|
*/
@@ -11516,12 +11498,12 @@
*
* |[
* g_object_class_install_property (object_class,
- * PROP_AUTHORS,
- * g_param_spec_boxed ("authors",
- * _("Authors"),
- * _("List of authors"),
- * G_TYPE_STRV,
- * G_PARAM_READWRITE));
+ * PROP_AUTHORS,
+ * g_param_spec_boxed ("authors",
+ * _("Authors"),
+ * _("List of authors"),
+ * G_TYPE_STRV,
+ * G_PARAM_READWRITE));
*
* gchar *authors[] = { "Owen", "Tim", NULL };
* g_object_set (obj, "authors", authors, NULL);
@@ -11900,7 +11882,7 @@
* but it cannot be assigned to a variable.
*
* |[
- * GValue value = G_VALUE_INIT;
+ * GValue value = G_VALUE_INIT;
* ]|
*
* Since: 2.30
@@ -12271,42 +12253,42 @@
* of an extension point has a name, and a priority. Use
* g_io_extension_point_implement() to implement an extension point.
*
- * |[
- * GIOExtensionPoint *ep;
+ * |[
+ * GIOExtensionPoint *ep;
*
- * /* Register an extension point */
- * ep = g_io_extension_point_register ("my-extension-point");
- * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
- * ]|
+ * /* Register an extension point */
+ * ep = g_io_extension_point_register ("my-extension-point");
+ * g_io_extension_point_set_required_type (ep, MY_TYPE_EXAMPLE);
+ * ]|
*
- * |[
- * /* Implement an extension point */
- * G_DEFINE_TYPE (MyExampleImpl, my_example_impl, MY_TYPE_EXAMPLE);
- * g_io_extension_point_implement ("my-extension-point",
- * my_example_impl_get_type (),
- * "my-example",
- * 10);
- * ]|
+ * |[
+ * /* 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 (),
+ * "my-example",
+ * 10);
+ * ]|
*
- * It is up to the code that registered the extension point how
- * it uses the implementations that have been associated with it.
- * Depending on the use case, it may use all implementations, or
- * only the one with the highest priority, or pick a specific
- * one by name.
+ * It is up to the code that registered the extension point how
+ * it uses the implementations that have been associated with it.
+ * Depending on the use case, it may use all implementations, or
+ * only the one with the highest priority, or pick a specific
+ * one by name.
*
- * 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>.
- * You are expected to run this command after installing a
- * GIO module.
+ * 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>.
+ * You are expected to run this command after installing a
+ * GIO module.
*
- * The <envar>GIO_EXTRA_MODULES</envar> environment variable can be
- * used to specify additional directories to automatically load modules
- * from. This environment variable has the same syntax as the
- * <envar>PATH</envar>. If two modules have the same base name in different
- * directories, then the latter one will be ignored. If additional
- * directories are specified GIO will load modules from the built-in
- * directory last.
+ * The <envar>GIO_EXTRA_MODULES</envar> environment variable can be
+ * used to specify additional directories to automatically load modules
+ * from. This environment variable has the same syntax as the
+ * <envar>PATH</envar>. If two modules have the same base name in different
+ * directories, then the latter one will be ignored. If additional
+ * directories are specified GIO will load modules from the built-in
+ * directory last.
*/
@@ -12478,9 +12460,9 @@
* g_free (uri);
*
* if (g_file_has_uri_scheme (file, "cdda"))
- * {
- * // do something special with uri
- * }
+ * {
+ * // do something special with uri
+ * }
* g_object_unref (file);
* </programlisting>
*
@@ -12589,7 +12571,7 @@
* <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:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* </example>
@@ -12597,7 +12579,7 @@
* <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:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* </example>
@@ -12605,7 +12587,7 @@
* <example id="gapplication-example-menu"><title>A GApplication with menus</title>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-menu.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* </example>
@@ -12658,7 +12640,7 @@
* </para>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* </example>
@@ -12672,7 +12654,7 @@
* </para>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline2.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* </example>
@@ -12695,7 +12677,7 @@
* </para>
* <programlisting>
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/tests/gapplication-example-cmdline3.c">
- * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
+ * <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
* </xi:include>
* </programlisting>
* </example>
@@ -12725,93 +12707,93 @@
*
* |[
* enum {
- * NOT_INITIALIZED,
- * INITIALIZING,
- * INITIALIZED
+ * NOT_INITIALIZED,
+ * INITIALIZING,
+ * INITIALIZED
* };
*
* static void
* _foo_ready_cb (Foo *self)
* {
- * GList *l;
+ * GList *l;
*
- * self->priv->state = INITIALIZED;
+ * self->priv->state = INITIALIZED;
*
- * for (l = self->priv->init_results; l != NULL; l = l->next)
- * {
- * GSimpleAsyncResult *simple = l->data;
+ * for (l = self->priv->init_results; l != NULL; l = l->next)
+ * {
+ * GSimpleAsyncResult *simple = l->data;
*
- * if (!self->priv->success)
- * g_simple_async_result_set_error (simple, ...);
+ * if (!self->priv->success)
+ * g_simple_async_result_set_error (simple, ...);
*
- * g_simple_async_result_complete (simple);
- * g_object_unref (simple);
- * }
+ * g_simple_async_result_complete (simple);
+ * g_object_unref (simple);
+ * }
*
- * g_list_free (self->priv->init_results);
- * self->priv->init_results = NULL;
+ * g_list_free (self->priv->init_results);
+ * self->priv->init_results = NULL;
* }
*
* static void
* foo_init_async (GAsyncInitable *initable,
- * int io_priority,
- * GCancellable *cancellable,
- * GAsyncReadyCallback callback,
- * gpointer user_data)
- * {
- * Foo *self = FOO (initable);
- * GSimpleAsyncResult *simple;
- *
- * simple = g_simple_async_result_new (G_OBJECT (initable)
- * callback,
- * user_data,
- * foo_init_async);
- *
- * switch (self->priv->state)
+ * int io_priority,
+ * GCancellable *cancellable,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
* {
- * case NOT_INITIALIZED:
- * _foo_get_ready (self);
- * self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
- * self->priv->state = INITIALIZING;
- * break;
- * case INITIALIZING:
- * self->priv->init_results = g_list_append (self->priv->init_results,
- * simple);
- * break;
- * case INITIALIZED:
- * if (!self->priv->success)
- * g_simple_async_result_set_error (simple, ...);
- *
- * g_simple_async_result_complete_in_idle (simple);
- * g_object_unref (simple);
- * break;
- * }
+ * Foo *self = FOO (initable);
+ * GSimpleAsyncResult *simple;
+ *
+ * simple = g_simple_async_result_new (G_OBJECT (initable)
+ * callback,
+ * user_data,
+ * foo_init_async);
+ *
+ * switch (self->priv->state)
+ * {
+ * case NOT_INITIALIZED:
+ * _foo_get_ready (self);
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * simple);
+ * self->priv->state = INITIALIZING;
+ * break;
+ * case INITIALIZING:
+ * self->priv->init_results = g_list_append (self->priv->init_results,
+ * simple);
+ * break;
+ * case INITIALIZED:
+ * if (!self->priv->success)
+ * g_simple_async_result_set_error (simple, ...);
+ *
+ * g_simple_async_result_complete_in_idle (simple);
+ * g_object_unref (simple);
+ * break;
+ * }
* }
*
* static gboolean
* foo_init_finish (GAsyncInitable *initable,
- * GAsyncResult *result,
- * GError **error)
+ * GAsyncResult *result,
+ * GError **error)
* {
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (initable), foo_init_async), FALSE);
+ * g_return_val_if_fail (g_simple_async_result_is_valid (result,
+ * G_OBJECT (initable), foo_init_async), FALSE);
*
- * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
- * error))
- * return FALSE;
+ * if (g_simple_async_result_propagate_error (G_SIMPLE_ASYNC_RESULT (result),
+ * error))
+ * return FALSE;
*
- * return TRUE;
+ * return TRUE;
* }
*
* static void
* foo_async_initable_iface_init (gpointer g_iface,
- * gpointer data)
+ * gpointer data)
* {
- * GAsyncInitableIface *iface = g_iface;
+ * GAsyncInitableIface *iface = g_iface;
*
- * iface->init_async = foo_init_async;
- * iface->init_finish = foo_init_finish;
+ * iface->init_async = foo_init_async;
+ * iface->init_finish = foo_init_finish;
* }
* ]|
*/
@@ -12852,42 +12834,42 @@
* Example of a typical asynchronous operation flow:
* |[
* void _theoretical_frobnitz_async (Theoretical *t,
- * GCancellable *c,
- * GAsyncReadyCallback *cb,
- * gpointer u);
+ * GCancellable *c,
+ * GAsyncReadyCallback *cb,
+ * gpointer u);
*
* gboolean _theoretical_frobnitz_finish (Theoretical *t,
- * GAsyncResult *res,
- * GError **e);
+ * GAsyncResult *res,
+ * GError **e);
*
* static void
* frobnitz_result_func (GObject *source_object,
- * GAsyncResult *res,
- * gpointer user_data)
+ * GAsyncResult *res,
+ * gpointer user_data)
* {
- * gboolean success = FALSE;
+ * gboolean success = FALSE;
*
- * success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ * success = _theoretical_frobnitz_finish (source_object, res, NULL);
*
- * if (success)
- * g_printf ("Hurray!\n");
- * else
- * g_printf ("Uh oh!\n");
+ * if (success)
+ * g_printf ("Hurray!\n");
+ * else
+ * g_printf ("Uh oh!\n");
*
- * /<!-- -->* ... *<!-- -->/
+ * /<!-- -->* ... *<!-- -->/
*
* }
*
* int main (int argc, void *argv[])
* {
- * /<!-- -->* ... *<!-- -->/
+ * /<!-- -->* ... *<!-- -->/
*
- * _theoretical_frobnitz_async (theoretical_data,
- * NULL,
- * frobnitz_result_func,
- * NULL);
+ * _theoretical_frobnitz_async (theoretical_data,
+ * NULL,
+ * frobnitz_result_func,
+ * NULL);
*
- * /<!-- -->* ... *<!-- -->/
+ * /<!-- -->* ... *<!-- -->/
* }
* ]|
*
@@ -13112,23 +13094,23 @@
* <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
* static gboolean
* on_authorize_authenticated_peer (GDBusAuthObserver *observer,
- * GIOStream *stream,
- * GCredentials *credentials,
- * gpointer user_data)
- * {
- * gboolean authorized;
- *
- * authorized = FALSE;
- * if (credentials != NULL)
+ * GIOStream *stream,
+ * GCredentials *credentials,
+ * gpointer user_data)
* {
- * GCredentials *own_credentials;
- * own_credentials = g_credentials_new ();
- * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
- * authorized = TRUE;
- * g_object_unref (own_credentials);
- * }
- *
- * return authorized;
+ * gboolean authorized;
+ *
+ * authorized = FALSE;
+ * if (credentials != NULL)
+ * {
+ * GCredentials *own_credentials;
+ * own_credentials = g_credentials_new ();
+ * if (g_credentials_is_same_user (credentials, own_credentials, NULL))
+ * authorized = TRUE;
+ * g_object_unref (own_credentials);
+ * }
+ *
+ * return authorized;
* }
* </programlisting></example>
*/
@@ -13152,8 +13134,8 @@
* used by two threads at the same time, #GDBusConnection's methods may be
* called from any thread<footnote>
* <para>
- * This is so that g_bus_get() and g_bus_get_sync() can safely return the
- * same #GDBusConnection when called from any thread.
+ * This is so that g_bus_get() and g_bus_get_sync() can safely return the
+ * same #GDBusConnection when called from any thread.
* </para>
* </footnote>.
*
@@ -13215,30 +13197,30 @@
*
* typedef enum
* {
- * FOO_BAR_ERROR_FAILED,
- * FOO_BAR_ERROR_ANOTHER_ERROR,
- * FOO_BAR_ERROR_SOME_THIRD_ERROR,
+ * FOO_BAR_ERROR_FAILED,
+ * FOO_BAR_ERROR_ANOTHER_ERROR,
+ * FOO_BAR_ERROR_SOME_THIRD_ERROR,
* } FooBarError;
*
* /<!-- -->* foo-bar-error.c: *<!-- -->/
*
* static const GDBusErrorEntry foo_bar_error_entries[] =
* {
- * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
- * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
- * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
+ * {FOO_BAR_ERROR_FAILED, "org.project.Foo.Bar.Error.Failed"},
+ * {FOO_BAR_ERROR_ANOTHER_ERROR, "org.project.Foo.Bar.Error.AnotherError"},
+ * {FOO_BAR_ERROR_SOME_THIRD_ERROR, "org.project.Foo.Bar.Error.SomeThirdError"},
* };
*
* GQuark
* foo_bar_error_quark (void)
* {
- * static volatile gsize quark_volatile = 0;
- * g_dbus_error_register_error_domain ("foo-bar-error-quark",
- * &quark_volatile,
- * foo_bar_error_entries,
- * G_N_ELEMENTS (foo_bar_error_entries));
- * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR);
- * return (GQuark) quark_volatile;
+ * static volatile gsize quark_volatile = 0;
+ * g_dbus_error_register_error_domain ("foo-bar-error-quark",
+ * &quark_volatile,
+ * foo_bar_error_entries,
+ * G_N_ELEMENTS (foo_bar_error_entries));
+ * G_STATIC_ASSERT (G_N_ELEMENTS (foo_bar_error_entries) - 1 == FOO_BAR_ERROR_SOME_THIRD_ERROR);
+ * return (GQuark) quark_volatile;
* }
* </programlisting></example>
* With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and
@@ -14412,8 +14394,8 @@
* <xref linkend="menu-example"/>.
*
* <figure id="menu-example">
- * <title>An example menu</title>
- * <graphic fileref="menu-example.png" format="PNG"></graphic>
+ * <title>An example menu</title>
+ * <graphic fileref="menu-example.png" format="PNG"></graphic>
* </figure>
*
* There are 8 "menus" visible in the screenshot: one menubar, two
@@ -14435,8 +14417,8 @@
* items contain references to other menus.
*
* <figure id="menu-model">
- * <title>A menu model</title>
- * <graphic fileref="menu-model.png" format="PNG"></graphic>
+ * <title>A menu model</title>
+ * <graphic fileref="menu-model.png" format="PNG"></graphic>
* </figure>
*
* Notice that the separators visible in <xref linkend="menu-example"/>
@@ -14816,11 +14798,11 @@
* <programlisting><![CDATA[
* <?xml version="1.0" encoding="UTF-8"?>
* <gresources>
- * <gresource prefix="/org/gtk/Example">
- * <file>data/splashscreen.png</file>
- * <file compressed="true">dialog.ui</file>
- * <file preprocess="xml-stripblanks">menumarkup.xml</file>
- * </gresource>
+ * <gresource prefix="/org/gtk/Example">
+ * <file>data/splashscreen.png</file>
+ * <file compressed="true">dialog.ui</file>
+ * <file preprocess="xml-stripblanks">menumarkup.xml</file>
+ * </gresource>
* </gresources>
* ]]></programlisting></example>
*
@@ -14948,21 +14930,21 @@
* <example id="schema-default-values"><title>Default values</title>
* <programlisting><![CDATA[
* <schemalist>
- * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
+ * <schema id="org.gtk.Test" path="/tests/" gettext-domain="test">
*
- * <key name="greeting" type="s">
- * <default l10n="messages">"Hello, earthlings"</default>
- * <summary>A greeting</summary>
- * <description>
- * Greeting of the invading martians
- * </description>
- * </key>
+ * <key name="greeting" type="s">
+ * <default l10n="messages">"Hello, earthlings"</default>
+ * <summary>A greeting</summary>
+ * <description>
+ * Greeting of the invading martians
+ * </description>
+ * </key>
*
- * <key name="box" type="(ii)">
- * <default>(20,30)</default>
- * </key>
+ * <key name="box" type="(ii)">
+ * <default>(20,30)</default>
+ * </key>
*
- * </schema>
+ * </schema>
* </schemalist>
* ]]></programlisting></example>
*
@@ -14970,90 +14952,90 @@
* <programlisting><![CDATA[
* <schemalist>
*
- * <enum id="org.gtk.Test.myenum">
- * <value nick="first" value="1"/>
- * <value nick="second" value="2"/>
- * </enum>
- *
- * <flags id="org.gtk.Test.myflags">
- * <value nick="flag1" value="1"/>
- * <value nick="flag2" value="2"/>
- * <value nick="flag3" value="4"/>
- * </flags>
- *
- * <schema id="org.gtk.Test">
- *
- * <key name="key-with-range" type="i">
- * <range min="1" max="100"/>
- * <default>10</default>
- * </key>
- *
- * <key name="key-with-choices" type="s">
- * <choices>
- * <choice value='Elisabeth'/>
- * <choice value='Annabeth'/>
- * <choice value='Joe'/>
- * </choices>
- * <aliases>
- * <alias value='Anna' target='Annabeth'/>
- * <alias value='Beth' target='Elisabeth'/>
- * </aliases>
- * <default>'Joe'</default>
- * </key>
- *
- * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
- * <default>'first'</default>
- * </key>
- *
- * <key name='flags-key' flags='org.gtk.Test.myflags'>
- * <default>["flag1",flag2"]</default>
- * </key>
- * </schema>
+ * <enum id="org.gtk.Test.myenum">
+ * <value nick="first" value="1"/>
+ * <value nick="second" value="2"/>
+ * </enum>
+ *
+ * <flags id="org.gtk.Test.myflags">
+ * <value nick="flag1" value="1"/>
+ * <value nick="flag2" value="2"/>
+ * <value nick="flag3" value="4"/>
+ * </flags>
+ *
+ * <schema id="org.gtk.Test">
+ *
+ * <key name="key-with-range" type="i">
+ * <range min="1" max="100"/>
+ * <default>10</default>
+ * </key>
+ *
+ * <key name="key-with-choices" type="s">
+ * <choices>
+ * <choice value='Elisabeth'/>
+ * <choice value='Annabeth'/>
+ * <choice value='Joe'/>
+ * </choices>
+ * <aliases>
+ * <alias value='Anna' target='Annabeth'/>
+ * <alias value='Beth' target='Elisabeth'/>
+ * </aliases>
+ * <default>'Joe'</default>
+ * </key>
+ *
+ * <key name='enumerated-key' enum='org.gtk.Test.myenum'>
+ * <default>'first'</default>
+ * </key>
+ *
+ * <key name='flags-key' flags='org.gtk.Test.myflags'>
+ * <default>["flag1",flag2"]</default>
+ * </key>
+ * </schema>
* </schemalist>
* ]]></programlisting></example>
*
* <refsect2>
- * <title>Vendor overrides</title>
- * <para>
- * Default values are defined in the schemas that get installed by
- * an application. Sometimes, it is necessary for a vendor or distributor
- * to adjust these defaults. Since patching the XML source for the schema
- * is inconvenient and error-prone,
- * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
- * so-called 'vendor override' files. These are keyfiles in the same
- * directory as the XML schema sources which can override default values.
- * The schema id serves as the group name in the key file, and the values
- * are expected in serialized GVariant form, as in the following example:
- * <informalexample><programlisting>
- * [org.gtk.Example]
- * key1='string'
- * key2=1.5
- * </programlisting></informalexample>
- * </para>
- * <para>
- * glib-compile-schemas expects schema files to have the extension
- * <filename>.gschema.override</filename>
- * </para>
+ * <title>Vendor overrides</title>
+ * <para>
+ * Default values are defined in the schemas that get installed by
+ * an application. Sometimes, it is necessary for a vendor or distributor
+ * to adjust these defaults. Since patching the XML source for the schema
+ * is inconvenient and error-prone,
+ * <link linkend="glib-compile-schemas">glib-compile-schemas</link> reads
+ * so-called 'vendor override' files. These are keyfiles in the same
+ * directory as the XML schema sources which can override default values.
+ * The schema id serves as the group name in the key file, and the values
+ * are expected in serialized GVariant form, as in the following example:
+ * <informalexample><programlisting>
+ * [org.gtk.Example]
+ * key1='string'
+ * key2=1.5
+ * </programlisting></informalexample>
+ * </para>
+ * <para>
+ * glib-compile-schemas expects schema files to have the extension
+ * <filename>.gschema.override</filename>
+ * </para>
* </refsect2>
*
* <refsect2>
- * <title>Binding</title>
- * <para>
- * A very convenient feature of GSettings lets you bind #GObject properties
- * directly to settings, using g_settings_bind(). Once a GObject property
- * has been bound to a setting, changes on either side are automatically
- * propagated to the other side. GSettings handles details like
- * mapping between GObject and GVariant types, and preventing infinite
- * cycles.
- * </para>
- * <para>
- * This makes it very easy to hook up a preferences dialog to the
- * underlying settings. To make this even more convenient, GSettings
- * looks for a boolean property with the name "sensitivity" and
- * automatically binds it to the writability of the bound setting.
- * If this 'magic' gets in the way, it can be suppressed with the
- * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
- * </para>
+ * <title>Binding</title>
+ * <para>
+ * A very convenient feature of GSettings lets you bind #GObject properties
+ * directly to settings, using g_settings_bind(). Once a GObject property
+ * has been bound to a setting, changes on either side are automatically
+ * propagated to the other side. GSettings handles details like
+ * mapping between GObject and GVariant types, and preventing infinite
+ * cycles.
+ * </para>
+ * <para>
+ * This makes it very easy to hook up a preferences dialog to the
+ * underlying settings. To make this even more convenient, GSettings
+ * looks for a boolean property with the name "sensitivity" and
+ * automatically binds it to the writability of the bound setting.
+ * If this 'magic' gets in the way, it can be suppressed with the
+ * #G_SETTINGS_BIND_NO_SENSITIVITY flag.
+ * </para>
* </refsect2>
*/
@@ -15119,47 +15101,47 @@
* |[
* typedef struct
* {
- * ...
- * GSettingsSchemaSource *schema_source;
- * ...
+ * ...
+ * GSettingsSchemaSource *schema_source;
+ * ...
* } Plugin;
*
* Plugin *
* initialise_plugin (const gchar *dir)
* {
- * Plugin *plugin;
+ * Plugin *plugin;
*
- * ...
+ * ...
*
- * plugin->schema_source =
- * g_settings_new_schema_source_from_directory (dir,
- * g_settings_schema_source_get_default (), FALSE, NULL);
+ * plugin->schema_source =
+ * g_settings_new_schema_source_from_directory (dir,
+ * g_settings_schema_source_get_default (), FALSE, NULL);
*
- * ...
+ * ...
*
- * return plugin;
+ * return plugin;
* }
*
* ...
*
* GSettings *
* plugin_get_settings (Plugin *plugin,
- * const gchar *schema_id)
+ * const gchar *schema_id)
* {
- * GSettingsSchema *schema;
+ * GSettingsSchema *schema;
*
- * if (schema_id == NULL)
- * schema_id = plugin->identifier;
+ * if (schema_id == NULL)
+ * schema_id = plugin->identifier;
*
- * schema = g_settings_schema_source_lookup (plugin->schema_source,
- * schema_id, FALSE);
+ * schema = g_settings_schema_source_lookup (plugin->schema_source,
+ * schema_id, FALSE);
*
- * if (schema == NULL)
- * {
- * ... disable the plugin or abort, etc ...
- * }
+ * if (schema == NULL)
+ * {
+ * ... disable the plugin or abort, etc ...
+ * }
*
- * return g_settings_new_full (schema, NULL, NULL);
+ * return g_settings_new_full (schema, NULL, NULL);
* }
* ]|
*
@@ -15175,12 +15157,12 @@
*
* |[
* {
- * GSettings *settings;
- * gint some_value;
+ * GSettings *settings;
+ * gint some_value;
*
- * settings = plugin_get_settings (self, NULL);
- * some_value = g_settings_get_int (settings, "some-value");
- * ...
+ * settings = plugin_get_settings (self, NULL);
+ * some_value = g_settings_get_int (settings, "some-value");
+ * ...
* }
* ]|
*
@@ -15295,98 +15277,98 @@
* |[
* static void
* baked_cb (Cake *cake,
- * gpointer user_data)
+ * 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.
- * */
- * GSimpleAsyncResult *result = user_data;
- *
- * if (cake == NULL)
- * g_simple_async_result_set_error (result,
- * BAKER_ERRORS,
- * BAKER_ERROR_NO_FLOUR,
- * "Go to the supermarket");
- * else
- * g_simple_async_result_set_op_res_gpointer (result,
- * g_object_ref (cake),
- * 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().
- * */
- * g_simple_async_result_complete (result);
- * g_object_unref (result);
+ * /* 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)
+ * g_simple_async_result_set_error (result,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_NO_FLOUR,
+ * "Go to the supermarket");
+ * else
+ * g_simple_async_result_set_op_res_gpointer (result,
+ * g_object_ref (cake),
+ * 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().
+ * */
+ * g_simple_async_result_complete (result);
+ * g_object_unref (result);
* }
*
* void
* baker_bake_cake_async (Baker *self,
- * guint radius,
- * GAsyncReadyCallback callback,
- * gpointer user_data)
- * {
- * GSimpleAsyncResult *simple;
- * Cake *cake;
- *
- * if (radius < 3)
- * {
- * g_simple_async_report_error_in_idle (G_OBJECT (self),
- * callback,
- * user_data,
- * BAKER_ERRORS,
- * BAKER_ERROR_TOO_SMALL,
- * "%ucm radius cakes are silly",
- * radius);
- * return;
- * }
- *
- * simple = g_simple_async_result_new (G_OBJECT (self),
- * callback,
- * user_data,
- * baker_bake_cake_async);
- * cake = _baker_get_cached_cake (self, radius);
- *
- * if (cake != NULL)
+ * guint radius,
+ * GAsyncReadyCallback callback,
+ * gpointer user_data)
* {
- * g_simple_async_result_set_op_res_gpointer (simple,
- * g_object_ref (cake),
- * 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.
- * */
- * g_object_unref (cake);
- * return;
- * }
- *
- * _baker_prepare_cake (self, radius, baked_cb, simple);
+ * GSimpleAsyncResult *simple;
+ * Cake *cake;
+ *
+ * if (radius < 3)
+ * {
+ * g_simple_async_report_error_in_idle (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * BAKER_ERRORS,
+ * BAKER_ERROR_TOO_SMALL,
+ * "%ucm radius cakes are silly",
+ * radius);
+ * return;
+ * }
+ *
+ * simple = g_simple_async_result_new (G_OBJECT (self),
+ * callback,
+ * user_data,
+ * baker_bake_cake_async);
+ * cake = _baker_get_cached_cake (self, radius);
+ *
+ * if (cake != NULL)
+ * {
+ * g_simple_async_result_set_op_res_gpointer (simple,
+ * g_object_ref (cake),
+ * 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.
+ * */
+ * g_object_unref (cake);
+ * return;
+ * }
+ *
+ * _baker_prepare_cake (self, radius, baked_cb, simple);
* }
*
* Cake *
* baker_bake_cake_finish (Baker *self,
- * GAsyncResult *result,
- * GError **error)
+ * GAsyncResult *result,
+ * GError **error)
* {
- * GSimpleAsyncResult *simple;
- * Cake *cake;
+ * GSimpleAsyncResult *simple;
+ * Cake *cake;
*
- * g_return_val_if_fail (g_simple_async_result_is_valid (result,
- * G_OBJECT (self),
- * baker_bake_cake_async),
- * NULL);
+ * g_return_val_if_fail (g_simple_async_result_is_valid (result,
+ * G_OBJECT (self),
+ * baker_bake_cake_async),
+ * NULL);
*
- * simple = (GSimpleAsyncResult *) result;
+ * simple = (GSimpleAsyncResult *) result;
*
- * if (g_simple_async_result_propagate_error (simple, error))
- * return NULL;
+ * if (g_simple_async_result_propagate_error (simple, error))
+ * return NULL;
*
- * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
- * return g_object_ref (cake);
+ * cake = CAKE (g_simple_async_result_get_op_res_gpointer (simple));
+ * return g_object_ref (cake);
* }
* ]|
*/
@@ -15510,56 +15492,56 @@
* |[
* MyConnectionType *
* connect_to_host (const char *hostname,
- * guint16 port,
- * GCancellable *cancellable,
- * GError **error)
- * {
- * MyConnection *conn = NULL;
- * GSocketConnectable *addr;
- * GSocketAddressEnumerator *enumerator;
- * GSocketAddress *sockaddr;
- * GError *conn_error = NULL;
- *
- * addr = g_network_address_new ("www.gnome.org", 80);
- * 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).
- * *<!-- -->/
- * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
- * {
- * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
- * g_object_unref (sockaddr);
- * }
- * g_object_unref (enumerator);
- *
- * if (conn)
- * {
- * if (conn_error)
- * {
- * /<!-- -->* 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.
- * *<!-- -->/
- * if (conn_error)
- * g_error_free (conn_error);
- * return NULL;
- * }
- * else
+ * guint16 port,
+ * GCancellable *cancellable,
+ * GError **error)
* {
- * g_error_propagate (error, conn_error);
- * return NULL;
- * }
+ * MyConnection *conn = NULL;
+ * GSocketConnectable *addr;
+ * GSocketAddressEnumerator *enumerator;
+ * GSocketAddress *sockaddr;
+ * GError *conn_error = NULL;
+ *
+ * addr = g_network_address_new ("www.gnome.org", 80);
+ * 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).
+ * *<!-- -->/
+ * while (!conn && (sockaddr = g_socket_address_enumerator_next (enumerator, cancellable, error))
+ * {
+ * conn = connect_to_sockaddr (sockaddr, conn_error ? NULL : &conn_error);
+ * g_object_unref (sockaddr);
+ * }
+ * g_object_unref (enumerator);
+ *
+ * if (conn)
+ * {
+ * if (conn_error)
+ * {
+ * /<!-- -->* 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.
+ * *<!-- -->/
+ * if (conn_error)
+ * g_error_free (conn_error);
+ * return NULL;
+ * }
+ * else
+ * {
+ * g_error_propagate (error, conn_error);
+ * return NULL;
+ * }
* }
* ]|
*/
@@ -16208,99 +16190,6 @@
/**
- * The string info map is an efficient data structure designed to be:
- *
- * 1) Implement <choices> with a list of valid strings
- *
- * 2) Implement <alias> by mapping one string to another
- *
- * 3) Implement enumerated types by mapping strings to integer values
- * (and back).
- *
- * The map is made out of an array of uint32s. Each entry in the array
- * is an integer value, followed by a specially formatted string value:
- *
- * The string starts with the byte 0xff or 0xfe, followed by the
- * content of the string, followed by a nul byte, followed by
- * additional nul bytes for padding, followed by a 0xff byte.
- *
- * Padding is added so that the entire formatted string takes up a
- * multiple of 4 bytes, and not less than 8 bytes. The requirement
- * for a string to take up 8 bytes is so that the scanner doesn't lose
- * synch and mistake a string for an integer value.
- *
- * The first byte of the formatted string depends on if the integer is
- * an enum value (0xff) or an alias (0xfe). If it is an alias then the
- * number refers to the word offset within the info map at which the
- * integer corresponding to the "target" value is stored.
- *
- * For example, consider the case of the string info map representing an
- * enumerated type of 'foo' (value 1) and 'bar' (value 2) and 'baz'
- * (alias for 'bar'). Note that string info maps are always little
- * endian.
- *
- * x01 x00 x00 x00 xff 'f' 'o' 'o' x00 x00 x00 xff x02 x00 x00 x00
- * xff 'b' 'a' 'r' x00 x00 x00 xff x03 x00 x00 x00 xfe 'b' 'a' 'z'
- * x00 x00 x00 xff
- *
- *
- * The operations that someone may want to perform with the map:
- *
- * - lookup if a string is valid (and not an alias)
- * - lookup the integer value for a enum 'nick'
- * - lookup the integer value for the target of an alias
- * - lookup an alias and convert it to its target string
- * - lookup the enum nick for a given value
- *
- * In order to lookup if a string is valid, it is padded on either side
- * (as described) and scanned for in the array. For example, you might
- * look for "foo":
- *
- * xff 'f' 'o' 'o' x00 x00 x00 xff
- *
- * In order to lookup the integer value for a nick, the string is padded
- * on either side and scanned for in the array, as above. Instead of
- * merely succeeding, we look at the integer value to the left of the
- * match. This is the enum value.
- *
- * In order to lookup an alias and convert it to its target enum value,
- * the string is padded on either side (as described, with 0xfe) and
- * scanned for. For example, you might look for "baz":
- *
- * xfe 'b' 'a' 'z' x00 x00 x00 xff
- *
- * The integer immediately preceding the match then contains the offset
- * of the integer value of the target. In our example, that's '3'.
- * This index is dereferenced to find the enum value of '2'.
- *
- * To convert the alias to its target string, 5 bytes just need to be
- * added past the start of the integer value to find the start of the
- * string.
- *
- * To lookup the enum nick for a given value, the value is searched for
- * in the array. To ensure that the value isn't matching the inside of a
- * string, we must check that it is either the first item in the array or
- * immediately preceded by the byte 0xff. It must also be immediately
- * followed by the byte 0xff.
- *
- * Because strings always take up a minimum of 2 words, because 0xff or
- * 0xfe never appear inside of a utf-8 string and because no two integer
- * values ever appear in sequence, the only way we can have the
- * sequence:
- *
- * xff __ __ __ __ xff (or 0xfe)
- *
- * is in the event of an integer nested between two strings.
- *
- * For implementation simplicity/efficiency, strings may not be more
- * than 65 characters in length (ie: 17 32bit words after padding).
- *
- * In the event that we are doing <choices> (ie: not an enum type) then
- * the value of each choice is set to zero and ignored.
- */
-
-
-/**
* _g_io_module_get_default:
* @extension_point: the name of an extension point
* @envvar: (allow-none): the name of an environment variable to override the default implementation.
@@ -16322,10 +16211,7 @@
* The result is cached after it is generated the first time, and
* the function is thread-safe.
*
- * @extension_point, or %NULL if there are no usable
- * implementations.
- *
- * Returns: (transfer none): an object implementing
+ * Returns: (transfer none): an object implementing @extension_point, or %NULL if there are no usable implementations.
*/
@@ -16703,9 +16589,7 @@
* The caller is responsible for freeing the list with g_strfreev() when
* it is no longer required.
*
- * actions in the groupb
- *
- * Returns: (transfer full): a %NULL-terminated array of the names of the
+ * Returns: (transfer full): a %NULL-terminated array of the names of the actions in the groupb
* Since: 2.28
*/
@@ -16786,33 +16670,33 @@
* <programlisting>
* static void
* activate_quit (GSimpleAction *simple,
- * GVariant *parameter,
- * gpointer user_data)
+ * GVariant *parameter,
+ * gpointer user_data)
* {
- * exit (0);
+ * exit (0);
* }
*
* static void
* activate_print_string (GSimpleAction *simple,
- * GVariant *parameter,
- * gpointer user_data)
+ * GVariant *parameter,
+ * gpointer user_data)
* {
- * g_print ("%s\n", g_variant_get_string (parameter, NULL));
+ * g_print ("%s\n", g_variant_get_string (parameter, NULL));
* }
*
* static GActionGroup *
* create_action_group (void)
* {
- * const GActionEntry entries[] = {
- * { "quit", activate_quit },
- * { "print-string", activate_print_string, "s" }
- * };
- * GSimpleActionGroup *group;
+ * const GActionEntry entries[] = {
+ * { "quit", activate_quit },
+ * { "print-string", activate_print_string, "s" }
+ * };
+ * GSimpleActionGroup *group;
*
- * group = g_simple_action_group_new ();
- * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
+ * group = g_simple_action_group_new ();
+ * g_action_map_add_action_entries (G_ACTION_MAP (group), entries, G_N_ELEMENTS (entries), NULL);
*
- * return G_ACTION_GROUP (group);
+ * return G_ACTION_GROUP (group);
* }
* </programlisting>
* </example>
@@ -16857,31 +16741,31 @@
* function present on most UNIX variants.
* Thus it provides the same advantages and pitfalls as alloca():
* <variablelist>
- * <varlistentry><term></term><listitem><para>
- * + alloca() is very fast, as on most systems it's implemented by just adjusting
- * the stack pointer register.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
- * blocks just build up and are released together at function end.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation sizes have to fit into the current stack frame. For instance in a
- * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
- * so be sparse with alloca() uses.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation failure due to insufficient stack space is not indicated with a %NULL
- * return like e.g. with malloc(). Instead, most systems probably handle it the same
- * way as out of stack space situations from infinite function recursion, i.e.
- * with a segmentation fault.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
- * Stack space allocated with alloca() in the same scope as a variable sized array
- * will be freed together with the variable sized array upon exit of that scope, and
- * not upon exit of the enclosing function scope.
- * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * + alloca() is very fast, as on most systems it's implemented by just adjusting
+ * the stack pointer register.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
+ * blocks just build up and are released together at function end.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation sizes have to fit into the current stack frame. For instance in a
+ * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
+ * so be sparse with alloca() uses.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation failure due to insufficient stack space is not indicated with a %NULL
+ * return like e.g. with malloc(). Instead, most systems probably handle it the same
+ * way as out of stack space situations from infinite function recursion, i.e.
+ * with a segmentation fault.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
+ * Stack space allocated with alloca() in the same scope as a variable sized array
+ * will be freed together with the variable sized array upon exit of that scope, and
+ * not upon exit of the enclosing function scope.
+ * </para></listitem></varlistentry>
* </variablelist>
*
* Returns: space for @size bytes, allocated on the stack
@@ -16919,9 +16803,7 @@
*
* Checks if a supported content type can be removed from an application.
*
- * content types from a given @appinfo, %FALSE if not.
- *
- * Returns: %TRUE if it is possible to remove supported
+ * Returns: %TRUE if it is possible to remove supported content types from a given @appinfo, %FALSE if not.
*/
@@ -17001,9 +16883,7 @@
* g_app_info_get_recommended_for_type() and
* g_app_info_get_fallback_for_type().
*
- * for given @content_type or %NULL on error.
- *
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error.
*/
@@ -17014,9 +16894,7 @@
* Gets the commandline with which the application will be
* started.
*
- * or %NULL if this information is not available
- *
- * Returns: a string containing the @appinfo's commandline,
+ * Returns: a string containing the @appinfo's commandline, or %NULL if this information is not available
* Since: 2.20
*/
@@ -17028,9 +16906,7 @@
*
* Gets the default #GAppInfo for a given content type.
*
- * %NULL on error.
- *
- * Returns: (transfer full): #GAppInfo for given @content_type or
+ * Returns: (transfer full): #GAppInfo for given @content_type or %NULL on error.
*/
@@ -17053,9 +16929,7 @@
*
* Gets a human-readable description of an installed application.
*
- * application @appinfo, or %NULL if none.
- *
- * Returns: a string containing a description of the
+ * Returns: a string containing a description of the application @appinfo, or %NULL if none.
*/
@@ -17066,9 +16940,7 @@
* Gets the display name of the application. The display name is often more
* descriptive to the user than the name itself.
*
- * no display name is available.
- *
- * Returns: the display name of the application for @appinfo, or the name if
+ * Returns: the display name of the application for @appinfo, or the name if no display name is available.
* Since: 2.24
*/
@@ -17079,9 +16951,7 @@
*
* Gets the executable's name for the installed application.
*
- * binaries name
- *
- * Returns: a string containing the @appinfo's application
+ * Returns: a string containing the @appinfo's application binaries name
*/
@@ -17093,9 +16963,7 @@
* those applications which claim to support the given content type
* by MIME type subclassing and not directly.
*
- * for given @content_type or %NULL on error.
- *
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error.
* Since: 2.28
*/
@@ -17106,9 +16974,7 @@
*
* Gets the icon for the application.
*
- * if there is no default icon.
- *
- * Returns: (transfer none): the default #GIcon for @appinfo or %NULL
+ * Returns: (transfer none): the default #GIcon for @appinfo or %NULL if there is no default icon.
*/
@@ -17149,9 +17015,7 @@
* the last one for which g_app_info_set_as_last_used_for_type() has been
* called.
*
- * for given @content_type or %NULL on error.
- *
- * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos
+ * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error.
* Since: 2.28
*/
@@ -17352,9 +17216,7 @@
* This is a %NULL-terminated array of strings, where each string has
* the form <literal>KEY=VALUE</literal>.
*
- * child's environment
- *
- * Returns: (array zero-terminated=1) (transfer full): the
+ * Returns: (array zero-terminated=1) (transfer full): the child's environment
* Since: 2.32
*/
@@ -17373,9 +17235,7 @@
* url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt";>
* FreeDesktop.Org Startup Notifications standard</ulink>.
*
- * not supported.
- *
- * Returns: a startup notification ID for the application, or %NULL if
+ * Returns: a startup notification ID for the application, or %NULL if not supported.
*/
@@ -17451,9 +17311,7 @@
* The return value is %NULL-terminated and should be freed using
* g_strfreev().
*
- * containing the arguments (the argv)
- *
- * Returns: (array length=argc) (transfer full): the string array
+ * Returns: (array length=argc) (transfer full): the string array containing the arguments (the argv)
* Since: 2.28
*/
@@ -17496,9 +17354,7 @@
* See g_application_command_line_getenv() if you are only interested
* in the value of a single environment variable.
*
- * strings, or %NULL if they were not sent
- *
- * Returns: (array zero-terminated=1) (transfer none): the environment
+ * Returns: (array zero-terminated=1) (transfer none): the environment strings, or %NULL if they were not sent
* Since: 2.28
*/
@@ -17745,11 +17601,11 @@
* For convenience, the restrictions on application identifiers are
* reproduced here:
* <itemizedlist>
- * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
- * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
- * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
- * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
- * <listitem>Application identifiers must not exceed 255 characters.</listitem>
+ * <listitem>Application identifiers must contain only the ASCII characters "[A-Z][a-z][0-9]_-." and must not begin with a digit.</listitem>
+ * <listitem>Application identifiers must contain at least one '.' (period) character (and thus at least three elements).</listitem>
+ * <listitem>Application identifiers must not begin or end with a '.' (period) character.</listitem>
+ * <listitem>Application identifiers must not contain consecutive '.' (period) characters.</listitem>
+ * <listitem>Application identifiers must not exceed 255 characters.</listitem>
* </itemizedlist>
*
* Returns: %TRUE if @application_id is valid
@@ -17952,14 +17808,8 @@
* This used to be how actions were associated with a #GApplication.
* Now there is #GActionMap for that.
*
- *
- * Deprecated:2.32:Use the #GActionMap interface instead. Never ever
- * mix use of this API with use of #GActionMap on the same @application
- * or things will go very badly wrong. This function is known to
- * introduce buggy behaviour (ie: signals not emitted on changes to the
- * action group), so you should really use #GActionMap instead.
- *
* Since: 2.28
+ * Deprecated: 2.32:Use the #GActionMap interface instead. Never ever mix use of this API with use of #GActionMap on the same @application or things will go very badly wrong. This function is known to introduce buggy behaviour (ie: signals not emitted on changes to the action group), so you should really use #GActionMap instead.
*/
@@ -18083,9 +17933,7 @@
* Finishes asynchronous initialization and returns the result.
* See g_async_initable_init_async().
*
- * will return %FALSE and set @error appropriately if present.
- *
- * Returns: %TRUE if successful. If an error has occurred, this function
+ * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
* Since: 2.22
*/
@@ -18120,9 +17968,7 @@
* Finishes the async construction for the various g_async_initable_new
* calls, returning the created object or %NULL on error.
*
- * Free with g_object_unref().
- *
- * Returns: (transfer full): a newly created #GObject, or %NULL on error.
+ * Returns: (transfer full): a newly created #GObject, or %NULL on error. Free with g_object_unref().
* Since: 2.22
*/
@@ -18176,9 +18022,7 @@
*
* Gets the source object from a #GAsyncResult.
*
- * or %NULL if there is none.
- *
- * Returns: (transfer full): a new reference to the source object for the @res,
+ * Returns: (transfer full): a new reference to the source object for the @res, or %NULL if there is none.
*/
@@ -18224,9 +18068,7 @@
* For the asynchronous, non-blocking, version of this function, see
* g_buffered_input_stream_fill_async().
*
- * or -1 on error.
- *
- * Returns: the number of bytes read into @stream's buffer, up to @count,
+ * Returns: the number of bytes read into @stream's buffer, up to @count, or -1 on error.
*/
@@ -18326,9 +18168,7 @@
* buffer must not be modified and will become invalid when reading from
* the stream or filling the buffer.
*
- * read-only buffer
- *
- * Returns: (array length=count) (element-type guint8) (transfer none):
+ * Returns: (array length=count) (element-type guint8) (transfer none): read-only buffer
*/
@@ -18373,9 +18213,7 @@
*
* Checks if the buffer automatically grows as data is added.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if the @stream's buffer automatically grows,
+ * Returns: %TRUE if the @stream's buffer automatically grows, %FALSE otherwise.
*/
@@ -18520,15 +18358,15 @@
* callbacks will be invoked after calling this function - there are three
* possible cases:
* <itemizedlist>
- * <listitem><para>
- * @name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
- * </para></listitem>
- * <listitem><para>
- * @bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
- * </para></listitem>
- * <listitem><para>
- * @bus_acquired_handler then @name_acquired_handler (if the name was obtained).
- * </para></listitem>
+ * <listitem><para>
+ * @name_lost_handler with a %NULL connection (if a connection to the bus can't be made).
+ * </para></listitem>
+ * <listitem><para>
+ * @bus_acquired_handler then @name_lost_handler (if the name can't be obtained)
+ * </para></listitem>
+ * <listitem><para>
+ * @bus_acquired_handler then @name_acquired_handler (if the name was obtained).
+ * </para></listitem>
* </itemizedlist>
* When you are done owning the name, just call g_bus_unown_name()
* with the owner id this function returns.
@@ -18561,9 +18399,7 @@
* Simply register objects to be exported in @bus_acquired_handler and
* unregister the objects (if any) in @name_lost_handler.
*
- * g_bus_unown_name() to stop owning the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
* Since: 2.26
*/
@@ -18581,9 +18417,7 @@
* Like g_bus_own_name() but takes a #GDBusConnection instead of a
* #GBusType.
*
- * g_bus_unown_name() to stop owning the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
* Since: 2.26
*/
@@ -18599,9 +18433,7 @@
* Version of g_bus_own_name_on_connection() using closures instead of callbacks for
* easier binding in other languages.
*
- * g_bus_unown_name() to stop owning the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
* Rename to: g_bus_own_name_on_connection
* Since: 2.26
*/
@@ -18619,9 +18451,7 @@
* Version of g_bus_own_name() using closures instead of callbacks for
* easier binding in other languages.
*
- * g_bus_unown_name() to stop owning the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name.
* Rename to: g_bus_own_name
* Since: 2.26
*/
@@ -18687,9 +18517,7 @@
* should create object proxies in @name_appeared_handler and destroy
* them again (if any) in @name_vanished_handler.
*
- * g_bus_unwatch_name() to stop watching the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
* Since: 2.26
*/
@@ -18707,9 +18535,7 @@
* Like g_bus_watch_name() but takes a #GDBusConnection instead of a
* #GBusType.
*
- * g_bus_unwatch_name() to stop watching the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
* Since: 2.26
*/
@@ -18725,9 +18551,7 @@
* Version of g_bus_watch_name_on_connection() using closures instead of callbacks for
* easier binding in other languages.
*
- * g_bus_unwatch_name() to stop watching the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
* Rename to: g_bus_watch_name_on_connection
* Since: 2.26
*/
@@ -18744,9 +18568,7 @@
* Version of g_bus_watch_name() using closures instead of callbacks for
* easier binding in other languages.
*
- * g_bus_unwatch_name() to stop watching the name.
- *
- * Returns: An identifier (never 0) that an be used with
+ * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name.
* Rename to: g_bus_watch_name
* Since: 2.26
*/
@@ -18794,9 +18616,7 @@
*
* See #GCancellable::cancelled for details on how to use this.
*
- * been cancelled.
- *
- * Returns: The id of the signal handler or 0 if @cancellable has already
+ * Returns: The id of the signal handler or 0 if @cancellable has already been cancelled.
* Since: 2.22
*/
@@ -18830,9 +18650,7 @@
*
* Gets the top cancellable from the stack.
*
- * if the stack is empty.
- *
- * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL
+ * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL if the stack is empty.
*/
@@ -18854,9 +18672,7 @@
*
* See also g_cancellable_make_pollfd().
*
- * is not supported, or on errors.
- *
- * Returns: A valid file descriptor. %-1 if the file descriptor
+ * Returns: A valid file descriptor. %-1 if the file descriptor is not supported, or on errors.
*/
@@ -18866,9 +18682,7 @@
*
* Checks if a cancellable job has been cancelled.
*
- * FALSE if called with %NULL or if item is not cancelled.
- *
- * Returns: %TRUE if @cancellable is cancelled,
+ * Returns: %TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled.
*/
@@ -18896,9 +18710,7 @@
* readable status. Reading to unset the readable status is done
* with g_cancellable_reset().
*
- * failure to prepare the cancellable.
- *
- * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on
+ * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable.
* Since: 2.22
*/
@@ -19054,9 +18866,7 @@
* Checks if a content type can be executable. Note that for instance
* things like text files can be executables (i.e. scripts and batch files).
*
- * can be executable, %FALSE otherwise.
- *
- * Returns: %TRUE if the file type corresponds to a type that
+ * Returns: %TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise.
*/
@@ -19067,9 +18877,7 @@
*
* Compares two content types for equality.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if the two strings are identical or equivalent,
+ * Returns: %TRUE if the two strings are identical or equivalent, %FALSE otherwise.
*/
@@ -19079,9 +18887,7 @@
*
* Tries to find a content type based on the mime type name.
*
- * or %NULL. Free with g_free()
- *
- * Returns: (allow-none): Newly allocated string with content type
+ * Returns: (allow-none): Newly allocated string with content type or %NULL. Free with g_free()
* Since: 2.18
*/
@@ -19092,9 +18898,7 @@
*
* Gets the human readable description of the content type.
*
- * returned string with g_free()
- *
- * Returns: a short description of the content type @type. Free the
+ * Returns: a short description of the content type @type. Free the returned string with g_free()
*/
@@ -19104,9 +18908,7 @@
*
* Gets the icon for a content type.
*
- * object with g_object_unref()
- *
- * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned
+ * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned object with g_object_unref()
*/
@@ -19116,9 +18918,7 @@
*
* Gets the mime type for the content type, if one is registered.
*
- * or %NULL if unknown.
- *
- * Returns: (allow-none): the registered mime type for the given @type,
+ * Returns: (allow-none): the registered mime type for the given @type, or %NULL if unknown.
*/
@@ -19134,9 +18934,7 @@
* or @data may be %NULL, in which case the guess will be based solely
* on the other argument.
*
- * given data. Free with g_free()
- *
- * Returns: a string indicating a guessed content type for the
+ * Returns: a string indicating a guessed content type for the given data. Free with g_free()
*/
@@ -19156,9 +18954,7 @@
* This function is useful in the implementation of
* g_mount_guess_content_type().
*
- * array of zero or more content types. Free with g_strfreev()
- *
- * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated
+ * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated array of zero or more content types. Free with g_strfreev()
* Since: 2.18
*/
@@ -19170,9 +18966,7 @@
*
* Determines if @type is a subset of @supertype.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if @type is a kind of @supertype,
+ * Returns: %TRUE if @type is a kind of @supertype, %FALSE otherwise.
*/
@@ -19369,11 +19163,7 @@
* logged) to use this method if there is no #GCredentials support for
* the OS or if @native_type isn't supported by the OS.
*
- * operation there is no #GCredentials support for the OS or if
- * @native_type isn't supported by the OS. Do not free the returned
- * data, it is owned by @credentials.
- *
- * Returns: The pointer to native credentials or %NULL if the
+ * Returns: The pointer to native credentials or %NULL if the operation there is no #GCredentials support for the OS or if @native_type isn't supported by the OS. Do not free the returned data, it is owned by @credentials.
* Since: 2.26
*/
@@ -19406,9 +19196,7 @@
* This operation can fail if #GCredentials is not supported on the
* the OS.
*
- * user, %FALSE otherwise or if @error is set.
- *
- * Returns: %TRUE if @credentials and @other_credentials has the same
+ * Returns: %TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set.
* Since: 2.26
*/
@@ -19510,9 +19298,7 @@
*
* Reads an unsigned 8-bit/1-byte value from @stream.
*
- * if an error occurred.
- *
- * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
+ * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 if an error occurred.
*/
@@ -19527,9 +19313,7 @@
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
*
- * an error occurred.
- *
- * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
+ * Returns: a signed 16-bit/2-byte value read from @stream or %0 if an error occurred.
*/
@@ -19548,9 +19332,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * an error occurred.
- *
- * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
+ * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if an error occurred.
*/
@@ -19569,9 +19351,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * an error occurred.
- *
- * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
+ * Returns: a signed 64-bit/8-byte value read from @stream or %0 if an error occurred.
*/
@@ -19590,13 +19370,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * NUL terminated byte array with the line that was read in (without
- * the newlines). Set @length to a #gsize to get the length of the
- * read line. On an error, it will return %NULL and @error will be
- * set. If there's no content to read, it will still return %NULL,
- * but @error won't be set.
- *
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
+ * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set.
*/
@@ -19631,13 +19405,7 @@
* string encoding in g_data_input_stream_read_line() applies here as
* well.
*
- * NUL-terminated byte array with the line that was read in
- * (without the newlines). Set @length to a #gsize to get the
- * length of the read line. On an error, it will return %NULL and
- * @error will be set. If there's no content to read, it will
- * still return %NULL, but @error won't be set.
- *
- * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a
+ * Returns: (transfer full) (array zero-terminated=1) (element-type guint8): a NUL-terminated byte array with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. If there's no content to read, it will still return %NULL, but @error won't be set.
* Since: 2.20
*/
@@ -19652,13 +19420,7 @@
* Finish an asynchronous call started by
* g_data_input_stream_read_line_async().
*
- * (without the newlines). Set @length to a #gsize to get the length
- * of the read line. On an error, it will return %NULL and @error
- * will be set. For UTF-8 conversion errors, the set error domain is
- * %G_CONVERT_ERROR. If there's no content to read, it will still
- * return %NULL, but @error won't be set.
- *
- * Returns: (transfer full): a string with the line that was read in
+ * Returns: (transfer full): a string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set.
* Since: 2.30
*/
@@ -19676,13 +19438,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * line that was read in (without the newlines). Set @length to a
- * #gsize to get the length of the read line. On an error, it will
- * return %NULL and @error will be set. For UTF-8 conversion errors,
- * the set error domain is %G_CONVERT_ERROR. If there's no content to
- * read, it will still return %NULL, but @error won't be set.
- *
- * Returns: (transfer full): a NUL terminated UTF-8 string with the
+ * Returns: (transfer full): a NUL terminated UTF-8 string with the line that was read in (without the newlines). Set @length to a #gsize to get the length of the read line. On an error, it will return %NULL and @error will be set. For UTF-8 conversion errors, the set error domain is %G_CONVERT_ERROR. If there's no content to read, it will still return %NULL, but @error won't be set.
* Since: 2.30
*/
@@ -19698,9 +19454,7 @@
* In order to get the correct byte order for this read operation,
* see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
*
- * an error occurred.
- *
- * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
+ * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if an error occurred.
*/
@@ -19719,9 +19473,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * an error occurred.
- *
- * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
+ * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if an error occurred.
*/
@@ -19740,9 +19492,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * an error occurred.
- *
- * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
+ * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if an error occurred.
*/
@@ -19766,11 +19516,7 @@
* g_data_input_stream_read_upto() instead, but note that that function
* does not consume the stop character.
*
- * before encountering any of the stop characters. Set @length to
- * a #gsize to get the length of the string. This function will
- * return %NULL on an error.
- *
- * Returns: (transfer full): a string with the data that was read
+ * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error.
*/
@@ -19813,13 +19559,8 @@
* Finish an asynchronous call started by
* g_data_input_stream_read_until_async().
*
- *
- * before encountering any of the stop characters. Set @length to
- * a #gsize to get the length of the string. This function will
- * return %NULL on an error.
- *
* Since: 2.20
- * Returns: (transfer full): a string with the data that was read
+ * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error.
*/
@@ -19843,11 +19584,7 @@
* Note that @stop_chars may contain '\0' if @stop_chars_len is
* specified.
*
- * before encountering any of the stop characters. Set @length to
- * a #gsize to get the length of the string. This function will
- * return %NULL on an error
- *
- * Returns: (transfer full): a string with the data that was read
+ * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error
* Since: 2.26
*/
@@ -19895,11 +19632,7 @@
* stop character. You have to use g_data_input_stream_read_byte() to
* get it before calling g_data_input_stream_read_upto_async() again.
*
- * before encountering any of the stop characters. Set @length to
- * a #gsize to get the length of the string. This function will
- * return %NULL on an error.
- *
- * Returns: (transfer full): a string with the data that was read
+ * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to a #gsize to get the length of the string. This function will return %NULL on an error.
* Since: 2.24
*/
@@ -20267,9 +20000,7 @@
* message. Similary, if a filter consumes an outgoing message, the
* message will not be sent to the other peer.
*
- * g_dbus_connection_remove_filter().
- *
- * Returns: A filter identifier that can be used with
+ * Returns: A filter identifier that can be used with g_dbus_connection_remove_filter().
* Since: 2.26
*/
@@ -20306,20 +20037,20 @@
* If the @parameters #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.:
* |[
- * g_dbus_connection_call (connection,
- * "org.freedesktop.StringThings",
- * "/org/freedesktop/StringThings",
- * "org.freedesktop.StringThings",
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * NULL,
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * (GAsyncReadyCallback) two_strings_done,
- * NULL);
+ * g_dbus_connection_call (connection,
+ * "org.freedesktop.StringThings",
+ * "/org/freedesktop/StringThings",
+ * "org.freedesktop.StringThings",
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * NULL,
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * (GAsyncReadyCallback) two_strings_done,
+ * NULL);
* ]|
*
* This is an asynchronous method. When the operation is finished, @callback will be invoked
@@ -20344,9 +20075,7 @@
*
* Finishes an operation started with g_dbus_connection_call().
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.26
*/
@@ -20374,6 +20103,7 @@
* operation will fail with %G_IO_ERROR_CANCELLED. If @parameters
* contains a value not compatible with the D-Bus protocol, the operation
* fails with %G_IO_ERROR_INVALID_ARGUMENT.
+ *
* If @reply_type is non-%NULL then the reply will be checked for having
* this type and an error will be raised if it does not match. Said
* another way, if you give a @reply_type then any non-%NULL return
@@ -20382,28 +20112,26 @@
* If the @parameters #GVariant is floating, it is consumed.
* This allows convenient 'inline' use of g_variant_new(), e.g.:
* |[
- * g_dbus_connection_call_sync (connection,
- * "org.freedesktop.StringThings",
- * "/org/freedesktop/StringThings",
- * "org.freedesktop.StringThings",
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * NULL,
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * &error);
+ * g_dbus_connection_call_sync (connection,
+ * "org.freedesktop.StringThings",
+ * "/org/freedesktop/StringThings",
+ * "org.freedesktop.StringThings",
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * NULL,
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * &error);
* ]|
*
* The calling thread is blocked until a reply is received. See
* g_dbus_connection_call() for the asynchronous version of
* this method.
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.26
*/
@@ -20441,9 +20169,7 @@
*
* Finishes an operation started with g_dbus_connection_call_with_unix_fd_list().
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.30
*/
@@ -20468,9 +20194,7 @@
*
* This method is only available on UNIX.
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.30
*/
@@ -20695,9 +20419,7 @@
* closed by the remote peer. See
* #GDBusConnection:exit-on-close for more details.
*
- * closed by the remote peer.
- *
- * Returns: Whether the process is terminated when @connection is
+ * Returns: Whether the process is terminated when @connection is closed by the remote peer.
* Since: 2.26
*/
@@ -20709,9 +20431,7 @@
* The GUID of the peer performing the role of server when
* authenticating. See #GDBusConnection:guid for more details.
*
- * @connection.
- *
- * Returns: The GUID. Do not free this string, it is owned by
+ * Returns: The GUID. Do not free this string, it is owned by @connection.
* Since: 2.26
*/
@@ -20730,9 +20450,7 @@
* each application is a client. So this method will always return
* %NULL for message bus clients.
*
- * this object, it is owned by @connection.
- *
- * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free
+ * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection.
* Since: 2.26
*/
@@ -20760,10 +20478,7 @@
* bus. This can also be used to figure out if @connection is a
* message bus connection.
*
- * bus connection. Do not free this string, it is owned by
- * @connection.
- *
- * Returns: The unique name or %NULL if @connection is not a message
+ * Returns: The unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection.
* Since: 2.26
*/
@@ -20980,9 +20695,7 @@
*
* See <xref linkend="gdbus-server"/> for an example of how to use this method.
*
- * that can be used with g_dbus_connection_unregister_object() .
- *
- * Returns: 0 if @error is set, otherwise a registration id (never 0)
+ * Returns: 0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() .
* Since: 2.26
*/
@@ -21032,9 +20745,7 @@
*
* See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method.
*
- * that can be used with g_dbus_connection_unregister_subtree() .
- *
- * Returns: 0 if @error is set, otherwise a subtree registration id (never 0)
+ * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) that can be used with g_dbus_connection_unregister_subtree() .
* Since: 2.26
*/
@@ -21078,9 +20789,7 @@
* Note that @message must be unlocked, unless @flags contain the
* %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag.
*
- * transmission, %FALSE if @error is set.
- *
- * Returns: %TRUE if the message was well-formed and queued for
+ * Returns: %TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set.
* Since: 2.26
*/
@@ -21371,9 +21080,7 @@
* Checks if @error represents an error received via D-Bus from a remote peer. If so,
* use g_dbus_error_get_remote_error() to get the name of the error.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if @error represents an error from a remote peer,
+ * Returns: %TRUE if @error represents an error from a remote peer, %FALSE otherwise.
* Since: 2.26
*/
@@ -21427,9 +21134,7 @@
* This is typically done in the routine that returns the #GQuark for
* an error domain.
*
- * exists.
- *
- * Returns: %TRUE if the association was created, %FALSE if it already
+ * Returns: %TRUE if the association was created, %FALSE if it already exists.
* Since: 2.26
*/
@@ -21529,57 +21234,57 @@
*
* 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>
+ * <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>
* 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
@@ -21595,10 +21300,7 @@
* See the g_dbus_gvariant_to_gvalue() function for how to convert a
* #GVariant to a #GValue.
*
- * @type holding the data from @gvalue or %NULL in case of
- * failure. Free with g_variant_unref().
- *
- * Returns: A #GVariant (never floating) of #GVariantType
+ * 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
*/
@@ -21626,9 +21328,7 @@
*
* Gets the #GDBusObject that @interface_ belongs to, if any.
*
- * reference should be freed with g_object_unref().
- *
- * Returns: (transfer full): A #GDBusObject or %NULL. The returned
+ * Returns: (transfer full): A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref().
* Since: 2.32
* Rename to: g_dbus_interface_get_object
*/
@@ -21657,9 +21357,7 @@
* g_dbus_interface_dup_object() for a thread-safe
* alternative.</warning>
*
- * reference belongs to @interface_ and should not be freed.
- *
- * Returns: (transfer none): A #GDBusObject or %NULL. The returned
+ * Returns: (transfer none): A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed.
* Since: 2.30
*/
@@ -21809,9 +21507,7 @@
*
* Use g_dbus_interface_skeleton_unexport() to unexport the object.
*
- * @error set.
- *
- * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with
+ * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with @error set.
* Since: 2.30
*/
@@ -21839,9 +21535,7 @@
*
* Gets the first connection that @interface_ is exported on, if any.
*
- * not exported anywhere. Do not free, the object belongs to @interface_.
- *
- * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is
+ * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_.
* Since: 2.30
*/
@@ -21852,11 +21546,7 @@
*
* Gets a list of the connections that @interface_ is exported on.
*
- * all the connections that @interface_ is exported on. The returned
- * list should be freed with g_list_free() after each element has
- * been freed with g_object_unref().
- *
- * Returns: (element-type GDBusConnection) (transfer full): A list of
+ * Returns: (element-type GDBusConnection) (transfer full): A list of all the connections that @interface_ is exported on. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().
* Since: 2.32
*/
@@ -21891,9 +21581,7 @@
*
* Gets the object path that @interface_ is exported on, if any.
*
- * anywhere. Do not free, the string belongs to @interface_.
- *
- * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported
+ * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_.
* Since: 2.30
*/
@@ -22043,9 +21731,7 @@
* transports in @string and that key/value pairs for each transport
* are valid.
*
- * supported by this library, %FALSE if @error is set.
- *
- * Returns: %TRUE if @string is a valid D-Bus address that is
+ * Returns: %TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set.
* Since: 2.26
*/
@@ -22076,9 +21762,7 @@
* (and linked models) must also originate from this same context, with
* the thread default main context unchanged.
*
- * g_object_unref().
- *
- * Returns: (transfer full): a #GDBusMenuModel object. Free with
+ * Returns: (transfer full): a #GDBusMenuModel object. Free with g_object_unref().
* Since: 2.32
*/
@@ -22092,10 +21776,7 @@
* Utility function to calculate how many bytes are needed to
* completely deserialize the D-Bus message stored at @blob.
*
- * @blob contains invalid data or not enough data is available to
- * determine the size).
- *
- * Returns: Number of bytes needed or -1 if @error is set (e.g. if
+ * Returns: Number of bytes needed or -1 if @error is set (e.g. if @blob contains invalid data or not enough data is available to determine the size).
* Since: 2.26
*/
@@ -22112,9 +21793,7 @@
* This operation can fail if e.g. @message contains file descriptors
* and the per-process or system-wide open files limit is reached.
*
- * Free with g_object_unref().
- *
- * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set.
+ * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref().
* Since: 2.26
*/
@@ -22125,9 +21804,7 @@
*
* Convenience to get the first item in the body of @message.
*
- * @message is not a string.
- *
- * Returns: The string item or %NULL if the first item in the body of
+ * Returns: The string item or %NULL if the first item in the body of @message is not a string.
* Since: 2.26
*/
@@ -22193,9 +21870,7 @@
*
* Gets a header field on @message.
*
- * otherwise. Do not free, it is owned by @message.
- *
- * Returns: A #GVariant with the value if the header was found, %NULL
+ * Returns: A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message.
* Since: 2.26
*/
@@ -22206,10 +21881,7 @@
*
* Gets an array of all header fields on @message that are set.
*
- * terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element
- * is a #guchar. Free with g_free().
- *
- * Returns: (array zero-terminated=1): An array of header fields
+ * Returns: (array zero-terminated=1): An array of header fields terminated by %G_DBUS_MESSAGE_HEADER_FIELD_INVALID. Each element is a #guchar. Free with g_free().
* Since: 2.26
*/
@@ -22334,9 +22006,7 @@
*
* This method is only available on UNIX.
*
- * associated. Do not free, this object is owned by @message.
- *
- * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are
+ * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message.
* Since: 2.26
*/
@@ -22372,9 +22042,7 @@
* order that the message was in can be retrieved using
* g_dbus_message_get_byte_order().
*
- * g_object_unref().
- *
- * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
+ * Returns: A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref().
* Since: 2.26
*/
@@ -22469,34 +22137,35 @@
* and formatting is subject to change at any time. Typical output
* looks something like this:
* <programlisting>
- * Flags: none
- * Version: 0
- * Serial: 4
- * Headers:
- * path -> objectpath '/org/gtk/GDBus/TestObject'
- * interface -> 'org.gtk.GDBus.TestInterface'
- * member -> 'GimmeStdout'
- * destination -> ':1.146'
- * Body: ()
+ * Type: method-call
+ * Flags: none
+ * Version: 0
+ * Serial: 4
+ * Headers:
+ * path -> objectpath '/org/gtk/GDBus/TestObject'
+ * interface -> 'org.gtk.GDBus.TestInterface'
+ * member -> 'GimmeStdout'
+ * destination -> ':1.146'
+ * Body: ()
* UNIX File Descriptors:
- * (none)
+ * (none)
* </programlisting>
* or
* <programlisting>
- * Flags: no-reply-expected
- * Version: 0
- * Serial: 477
- * Headers:
- * reply-serial -> uint32 4
- * destination -> ':1.159'
- * sender -> ':1.146'
- * num-unix-fds -> uint32 1
- * Body: ()
- * UNIX File Descriptors:
- * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
+ * Type: method-return
+ * Flags: no-reply-expected
+ * Version: 0
+ * Serial: 477
+ * Headers:
+ * reply-serial -> uint32 4
+ * destination -> ':1.159'
+ * sender -> ':1.146'
+ * num-unix-fds -> uint32 1
+ * Body: ()
+ * UNIX File Descriptors:
+ * fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
* </programlisting>
*
- * Type: method-return
* Returns: A string that should be freed with g_free().
* Since: 2.26
*/
@@ -22698,10 +22367,7 @@
* Serializes @message to a blob. The byte order returned by
* g_dbus_message_get_byte_order() will be used.
*
- * valid binary D-Bus message of @out_size bytes generated by @message
- * or %NULL if @error is set. Free with g_free().
- *
- * Returns: (array length=out_size) (transfer full): A pointer to a
+ * Returns: (array length=out_size) (transfer full): A pointer to a valid binary D-Bus message of @out_size bytes generated by @message or %NULL if @error is set. Free with g_free().
* Since: 2.26
*/
@@ -23029,9 +22695,7 @@
* <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based
* parser that only accepts a subset of valid XML documents.
*
- * with g_dbus_node_info_unref().
- *
- * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free
+ * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref().
* Since: 2.26
*/
@@ -23068,9 +22732,7 @@
* Gets the D-Bus interface with name @interface_name associated with
* @object, if any.
*
- * #GDBusInterface that must be freed with g_object_unref().
- *
- * Returns: (transfer full): %NULL if not found, otherwise a
+ * Returns: (transfer full): %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref().
* Since: 2.30
*/
@@ -23081,10 +22743,7 @@
*
* Gets the D-Bus interfaces associated with @object.
*
- * The returned list must be freed by g_list_free() after each element has been freed
- * with g_object_unref().
- *
- * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances.
+ * Returns: (element-type GDBusInterface) (transfer full): A list of #GDBusInterface instances. The returned list must be freed by g_list_free() after each element has been freed with g_object_unref().
* Since: 2.30
*/
@@ -23106,9 +22765,7 @@
*
* Gets the #GDBusConnection used by @manager.
*
- * the object belongs to @manager.
- *
- * Returns: (transfer none): A #GDBusConnection object. Do not free,
+ * Returns: (transfer none): A #GDBusConnection object. Do not free, the object belongs to @manager.
* Since: 2.30
*/
@@ -23119,9 +22776,7 @@
*
* Gets the flags that @manager was constructed with.
*
- * enumeration.
- *
- * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags
+ * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags enumeration.
* Since: 2.30
*/
@@ -23132,9 +22787,7 @@
*
* Gets the name that @manager is for.
*
- * belongs to @manager.
- *
- * Returns: A unique or well-known name. Do not free, the string
+ * Returns: A unique or well-known name. Do not free, the string belongs to @manager.
* Since: 2.30
*/
@@ -23148,9 +22801,7 @@
* #GObject::notify signal to track changes to the
* #GDBusObjectManagerClient:name-owner property.
*
- * g_free().
- *
- * Returns: The name owner or %NULL if no name owner exists. Free with
+ * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
* Since: 2.30
*/
@@ -23188,10 +22839,7 @@
*
* Finishes an operation started with g_dbus_object_manager_client_new().
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
- *
- * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
* Since: 2.30
*/
@@ -23230,10 +22878,7 @@
*
* Finishes an operation started with g_dbus_object_manager_client_new_for_bus().
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
- *
- * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
* Since: 2.30
*/
@@ -23257,10 +22902,7 @@
* blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus()
* for the asynchronous version.
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
- *
- * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
* Since: 2.30
*/
@@ -23283,10 +22925,7 @@
* blocked until a reply is received. See g_dbus_object_manager_client_new()
* for the asynchronous version.
*
- * #GDBusObjectManagerClient object or %NULL if @error is set. Free
- * with g_object_unref().
- *
- * Returns: (transfer full) (type GDBusObjectManagerClient): A
+ * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref().
* Since: 2.30
*/
@@ -23300,9 +22939,7 @@
* Gets the interface proxy for @interface_name at @object_path, if
* any.
*
- * with g_object_unref().
- *
- * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
+ * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free with g_object_unref().
* Since: 2.30
*/
@@ -23314,9 +22951,7 @@
*
* Gets the #GDBusObjectProxy at @object_path, if any.
*
- * g_object_unref().
- *
- * Returns: (transfer full): A #GDBusObject or %NULL. Free with
+ * Returns: (transfer full): A #GDBusObject or %NULL. Free with g_object_unref().
* Since: 2.30
*/
@@ -23338,11 +22973,7 @@
*
* Gets all #GDBusObject objects known to @manager.
*
- * #GDBusObject objects. The returned list should be freed with
- * g_list_free() after each element has been freed with
- * g_object_unref().
- *
- * Returns: (transfer full) (element-type GDBusObject): A list of
+ * Returns: (transfer full) (element-type GDBusObject): A list of #GDBusObject objects. The returned list should be freed with g_list_free() after each element has been freed with g_object_unref().
* Since: 2.30
*/
@@ -23388,10 +23019,7 @@
*
* Gets the #GDBusConnection used by @manager.
*
- * @manager isn't exported on a connection. The returned object should
- * be freed with g_object_unref().
- *
- * Returns: (transfer full): A #GDBusConnection object or %NULL if
+ * Returns: (transfer full): A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref().
* Since: 2.30
*/
@@ -23445,9 +23073,7 @@
*
* Gets the connection that @proxy is for.
*
- * object is owned by @proxy.
- *
- * Returns: (transfer none): A #GDBusConnection. Do not free, the
+ * Returns: (transfer none): A #GDBusConnection. Do not free, the object is owned by @proxy.
* Since: 2.30
*/
@@ -23592,16 +23218,16 @@
* If the @parameters #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.:
* |[
- * g_dbus_proxy_call (proxy,
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * (GAsyncReadyCallback) two_strings_done,
- * &data);
+ * g_dbus_proxy_call (proxy,
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * (GAsyncReadyCallback) two_strings_done,
+ * &data);
* ]|
*
* If @proxy has an expected interface (see
@@ -23631,9 +23257,7 @@
*
* Finishes an operation started with g_dbus_proxy_call().
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.26
*/
@@ -23664,15 +23288,15 @@
* If the @parameters #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.:
* |[
- * g_dbus_proxy_call_sync (proxy,
- * "TwoStrings",
- * g_variant_new ("(ss)",
- * "Thing One",
- * "Thing Two"),
- * G_DBUS_CALL_FLAGS_NONE,
- * -1,
- * NULL,
- * &error);
+ * g_dbus_proxy_call_sync (proxy,
+ * "TwoStrings",
+ * g_variant_new ("(ss)",
+ * "Thing One",
+ * "Thing Two"),
+ * G_DBUS_CALL_FLAGS_NONE,
+ * -1,
+ * NULL,
+ * &error);
* ]|
*
* The calling thread is blocked until a reply is received. See
@@ -23683,9 +23307,7 @@
* #GDBusProxy:g-interface-info) and @method_name is referenced by it,
* then the return value is checked against the return type.
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.26
*/
@@ -23719,9 +23341,7 @@
*
* Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.30
*/
@@ -23742,9 +23362,7 @@
*
* This method is only available on UNIX.
*
- * return values. Free with g_variant_unref().
- *
- * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with
+ * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref().
* Since: 2.30
*/
@@ -23761,10 +23379,7 @@
* #GDBusProxy:g-interface-info) and @property_name is referenced by
* it, then @value is checked against the type of the property.
*
- * for @property_name or %NULL if the value is not in the cache. The
- * returned reference must be freed with g_variant_unref().
- *
- * Returns: A reference to the #GVariant instance that holds the value
+ * Returns: A reference to the #GVariant instance that holds the value for @property_name or %NULL if the value is not in the cache. The returned reference must be freed with g_variant_unref().
* Since: 2.26
*/
@@ -23775,10 +23390,7 @@
*
* Gets the names of all cached properties on @proxy.
*
- * @proxy has no cached properties. Free the returned array with
- * g_strfreev().
- *
- * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
+ * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev().
* Since: 2.26
*/
@@ -23828,9 +23440,7 @@
* that @proxy conforms to. See the #GDBusProxy:g-interface-info
* property for more details.
*
- * object, it is owned by @proxy.
- *
- * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
+ * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy.
* Since: 2.26
*/
@@ -24040,11 +23650,11 @@
* If the @value #GVariant is floating, it is consumed. This allows
* convenient 'inline' use of g_variant_new(), e.g.
* |[
- * g_dbus_proxy_set_cached_property (proxy,
- * "SomeProperty",
- * g_variant_new ("(si)",
- * "A String",
- * 42));
+ * g_dbus_proxy_set_cached_property (proxy,
+ * "SomeProperty",
+ * g_variant_new ("(si)",
+ * "A String",
+ * 42));
* ]|
*
* Normally you will not need to use this method since @proxy is
@@ -24101,9 +23711,7 @@
* Gets a D-Bus address string that can be used by clients to connect
* to @server.
*
- * by @server.
- *
- * Returns: A D-Bus address string. Do not free, the string is owned
+ * Returns: A D-Bus address string. Do not free, the string is owned by @server.
* Since: 2.26
*/
@@ -24168,9 +23776,7 @@
* This is a synchronous failable constructor. See
* g_dbus_server_new() for the asynchronous version.
*
- * g_object_unref().
- *
- * Returns: A #GDBusServer or %NULL if @error is set. Free with
+ * Returns: A #GDBusServer or %NULL if @error is set. Free with g_object_unref().
* Since: 2.26
*/
@@ -24225,9 +23831,7 @@
*
* Gets the categories from the desktop file.
*
- * i.e. no attempt is made to split it by ';' or validate it.
- *
- * Returns: The unparsed Categories key from the desktop file;
+ * Returns: The unparsed Categories key from the desktop file; i.e. no attempt is made to split it by ';' or validate it.
*/
@@ -24304,10 +23908,7 @@
* Note that g_app_info_should_show() for @info will include this check (with
* %NULL for @desktop_env) as well as additional checks.
*
- * <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE
- * otherwise.
- *
- * Returns: %TRUE if the @info should be shown in @desktop_env according to the
+ * Returns: %TRUE if the @info should be shown in @desktop_env according to the <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE otherwise.
* Since: 2.30
*/
@@ -24416,13 +24017,13 @@
* The <ulink url="http://standards.freedesktop.org/menu-spec/latest/";>Desktop
* Menu specification</ulink> recognizes the following:
* <simplelist>
- * <member>GNOME</member>
- * <member>KDE</member>
- * <member>ROX</member>
- * <member>XFCE</member>
- * <member>LXDE</member>
- * <member>Unity</member>
- * <member>Old</member>
+ * <member>GNOME</member>
+ * <member>KDE</member>
+ * <member>ROX</member>
+ * <member>XFCE</member>
+ * <member>LXDE</member>
+ * <member>Unity</member>
+ * <member>Old</member>
* </simplelist>
*
* Should be called only once; subsequent calls are ignored.
@@ -24445,9 +24046,7 @@
*
* Checks if a drive can be polled for media changes.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if the @drive can be polled for media changes,
+ * Returns: %TRUE if the @drive can be polled for media changes, %FALSE otherwise.
*/
@@ -24510,9 +24109,7 @@
*
* Finishes ejecting a drive.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if the drive has been ejected successfully,
+ * Returns: %TRUE if the drive has been ejected successfully, %FALSE otherwise.
* Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead.
*/
@@ -24556,10 +24153,7 @@
* Use g_drive_get_identifier() to obtain the identifiers
* themselves.
*
- * array of strings containing kinds of identifiers. Use g_strfreev()
- * to free.
- *
- * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated
+ * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free.
*/
@@ -24569,9 +24163,7 @@
*
* Gets the icon for @drive.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GIcon for the @drive.
+ * Returns: (transfer full): #GIcon for the @drive. Free the returned object with g_object_unref().
*/
@@ -24582,10 +24174,7 @@
*
* Gets the identifier of the given kind for @drive.
*
- * requested identfier, or %NULL if the #GDrive
- * doesn't have this kind of identifier.
- *
- * Returns: a newly allocated string containing the
+ * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GDrive doesn't have this kind of identifier.
*/
@@ -24595,9 +24184,7 @@
*
* Gets the name of @drive.
*
- * string should be freed when no longer needed.
- *
- * Returns: a string containing @drive's name. The returned
+ * Returns: a string containing @drive's name. The returned string should be freed when no longer needed.
*/
@@ -24664,9 +24251,7 @@
*
* Checks if @drive is capabable of automatically detecting media changes.
*
- * media changes, %FALSE otherwise.
- *
- * Returns: %TRUE if the @drive is capabable of automatically detecting
+ * Returns: %TRUE if the @drive is capabable of automatically detecting media changes, %FALSE otherwise.
*/
@@ -24703,9 +24288,7 @@
*
* Finishes an operation started with g_drive_poll_for_media() on a drive.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if the drive has been poll_for_mediaed successfully,
+ * Returns: %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise.
*/
@@ -24736,9 +24319,7 @@
*
* Finishes starting a drive.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if the drive has been started successfully,
+ * Returns: %TRUE if the drive has been started successfully, %FALSE otherwise.
* Since: 2.22
*/
@@ -24770,9 +24351,7 @@
*
* Finishes stopping a drive.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if the drive has been stopped successfully,
+ * Returns: %TRUE if the drive has been stopped successfully, %FALSE otherwise.
* Since: 2.22
*/
@@ -24783,9 +24362,7 @@
*
* Gives back the icon from @emblem.
*
- * the emblem and should not be modified or freed.
- *
- * Returns: (transfer none): a #GIcon. The returned object belongs to
+ * Returns: (transfer none): a #GIcon. The returned object belongs to the emblem and should not be modified or freed.
* Since: 2.18
*/
@@ -24851,9 +24428,7 @@
*
* Gets the list of emblems for the @icon.
*
- * #GEmblem <!-- -->s that is owned by @emblemed
- *
- * Returns: (element-type Gio.Emblem) (transfer none): a #GList of
+ * Returns: (element-type Gio.Emblem) (transfer none): a #GList of #GEmblem <!-- -->s that is owned by @emblemed
* Since: 2.18
*/
@@ -24906,9 +24481,7 @@
* returned. Other errors are possible too, and depend on what kind of
* filesystem the file is on.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
+ * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -24940,9 +24513,7 @@
* Finishes an asynchronous file append operation started with
* g_file_append_to_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error.
+ * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -24975,9 +24546,7 @@
*
* Gets the file attribute with the name @name from @list.
*
- * attribute isn't found.
- *
- * Returns: a #GFileAttributeInfo for the @name, or %NULL if an
+ * Returns: a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found.
*/
@@ -25021,9 +24590,7 @@
*
* TODO: this is awkwardly worded.
*
- * in the given @ns, %FALSE otherwise.
- *
- * Returns: %TRUE if the matcher matches all of the entries
+ * Returns: %TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise.
*/
@@ -25033,9 +24600,7 @@
*
* Gets the next matched attribute from a #GFileAttributeMatcher.
*
- * no more attribute exist.
- *
- * Returns: a string containing the next attribute or %NULL if
+ * Returns: a string containing the next attribute or %NULL if no more attribute exist.
*/
@@ -25121,9 +24686,7 @@
* is a limitation of the current implementation, but may be fixed
* in the future.
*
- * @matcher that are not matched by @subtract
- *
- * Returns: A file attribute matcher matching all attributes of
+ * Returns: A file attribute matcher matching all attributes of @matcher that are not matched by @subtract
*/
@@ -25136,9 +24699,7 @@
* The output however, might not be identical, as the matcher may
* decide to use a different order or omit needless parts.
*
- * against or %NULL if @matcher was %NULL.
- *
- * Returns: a string describing the attributes the matcher matches
+ * Returns: a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL.
* Since: 2.32
*/
@@ -25288,10 +24849,7 @@
* Other errors are possible too, and depend on what kind of
* filesystem the file is on.
*
- * %NULL on error.
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileOutputStream for the newly created file, or
+ * Returns: (transfer full): a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -25324,9 +24882,7 @@
* Finishes an asynchronous file create operation started with
* g_file_create_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
+ * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -25359,9 +24915,7 @@
* supported, so make sure you really need to do read and write streaming,
* rather than just opening for reading or writing.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error.
+ * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -25397,9 +24951,7 @@
* Finishes an asynchronous file create operation started with
* g_file_create_readwrite_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileIOStream or %NULL on error.
+ * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -25477,9 +25029,7 @@
* Finishes an asynchronous eject operation started by
* g_file_eject_mountable().
*
- * otherwise.
- *
- * Returns: %TRUE if the @file was ejected successfully. %FALSE
+ * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise.
* Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead.
*/
@@ -25515,9 +25065,7 @@
* Finishes an asynchronous eject operation started by
* g_file_eject_mountable_with_operation().
*
- * otherwise.
- *
- * Returns: %TRUE if the @file was ejected successfully. %FALSE
+ * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise.
* Since: 2.22
*/
@@ -25550,9 +25098,7 @@
* If the file is not a directory, the G_FILE_ERROR_NOTDIR error will be returned.
* Other errors are possible too.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error.
+ * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref().
*/
@@ -25587,9 +25133,7 @@
* Finishes an async enumerate children operation.
* See g_file_enumerate_children_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred.
+ * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref().
*/
@@ -25694,9 +25238,7 @@
* enumerator is at the end, %NULL will be returned and @error will
* be unset.
*
- * Free the returned object with g_object_unref() when no longer needed.
- *
- * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator.
+ * Returns: (transfer full): A #GFileInfo or %NULL on error or end of enumerator. Free the returned object with g_object_unref() when no longer needed.
*/
@@ -25736,10 +25278,7 @@
*
* Finishes the asynchronous operation started with g_file_enumerator_next_files_async().
*
- * g_list_free() and unref the infos with g_object_unref() when you're
- * done with them.
- *
- * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with
+ * Returns: (transfer full) (element-type Gio.FileInfo): a #GList of #GFileInfo<!---->s. You must free the list with g_list_free() and unref the infos with g_object_unref() when you're done with them.
*/
@@ -25764,9 +25303,7 @@
*
* This call does no blocking i/o.
*
- * %FALSE if either is not a #GFile.
- *
- * Returns: %TRUE if @file1 and @file2 are equal.
+ * Returns: %TRUE if @file1 and @file2 are equal. %FALSE if either is not a #GFile.
*/
@@ -25786,9 +25323,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GMount where the @file is located or %NULL on error.
+ * Returns: (transfer full): a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -25819,9 +25354,7 @@
* Finishes an asynchronous find mount request.
* See g_file_find_enclosing_mount_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GMount for given @file or %NULL on error.
+ * Returns: (transfer full): #GMount for given @file or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -25843,10 +25376,7 @@
*
* This call does no blocking i/o.
*
- * if given #GFile is invalid. The returned string should be
- * freed with g_free() when no longer needed.
- *
- * Returns: string containing the #GFile's base name, or %NULL
+ * Returns: string containing the #GFile's base name, or %NULL if given #GFile is invalid. The returned string should be freed with g_free() when no longer needed.
*/
@@ -25863,9 +25393,7 @@
*
* This call does no blocking i/o.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile to a child specified by @name.
+ * Returns: (transfer full): a #GFile to a child specified by @name. Free the returned object with g_object_unref().
*/
@@ -25883,10 +25411,7 @@
*
* This call does no blocking i/o.
*
- * %NULL if the display name couldn't be converted.
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile to the specified child, or
+ * Returns: (transfer full): a #GFile to the specified child, or %NULL if the display name couldn't be converted. Free the returned object with g_object_unref().
*/
@@ -25900,10 +25425,7 @@
*
* This call does no blocking i/o.
*
- * #GFile or %NULL if there is no parent.
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile structure to the parent of the given
+ * Returns: (transfer full): a #GFile structure to the parent of the given #GFile or %NULL if there is no parent. Free the returned object with g_object_unref().
*/
@@ -25926,9 +25448,7 @@
*
* This call does no blocking i/o.
*
- * string should be freed with g_free() when no longer needed.
- *
- * Returns: a string containing the #GFile's parse name. The returned
+ * Returns: a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed.
*/
@@ -25940,10 +25460,7 @@
*
* This call does no blocking i/o.
*
- * no such path exists. The returned string should be
- * freed with g_free() when no longer needed.
- *
- * Returns: string containing the #GFile's path, or %NULL if
+ * Returns: string containing the #GFile's path, or %NULL if no such path exists. The returned string should be freed with g_free() when no longer needed.
*/
@@ -25956,10 +25473,7 @@
*
* This call does no blocking i/o.
*
- * to @parent, or %NULL if @descendant doesn't have @parent as prefix.
- * The returned string should be freed with g_free() when no longer needed.
- *
- * Returns: string with the relative path from @descendant
+ * Returns: string with the relative path from @descendant to @parent, or %NULL if @descendant doesn't have @parent as prefix. The returned string should be freed with g_free() when no longer needed.
*/
@@ -25971,9 +25485,7 @@
*
* This call does no blocking i/o.
*
- * The returned string should be freed with g_free() when no longer needed.
- *
- * Returns: a string containing the #GFile's URI.
+ * Returns: a string containing the #GFile's URI. The returned string should be freed with g_free() when no longer needed.
*/
@@ -25990,10 +25502,7 @@
*
* This call does no blocking i/o.
*
- * #GFile. The returned string should be freed with g_free()
- * when no longer needed.
- *
- * Returns: a string containing the URI scheme for the given
+ * Returns: a string containing the URI scheme for the given #GFile. The returned string should be freed with g_free() when no longer needed.
*/
@@ -26008,9 +25517,7 @@
* parent at all. If @parent is non-%NULL then %TRUE is only returned
* if @file is a child of @parent.
*
- * case that @parent is %NULL).
- *
- * Returns: %TRUE if @file is a child of @parent (or any parent in the
+ * Returns: %TRUE if @file is a child of @parent (or any parent in the case that @parent is %NULL).
* Since: 2.24
*/
@@ -26030,10 +25537,8 @@
* filesystem point of view), because the prefix of @file is an alias
* of @prefix.
*
- * %FALSE otherwise.
- *
* Virtual: prefix_matches
- * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix.
+ * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix. %FALSE otherwise.
*/
@@ -26046,10 +25551,7 @@
*
* This call does no blocking i/o.
*
- * given URI scheme, %FALSE if URI scheme is %NULL,
- * not supported, or #GFile is invalid.
- *
- * Returns: %TRUE if #GFile's backend supports the
+ * Returns: %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid.
*/
@@ -26061,12 +25563,8 @@
*
* This call does no blocking i/o.
*
- * integer that can be used as hash value for the #GFile.
- * This function is intended for easily hashing a #GFile to
- * add to a #GHashTable or similar data structure.
- *
* Virtual: hash
- * Returns: 0 if @file is not a valid #GFile, otherwise an
+ * Returns: 0 if @file is not a valid #GFile, otherwise an integer that can be used as hash value for the #GFile. This function is intended for easily hashing a #GFile to add to a #GHashTable or similar data structure.
*/
@@ -26086,9 +25584,7 @@
*
* Creates a new icon for a file.
*
- * @file, or %NULL on error.
- *
- * Returns: (transfer full) (type GFileIcon): a #GIcon for the given
+ * Returns: (transfer full) (type GFileIcon): a #GIcon for the given @file, or %NULL on error.
*/
@@ -26129,9 +25625,7 @@
* This escapes things as needed to make the string valid
* utf8.
*
- * When you're done with the string it must be freed with g_free().
- *
- * Returns: a UTF-8 string associated with the given @attribute.
+ * Returns: a UTF-8 string associated with the given @attribute. When you're done with the string it must be freed with g_free().
*/
@@ -26155,9 +25649,7 @@
* Gets the value of a byte string attribute. If the attribute does
* not contain a byte string, %NULL will be returned.
*
- * %NULL otherwise.
- *
- * Returns: the contents of the @attribute value as a byte string, or
+ * Returns: the contents of the @attribute value as a byte string, or %NULL otherwise.
*/
@@ -26171,9 +25663,7 @@
*
* Gets the attribute type, value and status for an attribute key.
*
- * %FALSE otherwise.
- *
- * Returns: (transfer none): %TRUE if @info has an attribute named @attribute,
+ * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, %FALSE otherwise.
*/
@@ -26211,9 +25701,7 @@
* Gets the value of a #GObject attribute. If the attribute does
* not contain a #GObject, %NULL will be returned.
*
- * %NULL otherwise.
- *
- * Returns: (transfer none): a #GObject associated with the given @attribute, or
+ * Returns: (transfer none): a #GObject associated with the given @attribute, or %NULL otherwise.
*/
@@ -26224,9 +25712,7 @@
*
* Gets the attribute status for an attribute key.
*
- * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
- *
- * Returns: a #GFileAttributeStatus for the given @attribute, or
+ * Returns: a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid.
*/
@@ -26238,9 +25724,7 @@
* Gets the value of a string attribute. If the attribute does
* not contain a string, %NULL will be returned.
*
- * %NULL otherwise.
- *
- * Returns: the contents of the @attribute value as a UTF-8 string, or
+ * Returns: the contents of the @attribute value as a UTF-8 string, or %NULL otherwise.
*/
@@ -26252,9 +25736,7 @@
* Gets the value of a stringv attribute. If the attribute does
* not contain a stringv, %NULL will be returned.
*
- * %NULL otherwise. Do not free. These returned strings are UTF-8.
- *
- * Returns: (transfer none): the contents of the @attribute value as a stringv, or
+ * Returns: (transfer none): the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8.
* Since: 2.22
*/
@@ -26266,9 +25748,7 @@
*
* Gets the attribute type for an attribute key.
*
- * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
- *
- * Returns: a #GFileAttributeType for the given @attribute, or
+ * Returns: a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set.
*/
@@ -26448,9 +25928,7 @@
*
* Checks if a file info structure has an attribute named @attribute.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if @Ginfo has an attribute named @attribute,
+ * Returns: %TRUE if @Ginfo has an attribute named @attribute, %FALSE otherwise.
*/
@@ -26462,9 +25940,7 @@
* Checks if a file info structure has an attribute in the
* specified @name_space.
*
- * %FALSE otherwise.
- *
- * Returns: %TRUE if @Ginfo has an attribute in @name_space,
+ * Returns: %TRUE if @Ginfo has an attribute in @name_space, %FALSE otherwise.
* Since: 2.22
*/
@@ -26476,10 +25952,7 @@
*
* Lists the file info structure's attributes.
*
- * possible attribute types for the given @name_space, or
- * %NULL on error.
- *
- * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the
+ * Returns: (array zero-terminated=1) (transfer full): a null-terminated array of strings of all of the possible attribute types for the given @name_space, or %NULL on error.
*/
@@ -26938,9 +26411,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * %FALSE if there were errors.
- *
- * Returns: %TRUE if the @file's contents were successfully loaded.
+ * Returns: %TRUE if the @file's contents were successfully loaded. %FALSE if there were errors.
*/
@@ -26982,9 +26453,7 @@
* g_free() when no longer needed. If @etag_out is present, it will be
* set to the new entity tag for the @file.
*
- * present, it will be set appropriately.
- *
- * Returns: %TRUE if the load was successful. If %FALSE and @error is
+ * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately.
*/
@@ -27025,9 +26494,7 @@
* The returned @content should be freed with g_free() when no longer
* needed.
*
- * present, it will be set appropriately.
- *
- * Returns: %TRUE if the load was successful. If %FALSE and @error is
+ * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately.
*/
@@ -27075,9 +26542,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * otherwise.
- *
- * Returns: %TRUE if all directories have been successfully created, %FALSE
+ * Returns: %TRUE if all directories have been successfully created, %FALSE otherwise.
* Since: 2.18
*/
@@ -27114,9 +26579,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
+ * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.18
*/
@@ -27145,10 +26608,8 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * Free the returned object with g_object_unref().
- *
* Virtual: monitor_dir
- * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
+ * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27183,9 +26644,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error.
+ * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27238,10 +26697,7 @@
*
* Finishes a mount operation started by g_file_mount_enclosing_volume().
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
- *
- * Returns: %TRUE if successful. If an error
+ * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
*/
@@ -27278,9 +26734,7 @@
* Finish an asynchronous mount operation that was started
* with g_file_mount_mountable().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile or %NULL on error.
+ * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27344,9 +26798,7 @@
* This operation never fails, but the returned object might not support any
* I/O operation if @arg points to a malformed path.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a new #GFile.
+ * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref().
*/
@@ -27358,9 +26810,7 @@
* fails, but the returned object might not support any I/O
* operation if @path is malformed.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a new #GFile for the given @path.
+ * Returns: (transfer full): a new #GFile for the given @path. Free the returned object with g_object_unref().
*/
@@ -27373,9 +26823,7 @@
* operation if @uri is malformed or if the uri type is
* not supported.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a new #GFile for the given @uri.
+ * Returns: (transfer full): a new #GFile for the given @uri. Free the returned object with g_object_unref().
*/
@@ -27396,9 +26844,7 @@
* Unlike the other #GFile constructors, this will return %NULL if
* a temporary file could not be created.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a new #GFile.
+ * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref().
* Since: 2.32
*/
@@ -27423,9 +26869,7 @@
* so make sure you really need to do read and write streaming, rather than
* just opening for reading or writing.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GFileIOStream or %NULL on error.
+ * Returns: (transfer full): #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -27459,9 +26903,7 @@
* Finishes an asynchronous file read operation started with
* g_file_open_readwrite_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileIOStream or %NULL on error.
+ * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -27581,9 +27023,7 @@
* Finish an asynchronous poll operation that was polled
* with g_file_poll_mountable().
*
- * otherwise.
- *
- * Returns: %TRUE if the operation finished successfully. %FALSE
+ * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
* Since: 2.22
*/
@@ -27601,9 +27041,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * When you are done with it, release it with g_object_unref()
- *
- * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors.
+ * Returns: (transfer full): a #GAppInfo if the handle was found, %NULL if there were errors. When you are done with it, release it with g_object_unref()
*/
@@ -27651,9 +27089,7 @@
* The primary use case of this method is to check if a file is a regular file,
* directory, or symlink.
*
- * does not exist
- *
- * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file
+ * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file does not exist
* Since: 2.18
*/
@@ -27687,9 +27123,7 @@
* If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
* Other errors are possible too, and depend on what kind of filesystem the file is on.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileInfo or %NULL if there was an error.
+ * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref().
*/
@@ -27725,9 +27159,7 @@
* Finishes an asynchronous filesystem info query. See
* g_file_query_filesystem_info_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
+ * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27765,9 +27197,7 @@
* If the file does not exist, the G_IO_ERROR_NOT_FOUND error will be returned.
* Other errors are possible too, and depend on what kind of filesystem the file is on.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error.
+ * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27802,9 +27232,7 @@
* Finishes an asynchronous file info query.
* See g_file_query_info_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GFileInfo for given @file or %NULL on error.
+ * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27825,9 +27253,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * When you are done with it, release it with g_file_attribute_info_list_unref()
- *
- * Returns: a #GFileAttributeInfoList describing the settable attributes.
+ * Returns: a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref()
*/
@@ -27845,9 +27271,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * When you are done with it, release it with g_file_attribute_info_list_unref()
- *
- * Returns: a #GFileAttributeInfoList describing the writable namespaces.
+ * Returns: a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref()
*/
@@ -27868,10 +27292,8 @@
* If the file is a directory, the G_IO_ERROR_IS_DIRECTORY error will be returned.
* Other errors are possible too, and depend on what kind of filesystem the file is on.
*
- * Free the returned object with g_object_unref().
- *
* Virtual: read_fn
- * Returns: (transfer full): #GFileInputStream or %NULL on error.
+ * Returns: (transfer full): #GFileInputStream or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27902,9 +27324,7 @@
* Finishes an asynchronous file read operation started with
* g_file_read_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileInputStream or %NULL on error.
+ * Returns: (transfer full): a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -27959,9 +27379,7 @@
* Other errors are possible too, and depend on what kind of
* filesystem the file is on.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileOutputStream or %NULL on error.
+ * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -28000,6 +27418,7 @@
* @error: a #GError, or %NULL
*
* Replaces the contents of @file with @contents of @length bytes.
+ *
* If @etag is specified (not %NULL) any existing file must have that etag, or
* the error %G_IO_ERROR_WRONG_ETAG will be returned.
*
@@ -28012,10 +27431,7 @@
* The returned @new_etag can be used to verify that the file hasn't changed the
* next time it is saved over.
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
- *
- * Returns: %TRUE if successful. If an error
+ * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
*/
@@ -28072,9 +27488,7 @@
* Finishes an asynchronous file replace operation started with
* g_file_replace_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileOutputStream, or %NULL on error.
+ * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -28098,9 +27512,7 @@
* supported, so make sure you really need to do read and write streaming,
* rather than just opening for reading or writing.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileIOStream or %NULL on error.
+ * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -28138,9 +27550,7 @@
* Finishes an asynchronous file replace operation started with
* g_file_replace_readwrite_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFileIOStream, or %NULL on error.
+ * Returns: (transfer full): a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -28154,10 +27564,7 @@
*
* This call does no blocking i/o.
*
- * is %NULL or if @file is invalid.
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path
+ * Returns: (transfer full): #GFile to the resolved path. %NULL if @relative_path is %NULL or if @file is invalid. Free the returned object with g_object_unref().
*/
@@ -28201,9 +27608,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * in the @file, %FALSE otherwise.
- *
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
*/
@@ -28223,9 +27628,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * in the @file, %FALSE otherwise.
- *
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
*/
@@ -28285,9 +27688,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * in the @file, %FALSE otherwise.
- *
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
*/
@@ -28307,9 +27708,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * in the @file, %FALSE otherwise.
- *
- * Returns: %TRUE if the @attribute was successfully set to @value
+ * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise.
*/
@@ -28393,10 +27792,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * if there was an error.
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL
+ * Returns: (transfer full): a #GFile specifying what @file was renamed to, or %NULL if there was an error. Free the returned object with g_object_unref().
*/
@@ -28428,9 +27824,7 @@
* Finishes setting a display name started with
* g_file_set_display_name_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile or %NULL on error.
+ * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref().
*/
@@ -28469,9 +27863,7 @@
* Finish an asynchronous start operation that was started
* with g_file_start_mountable().
*
- * otherwise.
- *
- * Returns: %TRUE if the operation finished successfully. %FALSE
+ * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
* Since: 2.22
*/
@@ -28509,9 +27901,7 @@
* Finish an asynchronous stop operation that was started
* with g_file_stop_mountable().
*
- * otherwise.
- *
- * Returns: %TRUE if the operation finished successfully. %FALSE
+ * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
* Since: 2.22
*/
@@ -28583,9 +27973,7 @@
* Finish an asynchronous unmount operation that was started
* with g_file_unmount_mountable().
*
- * otherwise.
- *
- * Returns: %TRUE if the operation finished successfully. %FALSE
+ * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
* Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead.
*/
@@ -28623,9 +28011,7 @@
* Finish an asynchronous unmount operation that was started
* with g_file_unmount_mountable_with_operation().
*
- * otherwise.
- *
- * Returns: %TRUE if the operation finished successfully. %FALSE
+ * Returns: %TRUE if the operation finished successfully. %FALSE otherwise.
* Since: 2.22
*/
@@ -28637,10 +28023,7 @@
*
* Obtains a completion for @initial_text from @completer.
*
- * This string is not owned by GIO, so remember to g_free() it
- * when finished.
- *
- * Returns: a completed string, or %NULL if no completion exists.
+ * Returns: a completed string, or %NULL if no completion exists. This string is not owned by GIO, so remember to g_free() it when finished.
*/
@@ -28651,9 +28034,7 @@
*
* Gets an array of completion strings for a given initial text.
*
- * This array must be freed by g_strfreev() when finished.
- *
- * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text.
+ * Returns: (array zero-terminated=1) (transfer full): array of strings with possible completions for @initial_text. This array must be freed by g_strfreev() when finished.
*/
@@ -28753,10 +28134,8 @@
*
* Gets a hash for an icon.
*
- * use in a #GHashTable or similar data structure.
- *
* Virtual: hash
- * Returns: a #guint containing a hash for the @icon, suitable for
+ * Returns: a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure.
*/
@@ -28772,9 +28151,7 @@
* implementations you need to ensure that each #GType is registered
* with the type system prior to calling g_icon_new_for_string().
*
- * interface or %NULL if @error is set.
- *
- * Returns: (transfer full): An object implementing the #GIcon
+ * Returns: (transfer full): An object implementing the #GIcon interface or %NULL if @error is set.
* Since: 2.20
*/
@@ -28793,22 +28170,20 @@
*
* <itemizedlist>
* <listitem><para>
- * If @icon is a #GFileIcon, the returned string is a native path
- * (such as <literal>/path/to/my icon.png</literal>) without escaping
- * if the #GFile for @icon is a native file. If the file is not
- * native, the returned string is the result of g_file_get_uri()
- * (such as <literal>sftp://path/to/my%20icon.png</literal>).
+ * If @icon is a #GFileIcon, the returned string is a native path
+ * (such as <literal>/path/to/my icon.png</literal>) without escaping
+ * if the #GFile for @icon is a native file. If the file is not
+ * native, the returned string is the result of g_file_get_uri()
+ * (such as <literal>sftp://path/to/my%20icon.png</literal>).
* </para></listitem>
* <listitem><para>
- * If @icon is a #GThemedIcon with exactly one name, the encoding is
- * simply the name (such as <literal>network-server</literal>).
+ * If @icon is a #GThemedIcon with exactly one name, the encoding is
+ * simply the name (such as <literal>network-server</literal>).
* </para></listitem>
* </itemizedlist>
*
- * be serialized. Use g_free() to free.
- *
* Virtual: to_tokens
- * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't
+ * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free.
* Since: 2.20
*/
@@ -29015,9 +28390,7 @@
*
* Tests if @address falls within the range described by @mask.
*
- * @mask.
- *
- * Returns: whether @address falls within the range described by
+ * Returns: whether @address falls within the range described by @mask.
* Since: 2.32
*/
@@ -29046,9 +28419,7 @@
* delimited by a "/". If it is not present, then the length is
* assumed to be the full length of the address.
*
- * on error.
- *
- * Returns: a new #GInetAddressMask corresponding to @string, or %NULL
+ * Returns: a new #GInetAddressMask corresponding to @string, or %NULL on error.
* Since: 2.32
*/
@@ -29071,9 +28442,7 @@
* Creates a #GInetAddress for the "any" address (unassigned/"don't
* care") for @family.
*
- * for @family.
- *
- * Returns: a new #GInetAddress corresponding to the "any" address
+ * Returns: a new #GInetAddress corresponding to the "any" address for @family.
* Since: 2.22
*/
@@ -29098,9 +28467,7 @@
*
* Parses @string as an IP address and creates a new #GInetAddress.
*
- * @string could not be parsed.
- *
- * Returns: a new #GInetAddress corresponding to @string, or %NULL if
+ * Returns: a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed.
* Since: 2.22
*/
@@ -29111,9 +28478,7 @@
*
* Creates a #GInetAddress for the loopback address for @family.
*
- * for @family.
- *
- * Returns: a new #GInetAddress corresponding to the loopback address
+ * Returns: a new #GInetAddress corresponding to the loopback address for @family.
* Since: 2.22
*/
@@ -29124,10 +28489,7 @@
*
* Gets the raw binary address data from @address.
*
- * which should not be modified, stored, or freed. The size of this
- * array can be gotten with g_inet_address_get_native_size().
- *
- * Returns: a pointer to an internal array of the bytes in @address,
+ * Returns: a pointer to an internal array of the bytes in @address, which should not be modified, stored, or freed. The size of this array can be gotten with g_inet_address_get_native_size().
* Since: 2.22
*/
@@ -29138,9 +28500,7 @@
*
* Converts @address to string form.
*
- * freed after use.
- *
- * Returns: a representation of @address as a string, which should be
+ * Returns: a representation of @address as a string, which should be freed after use.
* Since: 2.22
*/
@@ -29151,9 +28511,7 @@
*
* Gets @address's #GInetAddress.
*
- * g_object_ref()'d if it will be stored
- *
- * Returns: (transfer none): the #GInetAddress for @address, which must be
+ * Returns: (transfer none): the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored
* Since: 2.22
*/
@@ -29235,9 +28593,7 @@
* of the first call. This is so that it's safe to implement the singleton
* pattern in the GObject constructor function.
*
- * return %FALSE and set @error appropriately if present.
- *
- * Returns: %TRUE if successful. If an error has occurred, this function will
+ * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
* Since: 2.22
*/
@@ -29652,9 +29008,7 @@
*
* Finds a #GIOExtension for an extension point by name.
*
- * given name, or %NULL if there is no extension with that name
- *
- * Returns: (transfer none): the #GIOExtension for @extension_point that has the
+ * Returns: (transfer none): the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name
*/
@@ -29665,10 +29019,7 @@
* Gets a list of all extensions that implement this extension point.
* The list is sorted by priority, beginning with the highest priority.
*
- * #GIOExtension<!-- -->s. The list is owned by GIO and should not be
- * modified.
- *
- * Returns: (element-type GIOExtension) (transfer none): a #GList of
+ * Returns: (element-type GIOExtension) (transfer none): a #GList of #GIOExtension<!-- -->s. The list is owned by GIO and should not be modified.
*/
@@ -29678,9 +29029,7 @@
*
* Gets the required type for @extension_point.
*
- * or #G_TYPE_INVALID if the extension point has no required type
- *
- * Returns: the #GType that all implementations must have,
+ * Returns: the #GType that all implementations must have, or #G_TYPE_INVALID if the extension point has no required type
*/
@@ -29707,9 +29056,7 @@
*
* Looks up an existing extension point.
*
- * is no registered extension point with the given name.
- *
- * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there
+ * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name.
*/
@@ -29719,9 +29066,7 @@
*
* Registers an extension point.
*
- * owned by GIO and should not be freed.
- *
- * Returns: (transfer none): the new #GIOExtensionPoint. This object is
+ * Returns: (transfer none): the new #GIOExtensionPoint. This object is owned by GIO and should not be freed.
*/
@@ -29763,9 +29108,7 @@
* Creates a new GIOModule that will load the specific
* shared library when in use.
*
- * or %NULL on error.
- *
- * Returns: a #GIOModule from given @filename,
+ * Returns: a #GIOModule from given @filename, or %NULL on error.
*/
@@ -29795,10 +29138,7 @@
* run gio-querymodules in order to build the cache files required for
* lazy loading.
*
- * extension points of the module. The array must be suitable for
- * freeing with g_strfreev().
- *
- * Returns: (transfer full): A %NULL-terminated array of strings, listing the supported
+ * Returns: (transfer full): A %NULL-terminated array of strings, listing the supported extension points of the module. The array must be suitable for freeing with g_strfreev().
* Since: 2.24
*/
@@ -29862,13 +29202,7 @@
* all gtypes) then you can use g_io_modules_scan_all_in_directory()
* which allows delayed/lazy loading of modules.
*
- * from the directory,
- * All the modules are loaded into memory, if you want to
- * unload them (enabling on-demand loading) you must call
- * g_type_module_unuse() on all the modules. Free the list
- * with g_list_free().
- *
- * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
+ * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free().
*/
@@ -29883,13 +29217,7 @@
* all gtypes) then you can use g_io_modules_scan_all_in_directory()
* which allows delayed/lazy loading of modules.
*
- * from the directory,
- * All the modules are loaded into memory, if you want to
- * unload them (enabling on-demand loading) you must call
- * g_type_module_unuse() on all the modules. Free the list
- * with g_list_free().
- *
- * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded
+ * Returns: (element-type GIOModule) (transfer full): a list of #GIOModules loaded from the directory, All the modules are loaded into memory, if you want to unload them (enabling on-demand loading) you must call g_type_module_unuse() on all the modules. Free the list with g_list_free().
* Since: 2.30
*/
@@ -30096,9 +29424,7 @@
* Gets the input stream for this object. This is used
* for reading.
*
- * Do not free.
- *
- * Returns: (transfer none): a #GInputStream, owned by the #GIOStream.
+ * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. Do not free.
* Since: 2.22
*/
@@ -30110,9 +29436,7 @@
* Gets the output stream for this object. This is used for
* writing.
*
- * Do not free.
- *
- * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream.
+ * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. Do not free.
* Since: 2.22
*/
@@ -30208,8 +29532,8 @@
* of %TRUE will cause the following to appear in the keyfile:
*
* |[
- * [toplevel]
- * enabled=true
+ * [toplevel]
+ * enabled=true
* ]|
*
* If @root_group is %NULL then it is not permitted to store keys
@@ -30222,8 +29546,8 @@
* 12 then the following would appear in the keyfile:
*
* |[
- * [profiles/default]
- * font-size=12
+ * [profiles/default]
+ * font-size=12
* ]|
*
* The backend will refuse writes (and return writability as being
@@ -30342,10 +29666,7 @@
* Checks if any events are pending for the default #GMainContext
* (i.e. ready to be processed).
*
- *
- * Deprected: 2.2: Use g_main_context_pending() instead.
- *
- * Returns: %TRUE if any events are pending.
+ * Returns: %TRUE if any events are pending. Deprected: 2.2: Use g_main_context_pending() instead.
*/
@@ -30610,9 +29931,7 @@
* remains at the current position. The value returned in @value must
* be unreffed using g_variant_unref() when it is no longer in use.
*
- * attribute
- *
- * Returns: %TRUE on success, or %FALSE if there is no additional
+ * Returns: %TRUE on success, or %FALSE if there is no additional attribute
* Since: 2.32
*/
@@ -30789,15 +30108,15 @@
*
* <informalexample><programlisting><![CDATA[
* <menu id='edit-menu'>
- * <section>
- * <item label='Undo'/>
- * <item label='Redo'/>
- * </section>
- * <section>
- * <item label='Cut'/>
- * <item label='Copy'/>
- * <item label='Paste'/>
- * </section>
+ * <section>
+ * <item label='Undo'/>
+ * <item label='Redo'/>
+ * </section>
+ * <section>
+ * <item label='Cut'/>
+ * <item label='Copy'/>
+ * <item label='Paste'/>
+ * </section>
* </menu>
* ]]></programlisting></informalexample>
*
@@ -30810,19 +30129,19 @@
*
* <informalexample><programlisting><![CDATA[
* <menu id='edit-menu'>
- * <item>
- * <link name='section'>
- * <item label='Undo'/>
- * <item label='Redo'/>
- * </link>
- * </item>
- * <item>
- * <link name='section'>
- * <item label='Cut'/>
- * <item label='Copy'/>
- * <item label='Paste'/>
- * </link>
- * </item>
+ * <item>
+ * <link name='section'>
+ * <item label='Undo'/>
+ * <item label='Redo'/>
+ * </link>
+ * </item>
+ * <item>
+ * <link name='section'>
+ * <item label='Cut'/>
+ * <item label='Copy'/>
+ * <item label='Paste'/>
+ * </link>
+ * </item>
* </menu>
* ]]></programlisting></informalexample>
*
@@ -31168,9 +30487,7 @@
* type, then the positional parameters are ignored and %FALSE is
* returned.
*
- * type
- *
- * Returns: %TRUE if the named attribute was found with the expected
+ * Returns: %TRUE if the named attribute was found with the expected type
* Since: 2.32
*/
@@ -31236,9 +30553,7 @@
* An immutable #GMenuModel will never emit the #GMenuModel::items-changed
* signal. Consumers of the model may make optimisations accordingly.
*
- * emitted).
- *
- * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
+ * Returns: %TRUE if the model is mutable (ie: "items-changed" may be emitted).
* Since: 2.32
*/
@@ -31476,10 +30791,7 @@
* @mount is a path that reflects the main entry point for the user (e.g.
* the home directory, or the root of the volume).
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
- *
- * Returns: (transfer full): a #GFile.
+ * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -31492,10 +30804,7 @@
* This is a convenience method for getting the #GVolume and then
* using that object to get the #GDrive.
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
- *
- * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive.
+ * Returns: (transfer full): a #GDrive or %NULL if @mount is not associated with a volume or a drive. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -31505,10 +30814,7 @@
*
* Gets the icon for @mount.
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
- *
- * Returns: (transfer full): a #GIcon.
+ * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -31518,10 +30824,7 @@
*
* Gets the name of @mount.
*
- * The returned string should be freed with g_free()
- * when no longer needed.
- *
- * Returns: the name for the given @mount.
+ * Returns: the name for the given @mount. The returned string should be freed with g_free() when no longer needed.
*/
@@ -31531,10 +30834,7 @@
*
* Gets the root directory on @mount.
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
- *
- * Returns: (transfer full): a #GFile.
+ * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -31558,10 +30858,7 @@
* considered an opaque string. Returns %NULL if there is no UUID
* available.
*
- * The returned string should be freed with g_free()
- * when no longer needed.
- *
- * Returns: the UUID for @mount or %NULL if no UUID can be computed.
+ * Returns: the UUID for @mount or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed.
*/
@@ -31571,10 +30868,7 @@
*
* Gets the volume for the @mount.
*
- * The returned object should be unreffed with
- * g_object_unref() when no longer needed.
- *
- * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume.
+ * Returns: (transfer full): a #GVolume or %NULL if @mount is not associated with a volume. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -31613,9 +30907,7 @@
* %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content
* guessing.
*
- * Caller should free this array with g_strfreev() when done with it.
- *
- * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
+ * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it.
* Since: 2.18
*/
@@ -31636,9 +30928,7 @@
* This is an synchronous operation and as such may block doing IO;
* see g_mount_guess_content_type() for the asynchronous version.
*
- * Caller should free this array with g_strfreev() when done with it.
- *
- * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error.
+ * Returns: (transfer full) (element-type utf8): a %NULL-terminated array of content types or %NULL on error. Caller should free this array with g_strfreev() when done with it.
* Since: 2.18
*/
@@ -31693,9 +30983,7 @@
*
* Gets a choice from the mount operation.
*
- * the choice's list, or %0.
- *
- * Returns: an integer containing an index of the user's choice from
+ * Returns: an integer containing an index of the user's choice from the choice's list, or %0.
*/
@@ -32298,9 +31586,7 @@
*
* Gets the first child of a #GNode.
*
- * or has no children
- *
- * Returns: the first child of @node, or %NULL if @node is %NULL
+ * Returns: the first child of @node, or %NULL if @node is %NULL or has no children
*/
@@ -32346,9 +31632,7 @@
*
* Gets the next sibling of a #GNode.
*
- * or %NULL
- *
- * Returns: the next sibling of @node, or %NULL if @node is the last node
+ * Returns: the next sibling of @node, or %NULL if @node is the last node or %NULL
*/
@@ -32369,9 +31653,7 @@
*
* Gets the previous sibling of a #GNode.
*
- * node or %NULL
- *
- * Returns: the previous sibling of @node, or %NULL if @node is the first
+ * Returns: the previous sibling of @node, or %NULL if @node is the first node or %NULL
*/
@@ -32576,12 +31858,7 @@
*
* Splices an input stream into an output stream.
*
- * -1 if an error occurred. Note that if the number of bytes
- * spliced is greater than %G_MAXSSIZE, then that will be
- * returned, and there is no way to determine the actual number
- * of bytes spliced.
- *
- * Returns: a #gssize containing the size of the data spliced, or
+ * Returns: a #gssize containing the size of the data spliced, or -1 if an error occurred. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced.
*/
@@ -32613,11 +31890,7 @@
*
* Finishes an asynchronous stream splice operation.
*
- * number of bytes spliced is greater than %G_MAXSSIZE, then that
- * will be returned, and there is no way to determine the actual
- * number of bytes spliced.
- *
- * Returns: a #gssize of the number of bytes spliced. Note that if the
+ * Returns: a #gssize of the number of bytes spliced. Note that if the number of bytes spliced is greater than %G_MAXSSIZE, then that will be returned, and there is no way to determine the actual number of bytes spliced.
*/
@@ -32971,11 +32244,7 @@
* g_pollable_input_stream_read_nonblocking(), which will return a
* %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
*
- * has occurred on @stream, this will result in
- * g_pollable_input_stream_is_readable() returning %TRUE, and the
- * next attempt to read will return the error.
- *
- * Returns: %TRUE if @stream is readable, %FALSE if not. If an error
+ * Returns: %TRUE if @stream is readable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_input_stream_is_readable() returning %TRUE, and the next attempt to read will return the error.
* Since: 2.28
*/
@@ -33000,10 +32269,8 @@
* may happen if you call this method after a source triggers due
* to having been cancelled.
*
- * %G_IO_ERROR_WOULD_BLOCK).
- *
* Virtual: read_nonblocking
- * Returns: the number of bytes read, or -1 on error (including
+ * Returns: the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK).
*/
@@ -33056,11 +32323,7 @@
* g_pollable_output_stream_write_nonblocking(), which will return a
* %G_IO_ERROR_WOULD_BLOCK error rather than blocking.
*
- * has occurred on @stream, this will result in
- * g_pollable_output_stream_is_writable() returning %TRUE, and the
- * next attempt to write will return the error.
- *
- * Returns: %TRUE if @stream is writable, %FALSE if not. If an error
+ * Returns: %TRUE if @stream is writable, %FALSE if not. If an error has occurred on @stream, this will result in g_pollable_output_stream_is_writable() returning %TRUE, and the next attempt to write will return the error.
* Since: 2.28
*/
@@ -33085,10 +32348,8 @@
* may happen if you call this method after a source triggers due
* to having been cancelled.
*
- * %G_IO_ERROR_WOULD_BLOCK).
- *
* Virtual: write_nonblocking
- * Returns: the number of bytes written, or -1 on error (including
+ * Returns: the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK).
*/
@@ -33193,10 +32454,7 @@
* does the necessary handshake to connect to @proxy_address, and if
* required, wraps the #GIOStream to handle proxy payload.
*
- * be the same as @connection, in which case a reference
- * will be added.
- *
- * Returns: (transfer full): a #GIOStream that will replace @connection. This might
+ * Returns: (transfer full): a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added.
* Since: 2.26
*/
@@ -33236,9 +32494,7 @@
* Lookup "gio-proxy" extension point for a proxy implementation that supports
* specified protocol.
*
- * is not supported.
- *
- * Returns: (transfer full): return a #GProxy or NULL if protocol
+ * Returns: (transfer full): return a #GProxy or NULL if protocol is not supported.
* Since: 2.26
*/
@@ -33289,10 +32545,7 @@
* Direct connection should not be attempted unless it is part of the
* returned array of proxies.
*
- * NULL-terminated array of proxy URIs. Must be freed
- * with g_strfreev().
- *
- * Returns: (transfer full) (array zero-terminated=1): A
+ * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev().
* Since: 2.26
*/
@@ -33322,10 +32575,7 @@
* g_proxy_resolver_lookup_async() is complete. See
* g_proxy_resolver_lookup() for more details.
*
- * NULL-terminated array of proxy URIs. Must be freed
- * with g_strfreev().
- *
- * Returns: (transfer full) (array zero-terminated=1): A
+ * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev().
* Since: 2.26
*/
@@ -33351,7 +32601,7 @@
* g_remote_action_group_activate_action_full:
* @remote: a #GDBusActionGroup
* @action_name: the name of the action to activate
- * @parameter: (allow none): the optional parameter to the activation
+ * @parameter: (allow-none): the optional parameter to the activation
* @platform_data: the platform data to send
*
* Activates the remote action.
@@ -33469,9 +32719,7 @@
* operation, in which case @error (if non-%NULL) will be set to
* %G_IO_ERROR_CANCELLED.
*
- * form), or %NULL on error.
- *
- * Returns: a hostname (either ASCII-only, or in ASCII-encoded
+ * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error.
* Since: 2.22
*/
@@ -33505,9 +32753,7 @@
* a value from #GResolverError. If the operation was cancelled,
* @error will be set to %G_IO_ERROR_CANCELLED.
*
- * form), or %NULL on error.
- *
- * Returns: a hostname (either ASCII-only, or in ASCII-encoded
+ * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error.
* Since: 2.22
*/
@@ -33543,11 +32789,7 @@
* address, it may be easier to create a #GNetworkAddress and use its
* #GSocketConnectable interface.
*
- * of #GInetAddress, or %NULL on error. You
- * must unref each of the addresses and free the list when you are
- * done with it. (You can use g_resolver_free_addresses() to do this.)
- *
- * Returns: (element-type GInetAddress) (transfer full): a #GList
+ * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. You must unref each of the addresses and free the list when you are done with it. (You can use g_resolver_free_addresses() to do this.)
* Since: 2.22
*/
@@ -33582,10 +32824,7 @@
* a value from #GResolverError. If the operation was cancelled,
* @error will be set to %G_IO_ERROR_CANCELLED.
*
- * of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name()
- * for more details.
- *
- * Returns: (element-type GInetAddress) (transfer full): a #GList
+ * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details.
* Since: 2.22
*/
@@ -33622,10 +32861,7 @@
* to create a #GNetworkService and use its #GSocketConnectable
* interface.
*
- * or %NULL on error. You must free each of the targets and the list when you are
- * done with it. (You can use g_resolver_free_targets() to do this.)
- *
- * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
+ * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. You must free each of the targets and the list when you are done with it. (You can use g_resolver_free_targets() to do this.)
* Since: 2.22
*/
@@ -33663,9 +32899,7 @@
* a value from #GResolverError. If the operation was cancelled,
* @error will be set to %G_IO_ERROR_CANCELLED.
*
- * or %NULL on error. See g_resolver_lookup_service() for more details.
- *
- * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget,
+ * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details.
* Since: 2.22
*/
@@ -33773,9 +33007,7 @@
*
* @lookup_flags controls the behaviour of the lookup.
*
- * Free the returned object with g_bytes_unref().
- *
- * Returns: (transfer full): #GBytes or %NULL on error.
+ * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref().
* Since: 2.32
*/
@@ -33809,9 +33041,7 @@
*
* @lookup_flags controls the behaviour of the lookup.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GInputStream or %NULL on error.
+ * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.32
*/
@@ -33898,9 +33128,7 @@
*
* @lookup_flags controls the behaviour of the lookup.
*
- * Free the returned object with g_bytes_unref().
- *
- * Returns: (transfer full): #GBytes or %NULL on error.
+ * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref().
* Since: 2.32
*/
@@ -33917,9 +33145,7 @@
*
* @lookup_flags controls the behaviour of the lookup.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): #GInputStream or %NULL on error.
+ * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.32
*/
@@ -33980,10 +33206,7 @@
* triggering the cancellable object from another thread. If the operation
* was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
- *
- * Returns: %TRUE if successful. If an error
+ * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
*/
@@ -34012,11 +33235,8 @@
* operation was partially finished when the operation was cancelled the
* partial result will be returned, without an error.
*
- * has occurred, this function will return %FALSE and set @error
- * appropriately if present.
- *
* Virtual: truncate_fn
- * Returns: %TRUE if successful. If an error
+ * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present.
*/
@@ -34083,7 +33303,7 @@
* @tree: a #GTree containing the changes
* @path: (out): the location to save the path
* @keys: (out) (transfer container) (array zero-terminated=1): the location to save the relative keys
- * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL
+ * @values: (out) (allow-none) (transfer container) (array zero-terminated=1): the location to save the values, or %NULL
*
* Calculate the longest common prefix of all keys in a tree and write
* out an array of the key names relative to that prefix and,
@@ -34598,10 +33818,7 @@
* It is a programmer error to give a @key that isn't specified as
* having an array of strings type in the schema for @settings.
*
- * newly-allocated, %NULL-terminated array of strings, the value that
- * is stored at @key in @settings.
- *
- * Returns: (array zero-terminated=1) (transfer full): a
+ * Returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings.
* Since: 2.26
*/
@@ -34708,10 +33925,7 @@
* g_settings_list_schemas() represents the complete list of all
* installed schemas.
*
- * #GSettings schemas that are available. The list must not be
- * modified or freed.
- *
- * Returns: (element-type utf8) (transfer none): a list of relocatable
+ * Returns: (element-type utf8) (transfer none): a list of relocatable #GSettings schemas that are available. The list must not be modified or freed.
* Since: 2.28
*/
@@ -34728,10 +33942,7 @@
* g_settings_new_with_path()). See
* g_settings_list_relocatable_schemas() for that.
*
- * schemas that are available. The list must not be modified or
- * freed.
- *
- * Returns: (element-type utf8) (transfer none): a list of #GSettings
+ * Returns: (element-type utf8) (transfer none): a list of #GSettings schemas that are available. The list must not be modified or freed.
* Since: 2.26
*/
@@ -35065,9 +34276,7 @@
* schema for @settings or for the #GVariantType of @format to mismatch
* the type given in the schema.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.26
*/
@@ -35085,9 +34294,7 @@
* It is a programmer error to give a @key that isn't specified as
* having a boolean type in the schema for @settings.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.26
*/
@@ -35105,9 +34312,7 @@
* It is a programmer error to give a @key that isn't specified as
* having a 'double' type in the schema for @settings.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.26
*/
@@ -35168,9 +34373,7 @@
* It is a programmer error to give a @key that isn't specified as
* having a int32 type in the schema for @settings.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.26
*/
@@ -35188,9 +34391,7 @@
* It is a programmer error to give a @key that isn't specified as
* having a string type in the schema for @settings.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.26
*/
@@ -35209,9 +34410,7 @@
* It is a programmer error to give a @key that isn't specified as
* having an array of strings type in the schema for @settings.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.26
*/
@@ -35230,9 +34429,7 @@
* It is a programmer error to give a @key that isn't specified as
* having a uint32 type in the schema for @settings.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.30
*/
@@ -35251,9 +34448,7 @@
*
* If @value is floating then this function consumes the reference.
*
- * %FALSE if the key was not writable
- *
- * Returns: %TRUE if setting the key succeeded,
+ * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable
* Since: 2.26
*/
@@ -35596,9 +34791,7 @@
*
* Gets the operation result boolean from within the asynchronous result.
*
- * if the operation's result was %FALSE.
- *
- * Returns: %TRUE if the operation's result was %TRUE, %FALSE
+ * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE.
*/
@@ -35896,9 +35089,7 @@
* or return %G_IO_ERROR_WOULD_BLOCK if non-blocking I/O is enabled.
* To be notified of an incoming connection, wait for the %G_IO_IN condition.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a new #GSocket, or %NULL on error.
+ * Returns: (transfer full): a new #GSocket, or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -35923,10 +35114,7 @@
* internal errors (other than @cancellable being triggered) will be
* ignored.
*
- * error (in which case * error will be set) or if there are no
- * more addresses.
- *
- * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
+ * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case * error will be set) or if there are no more addresses.
*/
@@ -35954,10 +35142,7 @@
* g_socket_address_enumerator_next() for more information about
* error handling.
*
- * error (in which case * error will be set) or if there are no
- * more addresses.
- *
- * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on
+ * Returns: (transfer full): a #GSocketAddress (owned by the caller), or %NULL on error (in which case * error will be set) or if there are no more addresses.
*/
@@ -35980,9 +35165,7 @@
* You can use this to allocate memory to pass to
* g_socket_address_to_native().
*
- * @address represents
- *
- * Returns: the size of the native <type>struct sockaddr</type> that
+ * Returns: the size of the native <type>struct sockaddr</type> that @address represents
* Since: 2.22
*/
@@ -35995,9 +35178,7 @@
* Creates a #GSocketAddress subclass corresponding to the native
* <type>struct sockaddr</type> @native.
*
- * otherwise %NULL.
- *
- * Returns: a new #GSocketAddress if @native could successfully be converted,
+ * Returns: a new #GSocketAddress if @native could successfully be converted, otherwise %NULL.
* Since: 2.22
*/
@@ -36459,9 +35640,7 @@
*
* Creates a new #GSocketClient with the default options.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: a #GSocketClient.
+ * Returns: a #GSocketClient. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -36878,9 +36057,7 @@
*
* Try to get the local address of a socket connection.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GSocketAddress or %NULL on error.
+ * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -36892,9 +36069,7 @@
*
* Try to get the remote address of a socket connection.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GSocketAddress or %NULL on error.
+ * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -37033,9 +36208,7 @@
*
* Get the amount of data pending in the OS input buffer.
*
- * without blocking or -1 on error.
- *
- * Returns: the number of bytes that can be read from the socket
+ * Returns: the number of bytes that can be read from the socket without blocking or -1 on error.
* Since: 2.32
*/
@@ -37083,9 +36256,7 @@
* g_unix_connection_send_credentials() /
* g_unix_connection_receive_credentials() functions.
*
- * that must be freed with g_object_unref().
- *
- * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object
+ * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref().
* Since: 2.26
*/
@@ -37149,9 +36320,7 @@
* useful if the socket has been bound to a local address,
* either explicitly or implicitly when connecting.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GSocketAddress or %NULL on error.
+ * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -37201,9 +36370,7 @@
* Try to get the remove address of a connected socket. This is only
* useful for connection oriented sockets that have been connected.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GSocketAddress or %NULL on error.
+ * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -37598,9 +36765,7 @@
* system, so you can use protocols not listed in #GSocketProtocol if you
* know the protocol number used for it.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: a #GSocket or %NULL on error.
+ * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -37618,9 +36783,7 @@
* will be set to non-blocking mode, independent on the blocking
* mode of the #GSocket.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: a #GSocket or %NULL on error.
+ * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.22
*/
@@ -37657,9 +36820,7 @@
*
* On error -1 is returned and @error is set accordingly.
*
- * the peer, or -1 on error
- *
- * Returns: Number of bytes read, or 0 if the connection was closed by
+ * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
* Since: 2.22
*/
@@ -37681,9 +36842,7 @@
*
* See g_socket_receive() for additional information.
*
- * the peer, or -1 on error
- *
- * Returns: Number of bytes read, or 0 if the connection was closed by
+ * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
* Since: 2.22
*/
@@ -37758,9 +36917,7 @@
*
* On error -1 is returned and @error is set accordingly.
*
- * the peer, or -1 on error
- *
- * Returns: Number of bytes read, or 0 if the connection was closed by
+ * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
* Since: 2.22
*/
@@ -37778,9 +36935,7 @@
* the choice of blocking or non-blocking behavior is determined by
* the @blocking argument rather than by @socket's properties.
*
- * the peer, or -1 on error
- *
- * Returns: Number of bytes read, or 0 if the connection was closed by
+ * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error
* Since: 2.26
*/
@@ -37808,9 +36963,7 @@
*
* On error -1 is returned and @error is set accordingly.
*
- * on error
- *
- * Returns: Number of bytes written (which may be less than @size), or -1
+ * Returns: Number of bytes written (which may be less than @size), or -1 on error
* Since: 2.22
*/
@@ -37865,9 +37018,7 @@
*
* On error -1 is returned and @error is set accordingly.
*
- * on error
- *
- * Returns: Number of bytes written (which may be less than @size), or -1
+ * Returns: Number of bytes written (which may be less than @size), or -1 on error
* Since: 2.22
*/
@@ -37887,9 +37038,7 @@
*
* See g_socket_send() for additional information.
*
- * on error
- *
- * Returns: Number of bytes written (which may be less than @size), or -1
+ * Returns: Number of bytes written (which may be less than @size), or -1 on error
* Since: 2.22
*/
@@ -37907,9 +37056,7 @@
* the choice of blocking or non-blocking behavior is determined by
* the @blocking argument rather than by @socket's properties.
*
- * on error
- *
- * Returns: Number of bytes written (which may be less than @size), or -1
+ * Returns: Number of bytes written (which may be less than @size), or -1 on error
* Since: 2.26
*/
@@ -38405,10 +37552,10 @@
* In the following example, @icon1 and @icon2 are equivalent:
* |[
* const char *names[] = {
- * "gnome-dev-cdrom-audio",
- * "gnome-dev-cdrom",
- * "gnome-dev",
- * "gnome"
+ * "gnome-dev-cdrom-audio",
+ * "gnome-dev-cdrom",
+ * "gnome-dev",
+ * "gnome"
* };
*
* icon1 = g_themed_icon_new_from_names (names, 4);
@@ -38453,9 +37600,7 @@
*
* Gets the #GType of @backend's #GTlsCertificate implementation.
*
- * implementation.
- *
- * Returns: the #GType of @backend's #GTlsCertificate
+ * Returns: the #GType of @backend's #GTlsCertificate implementation.
* Since: 2.28
*/
@@ -38466,9 +37611,7 @@
*
* Gets the #GType of @backend's #GTlsClientConnection implementation.
*
- * implementation.
- *
- * Returns: the #GType of @backend's #GTlsClientConnection
+ * Returns: the #GType of @backend's #GTlsClientConnection implementation.
* Since: 2.28
*/
@@ -38489,9 +37632,7 @@
*
* Gets the default #GTlsDatabase used to verify TLS connections.
*
- * unreffed when done.
- *
- * Returns: (transfer full): the default database, which should be
+ * Returns: (transfer full): the default database, which should be unreffed when done.
* Since: 2.30
*/
@@ -38513,9 +37654,7 @@
*
* Gets the #GType of @backend's #GTlsServerConnection implementation.
*
- * implementation.
- *
- * Returns: the #GType of @backend's #GTlsServerConnection
+ * Returns: the #GType of @backend's #GTlsServerConnection implementation.
* Since: 2.28
*/
@@ -38538,10 +37677,7 @@
*
* Gets the #GTlsCertificate representing @cert's issuer, if known
*
- * or %NULL if @cert is self-signed or signed with an unknown
- * certificate.
- *
- * Returns: (transfer none): The certificate of @cert's issuer,
+ * Returns: (transfer none): The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate.
* Since: 2.28
*/
@@ -38557,10 +37693,7 @@
* PEM-encoded certificates, this will return an empty list and not
* set @error.
*
- * #GList containing #GTlsCertificate objects. You must free the list
- * and its contents when you are done with it.
- *
- * Returns: (element-type Gio.TlsCertificate) (transfer full): a
+ * Returns: (element-type Gio.TlsCertificate) (transfer full): a #GList containing #GTlsCertificate objects. You must free the list and its contents when you are done with it.
* Since: 2.28
*/
@@ -38659,10 +37792,7 @@
* Each item in the list is a #GByteArray which contains the complete
* subject DN of the certificate authority.
*
- * CA DNs. You should unref each element with g_byte_array_unref() and then
- * the free the list with g_list_free().
- *
- * Returns: (element-type GByteArray) (transfer full): the list of
+ * Returns: (element-type GByteArray) (transfer full): the list of CA DNs. You should unref each element with g_byte_array_unref() and then the free the list with g_list_free().
* Since: 2.28
*/
@@ -38673,10 +37803,7 @@
*
* Gets @conn's expected server identity
*
- * expected server identity, or %NULL if the expected identity is not
- * known.
- *
- * Returns: (transfer none): a #GSocketConnectable describing the
+ * Returns: (transfer none): a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known.
* Since: 2.28
*/
@@ -38715,9 +37842,7 @@
* must have pollable input and output streams) which is assumed to
* communicate with the server identified by @server_identity.
*
- * #GTlsClientConnection, or %NULL on error
- *
- * Returns: (transfer full) (type GTlsClientConnection): the new
+ * Returns: (transfer full) (type GTlsClientConnection): the new #GTlsClientConnection, or %NULL on error
* Since: 2.28
*/
@@ -38773,9 +37898,7 @@
* Used by #GTlsConnection implementations to emit the
* #GTlsConnection::accept-certificate signal.
*
- * %TRUE to accept @peer_cert
- *
- * Returns: %TRUE if one of the signal handlers has returned
+ * Returns: %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert
* Since: 2.28
*/
@@ -38863,9 +37986,7 @@
* when the connection is closed. See
* g_tls_connection_set_require_close_notify() for details.
*
- * notification.
- *
- * Returns: %TRUE if @conn requires a proper TLS close
+ * Returns: %TRUE if @conn requires a proper TLS close notification.
* Since: 2.28
*/
@@ -38940,9 +38061,7 @@
* Finish an asynchronous TLS handshake operation. See
* g_tls_connection_handshake() for more information.
*
- * case @error will be set.
- *
- * Returns: %TRUE on success, %FALSE on failure, in which
+ * Returns: %TRUE on success, %FALSE on failure, in which case @error will be set.
* Since: 2.28
*/
@@ -39133,9 +38252,7 @@
* This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform
* the lookup operation asynchronously.
*
- * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
- *
- * Returns: (transfer full) (allow-none): a newly allocated
+ * Returns: (transfer full) (allow-none): a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
* Since: 2.30
*/
@@ -39169,9 +38286,7 @@
* If the handle is no longer valid, or does not point to a certificate in
* this database, then %NULL will be returned.
*
- * Use g_object_unref() to release the certificate.
- *
- * Returns: (transfer full): a newly allocated #GTlsCertificate object.
+ * Returns: (transfer full): a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate.
* Since: 2.30
*/
@@ -39194,9 +38309,7 @@
* This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
* the lookup operation asynchronously.
*
- * or %NULL. Use g_object_unref() to release the certificate.
- *
- * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
+ * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
* Since: 2.30
*/
@@ -39227,9 +38340,7 @@
* Finish an asynchronous lookup issuer operation. See
* g_tls_database_lookup_certificate_issuer() for more information.
*
- * or %NULL. Use g_object_unref() to release the certificate.
- *
- * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
+ * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate.
* Since: 2.30
*/
@@ -39248,9 +38359,7 @@
* This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform
* the lookup operation asynchronously.
*
- * objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
- *
- * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate
+ * Returns: (transfer full) (element-type GTlsCertificate): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
* Since: 2.30
*/
@@ -39285,9 +38394,7 @@
* Finish an asynchronous lookup of certificates. See
* g_tls_database_lookup_certificates_issued_by() for more information.
*
- * Use g_object_unref() on each certificate, and g_list_free() on the release the list.
- *
- * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects.
+ * Returns: (transfer full): a newly allocated list of #GTlsCertificate objects. Use g_object_unref() on each certificate, and g_list_free() on the release the list.
* Since: 2.30
*/
@@ -39328,9 +38435,7 @@
* This function can block, use g_tls_database_verify_chain_async() to perform
* the verification operation asynchronously.
*
- * result of verification.
- *
- * Returns: the appropriate #GTlsCertificateFlags which represents the
+ * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification.
* Since: 2.30
*/
@@ -39363,9 +38468,8 @@
*
* Finish an asynchronous verify chain operation. See
* g_tls_database_verify_chain() for more information. *
- * result of verification.
*
- * Returns: the appropriate #GTlsCertificateFlags which represents the
+ * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification.
* Since: 2.30
*/
@@ -39390,9 +38494,7 @@
*
* The certificates in @anchors must be PEM encoded.
*
- * #GTlsFileDatabase, or %NULL on error
- *
- * Returns: (transfer full) (type GTlsFileDatabase): the new
+ * Returns: (transfer full) (type GTlsFileDatabase): the new #GTlsFileDatabase, or %NULL on error
* Since: 2.30
*/
@@ -39650,9 +38752,7 @@
* Creates a new #GTlsServerConnection wrapping @base_io_stream (which
* must have pollable input and output streams).
*
- * #GTlsServerConnection, or %NULL on error
- *
- * Returns: (transfer full) (type GTlsServerConnection): the new
+ * Returns: (transfer full) (type GTlsServerConnection): the new #GTlsServerConnection, or %NULL on error
* Since: 2.28
*/
@@ -39722,9 +38822,7 @@
* Other ways to exchange credentials with a foreign peer includes the
* #GUnixCredentialsMessage type and g_socket_get_credentials() function.
*
- * g_object_unref()), %NULL if @error is set.
- *
- * Returns: (transfer full): Received credentials on success (free with
+ * Returns: (transfer full): Received credentials on success (free with g_object_unref()), %NULL if @error is set.
* Since: 2.26
*/
@@ -39757,9 +38855,7 @@
* Finishes an asynchronous receive credentials operation started with
* g_unix_connection_receive_credentials_async().
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GCredentials, or %NULL on error.
+ * Returns: (transfer full): a #GCredentials, or %NULL on error. Free the returned object with g_object_unref().
* Since: 2.32
*/
@@ -39920,9 +39016,7 @@
* this index with g_unix_fd_list_get() then you will receive back a
* duplicated copy of the same file descriptor.
*
- * (and @error is set)
- *
- * Returns: the index of the appended fd in case of success, else -1
+ * Returns: the index of the appended fd in case of success, else -1 (and @error is set)
* Since: 2.24
*/
@@ -40011,9 +39105,7 @@
* This function never returns %NULL. In case there are no file
* descriptors contained in @list, an empty array is returned.
*
- * descriptors
- *
- * Returns: (array length=length) (transfer none): an array of file
+ * Returns: (array length=length) (transfer none): an array of file descriptors
* Since: 2.24
*/
@@ -40042,9 +39134,7 @@
* This function never returns %NULL. In case there are no file
* descriptors contained in @list, an empty array is returned.
*
- * descriptors
- *
- * Returns: (array length=length) (transfer full): an array of file
+ * Returns: (array length=length) (transfer full): an array of file descriptors
* Since: 2.24
*/
@@ -40127,9 +39217,7 @@
* This function never returns %NULL. In case there are no file
* descriptors contained in @message, an empty array is returned.
*
- * descriptors
- *
- * Returns: (array length=length) (transfer full): an array of file
+ * Returns: (array length=length) (transfer full): an array of file descriptors
* Since: 2.22
*/
@@ -40192,9 +39280,7 @@
* that only are used in the OS and has little to no relevance to the
* casual user.
*
- * of the OS.
- *
- * Returns: %TRUE if @mount_path is considered an implementation detail
+ * Returns: %TRUE if @mount_path is considered an implementation detail of the OS.
*/
@@ -40218,9 +39304,7 @@
*
* Compares two unix mounts.
*
- * or less than @mount2, respectively.
- *
- * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
+ * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively.
*/
@@ -40289,9 +39373,7 @@
* Guesses the name of a Unix mount.
* The result is a translated string.
*
- * be freed with g_free()
- *
- * Returns: A newly allocated string that must
+ * Returns: A newly allocated string that must be freed with g_free()
*/
@@ -40356,9 +39438,7 @@
*
* Compares two unix mount points.
*
- * or less than @mount2, respectively.
- *
- * Returns: 1, 0 or -1 if @mount1 is greater than, equal to,
+ * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively.
*/
@@ -40438,9 +39518,7 @@
* Guesses the name of a Unix mount point.
* The result is a translated string.
*
- * be freed with g_free()
- *
- * Returns: A newly allocated string that must
+ * Returns: A newly allocated string that must be freed with g_free()
*/
@@ -40493,9 +39571,7 @@
* allowing for checking if the mounts have changed with
* g_unix_mount_points_changed_since().
*
- * a #GList of the UNIX mountpoints.
- *
- * Returns: (element-type GUnixMountPoint) (transfer full):
+ * Returns: (element-type GUnixMountPoint) (transfer full): a #GList of the UNIX mountpoints.
*/
@@ -40518,9 +39594,7 @@
* timestamp, allowing for checking if the mounts have changed
* with g_unix_mounts_changed_since().
*
- * a #GList of the UNIX mounts.
- *
- * Returns: (element-type GUnixMountEntry) (transfer full):
+ * Returns: (element-type GUnixMountEntry) (transfer full): a #GList of the UNIX mounts.
*/
@@ -40731,9 +39805,7 @@
*
* Gets a #GFile for @path.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile.
+ * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref().
*/
@@ -40748,9 +39820,7 @@
* might not support any I/O operation if the URI
* is malformed or if the URI scheme is not supported.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile.
+ * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref().
*/
@@ -40769,10 +39839,7 @@
*
* Gets a list of URI schemes supported by @vfs.
*
- * The returned array belongs to GIO and must
- * not be freed or modified.
- *
- * Returns: (transfer none): a %NULL-terminated array of strings.
+ * Returns: (transfer none): a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified.
*/
@@ -40795,9 +39862,7 @@
* not support any I/O operations if the @parse_name cannot
* be parsed by the #GVfs module.
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GFile for the given @parse_name.
+ * Returns: (transfer full): a #GFile for the given @parse_name. Free the returned object with g_object_unref().
*/
@@ -40890,9 +39955,7 @@
* that @volume has. Use g_volume_get_identifier() to obtain
* the identifiers themselves.
*
- * of strings containing kinds of identifiers. Use g_strfreev() to free.
- *
- * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array
+ * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free.
*/
@@ -40908,19 +39971,20 @@
* other words, in code
*
* <programlisting>
- * GMount *mount;
- * GFile *mount_root
- * GFile *volume_activation_root;
+ * GMount *mount;
+ * GFile *mount_root
+ * GFile *volume_activation_root;
*
- * mount = g_volume_get_mount (volume); /* mounted, so never NULL */
- * mount_root = g_mount_get_root (mount);
- * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
+ * mount = g_volume_get_mount (volume); /* mounted, so never NULL */
+ * mount_root = g_mount_get_root (mount);
+ * volume_activation_root = g_volume_get_activation_root(volume); /* assume not NULL */
* </programlisting>
*
* then the expression
*
* <programlisting>
- * (g_file_has_prefix (volume_activation_root, mount_root) ||
+ * (g_file_has_prefix (volume_activation_root, mount_root) ||
+ * g_file_equal (volume_activation_root, mount_root))
* </programlisting>
*
* will always be %TRUE.
@@ -40929,9 +39993,7 @@
* implementations to find the underlying mount to shadow, see
* g_mount_is_shadowed() for more details.
*
- * g_object_unref() to free.
- *
- * Returns: (transfer full): the activation root of @volume or %NULL. Use
+ * Returns: (transfer full): the activation root of @volume or %NULL. Use g_object_unref() to free.
* Since: 2.18
*/
@@ -40942,10 +40004,7 @@
*
* Gets the drive for the @volume.
*
- * The returned object should be unreffed with g_object_unref()
- * when no longer needed.
- *
- * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive.
+ * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -40955,10 +40014,7 @@
*
* Gets the icon for @volume.
*
- * The returned object should be unreffed with g_object_unref()
- * when no longer needed.
- *
- * Returns: (transfer full): a #GIcon.
+ * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -40971,10 +40027,7 @@
* See the <link linkend="volume-identifier">introduction</link>
* for more information about volume identifiers.
*
- * requested identfier, or %NULL if the #GVolume
- * doesn't have this kind of identifier
- *
- * Returns: a newly allocated string containing the
+ * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GVolume doesn't have this kind of identifier
*/
@@ -40984,10 +40037,7 @@
*
* Gets the mount for the @volume.
*
- * The returned object should be unreffed with g_object_unref()
- * when no longer needed.
- *
- * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted.
+ * Returns: (transfer full): a #GMount or %NULL if @volume isn't mounted. The returned object should be unreffed with g_object_unref() when no longer needed.
*/
@@ -40997,9 +40047,7 @@
*
* Gets the name of @volume.
*
- * be freed with g_free() when no longer needed.
- *
- * Returns: the name for the given @volume. The returned string should
+ * Returns: the name for the given @volume. The returned string should be freed with g_free() when no longer needed.
*/
@@ -41023,10 +40071,7 @@
* considered an opaque string. Returns %NULL if there is no UUID
* available.
*
- * The returned string should be freed with g_free()
- * when no longer needed.
- *
- * Returns: the UUID for @volume or %NULL if no UUID can be computed.
+ * Returns: the UUID for @volume or %NULL if no UUID can be computed. The returned string should be freed with g_free() when no longer needed.
*/
@@ -41063,15 +40108,8 @@
* is to return #GVolume objects representing entries in the users
* "favorite servers" list or similar.
*
- * if no wants to adopt the #GMount.
- *
- * implementations should instead create shadow mounts with the URI of
- * the mount they intend to adopt. See the proxy volume monitor in
- * gvfs for an example of this. Also see g_mount_is_shadowed(),
- * g_mount_shadow() and g_mount_unshadow() functions.
- *
- * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL
- * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor
+ * Returns: (transfer full): the #GVolume object that is the parent for @mount or %NULL if no wants to adopt the #GMount.
+ * Deprecated: 2.20: Instead of using this function, #GVolumeMonitor implementations should instead create shadow mounts with the URI of the mount they intend to adopt. See the proxy volume monitor in gvfs for an example of this. Also see g_mount_is_shadowed(), g_mount_shadow() and g_mount_unshadow() functions.
*/
@@ -41080,9 +40118,7 @@
*
* Gets the volume monitor used by gio.
*
- * g_object_unref() when done with it.
- *
- * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call
+ * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call g_object_unref() when done with it.
*/
@@ -41106,9 +40142,7 @@
*
* Finds a #GMount object by its UUID (see g_mount_get_uuid())
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GMount or %NULL if no such mount is available.
+ * Returns: (transfer full): a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref().
*/
@@ -41132,9 +40166,7 @@
*
* Finds a #GVolume object by its UUID (see g_volume_get_uuid())
*
- * Free the returned object with g_object_unref().
- *
- * Returns: (transfer full): a #GVolume or %NULL if no such volume is available.
+ * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref().
*/
@@ -41403,9 +40435,7 @@
*
* Optionally doesn't list the desktop ids given in the @except
*
- * to handle @mime_type.
- *
- * Returns: a #GList containing the desktop ids which claim
+ * Returns: a #GList containing the desktop ids which claim to handle @mime_type.
*/
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index cff5259..13a9eee 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -148,9 +148,7 @@
* from @source_value into the target property of @target
* using @target_value.
*
- * otherwise
- *
- * Returns: %TRUE if the transformation was successful, and %FALSE
+ * Returns: %TRUE if the transformation was successful, and %FALSE otherwise
* Since: 2.26
*/
@@ -323,19 +321,19 @@
* The initialization process of a class involves:
* <itemizedlist>
* <listitem><para>
- * 1 - Copying common members from the parent class over to the
- * derived class structure.
+ * 1 - Copying common members from the parent class over to the
+ * derived class structure.
* </para></listitem>
* <listitem><para>
- * 2 - Zero initialization of the remaining members not copied
- * over from the parent class.
+ * 2 - Zero initialization of the remaining members not copied
+ * over from the parent class.
* </para></listitem>
* <listitem><para>
- * 3 - Invocation of the GBaseInitFunc() initializers of all parent
- * types and the class' type.
+ * 3 - Invocation of the GBaseInitFunc() initializers of all parent
+ * types and the class' type.
* </para></listitem>
* <listitem><para>
- * 4 - Invocation of the class' GClassInitFunc() initializer.
+ * 4 - Invocation of the class' GClassInitFunc() initializer.
* </para></listitem>
* </itemizedlist>
* Since derived classes are partially initialized through a memory copy
@@ -353,45 +351,45 @@
*
* |[
* typedef struct {
- * GObjectClass parent_class;
- * gint static_integer;
- * gchar *dynamic_string;
+ * GObjectClass parent_class;
+ * gint static_integer;
+ * gchar *dynamic_string;
* } TypeAClass;
* static void
* type_a_base_class_init (TypeAClass *class)
* {
- * class->dynamic_string = g_strdup ("some string");
+ * class->dynamic_string = g_strdup ("some string");
* }
* static void
* type_a_base_class_finalize (TypeAClass *class)
* {
- * g_free (class->dynamic_string);
+ * g_free (class->dynamic_string);
* }
* static void
* type_a_class_init (TypeAClass *class)
* {
- * class->static_integer = 42;
+ * class->static_integer = 42;
* }
*
* typedef struct {
- * TypeAClass parent_class;
- * gfloat static_float;
- * GString *dynamic_gstring;
+ * TypeAClass parent_class;
+ * gfloat static_float;
+ * GString *dynamic_gstring;
* } TypeBClass;
* static void
* type_b_base_class_init (TypeBClass *class)
* {
- * class->dynamic_gstring = g_string_new ("some other string");
+ * class->dynamic_gstring = g_string_new ("some other string");
* }
* static void
* type_b_base_class_finalize (TypeBClass *class)
* {
- * g_string_free (class->dynamic_gstring);
+ * g_string_free (class->dynamic_gstring);
* }
* static void
* type_b_class_init (TypeBClass *class)
* {
- * class->static_float = 3.14159265358979323846;
+ * class->static_float = 3.14159265358979323846;
* }
* ]|
* Initialization of TypeBClass will first cause initialization of
@@ -455,12 +453,13 @@
* @a: a value.
* @b: a value to compare with.
* @user_data: user data to pass to comparison function.
- * @Returns: negative value if @a < @b; zero if @a = @b; positive value if @a > @b.
*
* Specifies the type of a comparison function used to compare two
* values. The function should return a negative integer if the first
* 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 value if @a > @b.
*/
@@ -468,12 +467,13 @@
* GCompareFunc:
* @a: a value.
* @b: a value to compare with.
- * @Returns: negative value if @a < @b; zero if @a = @b; positive value if @a > @b.
*
* Specifies the type of a comparison function used to compare two
* values. The function should return a negative integer if the first
* 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 value if @a > @b.
*/
@@ -492,38 +492,38 @@
* threads to wake up to collect the data.
*
* <example>
- * <title>
- * Using GCond to block a thread until a condition is satisfied
- * </title>
- * <programlisting>
- * gpointer current_data = NULL;
- * GMutex data_mutex;
- * GCond data_cond;
- *
- * void
- * push_data (gpointer data)
- * {
- * g_mutex_lock (&data_mutex);
- * current_data = data;
- * g_cond_signal (&data_cond);
- * g_mutex_unlock (&data_mutex);
- * }
- *
- * gpointer
- * pop_data (void)
- * {
- * gpointer data;
- *
- * g_mutex_lock (&data_mutex);
- * while (!current_data)
- * g_cond_wait (&data_cond, &data_mutex);
- * data = current_data;
- * current_data = NULL;
- * g_mutex_unlock (&data_mutex);
- *
- * return data;
- * }
- * </programlisting>
+ * <title>
+ * Using GCond to block a thread until a condition is satisfied
+ * </title>
+ * <programlisting>
+ * gpointer current_data = NULL;
+ * GMutex data_mutex;
+ * GCond data_cond;
+ *
+ * void
+ * push_data (gpointer data)
+ * {
+ * g_mutex_lock (&data_mutex);
+ * current_data = data;
+ * g_cond_signal (&data_cond);
+ * g_mutex_unlock (&data_mutex);
+ * }
+ *
+ * gpointer
+ * pop_data (void)
+ * {
+ * gpointer data;
+ *
+ * g_mutex_lock (&data_mutex);
+ * while (!current_data)
+ * g_cond_wait (&data_cond, &data_mutex);
+ * data = current_data;
+ * current_data = NULL;
+ * g_mutex_unlock (&data_mutex);
+ *
+ * return data;
+ * }
+ * </programlisting>
* </example>
*
* Whenever a thread calls pop_data() now, it will wait until
@@ -951,9 +951,7 @@
* g_hash_table_foreach_remove(). It should return %TRUE if the
* key/value pair should be removed from the #GHashTable.
*
- * #GHashTable
- *
- * Returns: %TRUE if the key/value pair should be removed from the
+ * Returns: %TRUE if the key/value pair should be removed from the #GHashTable
*/
@@ -1385,11 +1383,12 @@
* @source: the #GIOChannel event source
* @condition: the condition which has been satisfied
* @data: user data set in g_io_add_watch() or g_io_add_watch_full()
- * @Returns: the function should return %FALSE if the event source should be removed
*
* Specifies the type of function passed to g_io_add_watch() or
* g_io_add_watch_full(), which is called when the requested condition
* on a #GIOChannel is satisfied.
+ *
+ * Returns: the function should return %FALSE if the event source should be removed
*/
@@ -1397,7 +1396,7 @@
* GIOFuncs:
* @io_read: reads raw bytes from the channel. This is called from various functions such as g_io_channel_read_chars() to read raw bytes from the channel. Encoding and buffering issues are dealt with at a higher level.
* @io_write: writes raw bytes to the channel. This is called from various functions such as g_io_channel_write_chars() to write raw bytes to the channel. Encoding and buffering issues are dealt with at a higher level.
- * @io_seek: (optional) seeks the channel. This is called from g_io_channel_seek() on channels that support it.
+ * @io_seek: (optional) seeks the channel. This is called from g_io_channel_seek() on channels that support it.
* @io_close: closes the channel. This is called from g_io_channel_close() after flushing the buffers.
* @io_create_watch: creates a watch on the channel. This call corresponds directly to g_io_create_watch().
* @io_free: called from g_io_channel_unref() when the channel needs to be freed. This function must free the memory associated with the channel, including freeing the #GIOChannel structure itself. The channel buffers have been flushed and possibly @io_close has been called by the time this function is called.
@@ -1536,16 +1535,14 @@
* <example>
* <title>Checking the version of the GLib library</title>
* <programlisting>
- * if (!GLIB_CHECK_VERSION (1, 2, 0))
- * g_error ("GLib version 1.2.0 or above is needed");
+ * if (!GLIB_CHECK_VERSION (1, 2, 0))
+ * g_error ("GLib version 1.2.0 or above is needed");
* </programlisting>
* </example>
*
* See glib_check_version() for a runtime check.
*
- * is the same as or newer than the passed-in version.
- *
- * Returns: %TRUE if the version of the GLib header files
+ * Returns: %TRUE if the version of the GLib header files is the same as or newer than the passed-in version.
*/
@@ -1866,21 +1863,21 @@
* access. Take for example the following function:
*
* <example>
- * <title>A function which will not work in a threaded environment</title>
- * <programlisting>
- * int
- * give_me_next_number (void)
- * {
- * static int current_number = 0;
- *
- * /<!-- -->* now do a very complicated calculation to calculate the new
- * * number, this might for example be a random number generator
- * *<!-- -->/
- * current_number = calc_next_number (current_number);
- *
- * return current_number;
- * }
- * </programlisting>
+ * <title>A function which will not work in a threaded environment</title>
+ * <programlisting>
+ * int
+ * give_me_next_number (void)
+ * {
+ * static int current_number = 0;
+ *
+ * /<!-- -->* now do a very complicated calculation to calculate the new
+ * * number, this might for example be a random number generator
+ * *<!-- -->/
+ * current_number = calc_next_number (current_number);
+ *
+ * return current_number;
+ * }
+ * </programlisting>
* </example>
*
* It is easy to see that this won't work in a multi-threaded
@@ -1888,22 +1885,22 @@
* access. A #GMutex can be used as a solution to this problem:
*
* <example>
- * <title>Using GMutex to protected a shared variable</title>
- * <programlisting>
- * int
- * give_me_next_number (void)
- * {
- * static GMutex mutex;
- * static int current_number = 0;
- * int ret_val;
- *
- * g_mutex_lock (&mutex);
- * ret_val = current_number = calc_next_number (current_number);
- * g_mutex_unlock (&mutex);
- *
- * return ret_val;
- * }
- * </programlisting>
+ * <title>Using GMutex to protected a shared variable</title>
+ * <programlisting>
+ * int
+ * give_me_next_number (void)
+ * {
+ * static GMutex mutex;
+ * static int current_number = 0;
+ * int ret_val;
+ *
+ * g_mutex_lock (&mutex);
+ * ret_val = current_number = calc_next_number (current_number);
+ * g_mutex_unlock (&mutex);
+ *
+ * return ret_val;
+ * }
+ * </programlisting>
* </example>
*
* Notice that the #GMutex is not initialised to any particular value.
@@ -1946,12 +1943,13 @@
* GNodeTraverseFunc:
* @node: a #GNode.
* @data: user data passed to g_node_traverse().
- * @Returns: %TRUE to stop the traversal.
*
* Specifies the type of function passed to g_node_traverse(). The
* function is called with each of the nodes visited, together with the
* user data passed to g_node_traverse(). If the function returns
* %TRUE, then the traversal is stopped.
+ *
+ * Returns: %TRUE to stop the traversal.
*/
@@ -2003,22 +2001,22 @@
*
* static GObject*
* my_singleton_constructor (GType type,
- * guint n_construct_params,
- * GObjectConstructParam *construct_params)
- * {
- * GObject *object;
- *
- * if (!the_singleton)
+ * guint n_construct_params,
+ * GObjectConstructParam *construct_params)
* {
- * object = G_OBJECT_CLASS (parent_class)->constructor (type,
- * n_construct_params,
- * construct_params);
- * the_singleton = MY_SINGLETON (object);
- * }
- * else
- * object = g_object_ref (G_OBJECT (the_singleton));
- *
- * return object;
+ * GObject *object;
+ *
+ * if (!the_singleton)
+ * {
+ * object = G_OBJECT_CLASS (parent_class)->constructor (type,
+ * n_construct_params,
+ * construct_params);
+ * the_singleton = MY_SINGLETON (object);
+ * }
+ * else
+ * object = g_object_ref (G_OBJECT (the_singleton));
+ *
+ * return object;
* }
* </programlisting></example>
*/
@@ -2121,9 +2119,7 @@
* The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
* options.
*
- * occurred, in which case @error should be set with g_set_error()
- *
- * Returns: %TRUE if the option was successfully parsed, %FALSE if an error
+ * Returns: %TRUE if the option was successfully parsed, %FALSE if an error occurred, in which case @error should be set with g_set_error()
*/
@@ -2209,9 +2205,7 @@
*
* The type of function that can be called before and after parsing.
*
- * occurred, in which case @error should be set with g_set_error()
- *
- * Returns: %TRUE if the function completed successfully, %FALSE if an error
+ * Returns: %TRUE if the function completed successfully, %FALSE if an error occurred, in which case @error should be set with g_set_error()
*/
@@ -2258,7 +2252,7 @@
* @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8
* @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
* @G_PARAM_PRIVATE: internal
- * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26
+ * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since 2.26
*
* Through the #GParamFlags flag values, certain aspects of parameters
* can be configured.
@@ -2615,9 +2609,7 @@
* Specifies the type of function passed to g_main_context_set_poll_func().
* The semantics of the function should match those of the poll() system call.
*
- * reported, or -1 if an error occurred.
- *
- * Returns: the number of #GPollFD elements which have events or errors
+ * Returns: the number of #GPollFD elements which have events or errors reported, or -1 if an error occurred.
*/
@@ -2696,51 +2688,51 @@
* g_rw_lock_reader_lock()).
*
* <example>
- * <title>An array with access functions</title>
- * <programlisting>
- * GRWLock lock;
- * GPtrArray *array;
- *
- * gpointer
- * my_array_get (guint index)
- * {
- * gpointer retval = NULL;
- *
- * if (!array)
- * return NULL;
- *
- * g_rw_lock_reader_lock (&lock);
- * if (index < array->len)
- * retval = g_ptr_array_index (array, index);
- * g_rw_lock_reader_unlock (&lock);
- *
- * return retval;
- * }
- *
- * void
- * my_array_set (guint index, gpointer data)
- * {
- * g_rw_lock_writer_lock (&lock);
- *
- * if (!array)
- * array = g_ptr_array_new (<!-- -->);
- *
- * if (index >= array->len)
- * g_ptr_array_set_size (array, index+1);
- * g_ptr_array_index (array, index) = data;
- *
- * g_rw_lock_writer_unlock (&lock);
- * }
- * </programlisting>
- * <para>
- * This example shows an array which can be accessed by many readers
- * (the <function>my_array_get()</function> function) simultaneously,
- * whereas the writers (the <function>my_array_set()</function>
- * function) will only be allowed once at a time and only if no readers
- * currently access the array. This is because of the potentially
- * dangerous resizing of the array. Using these functions is fully
- * multi-thread safe now.
- * </para>
+ * <title>An array with access functions</title>
+ * <programlisting>
+ * GRWLock lock;
+ * GPtrArray *array;
+ *
+ * gpointer
+ * my_array_get (guint index)
+ * {
+ * gpointer retval = NULL;
+ *
+ * if (!array)
+ * return NULL;
+ *
+ * g_rw_lock_reader_lock (&lock);
+ * if (index < array->len)
+ * retval = g_ptr_array_index (array, index);
+ * g_rw_lock_reader_unlock (&lock);
+ *
+ * return retval;
+ * }
+ *
+ * void
+ * my_array_set (guint index, gpointer data)
+ * {
+ * g_rw_lock_writer_lock (&lock);
+ *
+ * if (!array)
+ * array = g_ptr_array_new (<!-- -->);
+ *
+ * if (index >= array->len)
+ * g_ptr_array_set_size (array, index+1);
+ * g_ptr_array_index (array, index) = data;
+ *
+ * g_rw_lock_writer_unlock (&lock);
+ * }
+ * </programlisting>
+ * <para>
+ * This example shows an array which can be accessed by many readers
+ * (the <function>my_array_get()</function> function) simultaneously,
+ * whereas the writers (the <function>my_array_set()</function>
+ * function) will only be allowed once at a time and only if no readers
+ * currently access the array. This is because of the potentially
+ * dangerous resizing of the array. Using these functions is fully
+ * multi-thread safe now.
+ * </para>
* </example>
*
* If a #GRWLock is allocated in static storage then it can be used
@@ -2801,7 +2793,8 @@
* @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
* @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
* @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
+ * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
+ * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
* @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
* @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
* @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
@@ -3109,11 +3102,12 @@
* @a: a #GSequenceIter
* @b: a #GSequenceIter
* @data: user data
- * @Returns: zero if the iterators are equal, a negative value if @a comes before @b, and a positive value if @b comes before @a.
*
* A #GSequenceIterCompareFunc is a function used to compare iterators.
* It must return zero if the iterators compare equal, a negative value
* if @a comes before @b, and a positive value if @b comes before @a.
+ *
+ * Returns: zero if the iterators are equal, a negative value if @a comes before @b, and a positive value if @b comes before @a.
*/
@@ -3141,10 +3135,7 @@
* values is performed. The return value of signal emissions is then the
* value returned by the last callback.
*
- * should be aborted. Returning %FALSE means to abort the
- * current emission and %TRUE is returned for continuation.
- *
- * Returns: The accumulator function returns whether the signal emission
+ * Returns: The accumulator function returns whether the signal emission should be aborted. Returning %FALSE means to abort the current emission and %TRUE is returned for continuation.
*/
@@ -3181,9 +3172,7 @@
*
* You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
*
- * hook is disconnected (and destroyed).
- *
- * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
+ * Returns: whether it wants to stay connected. If it returns %FALSE, the signal hook is disconnected (and destroyed).
*/
@@ -3258,9 +3247,10 @@
* GSourceCallbackFuncs:
* @ref: Called when a reference is added to the callback object
* @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
- *
+ * @get: Called to extract the callback function and data from the callback object.
*
+ * The <structname>GSourceCallbackFuncs</structname> struct contains
+ * functions for managing callback objects.
*/
@@ -3707,9 +3697,7 @@
* The type of functions which are used to translate user-visible
* strings, for <option>--help</option> output.
*
- * The returned string is owned by GLib and must not be freed.
- *
- * Returns: a translation of the string for the current locale.
+ * Returns: a translation of the string for the current locale. The returned string is owned by GLib and must not be freed.
*/
@@ -3741,12 +3729,13 @@
* @key: a key of a #GTree node.
* @value: the value corresponding to the key.
* @data: user data passed to g_tree_traverse().
- * @Returns: %TRUE to stop the traversal.
*
* Specifies the type of function passed to g_tree_traverse(). It is
* passed the key and value of each node, together with the @user_data
* parameter passed to g_tree_traverse(). If the function returns
* %TRUE, the traversal is stopped.
+ *
+ * Returns: %TRUE to stop the traversal.
*/
@@ -3802,9 +3791,7 @@
* whether they actually want to cache the class of this type, since all
* classes are routed through the same #GTypeClassCacheFunc chain.
*
- * called, %FALSE to continue.
- *
- * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
+ * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being called, %FALSE to continue.
*/
@@ -4351,6 +4338,7 @@
/**
* GUnicodeScript:
+ * @G_UNICODE_SCRIPT_INVALID_CODE: a value never returned from g_unichar_get_script()
* @G_UNICODE_SCRIPT_COMMON: a character used by multiple different scripts
* @G_UNICODE_SCRIPT_INHERITED: a mark glyph that takes its script from the i base glyph to which it is attached
* @G_UNICODE_SCRIPT_ARABIC: Arabic
@@ -4390,7 +4378,8 @@
* @G_UNICODE_SCRIPT_TELUGU: Telugu
* @G_UNICODE_SCRIPT_THAANA: Thaana
* @G_UNICODE_SCRIPT_THAI: Thai
- * @G_UNICODE_SCRIPT_TIBETAN: Tibetan Canadian Aboriginal
+ * @G_UNICODE_SCRIPT_TIBETAN: Tibetan
+ * @G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL: Canadian Aboriginal
* @G_UNICODE_SCRIPT_YI: Yi
* @G_UNICODE_SCRIPT_TAGALOG: Tagalog
* @G_UNICODE_SCRIPT_HANUNOO: Hanunoo
@@ -4403,10 +4392,13 @@
* @G_UNICODE_SCRIPT_SHAVIAN: Shavian
* @G_UNICODE_SCRIPT_LINEAR_B: Linear B
* @G_UNICODE_SCRIPT_TAI_LE: Tai Le
- * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic New Tai Lue
+ * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic
+ * @G_UNICODE_SCRIPT_NEW_TAI_LUE: New Tai Lue
* @G_UNICODE_SCRIPT_BUGINESE: Buginese
* @G_UNICODE_SCRIPT_GLAGOLITIC: Glagolitic
- * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh Syloti Nagri Old Persian
+ * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh
+ * @G_UNICODE_SCRIPT_SYLOTI_NAGRI: Syloti Nagri
+ * @G_UNICODE_SCRIPT_OLD_PERSIAN: Old Persian
* @G_UNICODE_SCRIPT_KHAROSHTHI: Kharoshthi
* @G_UNICODE_SCRIPT_UNKNOWN: an unassigned code point
* @G_UNICODE_SCRIPT_BALINESE: Balinese
@@ -4426,10 +4418,16 @@
* @G_UNICODE_SCRIPT_LYCIAN: Lycian. Since 2.16.3
* @G_UNICODE_SCRIPT_LYDIAN: Lydian. Since 2.16.3
* @G_UNICODE_SCRIPT_AVESTAN: Avestan. Since 2.26
- * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26 Egyptian Hieroglpyhs. Since 2.26 Imperial Aramaic. Since 2.26 Inscriptional Pahlavi. Since 2.26 Inscriptional Parthian. Since 2.26
+ * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26
+ * @G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS: Egyptian Hieroglpyhs. Since 2.26
+ * @G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC: Imperial Aramaic. Since 2.26
+ * @G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI: Inscriptional Pahlavi. Since 2.26
+ * @G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN: Inscriptional Parthian. Since 2.26
* @G_UNICODE_SCRIPT_JAVANESE: Javanese. Since 2.26
* @G_UNICODE_SCRIPT_KAITHI: Kaithi. Since 2.26
- * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26 Meetei Mayek. Since 2.26 Old South Arabian. Since 2.26
+ * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26
+ * @G_UNICODE_SCRIPT_MEETEI_MAYEK: Meetei Mayek. Since 2.26
+ * @G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN: Old South Arabian. Since 2.26
* @G_UNICODE_SCRIPT_OLD_TURKIC: Old Turkic. Since 2.28
* @G_UNICODE_SCRIPT_SAMARITAN: Samaritan. Since 2.26
* @G_UNICODE_SCRIPT_TAI_THAM: Tai Tham. Since 2.26
@@ -4438,8 +4436,7 @@
* @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
* @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
* @G_UNICODE_SCRIPT_CHAKMA: Chakma. Since: 2.32
- * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32
- * @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32
+ * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32 @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32
* @G_UNICODE_SCRIPT_MIAO: Miao. Since: 2.32
* @G_UNICODE_SCRIPT_SHARADA: Sharada. Since: 2.32
* @G_UNICODE_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 2.32
@@ -4678,9 +4675,9 @@
*
* The typical usage would be something like:
* |[
- * char buf[G_ASCII_DTOSTR_BUF_SIZE];
+ * char buf[G_ASCII_DTOSTR_BUF_SIZE];
*
- * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
+ * fprintf (out, "value=%s\n", g_ascii_dtostr (buf, sizeof (buf), value));
* ]|
*/
@@ -4769,9 +4766,7 @@
*
* Check if the closure still needs a marshaller. See g_closure_set_marshal().
*
- * @closure.
- *
- * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
+ * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on @closure.
*/
@@ -4802,10 +4797,7 @@
* for return values and for <emphasis>out</emphasis> parameters, it doesn't
* make sense for <emphasis>in</emphasis> parameters.
*
- * <literal>const</literal> and API consumers should adjust their code
- * accordingly
- *
- * Deprecated: 2.30: API providers should replace all existing uses with
+ * Deprecated: 2.30: API providers should replace all existing uses with <literal>const</literal> and API consumers should adjust their code accordingly
*/
@@ -4979,11 +4971,11 @@
*
* |[
* G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_THING,
- * 0,
- * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
+ * gtk_gadget,
+ * GTK_TYPE_THING,
+ * 0,
+ * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
* ]|
* expands to
* |[
@@ -4996,42 +4988,42 @@
*
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
*
* GType
* gtk_gadget_get_type (void)
* {
- * return gtk_gadget_type_id;
+ * return gtk_gadget_type_id;
* }
*
* static void
* gtk_gadget_register_type (GTypeModule *type_module)
* {
- * const GTypeInfo g_define_type_info = {
- * sizeof (GtkGadgetClass),
- * (GBaseInitFunc) NULL,
- * (GBaseFinalizeFunc) NULL,
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * (GClassFinalizeFunc) gtk_gadget_class_finalize,
- * NULL, // class_data
- * sizeof (GtkGadget),
- * 0, // n_preallocs
- * (GInstanceInitFunc) gtk_gadget_init,
- * NULL // value_table
- * };
- * gtk_gadget_type_id = g_type_module_register_type (type_module,
- * GTK_TYPE_THING,
- * GtkGadget,
- * &g_define_type_info,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
+ * const GTypeInfo g_define_type_info = {
+ * sizeof (GtkGadgetClass),
+ * (GBaseInitFunc) NULL,
+ * (GBaseFinalizeFunc) NULL,
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * (GClassFinalizeFunc) gtk_gadget_class_finalize,
+ * NULL, // class_data
+ * sizeof (GtkGadget),
+ * 0, // n_preallocs
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * NULL // value_table
+ * };
+ * gtk_gadget_type_id = g_type_module_register_type (type_module,
+ * GTK_TYPE_THING,
+ * GtkGadget,
+ * &g_define_type_info,
+ * (GTypeFlags) flags);
+ * {
+ * const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
* }
* ]|
*
@@ -5129,11 +5121,11 @@
*
* |[
* G_DEFINE_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_WIDGET,
- * 0,
- * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
+ * gtk_gadget,
+ * GTK_TYPE_WIDGET,
+ * 0,
+ * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
* ]|
* expands to
* |[
@@ -5142,33 +5134,33 @@
* static gpointer gtk_gadget_parent_class = NULL;
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
*
* GType
* gtk_gadget_get_type (void)
* {
- * static volatile gsize g_define_type_id__volatile = 0;
- * if (g_once_init_enter (&g_define_type_id__volatile))
- * {
- * GType g_define_type_id =
- * g_type_register_static_simple (GTK_TYPE_WIDGET,
- * g_intern_static_string ("GtkGadget"),
- * sizeof (GtkGadgetClass),
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * sizeof (GtkGadget),
- * (GInstanceInitFunc) gtk_gadget_init,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
- * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
- * }
- * return g_define_type_id__volatile;
+ * static volatile gsize g_define_type_id__volatile = 0;
+ * if (g_once_init_enter (&g_define_type_id__volatile))
+ * {
+ * GType g_define_type_id =
+ * g_type_register_static_simple (GTK_TYPE_WIDGET,
+ * g_intern_static_string ("GtkGadget"),
+ * sizeof (GtkGadgetClass),
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * sizeof (GtkGadget),
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * (GTypeFlags) flags);
+ * {
+ * const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
+ * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
+ * }
+ * return g_define_type_id__volatile;
* }
* ]|
* The only pieces which have to be manually provided are the definitions of
@@ -5609,9 +5601,9 @@
* |[
* G_GNUC_INTERNAL
* void _g_log_fallback_handler (const gchar *log_domain,
- * GLogLevelFlags log_level,
- * const gchar *message,
- * gpointer unused_data);
+ * GLogLevelFlags log_level,
+ * const gchar *message,
+ * gpointer unused_data);
* ]|
*
* Since: 2.6
@@ -5704,9 +5696,9 @@
*
* |[
* gint g_snprintf (gchar *string,
- * gulong n,
- * gchar const *format,
- * ...) G_GNUC_PRINTF (3, 4);
+ * gulong n,
+ * gchar const *format,
+ * ...) G_GNUC_PRINTF (3, 4);
* ]|
*/
@@ -6053,7 +6045,7 @@
* before the spelling was fixed in GLib 2.30. It is kept here for
* compatibility reasons.
*
- * Deprecated:2.30:Use G_IO_FLAG_IS_WRITABLE instead.
+ * Deprecated: 2.30:Use G_IO_FLAG_IS_WRITABLE instead.
*/
@@ -6583,7 +6575,7 @@
/**
- * G_KEY_FILE_DESKTOP_KEY_URL :
+ * G_KEY_FILE_DESKTOP_KEY_URL:
*
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
* giving the URL to access. It is only valid for desktop entries
@@ -6653,7 +6645,7 @@
*
* |[
* if (G_LIKELY (random () != 1))
- * g_print ("not one");
+ * g_print ("not one");
* ]|
*
* Returns: the value of @expr
@@ -6707,23 +6699,23 @@
* <literal>G_LOCK_*</literal> macros:
*
* <example>
- * <title>Using the <literal>G_LOCK_*</literal> convenience macros</title>
- * <programlisting>
- * G_LOCK_DEFINE (current_number);
- *
- * int
- * give_me_next_number (void)
- * {
- * static int current_number = 0;
- * int ret_val;
- *
- * G_LOCK (current_number);
- * ret_val = current_number = calc_next_number (current_number);
- * G_UNLOCK (current_number);
- *
- * return ret_val;
- * }
- * </programlisting>
+ * <title>Using the <literal>G_LOCK_*</literal> convenience macros</title>
+ * <programlisting>
+ * G_LOCK_DEFINE (current_number);
+ *
+ * int
+ * give_me_next_number (void)
+ * {
+ * static int current_number = 0;
+ * int ret_val;
+ *
+ * G_LOCK (current_number);
+ * ret_val = current_number = calc_next_number (current_number);
+ * G_UNLOCK (current_number);
+ *
+ * return ret_val;
+ * }
+ * </programlisting>
* </example>
*/
@@ -7032,9 +7024,7 @@
*
* Returns %TRUE if a #GNode is a leaf node.
*
- * (i.e. it has no children)
- *
- * Returns: %TRUE if the #GNode is a leaf node
+ * Returns: %TRUE if the #GNode is a leaf node (i.e. it has no children)
*/
@@ -7044,9 +7034,7 @@
*
* Returns %TRUE if a #GNode is the root of a tree.
*
- * (i.e. it has no parent or siblings)
- *
- * Returns: %TRUE if the #GNode is the root of a tree
+ * Returns: %TRUE if the #GNode is the root of a tree (i.e. it has no parent or siblings)
*/
@@ -7085,9 +7073,7 @@
*
* Return the name of a class structure's type.
*
- * should not be freed.
- *
- * Returns: Type name of @class. The string is owned by the type system and
+ * Returns: Type name of @class. The string is owned by the type system and should not be freed.
*/
@@ -7127,9 +7113,7 @@
*
* Get the name of an object's type.
*
- * should not be freed.
- *
- * Returns: Type name of @object. The string is owned by the type system and
+ * Returns: Type name of @object. The string is owned by the type system and should not be freed.
*/
@@ -7150,7 +7134,7 @@
* A #GOnce must be initialized with this macro before it can be used.
*
* |[
- * GOnce my_once = G_ONCE_INIT;
+ * GOnce my_once = G_ONCE_INIT;
* ]|
*
* Since: 2.4
@@ -7613,13 +7597,13 @@
* const gchar *
* get_local_name (void)
* {
- * return g_private_get (&name_key);
+ * return g_private_get (&name_key);
* }
*
* void
* set_local_name (const gchar *name)
* {
- * g_private_replace (&name_key, g_strdup (name));
+ * g_private_replace (&name_key, g_strdup (name));
* }
*
*
@@ -7628,13 +7612,13 @@
* gint
* get_local_count (void)
* {
- * return GPOINTER_TO_INT (g_private_get (&count_key));
+ * return GPOINTER_TO_INT (g_private_get (&count_key));
* }
*
* void
* set_local_count (gint count)
* {
- * g_private_set (&count_key, GINT_TO_POINTER (count));
+ * g_private_set (&count_key, GINT_TO_POINTER (count));
* }
* ]|
*
@@ -7720,13 +7704,13 @@
* of g_signal_new().
* |[
* g_signal_new ("size_request",
- * G_TYPE_FROM_CLASS (gobject_class),
- * G_SIGNAL_RUN_FIRST,
- * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
- * NULL, NULL,
- * _gtk_marshal_VOID__BOXED,
- * G_TYPE_NONE, 1,
- * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
+ * G_TYPE_FROM_CLASS (gobject_class),
+ * G_SIGNAL_RUN_FIRST,
+ * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
+ * NULL, NULL,
+ * _gtk_marshal_VOID__BOXED,
+ * G_TYPE_NONE, 1,
+ * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
* ]|
*/
@@ -7806,7 +7790,7 @@
*
* |[
* #define ADD_ONE_TO_INT(x) \
- * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
+ * (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1))
* ]|
*
* Since: 2.30
@@ -7961,10 +7945,11 @@
/**
* G_TRYLOCK:
* @name: the name of the lock
- * @Returns: %TRUE, if the lock could be locked.
*
* Works like g_mutex_trylock(), but for a lock defined with
* #G_LOCK_DEFINE.
+ *
+ * Returns: %TRUE, if the lock could be locked.
*/
@@ -8891,12 +8876,12 @@
*
* |[
* g_object_class_install_property (object_class,
- * PROP_AUTHORS,
- * g_param_spec_boxed ("authors",
- * _("Authors"),
- * _("List of authors"),
- * G_TYPE_STRV,
- * G_PARAM_READWRITE));
+ * PROP_AUTHORS,
+ * g_param_spec_boxed ("authors",
+ * _("Authors"),
+ * _("List of authors"),
+ * G_TYPE_STRV,
+ * G_PARAM_READWRITE));
*
* gchar *authors[] = { "Owen", "Tim", NULL };
* g_object_set (obj, "authors", authors, NULL);
@@ -9052,7 +9037,7 @@
*
* |[
* if (G_UNLIKELY (random () == 1))
- * g_print ("a random one");
+ * g_print ("a random one");
* ]|
*
* Returns: the value of @expr
@@ -9337,7 +9322,7 @@
* but it cannot be assigned to a variable.
*
* |[
- * GValue value = G_VALUE_INIT;
+ * GValue value = G_VALUE_INIT;
* ]|
*
* Since: 2.30
@@ -9723,18 +9708,18 @@
*
* |[
* {
- * static const char *messages[] = {
- * NC_("some context", "some very meaningful message"),
- * NC_("some context", "and another one")
- * };
- * const char *string;
- * ...
- * string
- * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
- * : g_dpgettext2 (NULL, "some context", messages[index]);
- *
- * fputs (string);
- * ...
+ * static const char *messages[] = {
+ * NC_("some context", "some very meaningful message"),
+ * NC_("some context", "and another one")
+ * };
+ * const char *string;
+ * ...
+ * string
+ * = index > 1 ? g_dpgettext2 (NULL, "some context", "a default message")
+ * : g_dpgettext2 (NULL, "some context", messages[index]);
+ *
+ * fputs (string);
+ * ...
* }
* ]|
*
@@ -9765,17 +9750,17 @@
* at runtime.
* |[
* {
- * static const char *messages[] = {
- * N_("some very meaningful message"),
- * N_("and another one")
- * };
- * const char *string;
- * ...
- * string
- * = index > 1 ? _("a default message") : gettext (messages[index]);
- *
- * fputs (string);
- * ...
+ * static const char *messages[] = {
+ * N_("some very meaningful message"),
+ * N_("and another one")
+ * };
+ * const char *string;
+ * ...
+ * string
+ * = index > 1 ? _("a default message") : gettext (messages[index]);
+ *
+ * fputs (string);
+ * ...
* }
* ]|
*
@@ -9837,21 +9822,21 @@
* To free an array, use g_array_free().
*
* <example>
- * <title>Using a #GArray to store #gint values</title>
- * <programlisting>
- * 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. *<!-- -->/
- * garray = g_array_new (FALSE, FALSE, sizeof (gint));
- * for (i = 0; i < 10000; i++)
- * g_array_append_val (garray, i);
- * for (i = 0; i < 10000; i++)
- * if (g_array_index (garray, gint, i) != i)
- * g_print ("ERROR: got %d instead of %d\n",
- * g_array_index (garray, gint, i), i);
- * g_array_free (garray, TRUE);
- * </programlisting>
+ * <title>Using a #GArray to store #gint values</title>
+ * <programlisting>
+ * 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. *<!-- -->/
+ * garray = g_array_new (FALSE, FALSE, sizeof (gint));
+ * for (i = 0; i < 10000; i++)
+ * g_array_append_val (garray, i);
+ * for (i = 0; i < 10000; i++)
+ * if (g_array_index (garray, gint, i) != i)
+ * g_print ("ERROR: got %d instead of %d\n",
+ * g_array_index (garray, gint, i), i);
+ * g_array_free (garray, TRUE);
+ * </programlisting>
* </example>
*/
@@ -9872,25 +9857,25 @@
* To free a #GByteArray, use g_byte_array_free().
*
* <example>
- * <title>Using a #GByteArray</title>
- * <programlisting>
- * GByteArray *gbarray;
- * gint i;
- *
- * gbarray = g_byte_array_new (<!-- -->);
- * for (i = 0; i < 10000; i++)
- * g_byte_array_append (gbarray, (guint8*) "abcd", 4);
- *
- * for (i = 0; i < 10000; i++)
- * {
- * g_assert (gbarray->data[4*i] == 'a');
- * g_assert (gbarray->data[4*i+1] == 'b');
- * g_assert (gbarray->data[4*i+2] == 'c');
- * g_assert (gbarray->data[4*i+3] == 'd');
- * }
- *
- * g_byte_array_free (gbarray, TRUE);
- * </programlisting>
+ * <title>Using a #GByteArray</title>
+ * <programlisting>
+ * GByteArray *gbarray;
+ * gint i;
+ *
+ * gbarray = g_byte_array_new (<!-- -->);
+ * for (i = 0; i < 10000; i++)
+ * g_byte_array_append (gbarray, (guint8*) "abcd", 4);
+ *
+ * for (i = 0; i < 10000; i++)
+ * {
+ * g_assert (gbarray->data[4*i] == 'a');
+ * g_assert (gbarray->data[4*i+1] == 'b');
+ * g_assert (gbarray->data[4*i+2] == 'c');
+ * g_assert (gbarray->data[4*i+3] == 'd');
+ * }
+ *
+ * g_byte_array_free (gbarray, TRUE);
+ * </programlisting>
* </example>
*
* See #GBytes if you are interested in an immutable object representing a
@@ -9926,22 +9911,22 @@
* To free a pointer array, use g_ptr_array_free().
*
* <example>
- * <title>Using a #GPtrArray</title>
- * <programlisting>
- * GPtrArray *gparray;
- * gchar *string1 = "one", *string2 = "two", *string3 = "three";
- *
- * gparray = g_ptr_array_new (<!-- -->);
- * g_ptr_array_add (gparray, (gpointer) string1);
- * g_ptr_array_add (gparray, (gpointer) string2);
- * g_ptr_array_add (gparray, (gpointer) string3);
- *
- * if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
- * g_print ("ERROR: got %p instead of %p\n",
- * g_ptr_array_index (gparray, 0), string1);
- *
- * g_ptr_array_free (gparray, TRUE);
- * </programlisting>
+ * <title>Using a #GPtrArray</title>
+ * <programlisting>
+ * GPtrArray *gparray;
+ * gchar *string1 = "one", *string2 = "two", *string3 = "three";
+ *
+ * gparray = g_ptr_array_new (<!-- -->);
+ * g_ptr_array_add (gparray, (gpointer) string1);
+ * g_ptr_array_add (gparray, (gpointer) string2);
+ * g_ptr_array_add (gparray, (gpointer) string3);
+ *
+ * if (g_ptr_array_index (gparray, 0) != (gpointer) string1)
+ * g_print ("ERROR: got %p instead of %p\n",
+ * g_ptr_array_index (gparray, 0), string1);
+ *
+ * g_ptr_array_free (gparray, TRUE);
+ * </programlisting>
* </example>
*/
@@ -10475,9 +10460,9 @@
* last argument. For example:
* |[
* gboolean g_file_get_contents (const gchar *filename,
- * gchar **contents,
- * gsize *length,
- * GError **error);
+ * gchar **contents,
+ * gsize *length,
+ * GError **error);
* ]|
* If you pass a non-%NULL value for the <literal>error</literal>
* argument, it should point to a location where an error can be placed.
@@ -10488,17 +10473,17 @@
* g_file_get_contents ("foo.txt", &contents, NULL, &err);
* g_assert ((contents == NULL && err != NULL) || (contents != NULL && err == NULL));
* if (err != NULL)
- * {
- * /* Report error to user, and free error */
- * g_assert (contents == NULL);
- * fprintf (stderr, "Unable to read file: %s\n", err->message);
- * g_error_free (err);
- * }
+ * {
+ * /* 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 */
- * g_assert (contents != NULL);
- * }
+ * {
+ * /* Use file contents */
+ * g_assert (contents != NULL);
+ * }
* ]|
* Note that <literal>err != NULL</literal> in this example is a
* <emphasis>reliable</emphasis> indicator of whether
@@ -10511,9 +10496,9 @@
* argument:
* |[
* if (g_file_get_contents ("foo.txt", &contents, NULL, NULL)) /* ignore errors */
- * /* no error occurred */ ;
+ * /* no error occurred */ ;
* else
- * /* error */ ;
+ * /* error */ ;
* ]|
*
* The #GError object contains three fields: <literal>domain</literal>
@@ -10541,21 +10526,21 @@
* gint
* foo_open_file (GError **error)
* {
- * gint fd;
- *
- * fd = open ("file.txt", O_RDONLY);
- *
- * 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 */
- * g_strerror (errno));
- * return -1;
- * }
- * else
- * return fd;
+ * gint fd;
+ *
+ * fd = open ("file.txt", O_RDONLY);
+ *
+ * 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 */
+ * g_strerror (errno));
+ * return -1;
+ * }
+ * else
+ * return fd;
* }
* ]|
*
@@ -10567,17 +10552,17 @@
* gboolean
* my_function_that_can_fail (GError **err)
* {
- * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
*
- * if (!sub_function_that_can_fail (err))
- * {
- * /* assert that error was set by the sub-function */
- * g_assert (err == NULL || *err != NULL);
- * return FALSE;
- * }
+ * if (!sub_function_that_can_fail (err))
+ * {
+ * /* assert that error was set by the sub-function */
+ * g_assert (err == NULL || *err != NULL);
+ * return FALSE;
+ * }
*
- * /* otherwise continue, no error occurred */
- * g_assert (err == NULL || *err == NULL);
+ * /* otherwise continue, no error occurred */
+ * g_assert (err == NULL || *err == NULL);
* }
* ]|
*
@@ -10589,23 +10574,23 @@
* gboolean
* my_function_that_can_fail (GError **err)
* {
- * GError *tmp_error;
+ * GError *tmp_error;
*
- * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
*
- * tmp_error = NULL;
- * sub_function_that_can_fail (&tmp_error);
+ * tmp_error = NULL;
+ * sub_function_that_can_fail (&tmp_error);
*
- * if (tmp_error != NULL)
- * {
- * /* store tmp_error in err, if err != NULL,
- * * otherwise call g_error_free() on tmp_error
- * */
- * g_propagate_error (err, tmp_error);
- * return FALSE;
- * }
+ * if (tmp_error != NULL)
+ * {
+ * /* 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 */
* }
* ]|
*
@@ -10614,19 +10599,19 @@
* gboolean
* my_function_that_can_fail (GError **err)
* {
- * GError *tmp_error;
+ * GError *tmp_error;
*
- * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
*
- * tmp_error = NULL;
- * sub_function_that_can_fail (&tmp_error);
- * other_function_that_can_fail (&tmp_error);
+ * tmp_error = NULL;
+ * sub_function_that_can_fail (&tmp_error);
+ * other_function_that_can_fail (&tmp_error);
*
- * if (tmp_error != NULL)
- * {
- * g_propagate_error (err, tmp_error);
- * return FALSE;
- * }
+ * if (tmp_error != NULL)
+ * {
+ * g_propagate_error (err, tmp_error);
+ * return FALSE;
+ * }
* }
* ]|
* <literal>tmp_error</literal> should be checked immediately after
@@ -10641,20 +10626,20 @@
* gboolean
* my_function_that_can_fail (GError **err)
* {
- * GError *tmp_error;
+ * GError *tmp_error;
*
- * g_return_val_if_fail (err == NULL || *err == NULL, FALSE);
+ * 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);
+ * tmp_error = NULL;
+ * other_function_that_can_fail (&tmp_error);
*
- * if (tmp_error != NULL)
- * {
- * g_propagate_error (err, tmp_error);
- * return FALSE;
- * }
+ * if (tmp_error != NULL)
+ * {
+ * g_propagate_error (err, tmp_error);
+ * return FALSE;
+ * }
* }
* ]|
*
@@ -10667,105 +10652,105 @@
* Error domains and codes are conventionally named as follows:
* <itemizedlist>
* <listitem><para>
- * The error domain is called
- * <literal><NAMESPACE>_<MODULE>_ERROR</literal>,
- * for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
- * |[
+ * The error domain is called
+ * <literal><NAMESPACE>_<MODULE>_ERROR</literal>,
+ * for example %G_SPAWN_ERROR or %G_THREAD_ERROR:
+ * |[
* #define G_SPAWN_ERROR g_spawn_error_quark ()
*
* GQuark
* g_spawn_error_quark (void)
* {
- * return g_quark_from_static_string ("g-spawn-error-quark");
+ * return g_quark_from_static_string ("g-spawn-error-quark");
* }
- * ]|
+ * ]|
* </para></listitem>
* <listitem><para>
- * The quark function for the error domain is called
- * <literal><namespace>_<module>_error_quark</literal>,
- * for example g_spawn_error_quark() or g_thread_error_quark().
+ * The quark function for the error domain is called
+ * <literal><namespace>_<module>_error_quark</literal>,
+ * for example g_spawn_error_quark() or g_thread_error_quark().
* </para></listitem>
* <listitem><para>
- * The error codes are in an enumeration called
- * <literal><Namespace><Module>Error</literal>;
- * for example,#GThreadError or #GSpawnError.
+ * The error codes are in an enumeration called
+ * <literal><Namespace><Module>Error</literal>;
+ * for example,#GThreadError or #GSpawnError.
* </para></listitem>
* <listitem><para>
- * Members of the error code enumeration are called
- * <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>,
- * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
+ * Members of the error code enumeration are called
+ * <literal><NAMESPACE>_<MODULE>_ERROR_<CODE></literal>,
+ * for example %G_SPAWN_ERROR_FORK or %G_THREAD_ERROR_AGAIN.
* </para></listitem>
* <listitem><para>
- * If there's a "generic" or "unknown" error code for unrecoverable
- * errors it doesn't make sense to distinguish with specific codes,
- * it should be called <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>,
- * for example %G_SPAWN_ERROR_FAILED.
+ * If there's a "generic" or "unknown" error code for unrecoverable
+ * errors it doesn't make sense to distinguish with specific codes,
+ * it should be called <literal><NAMESPACE>_<MODULE>_ERROR_FAILED</literal>,
+ * for example %G_SPAWN_ERROR_FAILED.
* </para></listitem>
* </itemizedlist>
*
* Summary of rules for use of #GError:
* <itemizedlist>
* <listitem><para>
- * Do not report programming errors via #GError.
+ * Do not report programming errors via #GError.
* </para></listitem>
* <listitem><para>
- * The last argument of a function that returns an error should
- * be a location where a #GError can be placed (i.e. "#GError** error").
- * If #GError is used with varargs, the #GError** should be the last
- * argument before the "...".
+ * The last argument of a function that returns an error should
+ * be a location where a #GError can be placed (i.e. "#GError** error").
+ * If #GError is used with varargs, the #GError** should be the last
+ * argument before the "...".
* </para></listitem>
* <listitem><para>
- * The caller may pass %NULL for the #GError** if they are not interested
- * in details of the exact error that occurred.
+ * The caller may pass %NULL for the #GError** if they are not interested
+ * in details of the exact error that occurred.
* </para></listitem>
* <listitem><para>
- * If %NULL is passed for the #GError** argument, then errors should
- * not be returned to the caller, but your function should still
- * abort and return if an error occurs. That is, control flow should
- * not be affected by whether the caller wants to get a #GError.
+ * If %NULL is passed for the #GError** argument, then errors should
+ * not be returned to the caller, but your function should still
+ * abort and return if an error occurs. That is, control flow should
+ * not be affected by whether the caller wants to get a #GError.
* </para></listitem>
* <listitem><para>
- * If a #GError is reported, then your function by definition
- * <emphasis>had a fatal failure and did not complete whatever
- * it was supposed to do</emphasis>. If the failure was not fatal,
- * then you handled it and you should not report it. If it was fatal,
- * then you must report it and discontinue whatever you were doing
- * immediately.
+ * If a #GError is reported, then your function by definition
+ * <emphasis>had a fatal failure and did not complete whatever
+ * it was supposed to do</emphasis>. If the failure was not fatal,
+ * then you handled it and you should not report it. If it was fatal,
+ * then you must report it and discontinue whatever you were doing
+ * immediately.
* </para></listitem>
* <listitem><para>
- * If a #GError is reported, out parameters are not guaranteed to
- * be set to any defined value.
+ * If a #GError is reported, out parameters are not guaranteed to
+ * be set to any defined value.
* </para></listitem>
* <listitem><para>
- * A #GError* must be initialized to %NULL before passing its address
- * to a function that can report errors.
+ * A #GError* must be initialized to %NULL before passing its address
+ * to a function that can report errors.
* </para></listitem>
* <listitem><para>
- * "Piling up" errors is always a bug. That is, if you assign a
- * new #GError to a #GError* that is non-%NULL, thus overwriting
- * the previous error, it indicates that you should have aborted
- * the operation instead of continuing. If you were able to continue,
- * you should have cleared the previous error with g_clear_error().
- * g_set_error() will complain if you pile up errors.
+ * "Piling up" errors is always a bug. That is, if you assign a
+ * new #GError to a #GError* that is non-%NULL, thus overwriting
+ * the previous error, it indicates that you should have aborted
+ * the operation instead of continuing. If you were able to continue,
+ * you should have cleared the previous error with g_clear_error().
+ * g_set_error() will complain if you pile up errors.
* </para></listitem>
* <listitem><para>
- * By convention, if you return a boolean value indicating success
- * then %TRUE means success and %FALSE means failure. If %FALSE is
- * returned, the error <emphasis>must</emphasis> be set to a non-%NULL
- * value.
+ * By convention, if you return a boolean value indicating success
+ * then %TRUE means success and %FALSE means failure. If %FALSE is
+ * returned, the error <emphasis>must</emphasis> be set to a non-%NULL
+ * value.
* </para></listitem>
* <listitem><para>
- * A %NULL return value is also frequently used to mean that an error
- * occurred. You should make clear in your documentation whether %NULL
- * is a valid return value in non-error cases; if %NULL is a valid value,
- * then users must check whether an error was returned to see if the
- * function succeeded.
+ * A %NULL return value is also frequently used to mean that an error
+ * occurred. You should make clear in your documentation whether %NULL
+ * is a valid return value in non-error cases; if %NULL is a valid value,
+ * then users must check whether an error was returned to see if the
+ * function succeeded.
* </para></listitem>
* <listitem><para>
- * When implementing a function that can report errors, you may want
- * to add a check at the top of your function that the error return
- * location is either %NULL or contains a %NULL error (e.g.
- * <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>).
+ * When implementing a function that can report errors, you may want
+ * to add a check at the top of your function that the error return
+ * location is either %NULL or contains a %NULL error (e.g.
+ * <literal>g_return_if_fail (error == NULL || *error == NULL);</literal>).
* </para></listitem>
* </itemizedlist>
*/
@@ -10966,199 +10951,199 @@
* with type inferencing.
*
* <refsect2>
- * <title>Memory Use</title>
- * <para>
- * #GVariant tries to be quite efficient with respect to memory use.
- * This section gives a rough idea of how much memory is used by the
- * current implementation. The information here is subject to change
- * in the future.
- * </para>
- * <para>
- * The memory allocated by #GVariant can be grouped into 4 broad
- * purposes: memory for serialised data, memory for the type
- * information cache, buffer management memory and memory for the
- * #GVariant structure itself.
- * </para>
- * <refsect3 id="gvariant-serialised-data-memory">
- * <title>Serialised Data Memory</title>
- * <para>
- * This is the memory that is used for storing GVariant data in
- * serialised form. This is what would be sent over the network or
- * what would end up on disk.
- * </para>
- * <para>
- * The amount of memory required to store a boolean is 1 byte. 16,
- * 32 and 64 bit integers and double precision floating point numbers
- * use their "natural" size. Strings (including object path and
- * signature strings) are stored with a nul terminator, and as such
- * use the length of the string plus 1 byte.
- * </para>
- * <para>
- * Maybe types use no space at all to represent the null value and
- * use the same amount of space (sometimes plus one byte) as the
- * equivalent non-maybe-typed value to represent the non-null case.
- * </para>
- * <para>
- * Arrays use the amount of space required to store each of their
- * members, concatenated. Additionally, if the items stored in an
- * array are not of a fixed-size (ie: strings, other arrays, etc)
- * then an additional framing offset is stored for each item. The
- * size of this offset is either 1, 2 or 4 bytes depending on the
- * overall size of the container. Additionally, extra padding bytes
- * are added as required for alignment of child values.
- * </para>
- * <para>
- * Tuples (including dictionary entries) use the amount of space
- * required to store each of their members, concatenated, plus one
- * framing offset (as per arrays) for each non-fixed-sized item in
- * the tuple, except for the last one. Additionally, extra padding
- * bytes are added as required for alignment of child values.
- * </para>
- * <para>
- * Variants use the same amount of space as the item inside of the
- * variant, plus 1 byte, plus the length of the type string for the
- * item inside the variant.
- * </para>
- * <para>
- * As an example, consider a dictionary mapping strings to variants.
- * In the case that the dictionary is empty, 0 bytes are required for
- * the serialisation.
- * </para>
- * <para>
- * If we add an item "width" that maps to the int32 value of 500 then
- * we will use 4 byte to store the int32 (so 6 for the variant
- * containing it) and 6 bytes for the string. The variant must be
- * aligned to 8 after the 6 bytes of the string, so that's 2 extra
- * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
- * for the dictionary entry. An additional 1 byte is added to the
- * array as a framing offset making a total of 15 bytes.
- * </para>
- * <para>
- * If we add another entry, "title" that maps to a nullable string
- * that happens to have a value of null, then we use 0 bytes for the
- * null value (and 3 bytes for the variant to contain it along with
- * its type string) plus 6 bytes for the string. Again, we need 2
- * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
- * </para>
- * <para>
- * We now require extra padding between the two items in the array.
- * After the 14 bytes of the first item, that's 2 bytes required. We
- * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11
- * + 2 = 29 bytes to encode the entire two-item dictionary.
- * </para>
- * </refsect3>
- * <refsect3>
- * <title>Type Information Cache</title>
- * <para>
- * For each GVariant type that currently exists in the program a type
- * information structure is kept in the type information cache. The
- * type information structure is required for rapid deserialisation.
- * </para>
- * <para>
- * Continuing with the above example, if a #GVariant exists with the
- * type "a{sv}" then a type information struct will exist for
- * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
- * will share the same type information. Additionally, all
- * single-digit types are stored in read-only static memory and do
- * not contribute to the writable memory footprint of a program using
- * #GVariant.
- * </para>
- * <para>
- * Aside from the type information structures stored in read-only
- * memory, there are two forms of type information. One is used for
- * container types where there is a single element type: arrays and
- * maybe types. The other is used for container types where there
- * are multiple element types: tuples and dictionary entries.
- * </para>
- * <para>
- * Array type info structures are 6 * sizeof (void *), plus the
- * memory required to store the type string itself. This means that
- * on 32bit systems, the cache entry for "a{sv}" would require 30
- * bytes of memory (plus malloc overhead).
- * </para>
- * <para>
- * Tuple type info structures are 6 * sizeof (void *), plus 4 *
- * sizeof (void *) for each item in the tuple, plus the memory
- * required to store the type string itself. A 2-item tuple, for
- * example, would have a type information structure that consumed
- * writable memory in the size of 14 * sizeof (void *) (plus type
- * string) This means that on 32bit systems, the cache entry for
- * "{sv}" would require 61 bytes of memory (plus malloc overhead).
- * </para>
- * <para>
- * This means that in total, for our "a{sv}" example, 91 bytes of
- * type information would be allocated.
- * </para>
- * <para>
- * The type information cache, additionally, uses a #GHashTable to
- * store and lookup the cached items and stores a pointer to this
- * hash table in static storage. The hash table is freed when there
- * are zero items in the type cache.
- * </para>
- * <para>
- * Although these sizes may seem large it is important to remember
- * that a program will probably only have a very small number of
- * different types of values in it and that only one type information
- * structure is required for many different values of the same type.
- * </para>
- * </refsect3>
- * <refsect3>
- * <title>Buffer Management Memory</title>
- * <para>
- * #GVariant uses an internal buffer management structure to deal
- * with the various different possible sources of serialised data
- * that it uses. The buffer is responsible for ensuring that the
- * correct call is made when the data is no longer in use by
- * #GVariant. This may involve a g_free() or a g_slice_free() or
- * even g_mapped_file_unref().
- * </para>
- * <para>
- * One buffer management structure is used for each chunk of
- * serialised data. The size of the buffer management structure is 4
- * * (void *). On 32bit systems, that's 16 bytes.
- * </para>
- * </refsect3>
- * <refsect3>
- * <title>GVariant structure</title>
- * <para>
- * The size of a #GVariant structure is 6 * (void *). On 32 bit
- * systems, that's 24 bytes.
- * </para>
- * <para>
- * #GVariant structures only exist if they are explicitly created
- * with API calls. For example, if a #GVariant is constructed out of
- * serialised data for the example given above (with the dictionary)
- * then although there are 9 individual values that comprise the
- * entire dictionary (two keys, two values, two variants containing
- * the values, two dictionary entries, plus the dictionary itself),
- * only 1 #GVariant instance exists -- the one referring to the
- * dictionary.
- * </para>
- * <para>
- * If calls are made to start accessing the other values then
- * #GVariant instances will exist for those values only for as long
- * as they are in use (ie: until you call g_variant_unref()). The
- * type information is shared. The serialised data and the buffer
- * management structure for that serialised data is shared by the
- * child.
- * </para>
- * </refsect3>
- * <refsect3>
- * <title>Summary</title>
- * <para>
- * To put the entire example together, for our dictionary mapping
- * strings to variants (with two entries, as given above), we are
- * using 91 bytes of memory for type information, 29 byes of memory
- * for the serialised data, 16 bytes for buffer management and 24
- * bytes for the #GVariant instance, or a total of 160 bytes, plus
- * malloc overhead. If we were to use g_variant_get_child_value() to
- * access the two dictionary entries, we would use an additional 48
- * bytes. If we were to have other dictionaries of the same type, we
- * would use more memory for the serialised data and buffer
- * management for those dictionaries, but the type information would
- * be shared.
- * </para>
- * </refsect3>
+ * <title>Memory Use</title>
+ * <para>
+ * #GVariant tries to be quite efficient with respect to memory use.
+ * This section gives a rough idea of how much memory is used by the
+ * current implementation. The information here is subject to change
+ * in the future.
+ * </para>
+ * <para>
+ * The memory allocated by #GVariant can be grouped into 4 broad
+ * purposes: memory for serialised data, memory for the type
+ * information cache, buffer management memory and memory for the
+ * #GVariant structure itself.
+ * </para>
+ * <refsect3 id="gvariant-serialised-data-memory">
+ * <title>Serialised Data Memory</title>
+ * <para>
+ * This is the memory that is used for storing GVariant data in
+ * serialised form. This is what would be sent over the network or
+ * what would end up on disk.
+ * </para>
+ * <para>
+ * The amount of memory required to store a boolean is 1 byte. 16,
+ * 32 and 64 bit integers and double precision floating point numbers
+ * use their "natural" size. Strings (including object path and
+ * signature strings) are stored with a nul terminator, and as such
+ * use the length of the string plus 1 byte.
+ * </para>
+ * <para>
+ * Maybe types use no space at all to represent the null value and
+ * use the same amount of space (sometimes plus one byte) as the
+ * equivalent non-maybe-typed value to represent the non-null case.
+ * </para>
+ * <para>
+ * Arrays use the amount of space required to store each of their
+ * members, concatenated. Additionally, if the items stored in an
+ * array are not of a fixed-size (ie: strings, other arrays, etc)
+ * then an additional framing offset is stored for each item. The
+ * size of this offset is either 1, 2 or 4 bytes depending on the
+ * overall size of the container. Additionally, extra padding bytes
+ * are added as required for alignment of child values.
+ * </para>
+ * <para>
+ * Tuples (including dictionary entries) use the amount of space
+ * required to store each of their members, concatenated, plus one
+ * framing offset (as per arrays) for each non-fixed-sized item in
+ * the tuple, except for the last one. Additionally, extra padding
+ * bytes are added as required for alignment of child values.
+ * </para>
+ * <para>
+ * Variants use the same amount of space as the item inside of the
+ * variant, plus 1 byte, plus the length of the type string for the
+ * item inside the variant.
+ * </para>
+ * <para>
+ * As an example, consider a dictionary mapping strings to variants.
+ * In the case that the dictionary is empty, 0 bytes are required for
+ * the serialisation.
+ * </para>
+ * <para>
+ * If we add an item "width" that maps to the int32 value of 500 then
+ * we will use 4 byte to store the int32 (so 6 for the variant
+ * containing it) and 6 bytes for the string. The variant must be
+ * aligned to 8 after the 6 bytes of the string, so that's 2 extra
+ * bytes. 6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
+ * for the dictionary entry. An additional 1 byte is added to the
+ * array as a framing offset making a total of 15 bytes.
+ * </para>
+ * <para>
+ * If we add another entry, "title" that maps to a nullable string
+ * that happens to have a value of null, then we use 0 bytes for the
+ * null value (and 3 bytes for the variant to contain it along with
+ * its type string) plus 6 bytes for the string. Again, we need 2
+ * padding bytes. That makes a total of 6 + 2 + 3 = 11 bytes.
+ * </para>
+ * <para>
+ * We now require extra padding between the two items in the array.
+ * After the 14 bytes of the first item, that's 2 bytes required. We
+ * now require 2 framing offsets for an extra two bytes. 14 + 2 + 11
+ * + 2 = 29 bytes to encode the entire two-item dictionary.
+ * </para>
+ * </refsect3>
+ * <refsect3>
+ * <title>Type Information Cache</title>
+ * <para>
+ * For each GVariant type that currently exists in the program a type
+ * information structure is kept in the type information cache. The
+ * type information structure is required for rapid deserialisation.
+ * </para>
+ * <para>
+ * Continuing with the above example, if a #GVariant exists with the
+ * type "a{sv}" then a type information struct will exist for
+ * "a{sv}", "{sv}", "s", and "v". Multiple uses of the same type
+ * will share the same type information. Additionally, all
+ * single-digit types are stored in read-only static memory and do
+ * not contribute to the writable memory footprint of a program using
+ * #GVariant.
+ * </para>
+ * <para>
+ * Aside from the type information structures stored in read-only
+ * memory, there are two forms of type information. One is used for
+ * container types where there is a single element type: arrays and
+ * maybe types. The other is used for container types where there
+ * are multiple element types: tuples and dictionary entries.
+ * </para>
+ * <para>
+ * Array type info structures are 6 * sizeof (void *), plus the
+ * memory required to store the type string itself. This means that
+ * on 32bit systems, the cache entry for "a{sv}" would require 30
+ * bytes of memory (plus malloc overhead).
+ * </para>
+ * <para>
+ * Tuple type info structures are 6 * sizeof (void *), plus 4 *
+ * sizeof (void *) for each item in the tuple, plus the memory
+ * required to store the type string itself. A 2-item tuple, for
+ * example, would have a type information structure that consumed
+ * writable memory in the size of 14 * sizeof (void *) (plus type
+ * string) This means that on 32bit systems, the cache entry for
+ * "{sv}" would require 61 bytes of memory (plus malloc overhead).
+ * </para>
+ * <para>
+ * This means that in total, for our "a{sv}" example, 91 bytes of
+ * type information would be allocated.
+ * </para>
+ * <para>
+ * The type information cache, additionally, uses a #GHashTable to
+ * store and lookup the cached items and stores a pointer to this
+ * hash table in static storage. The hash table is freed when there
+ * are zero items in the type cache.
+ * </para>
+ * <para>
+ * Although these sizes may seem large it is important to remember
+ * that a program will probably only have a very small number of
+ * different types of values in it and that only one type information
+ * structure is required for many different values of the same type.
+ * </para>
+ * </refsect3>
+ * <refsect3>
+ * <title>Buffer Management Memory</title>
+ * <para>
+ * #GVariant uses an internal buffer management structure to deal
+ * with the various different possible sources of serialised data
+ * that it uses. The buffer is responsible for ensuring that the
+ * correct call is made when the data is no longer in use by
+ * #GVariant. This may involve a g_free() or a g_slice_free() or
+ * even g_mapped_file_unref().
+ * </para>
+ * <para>
+ * One buffer management structure is used for each chunk of
+ * serialised data. The size of the buffer management structure is 4
+ * * (void *). On 32bit systems, that's 16 bytes.
+ * </para>
+ * </refsect3>
+ * <refsect3>
+ * <title>GVariant structure</title>
+ * <para>
+ * The size of a #GVariant structure is 6 * (void *). On 32 bit
+ * systems, that's 24 bytes.
+ * </para>
+ * <para>
+ * #GVariant structures only exist if they are explicitly created
+ * with API calls. For example, if a #GVariant is constructed out of
+ * serialised data for the example given above (with the dictionary)
+ * then although there are 9 individual values that comprise the
+ * entire dictionary (two keys, two values, two variants containing
+ * the values, two dictionary entries, plus the dictionary itself),
+ * only 1 #GVariant instance exists -- the one referring to the
+ * dictionary.
+ * </para>
+ * <para>
+ * If calls are made to start accessing the other values then
+ * #GVariant instances will exist for those values only for as long
+ * as they are in use (ie: until you call g_variant_unref()). The
+ * type information is shared. The serialised data and the buffer
+ * management structure for that serialised data is shared by the
+ * child.
+ * </para>
+ * </refsect3>
+ * <refsect3>
+ * <title>Summary</title>
+ * <para>
+ * To put the entire example together, for our dictionary mapping
+ * strings to variants (with two entries, as given above), we are
+ * using 91 bytes of memory for type information, 29 byes of memory
+ * for the serialised data, 16 bytes for buffer management and 24
+ * bytes for the #GVariant instance, or a total of 160 bytes, plus
+ * malloc overhead. If we were to use g_variant_get_child_value() to
+ * access the two dictionary entries, we would use an additional 48
+ * bytes. If we were to have other dictionaries of the same type, we
+ * would use more memory for the serialised data and buffer
+ * management for those dictionaries, but the type information would
+ * be shared.
+ * </para>
+ * </refsect3>
* </refsect2>
*/
@@ -11230,388 +11215,388 @@
* A detailed description of GVariant type strings is given here:
*
* <refsect2 id='gvariant-typestrings'>
- * <title>GVariant Type Strings</title>
- * <para>
- * A GVariant type string can be any of the following:
- * </para>
- * <itemizedlist>
- * <listitem>
- * <para>
- * any basic type string (listed below)
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * "<literal>v</literal>", "<literal>r</literal>" or
- * "<literal>*</literal>"
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * one of the characters '<literal>a</literal>' or
- * '<literal>m</literal>', followed by another type string
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * the character '<literal>(</literal>', followed by a concatenation
- * of zero or more other type strings, followed by the character
- * '<literal>)</literal>'
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * the character '<literal>{</literal>', followed by a basic type
- * string (see below), followed by another type string, followed by
- * the character '<literal>}</literal>'
- * </para>
- * </listitem>
- * </itemizedlist>
- * <para>
- * A basic type string describes a basic type (as per
- * g_variant_type_is_basic()) and is always a single
- * character in length. The valid basic type strings are
- * "<literal>b</literal>", "<literal>y</literal>",
- * "<literal>n</literal>", "<literal>q</literal>",
- * "<literal>i</literal>", "<literal>u</literal>",
- * "<literal>x</literal>", "<literal>t</literal>",
- * "<literal>h</literal>", "<literal>d</literal>",
- * "<literal>s</literal>", "<literal>o</literal>",
- * "<literal>g</literal>" and "<literal>?</literal>".
- * </para>
- * <para>
- * The above definition is recursive to arbitrary depth.
- * "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
- * are both valid type strings, as is
- * "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
- * </para>
- * <para>
- * The meaning of each of the characters is as follows:
- * </para>
- * <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>
- * <literal>b</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>y</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_BYTE; a byte.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>n</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>q</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>i</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>u</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>x</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>t</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
- * integer.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>h</literal>
- * </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>
- * <literal>d</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
- * floating point value.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>s</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_STRING; a string.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>o</literal>
- * </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>
- * <literal>g</literal>
- * </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>
- * <literal>?</literal>
- * </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>
- * <literal>v</literal>
- * </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>
- * <literal>a</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used as a prefix on another type string to mean an array of
- * that type; the type string "<literal>ai</literal>", for
- * example, is the type of an array of 32 bit signed integers.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>m</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used as a prefix on another type string to mean a "maybe", or
- * "nullable", version of that type; the type string
- * "<literal>ms</literal>", for example, is the type of a value
- * that maybe contains a string, or maybe contains nothing.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>()</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * used to enclose zero or more other concatenated type strings
- * to create a tuple type; the type string
- * "<literal>(is)</literal>", for example, is the type of a pair
- * of an integer and a string.
- * </para>
- * </entry>
- * </row>
- * <row>
- * <entry>
- * <para>
- * <literal>r</literal>
- * </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>
- * <literal>{}</literal>
- * </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 "<literal>a{sd}</literal>", 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>
- * <literal>*</literal>
- * </para>
- * </entry>
- * <entry>
- * <para>
- * the type string of %G_VARIANT_TYPE_ANY; the indefinite type
- * that is a supertype of all types. Note that, as with all type
- * strings, this character represents exactly one type. It
- * cannot be used inside of tuples to mean "any number of items".
- * </para>
- * </entry>
- * </row>
- * </tbody>
- * </tgroup>
- * </informaltable>
- * <para>
- * Any type string of a container that contains an indefinite type is,
- * itself, an indefinite type. For example, the type string
- * "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
- * an indefinite type that is a supertype of every array type.
- * "<literal>(*s)</literal>" is a supertype of all tuples that
- * contain exactly two items where the second item is a string.
- * </para>
- * <para>
- * "<literal>a{?*}</literal>" is an indefinite type that is a
- * supertype of all arrays containing dictionary entries where the key
- * is any basic type and the value is any type at all. This is, by
- * definition, a dictionary, so this type string corresponds to
- * %G_VARIANT_TYPE_DICTIONARY. Note that, due to the restriction that
- * the key of a dictionary entry must be a basic type,
- * "<literal>{**}</literal>" is not a valid type string.
- * </para>
+ * <title>GVariant Type Strings</title>
+ * <para>
+ * A GVariant type string can be any of the following:
+ * </para>
+ * <itemizedlist>
+ * <listitem>
+ * <para>
+ * any basic type string (listed below)
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * "<literal>v</literal>", "<literal>r</literal>" or
+ * "<literal>*</literal>"
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * one of the characters '<literal>a</literal>' or
+ * '<literal>m</literal>', followed by another type string
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * the character '<literal>(</literal>', followed by a concatenation
+ * of zero or more other type strings, followed by the character
+ * '<literal>)</literal>'
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * the character '<literal>{</literal>', followed by a basic type
+ * string (see below), followed by another type string, followed by
+ * the character '<literal>}</literal>'
+ * </para>
+ * </listitem>
+ * </itemizedlist>
+ * <para>
+ * A basic type string describes a basic type (as per
+ * g_variant_type_is_basic()) and is always a single
+ * character in length. The valid basic type strings are
+ * "<literal>b</literal>", "<literal>y</literal>",
+ * "<literal>n</literal>", "<literal>q</literal>",
+ * "<literal>i</literal>", "<literal>u</literal>",
+ * "<literal>x</literal>", "<literal>t</literal>",
+ * "<literal>h</literal>", "<literal>d</literal>",
+ * "<literal>s</literal>", "<literal>o</literal>",
+ * "<literal>g</literal>" and "<literal>?</literal>".
+ * </para>
+ * <para>
+ * The above definition is recursive to arbitrary depth.
+ * "<literal>aaaaai</literal>" and "<literal>(ui(nq((y)))s)</literal>"
+ * are both valid type strings, as is
+ * "<literal>a(aa(ui)(qna{ya(yd)}))</literal>".
+ * </para>
+ * <para>
+ * The meaning of each of the characters is as follows:
+ * </para>
+ * <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>
+ * <literal>b</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>y</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_BYTE; a byte.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>n</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_INT16; a signed 16 bit
+ * integer.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>q</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_UINT16; an unsigned 16 bit
+ * integer.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>i</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_INT32; a signed 32 bit
+ * integer.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>u</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_UINT32; an unsigned 32 bit
+ * integer.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>x</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_INT64; a signed 64 bit
+ * integer.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>t</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_UINT64; an unsigned 64 bit
+ * integer.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>h</literal>
+ * </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>
+ * <literal>d</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_DOUBLE; a double precision
+ * floating point value.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>s</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_STRING; a string.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>o</literal>
+ * </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>
+ * <literal>g</literal>
+ * </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>
+ * <literal>?</literal>
+ * </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>
+ * <literal>v</literal>
+ * </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>
+ * <literal>a</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * used as a prefix on another type string to mean an array of
+ * that type; the type string "<literal>ai</literal>", for
+ * example, is the type of an array of 32 bit signed integers.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>m</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * used as a prefix on another type string to mean a "maybe", or
+ * "nullable", version of that type; the type string
+ * "<literal>ms</literal>", for example, is the type of a value
+ * that maybe contains a string, or maybe contains nothing.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>()</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * used to enclose zero or more other concatenated type strings
+ * to create a tuple type; the type string
+ * "<literal>(is)</literal>", for example, is the type of a pair
+ * of an integer and a string.
+ * </para>
+ * </entry>
+ * </row>
+ * <row>
+ * <entry>
+ * <para>
+ * <literal>r</literal>
+ * </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>
+ * <literal>{}</literal>
+ * </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 "<literal>a{sd}</literal>", 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>
+ * <literal>*</literal>
+ * </para>
+ * </entry>
+ * <entry>
+ * <para>
+ * the type string of %G_VARIANT_TYPE_ANY; the indefinite type
+ * that is a supertype of all types. Note that, as with all type
+ * strings, this character represents exactly one type. It
+ * cannot be used inside of tuples to mean "any number of items".
+ * </para>
+ * </entry>
+ * </row>
+ * </tbody>
+ * </tgroup>
+ * </informaltable>
+ * <para>
+ * Any type string of a container that contains an indefinite type is,
+ * itself, an indefinite type. For example, the type string
+ * "<literal>a*</literal>" (corresponding to %G_VARIANT_TYPE_ARRAY) is
+ * an indefinite type that is a supertype of every array type.
+ * "<literal>(*s)</literal>" is a supertype of all tuples that
+ * contain exactly two items where the second item is a string.
+ * </para>
+ * <para>
+ * "<literal>a{?*}</literal>" is an indefinite type that is a
+ * supertype of all arrays containing dictionary entries where the key
+ * is any basic type and the value is any type at all. This is, by
+ * definition, a dictionary, so this type string corresponds to
+ * %G_VARIANT_TYPE_DICTIONARY. Note that, due to the restriction that
+ * the key of a dictionary entry must be a basic type,
+ * "<literal>{**}</literal>" is not a valid type string.
+ * </para>
* </refsect2>
*/
@@ -11670,31 +11655,31 @@
* <programlisting>
* GHashTable *
* set_new (GHashFunc hash_func,
- * GEqualFunc equal_func,
- * GDestroyNotify destroy)
+ * GEqualFunc equal_func,
+ * GDestroyNotify destroy)
* {
- * return g_hash_table_new_full (hash_func, equal_func, destroy, NULL);
+ * return g_hash_table_new_full (hash_func, equal_func, destroy, NULL);
* }
*
* void
* set_add (GHashTable *set,
- * gpointer element)
+ * gpointer element)
* {
- * g_hash_table_replace (set, element, element);
+ * g_hash_table_replace (set, element, element);
* }
*
* gboolean
* set_contains (GHashTable *set,
- * gpointer element)
+ * gpointer element)
* {
- * return g_hash_table_lookup_extended (set, element, NULL, NULL);
+ * return g_hash_table_lookup_extended (set, element, NULL, NULL);
* }
*
* gboolean
* set_remove (GHashTable *set,
- * gpointer element)
+ * gpointer element)
* {
- * return g_hash_table_remove (set, element);
+ * return g_hash_table_remove (set, element);
* }
* </programlisting>
* </example>
@@ -11871,19 +11856,19 @@
* This syntax is obviously inspired by the .ini files commonly met
* on Windows, but there are some important differences:
* <itemizedlist>
- * <listitem>.ini files use the ';' character to begin comments,
- * key files use the '#' character.</listitem>
- * <listitem>Key files do not allow for ungrouped keys meaning only
- * comments can precede the first group.</listitem>
- * <listitem>Key files are always encoded in UTF-8.</listitem>
- * <listitem>Key and Group names are case-sensitive. For example, a
- * group called <literal>[GROUP]</literal> is a different from
- * <literal>[group]</literal>.</listitem>
- * <listitem>.ini files don't have a strongly typed boolean entry type,
- * they only have GetProfileInt(). In key files, only
- * <literal>true</literal> and <literal>false</literal> (in lower case)
- * are allowed.</listitem>
- * </itemizedlist>
+ * <listitem>.ini files use the ';' character to begin comments,
+ * key files use the '#' character.</listitem>
+ * <listitem>Key files do not allow for ungrouped keys meaning only
+ * comments can precede the first group.</listitem>
+ * <listitem>Key files are always encoded in UTF-8.</listitem>
+ * <listitem>Key and Group names are case-sensitive. For example, a
+ * group called <literal>[GROUP]</literal> is a different from
+ * <literal>[group]</literal>.</listitem>
+ * <listitem>.ini files don't have a strongly typed boolean entry type,
+ * they only have GetProfileInt(). In key files, only
+ * <literal>true</literal> and <literal>false</literal> (in lower case)
+ * are allowed.</listitem>
+ * </itemizedlist>
*
* Note that in contrast to the
* <ulink url="http://freedesktop.org/Standards/desktop-entry-spec";>Desktop
@@ -12130,7 +12115,7 @@
* <listitem>Elements</listitem>
* <listitem>Attributes</listitem>
* <listitem>5 standard entities:
- * <literal>&amp; &lt; &gt; &quot; &apos;</literal>
+ * <literal>&amp; &lt; &gt; &quot; &apos;</literal>
* </listitem>
* <listitem>Character references</listitem>
* <listitem>Sections marked as CDATA</listitem>
@@ -12204,19 +12189,19 @@
*
* /* Allocate 10000 blocks. */
* for (i = 0; i < 10000; i++)
- * {
- * mem[i] = g_slice_alloc (50);
+ * {
+ * mem[i] = g_slice_alloc (50);
*
- * /* Fill in the memory with some junk. */
- * for (j = 0; j < 50; j++)
- * mem[i][j] = i * j;
- * }
+ * /* Fill in the memory with some junk. */
+ * for (j = 0; j < 50; j++)
+ * mem[i][j] = i * j;
+ * }
*
* /* Now free all of the blocks. */
* for (i = 0; i < 10000; i++)
- * {
- * g_slice_free1 (50, mem[i]);
- * }
+ * {
+ * g_slice_free1 (50, mem[i]);
+ * }
* </programlisting></example>
*
* <example>
@@ -12226,6 +12211,7 @@
*
* /* 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. */
* array->data = NULL;
* array->len = 0;
@@ -12294,22 +12280,22 @@
* The example demonstrates a number of features of the GOption
* commandline parser
* <itemizedlist><listitem><para>
- * Options can be single letters, prefixed by a single dash. Multiple
- * short options can be grouped behind a single dash.
+ * Options can be single letters, prefixed by a single dash. Multiple
+ * short options can be grouped behind a single dash.
* </para></listitem><listitem><para>
- * Long options are prefixed by two consecutive dashes.
+ * Long options are prefixed by two consecutive dashes.
* </para></listitem><listitem><para>
- * Options can have an extra argument, which can be a number, a string or
- * a filename. For long options, the extra argument can be appended with
- * an equals sign after the option name, which is useful if the extra
- * argument starts with a dash, which would otherwise cause it to be
- * interpreted as another option.
+ * Options can have an extra argument, which can be a number, a string or
+ * a filename. For long options, the extra argument can be appended with
+ * an equals sign after the option name, which is useful if the extra
+ * argument starts with a dash, which would otherwise cause it to be
+ * interpreted as another option.
* </para></listitem><listitem><para>
- * Non-option arguments are returned to the application as rest arguments.
+ * Non-option arguments are returned to the application as rest arguments.
* </para></listitem><listitem><para>
- * An argument consisting solely of two dashes turns off further parsing,
- * any remaining arguments (even those starting with a dash) are returned
- * to the application as rest arguments.
+ * An argument consisting solely of two dashes turns off further parsing,
+ * any remaining arguments (even those starting with a dash) are returned
+ * to the application as rest arguments.
* </para></listitem></itemizedlist>
*
* Another important feature of GOption is that it can automatically
@@ -12324,20 +12310,20 @@
*
* <informalexample><screen>
* Usage:
- * testtreemodel [OPTION...] - test tree model performance
+ * testtreemodel [OPTION...] - test tree model performance
*
* Help Options:
- * -h, --help Show help options
- * --help-all Show all help options
- * --help-gtk Show GTK+ Options
+ * -h, --help Show help options
+ * --help-all Show all help options
+ * --help-gtk Show GTK+ Options
*
* Application Options:
- * -r, --repeats=N Average over N repetitions
- * -m, --max-size=M Test up to 2^M items
- * --display=DISPLAY X display to use
- * -v, --verbose Be verbose
- * -b, --beep Beep when done
- * --rand Randomize the data
+ * -r, --repeats=N Average over N repetitions
+ * -m, --max-size=M Test up to 2^M items
+ * --display=DISPLAY X display to use
+ * -v, --verbose Be verbose
+ * -b, --beep Beep when done
+ * --rand Randomize the data
* </screen></informalexample>
*
* GOption groups options in #GOptionGroup<!-- -->s, which makes it easy to
@@ -12364,30 +12350,30 @@
*
* static GOptionEntry entries[] =
* {
- * { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
- * { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
- * { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
- * { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
- * { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Randomize the data", NULL },
- * { NULL }
+ * { "repeats", 'r', 0, G_OPTION_ARG_INT, &repeats, "Average over N repetitions", "N" },
+ * { "max-size", 'm', 0, G_OPTION_ARG_INT, &max_size, "Test up to 2^M items", "M" },
+ * { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
+ * { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
+ * { "rand", 0, 0, G_OPTION_ARG_NONE, &rand, "Randomize the data", NULL },
+ * { NULL }
* };
*
* int
* main (int argc, char *argv[])
* {
- * GError *error = NULL;
- * GOptionContext *context;
+ * GError *error = NULL;
+ * GOptionContext *context;
*
- * context = g_option_context_new ("- test tree model performance");
- * g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
- * g_option_context_add_group (context, gtk_get_option_group (TRUE));
- * if (!g_option_context_parse (context, &argc, &argv, &error))
- * {
- * g_print ("option parsing failed: %s\n", error->message);
- * exit (1);
- * }
+ * context = g_option_context_new ("- test tree model performance");
+ * g_option_context_add_main_entries (context, entries, GETTEXT_PACKAGE);
+ * g_option_context_add_group (context, gtk_get_option_group (TRUE));
+ * if (!g_option_context_parse (context, &argc, &argv, &error))
+ * {
+ * g_print ("option parsing failed: %s\n", error->message);
+ * exit (1);
+ * }
*
- * /* ... */
+ * /* ... */
*
* }
* </programlisting></informalexample>
@@ -12681,30 +12667,30 @@
* RUnit), which in turn is based on smalltalk unit testing concepts.
*
* <variablelist>
- * <varlistentry>
- * <term>Test case</term>
- * <listitem>Tests (test methods) are grouped together with their
- * fixture into test cases.</listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>Fixture</term>
- * <listitem>A test fixture consists of fixture data and setup and
- * teardown methods to establish the environment for the test
- * functions. We use fresh fixtures, i.e. fixtures are newly set
- * up and torn down around each test invocation to avoid dependencies
- * between tests.</listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>Test suite</term>
- * <listitem>Test cases can be grouped into test suites, to allow
- * subsets of the available tests to be run. Test suites can be
- * grouped into other test suites as well.</listitem>
- * </varlistentry>
+ * <varlistentry>
+ * <term>Test case</term>
+ * <listitem>Tests (test methods) are grouped together with their
+ * fixture into test cases.</listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>Fixture</term>
+ * <listitem>A test fixture consists of fixture data and setup and
+ * teardown methods to establish the environment for the test
+ * functions. We use fresh fixtures, i.e. fixtures are newly set
+ * up and torn down around each test invocation to avoid dependencies
+ * between tests.</listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>Test suite</term>
+ * <listitem>Test cases can be grouped into test suites, to allow
+ * subsets of the available tests to be run. Test suites can be
+ * grouped into other test suites as well.</listitem>
+ * </varlistentry>
* </variablelist>
* The API is designed to handle creation and registration of test suites
* and test cases implicitly. A simple call like
* |[
- * g_test_add_func ("/misc/assertions", test_assertions);
+ * g_test_add_func ("/misc/assertions", test_assertions);
* ]|
* creates a test suite called "misc" with a single test case named
* "assertions", which consists of running the test_assertions function.
@@ -12801,42 +12787,42 @@
* UNIX APIs are problematic in threaded programs. Some notable examples
* are
* <itemizedlist>
- * <listitem>
- * C library functions that return data in statically allocated
- * buffers, such as strtok() or strerror(). For many of these,
- * there are thread-safe variants with a _r suffix, or you can
- * look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
- * </listitem>
- * <listitem>
- * setenv() and unsetenv() manipulate the process environment in
- * a not thread-safe way, and may interfere with getenv() calls
- * in other threads. Note that getenv() calls may be
- * <quote>hidden</quote> behind other APIs. For example, GNU gettext()
- * calls getenv() under the covers. In general, it is best to treat
- * the environment as readonly. If you absolutely have to modify the
- * environment, do it early in main(), when no other threads are around yet.
- * </listitem>
- * <listitem>
- * setlocale() changes the locale for the entire process, affecting
- * all threads. Temporary changes to the locale are often made to
- * change the behavior of string scanning or formatting functions
- * like scanf() or printf(). GLib offers a number of string APIs
- * (like g_ascii_formatd() or g_ascii_strtod()) that can often be
- * used as an alternative. Or you can use the uselocale() function
- * to change the locale only for the current thread.
- * </listitem>
- * <listitem>
- * fork() only takes the calling thread into the child's copy of the
- * process image. If other threads were executing in critical
- * sections they could have left mutexes locked which could easily
- * cause deadlocks in the new child. For this reason, you should
- * call exit() or exec() as soon as possible in the child and only
- * make signal-safe library calls before that.
- * </listitem>
- * <listitem>
- * daemon() uses fork() in a way contrary to what is described
- * above. It should not be used with GLib programs.
- * </listitem>
+ * <listitem>
+ * C library functions that return data in statically allocated
+ * buffers, such as strtok() or strerror(). For many of these,
+ * there are thread-safe variants with a _r suffix, or you can
+ * look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
+ * </listitem>
+ * <listitem>
+ * setenv() and unsetenv() manipulate the process environment in
+ * a not thread-safe way, and may interfere with getenv() calls
+ * in other threads. Note that getenv() calls may be
+ * <quote>hidden</quote> behind other APIs. For example, GNU gettext()
+ * calls getenv() under the covers. In general, it is best to treat
+ * the environment as readonly. If you absolutely have to modify the
+ * environment, do it early in main(), when no other threads are around yet.
+ * </listitem>
+ * <listitem>
+ * setlocale() changes the locale for the entire process, affecting
+ * all threads. Temporary changes to the locale are often made to
+ * change the behavior of string scanning or formatting functions
+ * like scanf() or printf(). GLib offers a number of string APIs
+ * (like g_ascii_formatd() or g_ascii_strtod()) that can often be
+ * used as an alternative. Or you can use the uselocale() function
+ * to change the locale only for the current thread.
+ * </listitem>
+ * <listitem>
+ * fork() only takes the calling thread into the child's copy of the
+ * process image. If other threads were executing in critical
+ * sections they could have left mutexes locked which could easily
+ * cause deadlocks in the new child. For this reason, you should
+ * call exit() or exec() as soon as possible in the child and only
+ * make signal-safe library calls before that.
+ * </listitem>
+ * <listitem>
+ * daemon() uses fork() in a way contrary to what is described
+ * above. It should not be used with GLib programs.
+ * </listitem>
* </itemizedlist>
*
* GLib itself is internally completely thread-safe (all global data is
@@ -12983,8 +12969,8 @@
* you want to pass an integer instead of a pointer. You could allocate
* an integer, with something like:
* |[
- * int *ip = g_new (int, 1);
- * *ip = 42;
+ * int *ip = g_new (int, 1);
+ * *ip = 42;
* ]|
* But this is inconvenient, and it's annoying to have to free the
* memory at some later time.
@@ -12993,18 +12979,18 @@
* intends to support). Thus you can store at least 32-bit integer values
* in a pointer value. Naively, you might try this, but it's incorrect:
* |[
- * gpointer p;
- * int i;
- * p = (void*) 42;
- * i = (int) p;
+ * gpointer p;
+ * int i;
+ * p = (void*) 42;
+ * i = (int) p;
* ]|
* Again, that example was <emphasis>not</emphasis> correct, don't copy it.
* The problem is that on some systems you need to do this:
* |[
- * gpointer p;
- * int i;
- * p = (void*) (long) 42;
- * i = (int) (long) p;
+ * gpointer p;
+ * int i;
+ * p = (void*) (long) 42;
+ * i = (int) (long) p;
* ]|
* The GLib macros GPOINTER_TO_INT(), GINT_TO_POINTER(), etc. take care
* to do the right thing on the every platform.
@@ -13025,16 +13011,16 @@
* GLib defines a number of commonly used types, which can be divided
* into 4 groups:
* - New types which are not part of standard C (but are defined in
- * various C standard library header files) - #gboolean, #gsize,
- * #gssize, #goffset, #gintptr, #guintptr.
+ * various C standard library header files) - #gboolean, #gsize,
+ * #gssize, #goffset, #gintptr, #guintptr.
* - Integer types which are guaranteed to be the same size across
- * all platforms - #gint8, #guint8, #gint16, #guint16, #gint32,
- * #guint32, #gint64, #guint64.
+ * all platforms - #gint8, #guint8, #gint16, #guint16, #gint32,
+ * #guint32, #gint64, #guint64.
* - Types which are easier to use than their standard C counterparts -
- * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
+ * #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
* - Types which correspond exactly to standard C types, but are
- * included for completeness - #gchar, #gint, #gshort, #glong,
- * #gfloat, #gdouble.
+ * included for completeness - #gchar, #gint, #gshort, #glong,
+ * #gfloat, #gdouble.
*
* GLib also defines macros for the limits of some of the standard
* integer and floating point types, as well as macros for suitable
@@ -13164,10 +13150,7 @@
*
* See your C library manual for more details about access().
*
- * object that has all the tested permissions, or -1 otherwise or on
- * error.
- *
- * Returns: zero if the pathname refers to an existing file system
+ * Returns: zero if the pathname refers to an existing file system object that has all the tested permissions, or -1 otherwise or on error.
* Since: 2.8
*/
@@ -13181,31 +13164,31 @@
* function present on most UNIX variants.
* Thus it provides the same advantages and pitfalls as alloca():
* <variablelist>
- * <varlistentry><term></term><listitem><para>
- * + alloca() is very fast, as on most systems it's implemented by just adjusting
- * the stack pointer register.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
- * blocks just build up and are released together at function end.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation sizes have to fit into the current stack frame. For instance in a
- * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
- * so be sparse with alloca() uses.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation failure due to insufficient stack space is not indicated with a %NULL
- * return like e.g. with malloc(). Instead, most systems probably handle it the same
- * way as out of stack space situations from infinite function recursion, i.e.
- * with a segmentation fault.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
- * Stack space allocated with alloca() in the same scope as a variable sized array
- * will be freed together with the variable sized array upon exit of that scope, and
- * not upon exit of the enclosing function scope.
- * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * + alloca() is very fast, as on most systems it's implemented by just adjusting
+ * the stack pointer register.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
+ * blocks just build up and are released together at function end.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation sizes have to fit into the current stack frame. For instance in a
+ * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
+ * so be sparse with alloca() uses.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation failure due to insufficient stack space is not indicated with a %NULL
+ * return like e.g. with malloc(). Instead, most systems probably handle it the same
+ * way as out of stack space situations from infinite function recursion, i.e.
+ * with a segmentation fault.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
+ * Stack space allocated with alloca() in the same scope as a variable sized array
+ * will be freed together with the variable sized array upon exit of that scope, and
+ * not upon exit of the enclosing function scope.
+ * </para></listitem></varlistentry>
* </variablelist>
*
* Returns: space for @size bytes, allocated on the stack
@@ -13216,7 +13199,6 @@
* g_array_append_val:
* @a: a #GArray.
* @v: the value to append to the #GArray.
- * @Returns: the #GArray.
*
* Adds the value on to the end of the array. The array will grow in
* size automatically if necessary.
@@ -13224,6 +13206,8 @@
* <note><para>g_array_append_val() is a macro which uses a reference
* to the value parameter @v. This means that you cannot use it with
* literal values such as "27". You must use variables.</para></note>
+ *
+ * Returns: the #GArray.
*/
@@ -13232,9 +13216,10 @@
* @array: a #GArray.
* @data: a pointer to the elements to append to the end of the array.
* @len: the number of elements to append.
- * @Returns: the #GArray.
*
* Adds @len elements onto the end of the array.
+ *
+ * Returns: the #GArray.
*/
@@ -13242,7 +13227,6 @@
* g_array_free:
* @array: a #GArray.
* @free_segment: if %TRUE the actual element data is freed as well.
- * @Returns: the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free().
*
* Frees the memory allocated for the #GArray. If @free_segment is
* %TRUE it frees the memory block holding the elements as well and
@@ -13254,6 +13238,8 @@
*
* <note><para>If array elements contain dynamically-allocated memory,
* they should be freed separately.</para></note>
+ *
+ * Returns: the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free().
*/
@@ -13273,20 +13259,21 @@
* @a: a #GArray.
* @t: the type of the elements.
* @i: the index of the element to return.
- * @Returns: the element of the #GArray at the index given by @i.
*
* Returns the element of a #GArray at the given index. The return
* value is cast to the given type.
*
* <example>
- * <title>Getting a pointer to an element in a #GArray</title>
- * <programlisting>
- * EDayViewEvent *event;
- * /<!-- -->* This gets a pointer to the 4th element
- * in the array of EDayViewEvent structs. *<!-- -->/
- * event = &g_array_index (events, EDayViewEvent, 3);
- * </programlisting>
+ * <title>Getting a pointer to an element in a #GArray</title>
+ * <programlisting>
+ * EDayViewEvent *event;
+ * /<!-- -->* This gets a pointer to the 4th element
+ * in the array of EDayViewEvent structs. *<!-- -->/
+ * event = &g_array_index (events, EDayViewEvent, 3);
+ * </programlisting>
* </example>
+ *
+ * Returns: the element of the #GArray at the index given by @i.
*/
@@ -13295,13 +13282,14 @@
* @a: a #GArray.
* @i: the index to place the element at.
* @v: the value to insert into the array.
- * @Returns: the #GArray.
*
* Inserts an element into an array at the given index.
*
* <note><para>g_array_insert_val() is a macro which uses a reference
* to the value parameter @v. This means that you cannot use it with
* literal values such as "27". You must use variables.</para></note>
+ *
+ * Returns: the #GArray.
*/
@@ -13311,9 +13299,10 @@
* @index_: the index to place the elements at.
* @data: a pointer to the elements to insert.
* @len: the number of elements to insert.
- * @Returns: the #GArray.
*
* Inserts @len elements into a #GArray at the given index.
+ *
+ * Returns: the #GArray.
*/
@@ -13322,9 +13311,10 @@
* @zero_terminated: %TRUE if the array should have an extra element at the end which is set to 0.
* @clear_: %TRUE if #GArray elements should be automatically cleared to 0 when they are allocated.
* @element_size: the size of each element in bytes.
- * @Returns: the new #GArray.
*
* Creates a new #GArray with a reference count of 1.
+ *
+ * Returns: the new #GArray.
*/
@@ -13332,7 +13322,6 @@
* g_array_prepend_val:
* @a: a #GArray.
* @v: the value to prepend to the #GArray.
- * @Returns: the #GArray.
*
* Adds the value on to the start of the array. The array will grow in
* size automatically if necessary.
@@ -13344,6 +13333,8 @@
* <note><para>g_array_prepend_val() is a macro which uses a reference
* to the value parameter @v. This means that you cannot use it with
* literal values such as "27". You must use variables.</para></note>
+ *
+ * Returns: the #GArray.
*/
@@ -13352,13 +13343,14 @@
* @array: a #GArray.
* @data: a pointer to the elements to prepend to the start of the array.
* @len: the number of elements to prepend.
- * @Returns: the #GArray.
*
* Adds @len elements onto the start of the array.
*
* This operation is slower than g_array_append_vals() since the
* existing elements in the array have to be moved to make space for
* the new elements.
+ *
+ * Returns: the #GArray.
*/
@@ -13378,10 +13370,11 @@
* g_array_remove_index:
* @array: a #GArray.
* @index_: the index of the element to remove.
- * @Returns: the #GArray.
*
* Removes the element at the given index from a #GArray. The following
* elements are moved down one place.
+ *
+ * Returns: the #GArray.
*/
@@ -13389,12 +13382,13 @@
* g_array_remove_index_fast:
* @array: a @GArray.
* @index_: the index of the element to remove.
- * @Returns: the #GArray.
*
* Removes the element at the given index from a #GArray. The last
* element in the array is used to fill in the space, so this function
* does not preserve the order of the #GArray. But it is faster than
* g_array_remove_index().
+ *
+ * Returns: the #GArray.
*/
@@ -13403,11 +13397,11 @@
* @array: a @GArray.
* @index_: the index of the first element to remove.
* @length: the number of elements to remove.
- * @Returns: the #GArray.
*
* Removes the given number of elements starting at the given index
* from a #GArray. The following elements are moved to close the gap.
*
+ * Returns: the #GArray.
* Since: 2.4
*/
@@ -13435,10 +13429,11 @@
* g_array_set_size:
* @array: a #GArray.
* @length: the new size of the #GArray.
- * @Returns: the #GArray.
*
* Sets the size of the array, expanding it if necessary. If the array
* was created with @clear_ set to %TRUE, the new elements are set to 0.
+ *
+ * Returns: the #GArray.
*/
@@ -13448,12 +13443,13 @@
* @clear_: %TRUE if all bits in the array should be cleared to 0 on allocation.
* @element_size: size of each element in the array.
* @reserved_size: number of elements preallocated.
- * @Returns: the new #GArray.
*
* Creates a new #GArray with @reserved_size elements preallocated and
* a reference count of 1. This avoids frequent reallocation, if you
* are going to add many elements to the array. Note however that the
* size of the array is still 0.
+ *
+ * Returns: the new #GArray.
*/
@@ -13510,9 +13506,7 @@
* a char, so there's no worry about sign extension if characters
* are signed.
*
- * g_ascii_isdigit()), its numeric value. Otherwise, -1.
- *
- * Returns: If @c is a decimal digit (according to
+ * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), its numeric value. Otherwise, -1.
*/
@@ -13758,9 +13752,7 @@
* characters include all ASCII letters. If you compare two CP932
* strings using this function, you will get false matches.
*
- * or a positive value if @s1 > @s2.
- *
- * Returns: 0 if the strings match, a negative value if @s1 < @s2,
+ * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2.
*/
@@ -13771,12 +13763,7 @@
*
* Converts all upper case ASCII letters to lower case ASCII letters.
*
- * characters in @str converted to lower case, with
- * semantics that exactly match g_ascii_tolower(). (Note
- * that this is unlike the old g_strdown(), which modified
- * the string in place.)
- *
- * Returns: a newly-allocated string, with all the upper case
+ * Returns: a newly-allocated string, with all the upper case characters in @str converted to lower case, with semantics that exactly match g_ascii_tolower(). (Note that this is unlike the old g_strdown(), which modified the string in place.)
*/
@@ -13797,9 +13784,7 @@
* function only on strings known to be in encodings where bytes
* corresponding to ASCII letters always represent themselves.
*
- * or a positive value if @s1 > @s2.
- *
- * Returns: 0 if the strings match, a negative value if @s1 < @s2,
+ * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2.
*/
@@ -13901,12 +13886,7 @@
*
* Converts all lower case ASCII letters to upper case ASCII letters.
*
- * characters in @str converted to upper case, with
- * semantics that exactly match g_ascii_toupper(). (Note
- * that this is unlike the old g_strup(), which modified
- * the string in place.)
- *
- * Returns: a newly allocated string, with all the lower case
+ * Returns: a newly allocated string, with all the lower case characters in @str converted to upper case, with semantics that exactly match g_ascii_toupper(). (Note that this is unlike the old g_strup(), which modified the string in place.)
*/
@@ -13924,10 +13904,7 @@
* don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
*
- * If @c is not an ASCII upper case letter,
- * @c is returned unchanged.
- *
- * Returns: the result of converting @c to lower case.
+ * Returns: the result of converting @c to lower case. If @c is not an ASCII upper case letter, @c is returned unchanged.
*/
@@ -13945,10 +13922,7 @@
* don't call it on <literal>EOF</literal> but no need to worry about casting to #guchar
* before passing a possibly non-ASCII character in.
*
- * If @c is not an ASCII lower case letter,
- * @c is returned unchanged.
- *
- * Returns: the result of converting @c to upper case.
+ * Returns: the result of converting @c to upper case. If @c is not an ASCII lower case letter, @c is returned unchanged.
*/
@@ -13961,9 +13935,7 @@
* a char, so there's no worry about sign extension if characters
* are signed.
*
- * g_ascii_isxdigit()), its numeric value. Otherwise, -1.
- *
- * Returns: If @c is a hex digit (according to
+ * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), its numeric value. Otherwise, -1.
*/
@@ -14048,7 +14020,7 @@
* includes the actual values of @s1 and @s2.
*
* |[
- * g_assert_cmpstr (mystring, ==, "fubar");
+ * g_assert_cmpstr (mystring, ==, "fubar");
* ]|
*
* Since: 2.16
@@ -14305,12 +14277,10 @@
/**
* g_async_queue_ref_unlocked:
* @queue: a #GAsyncQueue
- * @Deprecated: Since 2.8, reference counting is done atomically
*
* Increases the reference count of the asynchronous @queue by 1.
*
- * so g_async_queue_ref() can be used regardless of the @queue's
- * lock.
+ * Deprecated: 2.8: Reference counting is done atomically. so g_async_queue_ref() can be used regardless of the @queue's lock.
*/
@@ -14334,13 +14304,13 @@
* If you were sorting a list of priority numbers to make sure the
* lowest priority would be at the top of the queue, you could use:
* |[
- * gint32 id1;
- * gint32 id2;
+ * gint32 id1;
+ * gint32 id2;
*
- * id1 = GPOINTER_TO_INT (element1);
- * id2 = GPOINTER_TO_INT (element2);
+ * id1 = GPOINTER_TO_INT (element1);
+ * id2 = GPOINTER_TO_INT (element2);
*
- * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
+ * return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
* ]|
*
* Since: 2.10
@@ -14380,9 +14350,7 @@
* To easily calculate @end_time, a combination of g_get_current_time()
* and g_time_val_add() can be used.
*
- * received before @end_time.
- *
- * Returns: data from the queue or %NULL, when no data is
+ * Returns: data from the queue or %NULL, when no data is received before @end_time.
* Deprecated: use g_async_queue_timeout_pop().
*/
@@ -14402,9 +14370,7 @@
*
* This function must be called while holding the @queue's lock.
*
- * received before @end_time.
- *
- * Returns: data from the queue or %NULL, when no data is
+ * Returns: data from the queue or %NULL, when no data is received before @end_time.
* Deprecated: use g_async_queue_timeout_pop_unlocked().
*/
@@ -14419,9 +14385,7 @@
*
* If no data is received before the timeout, %NULL is returned.
*
- * received before the timeout.
- *
- * Returns: data from the queue or %NULL, when no data is
+ * Returns: data from the queue or %NULL, when no data is received before the timeout.
*/
@@ -14437,9 +14401,7 @@
*
* This function must be called while holding the @queue's lock.
*
- * received before the timeout.
- *
- * Returns: data from the queue or %NULL, when no data is
+ * Returns: data from the queue or %NULL, when no data is received before the timeout.
*/
@@ -14450,9 +14412,7 @@
* Tries to pop data from the @queue. If no data is available,
* %NULL is returned.
*
- * available immediately.
- *
- * Returns: data from the queue or %NULL, when no data is
+ * Returns: data from the queue or %NULL, when no data is available immediately.
*/
@@ -14465,9 +14425,7 @@
*
* This function must be called while holding the @queue's lock.
*
- * available immediately.
- *
- * Returns: data from the queue or %NULL, when no data is
+ * Returns: data from the queue or %NULL, when no data is available immediately.
*/
@@ -14499,15 +14457,13 @@
/**
* g_async_queue_unref_and_unlock:
* @queue: a #GAsyncQueue
- * @Deprecated: Since 2.8, reference counting is done atomically
*
* Decreases the reference count of the asynchronous @queue by 1
* and releases the lock. This function must be called while holding
* the @queue's lock. If the reference count went to 0, the @queue
* will be destroyed and the memory allocated will be freed.
*
- * so g_async_queue_unref() can be used regardless of the @queue's
- * lock.
+ * Deprecated: 2.8: Reference counting is done atomically. so g_async_queue_unref() can be used regardless of the @queue's lock.
*/
@@ -14546,7 +14502,7 @@
* calling g_atexit() (or atexit()) except in the main executable of a
* program.
*
- * Deprecated:2.32: It is best to avoid g_atexit().
+ * Deprecated: 2.32: It is best to avoid g_atexit().
*/
@@ -14846,11 +14802,7 @@
*
* Decode a sequence of Base-64 encoded text into binary data
*
- * newly allocated buffer containing the binary data
- * that @text represents. The returned buffer must
- * be freed with g_free().
- *
- * Returns: (transfer full) (array length=out_len) (element-type guint8):
+ * Returns: (transfer full) (array length=out_len) (element-type guint8): newly allocated buffer containing the binary data that @text represents. The returned buffer must be freed with g_free().
* Since: 2.12
*/
@@ -14863,9 +14815,7 @@
* Decode a sequence of Base-64 encoded text into binary data
* by overwriting the input data.
*
- * is the same as the input @text.
- *
- * Returns: (transfer none): The binary data that @text responds. This pointer
+ * Returns: (transfer none): The binary data that @text responds. This pointer is the same as the input @text.
* Since: 2.20
*/
@@ -14900,10 +14850,7 @@
* Encode a sequence of binary data into its Base-64 stringified
* representation.
*
- * encoded string representing @data. The returned string must
- * be freed with g_free().
- *
- * Returns: (transfer full): a newly allocated, zero-terminated Base-64
+ * Returns: (transfer full): a newly allocated, zero-terminated Base-64 encoded string representing @data. The returned string must be freed with g_free().
* Since: 2.12
*/
@@ -14968,14 +14915,8 @@
* components. It returns a pointer into the given file name
* string.
*
- * directory components
- *
- * Deprecated:2.2: Use g_path_get_basename() instead, but notice
- * that g_path_get_basename() allocates new memory for the
- * returned string, unlike this function which returns a pointer
- * into the argument.
- *
- * Returns: the name of the file without any leading
+ * Returns: the name of the file without any leading directory components
+ * Deprecated: 2.2: Use g_path_get_basename() instead, but notice that g_path_get_basename() allocates new memory for the returned string, unlike this function which returns a pointer into the argument.
*/
@@ -15199,9 +15140,7 @@
* In the event the URI cannot be found, %NULL is returned and
* @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
- * Use g_strfreev() to free it.
- *
- * Returns: a newly allocated %NULL-terminated array of strings.
+ * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
* Since: 2.12
*/
@@ -15217,9 +15156,7 @@
* In the event the URI cannot be found, %NULL is returned and
* @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
- * URI cannot be found.
- *
- * Returns: a newly allocated string or %NULL if the specified
+ * Returns: a newly allocated string or %NULL if the specified URI cannot be found.
* Since: 2.12
*/
@@ -15239,9 +15176,7 @@
* The returned array is %NULL terminated, so @length may optionally
* be %NULL.
*
- * Use g_strfreev() to free it.
- *
- * Returns: a newly allocated %NULL-terminated array of group names.
+ * Returns: a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it.
* Since: 2.12
*/
@@ -15259,9 +15194,7 @@
* In the event the URI cannot be found, %FALSE is returned and
* @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
- * You should free the returned strings.
- *
- * Returns: %TRUE if the icon for the bookmark for the URI was found.
+ * Returns: %TRUE if the icon for the bookmark for the URI was found. You should free the returned strings.
* Since: 2.12
*/
@@ -15297,9 +15230,7 @@
* event that the MIME type cannot be found, %NULL is returned and
* @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE.
*
- * URI cannot be found.
- *
- * Returns: a newly allocated string or %NULL if the specified
+ * Returns: a newly allocated string or %NULL if the specified URI cannot be found.
* Since: 2.12
*/
@@ -15344,9 +15275,7 @@
* In the event the URI cannot be found, %NULL is returned and
* @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND.
*
- * URI cannot be found.
- *
- * Returns: a newly allocated string or %NULL if the specified
+ * Returns: a newly allocated string or %NULL if the specified URI cannot be found.
* Since: 2.12
*/
@@ -15360,9 +15289,7 @@
* The array of returned URIs will be %NULL-terminated, so @length may
* optionally be %NULL.
*
- * Use g_strfreev() to free it.
- *
- * Returns: a newly allocated %NULL-terminated array of strings.
+ * Returns: a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
* Since: 2.12
*/
@@ -15590,7 +15517,6 @@
* @count: the number of registrations done for this application
* @stamp: the time of the last registration for this application
* @error: return location for a #GError or %NULL
- * @exec can have one of these two modifiers: "\%f", which will
*
* Sets the meta-data of application @name inside the list of
* applications that have registered a bookmark for @uri inside
@@ -15601,6 +15527,7 @@
*
* @name can be any UTF-8 encoded string used to identify an
* application.
+ * @exec can have one of these two modifiers: "\%f", which will
* be expanded as the local file name retrieved from the bookmark's
* URI; "\%u", which will be expanded as the bookmark's URI.
* The expansion is done automatically when retrieving the stored
@@ -15620,9 +15547,7 @@
* #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark
* for @uri is found, one is created.
*
- * changed.
- *
- * Returns: %TRUE if the application's meta-data was successfully
+ * Returns: %TRUE if the application's meta-data was successfully changed.
* Since: 2.12
*/
@@ -15768,9 +15693,7 @@
*
* This function outputs @bookmark as a string.
*
- * the contents of the #GBookmarkFile
- *
- * Returns: a newly allocated string holding
+ * Returns: a newly allocated string holding the contents of the #GBookmarkFile
* Since: 2.12
*/
@@ -15885,10 +15808,11 @@
* @array: a #GByteArray.
* @data: the byte data to be added.
* @len: the number of bytes to add.
- * @Returns: the #GByteArray.
*
* Adds the given bytes to the end of the #GByteArray. The array will
* grow in size automatically if necessary.
+ *
+ * Returns: the #GByteArray.
*/
@@ -15896,12 +15820,13 @@
* g_byte_array_free:
* @array: a #GByteArray.
* @free_segment: if %TRUE the actual byte data is freed as well.
- * @Returns: the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free().
*
* Frees the memory allocated by the #GByteArray. If @free_segment is
* %TRUE it frees the actual byte data. If the reference count of
* @array is greater than one, the #GByteArray wrapper is preserved but
* the size of @array will be set to zero.
+ *
+ * Returns: the element data if @free_segment is %FALSE, otherwise %NULL. The element data should be freed using g_free().
*/
@@ -15918,19 +15843,17 @@
* This is identical to using g_bytes_new_take() and g_byte_array_free()
* together.
*
- *
- * data that was in the array
- *
* Since: 2.32
- * Returns: (transfer full): a new immutable #GBytes representing same byte
+ * Returns: (transfer full): a new immutable #GBytes representing same byte data that was in the array
*/
/**
* g_byte_array_new:
- * @Returns: the new #GByteArray.
*
* Creates a new #GByteArray with a reference count of 1.
+ *
+ * Returns: the new #GByteArray.
*/
@@ -15952,10 +15875,11 @@
* @array: a #GByteArray.
* @data: the byte data to be added.
* @len: the number of bytes to add.
- * @Returns: the #GByteArray.
*
* Adds the given data to the start of the #GByteArray. The array will
* grow in size automatically if necessary.
+ *
+ * Returns: the #GByteArray.
*/
@@ -15975,10 +15899,11 @@
* g_byte_array_remove_index:
* @array: a #GByteArray.
* @index_: the index of the byte to remove.
- * @Returns: the #GByteArray.
*
* Removes the byte at the given index from a #GByteArray. The
* following bytes are moved down one place.
+ *
+ * Returns: the #GByteArray.
*/
@@ -15986,12 +15911,13 @@
* g_byte_array_remove_index_fast:
* @array: a #GByteArray.
* @index_: the index of the byte to remove.
- * @Returns: the #GByteArray.
*
* Removes the byte at the given index from a #GByteArray. The last
* element in the array is used to fill in the space, so this function
* does not preserve the order of the #GByteArray. But it is faster
* than g_byte_array_remove_index().
+ *
+ * Returns: the #GByteArray.
*/
@@ -16000,11 +15926,11 @@
* @array: a @GByteArray.
* @index_: the index of the first byte to remove.
* @length: the number of bytes to remove.
- * @Returns: the #GByteArray.
*
* Removes the given number of bytes starting at the given index from a
* #GByteArray. The following elements are moved to close the gap.
*
+ * Returns: the #GByteArray.
* Since: 2.4
*/
@@ -16013,21 +15939,23 @@
* g_byte_array_set_size:
* @array: a #GByteArray.
* @length: the new size of the #GByteArray.
- * @Returns: the #GByteArray.
*
* Sets the size of the #GByteArray, expanding it if necessary.
+ *
+ * Returns: the #GByteArray.
*/
/**
* g_byte_array_sized_new:
* @reserved_size: number of bytes preallocated.
- * @Returns: the new #GByteArray.
*
* Creates a new #GByteArray with @reserved_size bytes preallocated.
* This avoids frequent reallocation, if you are going to add many
* bytes to the array. Note however that the size of the array is still
* 0.
+ *
+ * Returns: the new #GByteArray.
*/
@@ -16082,9 +16010,7 @@
*
* This function can be used to sort GBytes instances in lexographical order.
*
- * greater, and zero if bytes2 is equal to bytes1
- *
- * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
+ * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is greater, and zero if bytes2 is equal to bytes1
* Since: 2.32
*/
@@ -16181,10 +16107,11 @@
* g_bytes_new_static:
* @data: (array length=size): the data to be used for the bytes
* @size: the size of @data
- * @data must be static (ie: never modified or freed).
*
* Creates a new #GBytes from static data.
*
+ * @data must be static (ie: never modified or freed).
+ *
* Returns: (transfer full): a new #GBytes
* Since: 2.32
*/
@@ -16283,9 +16210,7 @@
* g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
* data is copied.
*
- * be freed with g_free()
- *
- * Returns: (transfer full): a pointer to the same byte data, which should
+ * Returns: (transfer full): a pointer to the same byte data, which should be freed with g_free()
* Since: 2.32
*/
@@ -16312,9 +16237,7 @@
* g_checksum_get_string() or g_checksum_get_digest(), the copied
* checksum will be closed as well.
*
- * when finished using it.
- *
- * Returns: the copy of the passed #GChecksum. Use g_checksum_free()
+ * Returns: the copy of the passed #GChecksum. Use g_checksum_free() when finished using it.
* Since: 2.16
*/
@@ -16356,10 +16279,7 @@
*
* The hexadecimal characters will be lower case.
*
- * returned string is owned by the checksum and should not be modified
- * or freed.
- *
- * Returns: the hexadecimal representation of the checksum. The
+ * Returns: the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed.
* Since: 2.16
*/
@@ -16382,9 +16302,7 @@
* will be closed and it won't be possible to call g_checksum_update()
* on it anymore.
*
- * Use g_checksum_free() to free the memory allocated by it.
- *
- * Returns: the newly created #GChecksum, or %NULL.
+ * Returns: the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it.
* Since: 2.16
*/
@@ -16405,9 +16323,7 @@
*
* Gets the length in bytes of digests of type @checksum_type
*
- * not supported.
- *
- * Returns: the checksum length, or -1 if @checksum_type is
+ * Returns: the checksum length, or -1 if @checksum_type is not supported.
* Since: 2.16
*/
@@ -16560,9 +16476,7 @@
*
* The hexadecimal string returned will be in lower case.
*
- * The returned string should be freed with g_free() when done using it.
- *
- * Returns: the digest of the binary data as a string in hexadecimal.
+ * Returns: the digest of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it.
* Since: 2.16
*/
@@ -16577,9 +16491,7 @@
*
* The hexadecimal string returned will be in lower case.
*
- * should be freed with g_free() when done using it.
- *
- * Returns: the checksum as a hexadecimal string. The returned string
+ * Returns: the checksum as a hexadecimal string. The returned string should be freed with g_free() when done using it.
* Since: 2.16
*/
@@ -16598,9 +16510,7 @@
*
* The hexadecimal string returned will be in lower case.
*
- * The returned string should be freed with g_free() when done using it.
- *
- * Returns: the HMAC of the binary data as a string in hexadecimal.
+ * Returns: the HMAC of the binary data as a string in hexadecimal. The returned string should be freed with g_free() when done using it.
* Since: 2.30
*/
@@ -16617,10 +16527,7 @@
*
* The hexadecimal string returned will be in lower case.
*
- * The returned string should be freed with g_free()
- * when done using it.
- *
- * Returns: the HMAC as a hexadecimal string.
+ * Returns: the HMAC as a hexadecimal string. The returned string should be freed with g_free() when done using it.
* Since: 2.30
*/
@@ -16727,27 +16634,27 @@
* gpointer
* pop_data_timed (void)
* {
- * gint64 end_time;
- * gpointer data;
+ * gint64 end_time;
+ * gpointer data;
*
- * g_mutex_lock (&data_mutex);
+ * g_mutex_lock (&data_mutex);
*
- * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
- * while (!current_data)
- * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
- * {
- * // timeout has passed.
- * g_mutex_unlock (&data_mutex);
- * return NULL;
- * }
+ * end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
+ * while (!current_data)
+ * if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
+ * {
+ * // timeout has passed.
+ * g_mutex_unlock (&data_mutex);
+ * return NULL;
+ * }
*
- * // there is data for us
- * data = current_data;
- * current_data = NULL;
+ * // there is data for us
+ * data = current_data;
+ * current_data = NULL;
*
- * g_mutex_unlock (&data_mutex);
+ * g_mutex_unlock (&data_mutex);
*
- * return data;
+ * return data;
* }
* ]|
*
@@ -16766,7 +16673,7 @@
/**
* g_convert:
* @str: the string to convert
- * @len: the length of the string, or -1 if the string is nul-terminated<footnote id="nul-unsafe">
+ * @len: the length of the string, or -1 if the string is nul-terminated<footnote id="nul-unsafe"> <para> Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe. </para> </footnote>.
* @to_codeset: name of character set into which to convert @str
* @from_codeset: character set of @str.
* @bytes_read: (out): location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence.
@@ -16778,10 +16685,7 @@
* Note that you should use g_iconv() for streaming
* conversions<footnoteref linkend="streaming-state"/>.
*
- * nul-terminated string, which must be freed with
- * g_free(). Otherwise %NULL and @error will be set.
- *
- * Returns: If the conversion was successful, a newly allocated
+ * Returns: If the conversion was successful, a newly allocated nul-terminated string, which must be freed with g_free(). Otherwise %NULL and @error will be set.
*/
@@ -16791,7 +16695,7 @@
* @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>.
* @to_codeset: name of character set into which to convert @str
* @from_codeset: character set of @str.
- * @fallback: UTF-8 string to use in place of character not present in the target encoding. (The string must be representable in the target encoding).
+ * @fallback: UTF-8 string to use in place of character not present in the target encoding. (The string must be representable in the target encoding). If %NULL, characters not in the target encoding will be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
* @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. Even if the conversion was successful, this may be less than @len if there were partial characters at the end of the input.
* @bytes_written: the number of bytes stored in the output buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur.
@@ -16807,10 +16711,7 @@
* Note that you should use g_iconv() for streaming
* conversions<footnoteref linkend="streaming-state"/>.
*
- * nul-terminated string, which must be freed with
- * g_free(). Otherwise %NULL and @error will be set.
- *
- * Returns: If the conversion was successful, a newly allocated
+ * Returns: If the conversion was successful, a newly allocated nul-terminated string, which must be freed with g_free(). Otherwise %NULL and @error will be set.
*/
@@ -16827,7 +16728,7 @@
*
* Note that you should use g_iconv() for streaming
* conversions<footnote id="streaming-state">
- * <para>
+ * <para>
* Despite the fact that @byes_read can return information about partial
* characters, the <literal>g_convert_...</literal> functions
* are not generally suitable for streaming. If the underlying converter
@@ -16837,13 +16738,10 @@
* for CP1255 which does not emit a base character until it knows that
* the next character is not a mark that could combine with the base
* character.)
- * </para>
+ * </para>
* </footnote>.
*
- * nul-terminated string, which must be freed with
- * g_free(). Otherwise %NULL and @error will be set.
- *
- * Returns: If the conversion was successful, a newly allocated
+ * Returns: If the conversion was successful, a newly allocated nul-terminated string, which must be freed with g_free(). Otherwise %NULL and @error will be set.
*/
@@ -16855,6 +16753,7 @@
* A wrapper for the POSIX creat() function. The creat() function is
* used to convert a pathname into a file descriptor, creating a file
* if necessary.
+ *
* On POSIX systems file descriptors are implemented by the operating
* system. On Windows, it's the C library that implements creat() and
* file descriptors. The actual Windows API for opening files is
@@ -16871,9 +16770,7 @@
*
* See your C library manual for more details about creat().
*
- * return value can be used exactly like the return value from creat().
- *
- * Returns: a new file descriptor, or -1 if an error occurred. The
+ * Returns: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from creat().
* Since: 2.8
*/
@@ -16924,10 +16821,11 @@
* g_datalist_get_data:
* @datalist: a datalist.
* @key: the string identifying a data element.
- * @Returns: the data element, or %NULL if it is not found.
*
* Gets a data element, using its string identifier. This is slower than
* g_datalist_id_get_data() because it compares strings.
+ *
+ * Returns: the data element, or %NULL if it is not found.
*/
@@ -16947,9 +16845,10 @@
* g_datalist_id_get_data:
* @datalist: a datalist.
* @key_id: the #GQuark identifying a data element.
- * @Returns: the data element, or %NULL if it is not found.
*
* Retrieves the data element corresponding to @key_id.
+ *
+ * Returns: the data element, or %NULL if it is not found.
*/
@@ -16966,10 +16865,11 @@
* g_datalist_id_remove_no_notify:
* @datalist: a datalist.
* @key_id: the #GQuark identifying a data element.
- * @Returns: the data previously stored at @key_id, or %NULL if none.
*
* Removes an element, without calling its destroy notification
* function.
+ *
+ * Returns: the data previously stored at @key_id, or %NULL if none.
*/
@@ -17102,9 +17002,10 @@
* g_dataset_get_data:
* @l: the location identifying the dataset.
* @k: the string identifying the data element.
- * @Returns: the data element corresponding to the string, or %NULL if it is not found.
*
* Gets the data element corresponding to a string.
+ *
+ * Returns: the data element corresponding to the string, or %NULL if it is not found.
*/
@@ -17112,9 +17013,10 @@
* g_dataset_id_get_data:
* @dataset_location: the location identifying the dataset.
* @key_id: the #GQuark id to identify the data element.
- * @Returns: the data element corresponding to the #GQuark, or %NULL if it is not found.
*
* Gets the data element corresponding to a #GQuark.
+ *
+ * Returns: the data element corresponding to the #GQuark, or %NULL if it is not found.
*/
@@ -17132,10 +17034,11 @@
* g_dataset_id_remove_no_notify:
* @dataset_location: the location identifying the dataset.
* @key_id: the #GQuark ID identifying the data element.
- * @Returns: the data previously stored at @key_id, or %NULL if none.
*
* Removes an element, without calling its destroy notification
* function.
+ *
+ * Returns: the data previously stored at @key_id, or %NULL if none.
*/
@@ -17276,9 +17179,7 @@
* qsort()-style comparison function for dates.
* Both dates must be valid.
*
- * greater than zero if @lhs is greater than @rhs
- *
- * Returns: 0 for equal, less than zero if @lhs is less than @rhs,
+ * Returns: 0 for equal, less than zero if @lhs is less than @rhs, greater than zero if @lhs is greater than @rhs
*/
@@ -17617,7 +17518,7 @@
*
* To set the value of a date to the current day, you could write:
* |[
- * g_date_set_time_t (date, time (NULL));
+ * g_date_set_time_t (date, time (NULL));
* ]|
*
* Since: 2.10
@@ -17717,9 +17618,7 @@
*
* Creates a copy of @datetime and adds the specified timespan to the copy.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17732,9 +17631,7 @@
* Creates a copy of @datetime and adds the specified number of days to the
* copy.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17752,9 +17649,7 @@
* Creates a new #GDateTime adding the specified values to the current date and
* time in @datetime.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime that should be freed with
+ * Returns: the newly created #GDateTime that should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17766,9 +17661,7 @@
*
* Creates a copy of @datetime and adds the specified number of hours
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17780,9 +17673,7 @@
*
* Creates a copy of @datetime adding the specified number of minutes.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17795,9 +17686,7 @@
* Creates a copy of @datetime and adds the specified number of months to the
* copy.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17809,9 +17698,7 @@
*
* Creates a copy of @datetime and adds the specified number of seconds.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17824,9 +17711,7 @@
* Creates a copy of @datetime and adds the specified number of weeks to the
* copy.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17839,9 +17724,7 @@
* Creates a copy of @datetime and adds the specified number of years to the
* copy.
*
- * g_date_time_unref().
- *
- * Returns: the newly created #GDateTime which should be freed with
+ * Returns: the newly created #GDateTime which should be freed with g_date_time_unref().
* Since: 2.26
*/
@@ -17854,9 +17737,7 @@
* A comparison function for #GDateTimes that is suitable
* as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
*
- * than @dt2.
- *
- * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater
+ * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater than @dt2.
* Since: 2.26
*/
@@ -17870,9 +17751,7 @@
* #GTimeSpan that is returned is effectively @end - @begin (ie:
* positive if the first simparameter is larger).
*
- * span expressed in microseconds.
- *
- * Returns: the difference between the two #GDateTime, as a time
+ * Returns: the difference between the two #GDateTime, as a time span expressed in microseconds.
* Since: 2.26
*/
@@ -17913,209 +17792,209 @@
* The following format specifiers are supported:
*
* <variablelist>
- * <varlistentry><term>
- * <literal>\%a</literal>:
- * </term><listitem><simpara>
- * the abbreviated weekday name according to the current locale
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%A</literal>:
- * </term><listitem><simpara>
- * the full weekday name according to the current locale
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%b</literal>:
- * </term><listitem><simpara>
- * the abbreviated month name according to the current locale
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%B</literal>:
- * </term><listitem><simpara>
- * the full month name according to the current locale
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%c</literal>:
- * </term><listitem><simpara>
- * the preferred date and time representation for the current locale
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%C</literal>:
- * </term><listitem><simpara>
- * The century number (year/100) as a 2-digit integer (00-99)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%d</literal>:
- * </term><listitem><simpara>
- * the day of the month as a decimal number (range 01 to 31)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%e</literal>:
- * </term><listitem><simpara>
- * the day of the month as a decimal number (range 1 to 31)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%F</literal>:
- * </term><listitem><simpara>
- * equivalent to <literal>\%Y-\%m-\%d</literal> (the ISO 8601 date
- * format)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%g</literal>:
- * </term><listitem><simpara>
- * the last two digits of the ISO 8601 week-based year as a decimal
- * number (00-99). This works well with \%V and \%u.
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%G</literal>:
- * </term><listitem><simpara>
- * the ISO 8601 week-based year as a decimal number. This works well
- * with \%V and \%u.
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%h</literal>:
- * </term><listitem><simpara>
- * equivalent to <literal>\%b</literal>
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%H</literal>:
- * </term><listitem><simpara>
- * the hour as a decimal number using a 24-hour clock (range 00 to
- * 23)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%I</literal>:
- * </term><listitem><simpara>
- * the hour as a decimal number using a 12-hour clock (range 01 to
- * 12)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%j</literal>:
- * </term><listitem><simpara>
- * the day of the year as a decimal number (range 001 to 366)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%k</literal>:
- * </term><listitem><simpara>
- * the hour (24-hour clock) as a decimal number (range 0 to 23);
- * single digits are preceded by a blank
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%l</literal>:
- * </term><listitem><simpara>
- * the hour (12-hour clock) as a decimal number (range 1 to 12);
- * single digits are preceded by a blank
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%m</literal>:
- * </term><listitem><simpara>
- * the month as a decimal number (range 01 to 12)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%M</literal>:
- * </term><listitem><simpara>
- * the minute as a decimal number (range 00 to 59)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%p</literal>:
- * </term><listitem><simpara>
- * either "AM" or "PM" according to the given time value, or the
- * corresponding strings for the current locale. Noon is treated as
- * "PM" and midnight as "AM".
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%P</literal>:
- * </term><listitem><simpara>
- * like \%p but lowercase: "am" or "pm" or a corresponding string for
- * the current locale
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%r</literal>:
- * </term><listitem><simpara>
- * the time in a.m. or p.m. notation
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%R</literal>:
- * </term><listitem><simpara>
- * the time in 24-hour notation (<literal>\%H:\%M</literal>)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%s</literal>:
- * </term><listitem><simpara>
- * the number of seconds since the Epoch, that is, since 1970-01-01
- * 00:00:00 UTC
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%S</literal>:
- * </term><listitem><simpara>
- * the second as a decimal number (range 00 to 60)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%t</literal>:
- * </term><listitem><simpara>
- * a tab character
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%T</literal>:
- * </term><listitem><simpara>
- * the time in 24-hour notation with seconds (<literal>\%H:\%M:\%S</literal>)
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%u</literal>:
- * </term><listitem><simpara>
- * the ISO 8601 standard day of the week as a decimal, range 1 to 7,
- * Monday being 1. This works well with \%G and \%V.
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%V</literal>:
- * </term><listitem><simpara>
- * the ISO 8601 standard week number of the current year as a decimal
- * number, range 01 to 53, where week 1 is the first week that has at
- * least 4 days in the new year. See g_date_time_get_week_of_year().
- * This works well with \%G and \%u.
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%w</literal>:
- * </term><listitem><simpara>
- * the day of the week as a decimal, range 0 to 6, Sunday being 0.
- * This is not the ISO 8601 standard format -- use \%u instead.
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%x</literal>:
- * </term><listitem><simpara>
- * the preferred date representation for the current locale without
- * the time
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%X</literal>:
- * </term><listitem><simpara>
- * the preferred time representation for the current locale without
- * the date
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%y</literal>:
- * </term><listitem><simpara>
- * the year as a decimal number without the century
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%Y</literal>:
- * </term><listitem><simpara>
- * the year as a decimal number including the century
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%z</literal>:
- * </term><listitem><simpara>
- * the time-zone as hour offset from UTC
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%Z</literal>:
- * </term><listitem><simpara>
- * the time zone or name or abbreviation
- * </simpara></listitem></varlistentry>
- * <varlistentry><term>
- * <literal>\%\%</literal>:
- * </term><listitem><simpara>
- * a literal <literal>\%</literal> character
- * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%a</literal>:
+ * </term><listitem><simpara>
+ * the abbreviated weekday name according to the current locale
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%A</literal>:
+ * </term><listitem><simpara>
+ * the full weekday name according to the current locale
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%b</literal>:
+ * </term><listitem><simpara>
+ * the abbreviated month name according to the current locale
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%B</literal>:
+ * </term><listitem><simpara>
+ * the full month name according to the current locale
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%c</literal>:
+ * </term><listitem><simpara>
+ * the preferred date and time representation for the current locale
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%C</literal>:
+ * </term><listitem><simpara>
+ * The century number (year/100) as a 2-digit integer (00-99)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%d</literal>:
+ * </term><listitem><simpara>
+ * the day of the month as a decimal number (range 01 to 31)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%e</literal>:
+ * </term><listitem><simpara>
+ * the day of the month as a decimal number (range 1 to 31)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%F</literal>:
+ * </term><listitem><simpara>
+ * equivalent to <literal>\%Y-\%m-\%d</literal> (the ISO 8601 date
+ * format)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%g</literal>:
+ * </term><listitem><simpara>
+ * the last two digits of the ISO 8601 week-based year as a decimal
+ * number (00-99). This works well with \%V and \%u.
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%G</literal>:
+ * </term><listitem><simpara>
+ * the ISO 8601 week-based year as a decimal number. This works well
+ * with \%V and \%u.
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%h</literal>:
+ * </term><listitem><simpara>
+ * equivalent to <literal>\%b</literal>
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%H</literal>:
+ * </term><listitem><simpara>
+ * the hour as a decimal number using a 24-hour clock (range 00 to
+ * 23)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%I</literal>:
+ * </term><listitem><simpara>
+ * the hour as a decimal number using a 12-hour clock (range 01 to
+ * 12)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%j</literal>:
+ * </term><listitem><simpara>
+ * the day of the year as a decimal number (range 001 to 366)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%k</literal>:
+ * </term><listitem><simpara>
+ * the hour (24-hour clock) as a decimal number (range 0 to 23);
+ * single digits are preceded by a blank
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%l</literal>:
+ * </term><listitem><simpara>
+ * the hour (12-hour clock) as a decimal number (range 1 to 12);
+ * single digits are preceded by a blank
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%m</literal>:
+ * </term><listitem><simpara>
+ * the month as a decimal number (range 01 to 12)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%M</literal>:
+ * </term><listitem><simpara>
+ * the minute as a decimal number (range 00 to 59)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%p</literal>:
+ * </term><listitem><simpara>
+ * either "AM" or "PM" according to the given time value, or the
+ * corresponding strings for the current locale. Noon is treated as
+ * "PM" and midnight as "AM".
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%P</literal>:
+ * </term><listitem><simpara>
+ * like \%p but lowercase: "am" or "pm" or a corresponding string for
+ * the current locale
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%r</literal>:
+ * </term><listitem><simpara>
+ * the time in a.m. or p.m. notation
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%R</literal>:
+ * </term><listitem><simpara>
+ * the time in 24-hour notation (<literal>\%H:\%M</literal>)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%s</literal>:
+ * </term><listitem><simpara>
+ * the number of seconds since the Epoch, that is, since 1970-01-01
+ * 00:00:00 UTC
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%S</literal>:
+ * </term><listitem><simpara>
+ * the second as a decimal number (range 00 to 60)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%t</literal>:
+ * </term><listitem><simpara>
+ * a tab character
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%T</literal>:
+ * </term><listitem><simpara>
+ * the time in 24-hour notation with seconds (<literal>\%H:\%M:\%S</literal>)
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%u</literal>:
+ * </term><listitem><simpara>
+ * the ISO 8601 standard day of the week as a decimal, range 1 to 7,
+ * Monday being 1. This works well with \%G and \%V.
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%V</literal>:
+ * </term><listitem><simpara>
+ * the ISO 8601 standard week number of the current year as a decimal
+ * number, range 01 to 53, where week 1 is the first week that has at
+ * least 4 days in the new year. See g_date_time_get_week_of_year().
+ * This works well with \%G and \%u.
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%w</literal>:
+ * </term><listitem><simpara>
+ * the day of the week as a decimal, range 0 to 6, Sunday being 0.
+ * This is not the ISO 8601 standard format -- use \%u instead.
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%x</literal>:
+ * </term><listitem><simpara>
+ * the preferred date representation for the current locale without
+ * the time
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%X</literal>:
+ * </term><listitem><simpara>
+ * the preferred time representation for the current locale without
+ * the date
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%y</literal>:
+ * </term><listitem><simpara>
+ * the year as a decimal number without the century
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%Y</literal>:
+ * </term><listitem><simpara>
+ * the year as a decimal number including the century
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%z</literal>:
+ * </term><listitem><simpara>
+ * the time-zone as hour offset from UTC
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%Z</literal>:
+ * </term><listitem><simpara>
+ * the time zone or name or abbreviation
+ * </simpara></listitem></varlistentry>
+ * <varlistentry><term>
+ * <literal>\%\%</literal>:
+ * </term><listitem><simpara>
+ * a literal <literal>\%</literal> character
+ * </simpara></listitem></varlistentry>
* </variablelist>
*
* Some conversion specifications can be modified by preceding the
@@ -18123,40 +18002,37 @@
* following modifiers are supported for many of the numeric
* conversions:
* <variablelist>
- * <varlistentry>
- * <term>O</term>
- * <listitem>
- * Use alternative numeric symbols, if the current locale
- * supports those.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>_</term>
- * <listitem>
- * Pad a numeric result with spaces.
- * This overrides the default padding for the specifier.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>-</term>
- * <listitem>
- * Do not pad a numeric result.
- * This overrides the default padding for the specifier.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>0</term>
- * <listitem>
- * Pad a numeric result with zeros.
- * This overrides the default padding for the specifier.
- * </listitem>
- * </varlistentry>
+ * <varlistentry>
+ * <term>O</term>
+ * <listitem>
+ * Use alternative numeric symbols, if the current locale
+ * supports those.
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>_</term>
+ * <listitem>
+ * Pad a numeric result with spaces.
+ * This overrides the default padding for the specifier.
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>-</term>
+ * <listitem>
+ * Do not pad a numeric result.
+ * This overrides the default padding for the specifier.
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>0</term>
+ * <listitem>
+ * Pad a numeric result with zeros.
+ * This overrides the default padding for the specifier.
+ * </listitem>
+ * </varlistentry>
* </variablelist>
*
- * or %NULL in the case that there was an error. The string
- * should be freed with g_free().
- *
- * Returns: a newly allocated string formatted to the requested format
+ * Returns: a newly allocated string formatted to the requested format or %NULL in the case that there was an error. The string should be freed with g_free().
* Since: 2.26
*/
@@ -18276,10 +18152,7 @@
* months and "EDT" during the summer months when daylight savings
* time is in effect.
*
- * string is owned by the #GDateTime and it should not be
- * modified or freed
- *
- * Returns: (transfer none): the time zone abbreviation. The returned
+ * Returns: (transfer none): the time zone abbreviation. The returned string is owned by the #GDateTime and it should not be modified or freed
* Since: 2.26
*/
@@ -18297,9 +18170,7 @@
*
* If @datetime represents UTC time, then the offset is always zero.
*
- * get the local time
- *
- * Returns: the number of microseconds that should be added to UTC to
+ * Returns: the number of microseconds that should be added to UTC to get the local time
* Since: 2.26
*/
@@ -18886,9 +18757,9 @@
* <listitem>@domain is not %NULL</listitem>
* <listitem>textdomain() has been called to set a default text domain</listitem>
* <listitem>there is no translations available for the default text domain
- * and the current locale</listitem>
+ * and the current locale</listitem>
* <listitem>current locale is not "C" or any English locales (those
- * starting with "en_")</listitem>
+ * starting with "en_")</listitem>
* </itemizedlist>
*
* Note that this behavior may not be desired for example if an application
@@ -18928,11 +18799,7 @@
* Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not
* modified, and might thus be a read-only literal string.
*
- * should be freed with g_free() when not needed any longer and is
- * is in the GLib file name encoding. In case of errors, %NULL is
- * returned and @error will be set.
- *
- * Returns: (type filename): The actual name used. This string
+ * Returns: (type filename): The actual name used. This string should be freed with g_free() when not needed any longer and is is in the GLib file name encoding. In case of errors, %NULL is returned and @error will be set.
* Since: 2.30
*/
@@ -18947,10 +18814,7 @@
* directory can then be retrieved using g_dir_read_name(). Note
* that the ordering is not defined.
*
- * If non-%NULL, you must free the result with g_dir_close()
- * when you are finished with it.
- *
- * Returns: a newly allocated #GDir on success, %NULL on failure.
+ * Returns: a newly allocated #GDir on success, %NULL on failure. If non-%NULL, you must free the result with g_dir_close() when you are finished with it.
*/
@@ -18969,10 +18833,7 @@
* On Windows, as is true of all GLib functions which operate on
* filenames, the returned name is in UTF-8.
*
- * more entries. The return value is owned by GLib and
- * must not be modified or freed.
- *
- * Returns: The entry's name or %NULL if there are no
+ * Returns: The entry's name or %NULL if there are no more entries. The return value is owned by GLib and must not be modified or freed.
*/
@@ -19143,11 +19004,7 @@
* value contains references to other environment variables, they
* are expanded.
*
- * the environment variable is not set in @envp. The returned
- * string is owned by @envp, and will be freed if @variable is
- * set or unset again.
- *
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: the value of the environment variable, or %NULL if the environment variable is not set in @envp. The returned string is owned by @envp, and will be freed if @variable is set or unset again.
* Since: 2.32
*/
@@ -19166,9 +19023,7 @@
* file name encoding. On UNIX, this means that they can be
* arbitrary byte strings. On Windows, they should be in UTF-8.
*
- * updated environment list. Free it using g_strfreev().
- *
- * Returns: (array zero-terminated=1) (transfer full): the
+ * Returns: (array zero-terminated=1) (transfer full): the updated environment list. Free it using g_strfreev().
* Since: 2.32
*/
@@ -19181,9 +19036,7 @@
* Removes the environment variable @variable from the provided
* environment @envp.
*
- * updated environment list. Free it using g_strfreev().
- *
- * Returns: (array zero-terminated=1) (transfer full): the
+ * Returns: (array zero-terminated=1) (transfer full): the updated environment list. Free it using g_strfreev().
* Since: 2.32
*/
@@ -19340,11 +19193,7 @@
* when not needed any longer. The returned name is in the GLib file
* name encoding.
*
- * reading and writing. The file is opened in binary mode on platforms
- * where there is a difference. The file handle should be closed with
- * close(). In case of errors, -1 is returned and @error will be set.
- *
- * Returns: A file handle (as from open()) to the file opened for
+ * Returns: A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and @error will be set.
*/
@@ -19357,9 +19206,7 @@
* readlink() function. The returned string is in the encoding used
* for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
*
- * or %NULL if an error occurred.
- *
- * Returns: A newly-allocated string with the contents of the symbolic link,
+ * Returns: A newly-allocated string with the contents of the symbolic link, or %NULL if an error occurred.
* Since: 2.4
*/
@@ -19378,20 +19225,20 @@
* file which is then renamed to the final name. Notes:
* <itemizedlist>
* <listitem>
- * On Unix, if @filename already exists hard links to @filename will break.
- * Also since the file is recreated, existing permissions, access control
- * lists, metadata etc. may be lost. If @filename is a symbolic link,
- * the link itself will be replaced, not the linked file.
+ * On Unix, if @filename already exists hard links to @filename will break.
+ * Also since the file is recreated, existing permissions, access control
+ * lists, metadata etc. may be lost. If @filename is a symbolic link,
+ * the link itself will be replaced, not the linked file.
* </listitem>
* <listitem>
- * On Windows renaming a file will not remove an existing file with the
- * new name, so on Windows there is a race condition between the existing
- * file being removed and the temporary file being renamed.
+ * On Windows renaming a file will not remove an existing file with the
+ * new name, so on Windows there is a race condition between the existing
+ * file being removed and the temporary file being renamed.
* </listitem>
* <listitem>
- * On Windows there is no way to remove a file that is open to some
- * process, or mapped into memory. Thus, this function will fail if
- * @filename already exists and is open.
+ * On Windows there is no way to remove a file that is open to some
+ * process, or mapped into memory. Thus, this function will fail if
+ * @filename already exists and is open.
* </listitem>
* </itemizedlist>
*
@@ -19434,11 +19281,11 @@
* tricked into writing into a different location. It doesn't work!
* |[
* /* DON'T DO THIS */
- * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
- * {
- * fd = g_open (filename, O_WRONLY);
- * /* write to fd */
- * }
+ * if (!g_file_test (filename, G_FILE_TEST_IS_SYMLINK))
+ * {
+ * fd = g_open (filename, O_WRONLY);
+ * /* write to fd */
+ * }
* ]|
*
* Another thing to note is that %G_FILE_TEST_EXISTS and
@@ -19479,9 +19326,7 @@
* This function is preferred over g_filename_display_name() if you know the
* whole path, as it allows translation.
*
- * a rendition of the basename of the filename in valid UTF-8
- *
- * Returns: a newly allocated string containing
+ * Returns: a newly allocated string containing a rendition of the basename of the filename in valid UTF-8
* Since: 2.6
*/
@@ -19506,9 +19351,7 @@
* g_filename_display_basename(), since that allows location-based
* translation of filenames.
*
- * a rendition of the filename in valid UTF-8
- *
- * Returns: a newly allocated string containing
+ * Returns: a newly allocated string containing a rendition of the filename in valid UTF-8
* Since: 2.6
*/
@@ -19522,9 +19365,7 @@
* Converts an escaped ASCII-encoded URI to a local filename in the
* encoding used for filenames.
*
- * filename, or %NULL on an error.
- *
- * Returns: a newly-allocated string holding the resulting
+ * Returns: a newly-allocated string holding the resulting filename, or %NULL on an error.
*/
@@ -19554,9 +19395,7 @@
* Converts an absolute filename to an escaped ASCII-encoded URI, with the path
* component following Section 3.3. of RFC 2396.
*
- * URI, or %NULL on an error.
- *
- * Returns: a newly-allocated string holding the resulting
+ * Returns: a newly-allocated string holding the resulting URI, or %NULL on an error.
*/
@@ -19621,9 +19460,7 @@
*
* See your C library manual for more details about fopen().
*
- * opened, or %NULL if an error occurred
- *
- * Returns: A <type>FILE</type> pointer if the file was successfully
+ * Returns: A <type>FILE</type> pointer if the file was successfully opened, or %NULL if an error occurred
* Since: 2.6
*/
@@ -19644,9 +19481,7 @@
* See g_format_size_full() for more options about how the size might be
* formatted.
*
- * file size
- *
- * Returns: a newly-allocated formatted string containing a human readable
+ * Returns: a newly-allocated formatted string containing a human readable file size
* Since: 2.30
*/
@@ -19665,14 +19500,9 @@
*
* This string should be freed with g_free() when not needed any longer.
*
- * readable file size
- *
- *
- * Deprecated:2.30: This function is broken due to its use of SI
- * suffixes to denote IEC units. Use g_format_size() instead.
- *
- * Returns: a newly-allocated formatted string containing a human
+ * Returns: a newly-allocated formatted string containing a human readable file size
* Since: 2.16
+ * Deprecated: 2.30: This function is broken due to its use of SI suffixes to denote IEC units. Use g_format_size() instead.
*/
@@ -19686,9 +19516,7 @@
* This function is similar to g_format_size() but allows for flags
* that modify the output. See #GFormatSizeFlags.
*
- * readable file size
- *
- * Returns: a newly-allocated formatted string containing a human
+ * Returns: a newly-allocated formatted string containing a human readable file size
* Since: 2.30
*/
@@ -19727,9 +19555,7 @@
*
* See your C library manual for more details about freopen().
*
- * opened, or %NULL if an error occurred.
- *
- * Returns: A <literal>FILE</literal> pointer if the file was successfully
+ * Returns: A <literal>FILE</literal> pointer if the file was successfully opened, or %NULL if an error occurred.
* Since: 2.6
*/
@@ -19781,9 +19607,7 @@
*
* Gets the character set for the current locale.
*
- * of the character set. This string must be freed with g_free().
- *
- * Returns: a newly allocated string containing the name
+ * Returns: a newly allocated string containing the name of the character set. This string must be freed with g_free().
*/
@@ -19824,9 +19648,7 @@
* The return value is freshly allocated and it should be freed with
* g_strfreev() when it is no longer needed.
*
- * environment variables
- *
- * Returns: (array zero-terminated=1) (transfer full): the list of
+ * Returns: (array zero-terminated=1) (transfer full): the list of environment variables
* Since: 2.28
*/
@@ -19880,9 +19702,9 @@
* cases need special handling to deal with the case where
* <envar>HOME</envar> is
* <simplelist>
- * <member>Not owned by the user</member>
- * <member>Not writeable</member>
- * <member>Not even readable</member>
+ * <member>Not owned by the user</member>
+ * <member>Not writeable</member>
+ * <member>Not even readable</member>
* </simplelist>
* Since applications are in general <emphasis>not</emphasis> written
* to deal with these situations it was considered better to make
@@ -19890,9 +19712,9 @@
* return the real home directory for the user. If applications
* want to pay attention to <envar>HOME</envar>, they can do:
* |[
- * const char *homedir = g_getenv ("HOME");
- * if (!homedir)
- * homedir = g_get_home_dir (<!-- -->);
+ * const char *homedir = g_getenv ("HOME");
+ * if (!homedir)
+ * homedir = g_get_home_dir (<!-- -->);
* ]|
*
* Returns: the current user's home directory
@@ -19935,9 +19757,7 @@
* <envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar> and <envar>LANG</envar>
* to find the list of locales specified by the user.
*
- * that must not be modified or freed.
- *
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib
+ * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed.
* Since: 2.6
*/
@@ -19957,10 +19777,7 @@
* If you need the list of variants for the <emphasis>current locale</emphasis>,
* use g_get_language_names().
*
- * allocated array of newly allocated strings with the locale variants. Free with
- * g_strfreev().
- *
- * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly
+ * Returns: (transfer full) (array zero-terminated=1) (element-type utf8): a newly allocated array of newly allocated strings with the locale variants. Free with g_strfreev().
* Since: 2.28
*/
@@ -19999,9 +19816,7 @@
* which is called by gtk_init(). The program name is found by taking
* the last component of <literal>argv[0]</literal>.)
*
- * to GLib and must not be modified or freed.
- *
- * Returns: the name of the program. The returned string belongs
+ * Returns: the name of the program. The returned string belongs to GLib and must not be modified or freed.
*/
@@ -20054,9 +19869,7 @@
* of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
* This information will not roam and is available to anyone using the computer.
*
- * not be modified or freed.
- *
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
+ * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed.
* Since: 2.6
*/
@@ -20094,9 +19907,7 @@
* Note that on Windows the returned list can vary depending on where
* this function is called.
*
- * not be modified or freed.
- *
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
+ * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed.
* Since: 2.6
*/
@@ -20131,9 +19942,7 @@
* C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
* See documentation for CSIDL_INTERNET_CACHE.
*
- * or freed.
- *
- * Returns: a string owned by GLib that must not be modified
+ * Returns: a string owned by GLib that must not be modified or freed.
* Since: 2.6
*/
@@ -20154,9 +19963,7 @@
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_data_dir() returns.
*
- * or freed.
- *
- * Returns: a string owned by GLib that must not be modified
+ * Returns: a string owned by GLib that must not be modified or freed.
* Since: 2.6
*/
@@ -20177,9 +19984,7 @@
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_config_dir() returns.
*
- * or freed.
- *
- * Returns: a string owned by GLib that must not be modified
+ * Returns: a string owned by GLib that must not be modified or freed.
* Since: 2.6
*/
@@ -20234,10 +20039,7 @@
* of the special directory without requiring the session to restart; GLib
* will not reflect any change once the special directories are loaded.
*
- * if the logical id was not found. The returned string is owned by
- * GLib and should not be modified or freed.
- *
- * Returns: the path to the specified special directory, or %NULL
+ * Returns: the path to the specified special directory, or %NULL if the logical id was not found. The returned string is owned by GLib and should not be modified or freed.
* Since: 2.14
*/
@@ -20254,11 +20056,7 @@
* On Windows, in case the environment variable's value contains
* references to other environment variables, they are expanded.
*
- * the environment variable is not found. The returned string
- * may be overwritten by the next call to g_getenv(), g_setenv()
- * or g_unsetenv().
- *
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: the value of the environment variable, or %NULL if the environment variable is not found. The returned string may be overwritten by the next call to g_getenv(), g_setenv() or g_unsetenv().
*/
@@ -20323,10 +20121,7 @@
* (keep in mind that an O(n) find/foreach operation issued for all n
* values in a hash table ends up needing O(n*n) operations).
*
- * for which @predicate evaluates to %TRUE. If no pair with the
- * requested property is found, %NULL is returned.
- *
- * Returns: (allow-none): The value of the first key/value pair is returned,
+ * Returns: (allow-none): The value of the first key/value pair is returned, for which @predicate evaluates to %TRUE. If no pair with the requested property is found, %NULL is returned.
* Since: 2.4
*/
@@ -20402,11 +20197,7 @@
* Retrieves every key inside @hash_table. The returned data
* is valid until @hash_table is modified.
*
- * table. The content of the list is owned by the hash table and
- * should not be modified or freed. Use g_list_free() when done
- * using the list.
- *
- * Returns: a #GList containing all the keys inside the hash
+ * Returns: a #GList containing all the keys inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list.
* Since: 2.14
*/
@@ -20418,11 +20209,7 @@
* Retrieves every value inside @hash_table. The returned data
* is valid until @hash_table is modified.
*
- * table. The content of the list is owned by the hash table and
- * should not be modified or freed. Use g_list_free() when done
- * using the list.
- *
- * Returns: a #GList containing all the values inside the hash
+ * Returns: a #GList containing all the values inside the hash table. The content of the list is owned by the hash table and should not be modified or freed. Use g_list_free() when done using the list.
* Since: 2.14
*/
@@ -20469,9 +20256,9 @@
*
* 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 */
+ * }
* ]|
*
* Since: 2.16
@@ -20737,9 +20524,7 @@
* g_hmac_get_string() or g_hmac_get_digest(), the copied
* HMAC will be closed as well.
*
- * when finished using it.
- *
- * Returns: the copy of the passed #GHmac. Use g_hmac_unref()
+ * Returns: the copy of the passed #GHmac. Use g_hmac_unref() when finished using it.
* Since: 2.30
*/
@@ -20771,10 +20556,7 @@
*
* The hexadecimal characters will be lower case.
*
- * returned string is owned by the HMAC and should not be modified
- * or freed.
- *
- * Returns: the hexadecimal representation of the HMAC. The
+ * Returns: the hexadecimal representation of the HMAC. The returned string is owned by the HMAC and should not be modified or freed.
* Since: 2.30
*/
@@ -20799,9 +20581,7 @@
* will be closed and it won't be possible to call g_hmac_update()
* on it anymore.
*
- * Use g_hmac_unref() to free the memory allocated by it.
- *
- * Returns: the newly created #GHmac, or %NULL.
+ * Returns: the newly created #GHmac, or %NULL. Use g_hmac_unref() to free the memory allocated by it.
* Since: 2.30
*/
@@ -20923,9 +20703,7 @@
*
* Finds a #GHook in a #GHookList with the given data.
*
- * #GHook is found
- *
- * Returns: the #GHook with the given @data or %NULL if no matching
+ * Returns: the #GHook with the given @data or %NULL if no matching #GHook is found
*/
@@ -20937,9 +20715,7 @@
*
* Finds a #GHook in a #GHookList with the given function.
*
- * #GHook is found
- *
- * Returns: the #GHook with the given @func or %NULL if no matching
+ * Returns: the #GHook with the given @func or %NULL if no matching #GHook is found
*/
@@ -20952,9 +20728,7 @@
*
* Finds a #GHook in a #GHookList with the given function and data.
*
- * no matching #GHook is found
- *
- * Returns: the #GHook with the given @func and @data or %NULL if
+ * Returns: the #GHook with the given @func and @data or %NULL if no matching #GHook is found
*/
@@ -21132,9 +20906,7 @@
* segments, and so it is possible for g_hostname_is_non_ascii() and
* g_hostname_is_ascii_encoded() to both return %TRUE for a name.
*
- * segments.
- *
- * Returns: %TRUE if @hostname contains any ASCII-encoded
+ * Returns: %TRUE if @hostname contains any ASCII-encoded segments.
* Since: 2.22
*/
@@ -21176,9 +20948,7 @@
* string containing no uppercase letters and not ending with a
* trailing dot.
*
- * @hostname is in some way invalid.
- *
- * Returns: an ASCII hostname, which must be freed, or %NULL if
+ * Returns: an ASCII hostname, which must be freed, or %NULL if @hostname is in some way invalid.
* Since: 2.22
*/
@@ -21195,9 +20965,7 @@
* Of course if @hostname is not an internationalized hostname, then
* the canonical presentation form will be entirely ASCII.
*
- * @hostname is in some way invalid.
- *
- * Returns: a UTF-8 hostname, which must be freed, or %NULL if
+ * Returns: a UTF-8 hostname, which must be freed, or %NULL if @hostname is in some way invalid.
* Since: 2.22
*/
@@ -21270,9 +21038,7 @@
* GLib provides g_convert() and g_locale_to_utf8() which are likely
* more convenient than the raw iconv wrappers.
*
- * opening the converter failed.
- *
- * Returns: a "conversion descriptor", or (GIConv)-1 if
+ * Returns: a "conversion descriptor", or (GIConv)-1 if opening the converter failed.
*/
@@ -21475,7 +21241,7 @@
* flushed, ignoring errors. The channel will not be freed until the
* last reference is dropped using g_io_channel_unref().
*
- * Deprecated:2.2: Use g_io_channel_shutdown() instead.
+ * Deprecated: 2.2: Use g_io_channel_shutdown() instead.
*/
@@ -21485,9 +21251,7 @@
*
* Converts an <literal>errno</literal> error number to a #GIOChannelError.
*
- * %G_IO_CHANNEL_ERROR_INVAL.
- *
- * Returns: a #GIOChannelError error number, e.g.
+ * Returns: a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL.
*/
@@ -21507,10 +21271,7 @@
*
* Flushes the write buffer for the GIOChannel.
*
- * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or
- * #G_IO_STATUS_ERROR.
- *
- * Returns: the status of the operation: One of
+ * Returns: the status of the operation: One of #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or #G_IO_STATUS_ERROR.
*/
@@ -21555,9 +21316,7 @@
* destroyed. The default value of this is %TRUE for channels created
* by g_io_channel_new_file (), and %FALSE for all other channels.
*
- * the GIOChannel data structure.
- *
- * Returns: Whether the channel will be closed on the final unref of
+ * Returns: Whether the channel will be closed on the final unref of the GIOChannel data structure.
*/
@@ -21569,9 +21328,7 @@
* The internal encoding is always UTF-8. The encoding %NULL
* makes the channel safe for binary data.
*
- * owned by GLib and must not be freed.
- *
- * Returns: A string containing the encoding, this string is
+ * Returns: A string containing the encoding, this string is owned by GLib and must not be freed.
*/
@@ -21602,9 +21359,7 @@
* where in the file a line break occurs. A value of %NULL
* indicates autodetection.
*
- * is owned by GLib and must not be freed.
- *
- * Returns: The line termination string. This value
+ * Returns: The line termination string. This value is owned by GLib and must not be freed.
*/
@@ -21645,10 +21400,8 @@
*
* Reads data from a #GIOChannel.
*
- *
- * Deprecated:2.2: Use g_io_channel_read_chars() instead.
- *
* Returns: %G_IO_ERROR_NONE if the operation was successful.
+ * Deprecated: 2.2: Use g_io_channel_read_chars() instead.
*/
@@ -21705,9 +21458,7 @@
*
* Reads all the remaining data from the file.
*
- * This function never returns %G_IO_STATUS_EOF.
- *
- * Returns: %G_IO_STATUS_NORMAL on success.
+ * Returns: %G_IO_STATUS_NORMAL on success. This function never returns %G_IO_STATUS_EOF.
*/
@@ -21743,10 +21494,8 @@
* Sets the current position in the #GIOChannel, similar to the standard
* library function fseek().
*
- *
- * Deprecated:2.2: Use g_io_channel_seek_position() instead.
- *
* Returns: %G_IO_ERROR_NONE if the operation was successful.
+ * Deprecated: 2.2: Use g_io_channel_seek_position() instead.
*/
@@ -21825,33 +21574,33 @@
* is true:
* <itemizedlist>
* <listitem><para>
- * The channel was just created, and has not been written to or read
- * from yet.
+ * The channel was just created, and has not been written to or read
+ * from yet.
* </para></listitem>
* <listitem><para>
- * The channel is write-only.
+ * The channel is write-only.
* </para></listitem>
* <listitem><para>
- * The channel is a file, and the file pointer was just
- * repositioned by a call to g_io_channel_seek_position().
- * (This flushes all the internal buffers.)
+ * The channel is a file, and the file pointer was just
+ * repositioned by a call to g_io_channel_seek_position().
+ * (This flushes all the internal buffers.)
* </para></listitem>
* <listitem><para>
- * The current encoding is %NULL or UTF-8.
+ * The current encoding is %NULL or UTF-8.
* </para></listitem>
* <listitem><para>
- * One of the (new API) read functions has just returned %G_IO_STATUS_EOF
- * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
+ * One of the (new API) read functions has just returned %G_IO_STATUS_EOF
+ * (or, in the case of g_io_channel_read_to_end(), %G_IO_STATUS_NORMAL).
* </para></listitem>
* <listitem><para>
- * One of the functions g_io_channel_read_chars() or
- * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
- * %G_IO_STATUS_ERROR. This may be useful in the case of
- * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
- * Returning one of these statuses from g_io_channel_read_line(),
- * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
- * does <emphasis>not</emphasis> guarantee that the encoding can
- * be changed.
+ * One of the functions g_io_channel_read_chars() or
+ * g_io_channel_read_unichar() has returned %G_IO_STATUS_AGAIN or
+ * %G_IO_STATUS_ERROR. This may be useful in the case of
+ * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+ * Returning one of these statuses from g_io_channel_read_line(),
+ * g_io_channel_read_line_string(), or g_io_channel_read_to_end()
+ * does <emphasis>not</emphasis> guarantee that the encoding can
+ * be changed.
* </para></listitem>
* </itemizedlist>
* Channels which do not meet one of the above conditions cannot call
@@ -21903,19 +21652,19 @@
/**
* g_io_channel_unix_get_fd:
* @channel: a #GIOChannel, created with g_io_channel_unix_new().
- * @Returns: the file descriptor of the #GIOChannel.
*
* Returns the file descriptor of the #GIOChannel.
*
* On Windows this function returns the file descriptor or socket of
* the #GIOChannel.
+ *
+ * Returns: the file descriptor of the #GIOChannel.
*/
/**
* g_io_channel_unix_new:
* @fd: a file descriptor.
- * @Returns: a new #GIOChannel.
*
* Creates a new #GIOChannel given a file descriptor. On UNIX systems
* this works for plain files, pipes, and sockets.
@@ -21937,6 +21686,8 @@
* in case the argument you pass to this function happens to be both a
* valid file descriptor and socket. If that happens a warning is
* issued, and GLib assumes that it is the file descriptor you mean.
+ *
+ * Returns: a new #GIOChannel.
*/
@@ -21951,7 +21702,6 @@
/**
* g_io_channel_win32_new_fd:
* @fd: a C library file descriptor.
- * @Returns: a new #GIOChannel.
*
* Creates a new #GIOChannel given a file descriptor on Windows. This
* works for file descriptors from the C runtime.
@@ -21975,25 +21725,27 @@
* thread. Your code should call only g_io_channel_read().
*
* This function is available only in GLib on Windows.
+ *
+ * Returns: a new #GIOChannel.
*/
/**
* g_io_channel_win32_new_messages:
* @hwnd: a window handle.
- * @Returns: a new #GIOChannel.
*
* Creates a new #GIOChannel given a window handle on Windows.
*
* This function creates a #GIOChannel that can be used to poll for
* Windows messages for the window in question.
+ *
+ * Returns: a new #GIOChannel.
*/
/**
* g_io_channel_win32_new_socket:
* @socket: a Winsock socket
- * @Returns: a new #GIOChannel
*
* Creates a new #GIOChannel given a socket on Windows.
*
@@ -22003,6 +21755,8 @@
* Polling a #GSource created to watch a channel for a socket puts the
* socket in non-blocking mode. This is a side-effect of the
* implementation and unavoidable.
+ *
+ * Returns: a new #GIOChannel
*/
@@ -22015,10 +21769,8 @@
*
* Writes data to a #GIOChannel.
*
- *
- * Deprecated:2.2: Use g_io_channel_write_chars() instead.
- *
* Returns: %G_IO_ERROR_NONE if the operation was successful.
+ * Deprecated: 2.2: Use g_io_channel_write_chars() instead.
*/
@@ -22102,9 +21854,7 @@
* associated with @key cannot be interpreted as a boolean then %FALSE
* is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
*
- * or %FALSE if the key was not found or could not be parsed.
- *
- * Returns: the value associated with the key as a boolean,
+ * Returns: the value associated with the key as a boolean, or %FALSE if the key was not found or could not be parsed.
* Since: 2.6
*/
@@ -22125,11 +21875,7 @@
* with @key cannot be interpreted as booleans then %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
*
- * the values associated with the key as a list of booleans, or %NULL if the
- * key was not found or could not be parsed. The returned list of booleans
- * should be freed with g_free() when no longer needed.
- *
- * Returns: (array length=length) (element-type gboolean) (transfer container):
+ * Returns: (array length=length) (element-type gboolean) (transfer container): the values associated with the key as a list of booleans, or %NULL if the key was not found or could not be parsed. The returned list of booleans should be freed with g_free() when no longer needed.
* Since: 2.6
*/
@@ -22166,9 +21912,7 @@
* with @key cannot be interpreted as a double then 0.0 is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
*
- * 0.0 if the key was not found or could not be parsed.
- *
- * Returns: the value associated with the key as a double, or
+ * Returns: the value associated with the key as a double, or 0.0 if the key was not found or could not be parsed.
* Since: 2.12
*/
@@ -22189,11 +21933,7 @@
* with @key cannot be interpreted as doubles then %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
*
- * the values associated with the key as a list of doubles, or %NULL if the
- * key was not found or could not be parsed. The returned list of doubles
- * should be freed with g_free() when no longer needed.
- *
- * Returns: (array length=length) (element-type gdouble) (transfer container):
+ * Returns: (array length=length) (element-type gdouble) (transfer container): the values associated with the key as a list of doubles, or %NULL if the key was not found or could not be parsed. The returned list of doubles should be freed with g_free() when no longer needed.
* Since: 2.12
*/
@@ -22207,9 +21947,7 @@
* The array of returned groups will be %NULL-terminated, so
* @length may optionally be %NULL.
*
- * Use g_strfreev() to free it.
- *
- * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
+ * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
* Since: 2.6
*/
@@ -22225,9 +21963,7 @@
* 64-bit integer. This is similar to g_key_file_get_integer() but can return
* 64-bit results without truncation.
*
- * 0 if the key was not found or could not be parsed.
- *
- * Returns: the value associated with the key as a signed 64-bit integer, or
+ * Returns: the value associated with the key as a signed 64-bit integer, or 0 if the key was not found or could not be parsed.
* Since: 2.26
*/
@@ -22247,9 +21983,7 @@
* with @key cannot be interpreted as an integer then 0 is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
*
- * 0 if the key was not found or could not be parsed.
- *
- * Returns: the value associated with the key as an integer, or
+ * Returns: the value associated with the key as an integer, or 0 if the key was not found or could not be parsed.
* Since: 2.6
*/
@@ -22270,11 +22004,7 @@
* with @key cannot be interpreted as integers then %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
*
- * the values associated with the key as a list of integers, or %NULL if
- * the key was not found or could not be parsed. The returned list of
- * integers should be freed with g_free() when no longer needed.
- *
- * Returns: (array length=length) (element-type gint) (transfer container):
+ * Returns: (array length=length) (element-type gint) (transfer container): the values associated with the key as a list of integers, or %NULL if the key was not found or could not be parsed. The returned list of integers should be freed with g_free() when no longer needed.
* Since: 2.6
*/
@@ -22292,9 +22022,7 @@
* be found, %NULL is returned and @error is set to
* #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
*
- * Use g_strfreev() to free it.
- *
- * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings.
+ * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
* Since: 2.6
*/
@@ -22316,9 +22044,7 @@
* with @key cannot be interpreted or no suitable translation can
* be found then the untranslated value is returned.
*
- * key cannot be found.
- *
- * Returns: a newly allocated string or %NULL if the specified
+ * Returns: a newly allocated string or %NULL if the specified key cannot be found.
* Since: 2.6
*/
@@ -22335,6 +22061,7 @@
* Returns the values associated with @key under @group_name
* translated in the given @locale if available. If @locale is
* %NULL then the current locale is assumed.
+ *
* If @key cannot be found then %NULL is returned and @error is set
* to #G_KEY_FILE_ERROR_KEY_NOT_FOUND. If the values associated
* with @key cannot be interpreted or no suitable translations
@@ -22342,10 +22069,7 @@
* returned array is %NULL-terminated, so @length may optionally
* be %NULL.
*
- * or %NULL if the key isn't found. The string array should be freed
- * with g_strfreev().
- *
- * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array
+ * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full): a newly allocated %NULL-terminated string array or %NULL if the key isn't found. The string array should be freed with g_strfreev().
* Since: 2.6
*/
@@ -22377,9 +22101,7 @@
* event that the @group_name cannot be found, %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
*
- * key cannot be found.
- *
- * Returns: a newly allocated string or %NULL if the specified
+ * Returns: a newly allocated string or %NULL if the specified key cannot be found.
* Since: 2.6
*/
@@ -22399,10 +22121,7 @@
* event that the @group_name cannot be found, %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
*
- * a %NULL-terminated string array or %NULL if the specified
- * key cannot be found. The array should be freed with g_strfreev().
- *
- * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full):
+ * Returns: (array length=length zero-terminated=1) (element-type utf8) (transfer full): a %NULL-terminated string array or %NULL if the specified key cannot be found. The array should be freed with g_strfreev().
* Since: 2.6
*/
@@ -22418,9 +22137,7 @@
* 64-bit integer. This is similar to g_key_file_get_integer() but can return
* large positive results without truncation.
*
- * or 0 if the key was not found or could not be parsed.
- *
- * Returns: the value associated with the key as an unsigned 64-bit integer,
+ * Returns: the value associated with the key as an unsigned 64-bit integer, or 0 if the key was not found or could not be parsed.
* Since: 2.26
*/
@@ -22440,10 +22157,7 @@
* event that the @group_name cannot be found, %NULL is returned
* and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND.
*
- *
- * key cannot be found.
- *
- * Returns: a newly allocated string or %NULL if the specified
+ * Returns: a newly allocated string or %NULL if the specified key cannot be found.
* Since: 2.6
*/
@@ -22455,9 +22169,7 @@
*
* Looks whether the key file has the group @group_name.
*
- * otherwise.
- *
- * Returns: %TRUE if @group_name is a part of @key_file, %FALSE
+ * Returns: %TRUE if @group_name is a part of @key_file, %FALSE otherwise.
* Since: 2.6
*/
@@ -22480,9 +22192,7 @@
* Language bindings should use g_key_file_get_value() to test whether
* or not a key exists.
*
- * otherwise.
- *
- * Returns: %TRUE if @key is a part of @group_name, %FALSE
+ * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise.
* Since: 2.6
*/
@@ -22868,9 +22578,7 @@
* Note that this function never reports an error,
* so it is safe to pass %NULL as @error.
*
- * the contents of the #GKeyFile
- *
- * Returns: a newly allocated string holding
+ * Returns: a newly allocated string holding the contents of the #GKeyFile
* Since: 2.6
*/
@@ -22888,11 +22596,12 @@
/**
* g_list_alloc:
- * @Returns: a pointer to the newly-allocated #GList element.
*
* Allocates space for one #GList element. It is called by
* g_list_append(), g_list_prepend(), g_list_insert() and
* g_list_insert_sorted() and so is rarely used on its own.
+ *
+ * Returns: a pointer to the newly-allocated #GList element.
*/
@@ -22982,9 +22691,7 @@
* Finds the element in a #GList which
* contains the given data.
*
- * or %NULL if it is not found
- *
- * Returns: the found #GList element,
+ * Returns: the found #GList element, or %NULL if it is not found
*/
@@ -23011,9 +22718,7 @@
*
* Gets the first element in a #GList.
*
- * or %NULL if the #GList has no elements
- *
- * Returns: the first element in the #GList,
+ * Returns: the first element in the #GList, or %NULL if the #GList has no elements
*/
@@ -23078,9 +22783,7 @@
* Gets the position of the element containing
* the given data (starting from 0).
*
- * or -1 if the data is not found
- *
- * Returns: the index of the element containing the data,
+ * Returns: the index of the element containing the data, or -1 if the data is not found
*/
@@ -23142,9 +22845,7 @@
*
* Gets the last element in a #GList.
*
- * or %NULL if the #GList has no elements
- *
- * Returns: the last element in the #GList,
+ * Returns: the last element in the #GList, or %NULL if the #GList has no elements
*/
@@ -23166,9 +22867,10 @@
/**
* g_list_next:
* @list: an element in a #GList.
- * @Returns: the next element, or %NULL if there are no more elements.
*
* A convenience macro to get the next element in a #GList.
+ *
+ * Returns: the next element, or %NULL if there are no more elements.
*/
@@ -23179,9 +22881,7 @@
*
* Gets the element at the given position in a #GList.
*
- * the end of the #GList
- *
- * Returns: the element, or %NULL if the position is off
+ * Returns: the element, or %NULL if the position is off the end of the #GList
*/
@@ -23192,9 +22892,7 @@
*
* Gets the data of the element at the given position.
*
- * is off the end of the #GList
- *
- * Returns: the element's data, or %NULL if the position
+ * Returns: the element's data, or %NULL if the position is off the end of the #GList
*/
@@ -23205,9 +22903,7 @@
*
* Gets the element @n places before @list.
*
- * off the end of the #GList
- *
- * Returns: the element, or %NULL if the position is
+ * Returns: the element, or %NULL if the position is off the end of the #GList
*/
@@ -23219,9 +22915,7 @@
* Gets the position of the given element
* in the #GList (starting from 0).
*
- * or -1 if the element is not found
- *
- * Returns: the position of the element in the #GList,
+ * Returns: the position of the element in the #GList, or -1 if the element is not found
*/
@@ -23251,9 +22945,10 @@
/**
* g_list_previous:
* @list: an element in a #GList.
- * @Returns: the previous element, or %NULL if there are no previous elements.
*
* A convenience macro to get the previous element in a #GList.
+ *
+ * Returns: the previous element, or %NULL if there are no previous elements.
*/
@@ -23345,9 +23040,7 @@
* use cases for environment variables in GLib-using programs you want
* the UTF-8 encoding that this function and g_getenv() provide.
*
- * list of strings which must be freed with g_strfreev().
- *
- * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated
+ * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated list of strings which must be freed with g_strfreev().
* Since: 2.8
*/
@@ -23416,21 +23109,21 @@
* The behavior of this log handler can be influenced by a number of
* environment variables:
* <variablelist>
- * <varlistentry>
- * <term><envar>G_MESSAGES_PREFIXED</envar></term>
- * <listitem>
- * A :-separated list of log levels for which messages should
- * be prefixed by the program name and PID of the aplication.
- * </listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><envar>G_MESSAGES_DEBUG</envar></term>
- * <listitem>
- * A space-separated list of log domains for which debug and
- * informational messages are printed. By default these
- * messages are not printed.
- * </listitem>
- * </varlistentry>
+ * <varlistentry>
+ * <term><envar>G_MESSAGES_PREFIXED</envar></term>
+ * <listitem>
+ * A :-separated list of log levels for which messages should
+ * be prefixed by the program name and PID of the aplication.
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><envar>G_MESSAGES_DEBUG</envar></term>
+ * <listitem>
+ * A space-separated list of log domains for which debug and
+ * informational messages are printed. By default these
+ * messages are not printed.
+ * </listitem>
+ * </varlistentry>
* </variablelist>
*
* stderr is used for levels %G_LOG_LEVEL_ERROR, %G_LOG_LEVEL_CRITICAL,
@@ -23513,7 +23206,7 @@
* (application) domain</title>
* <programlisting>
* g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
- * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
+ * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* </programlisting>
* </example>
*
@@ -23521,7 +23214,7 @@
* <title>Adding a log handler for all critical messages from GTK+</title>
* <programlisting>
* g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
- * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
+ * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* </programlisting>
* </example>
*
@@ -23530,7 +23223,7 @@
* GLib</title>
* <programlisting>
* g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
- * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
+ * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* </programlisting>
* </example>
*
@@ -23565,9 +23258,7 @@
*
* See your C library manual for more details about lstat().
*
- * occurred
- *
- * Returns: 0 if the information was successfully retrieved, -1 if an error
+ * Returns: 0 if the information was successfully retrieved, -1 if an error occurred
* Since: 2.6
*/
@@ -23587,9 +23278,7 @@
* can call g_main_context_prepare(), g_main_context_query(),
* g_main_context_check(), g_main_context_dispatch().
*
- * this thread is now the owner of @context.
- *
- * Returns: %TRUE if the operation succeeded, and
+ * Returns: %TRUE if the operation succeeded, and this thread is now the owner of @context.
*/
@@ -23701,9 +23390,7 @@
* If you need to hold a reference on the context, use
* g_main_context_ref_thread_default() instead.
*
- * %NULL if the thread-default context is the global default context.
- *
- * Returns: (transfer none): the thread-default #GMainContext, or
+ * Returns: (transfer none): the thread-default #GMainContext, or %NULL if the thread-default context is the global default context.
* Since: 2.22
*/
@@ -23836,9 +23523,7 @@
* Prepares to poll sources within a main loop. The resulting information
* for polling is determined by calling g_main_context_query ().
*
- * prior to polling.
- *
- * Returns: %TRUE if some source is ready to be dispatched
+ * Returns: %TRUE if some source is ready to be dispatched prior to polling.
*/
@@ -23889,10 +23574,7 @@
*
* Determines information necessary to poll this main loop.
*
- * or, if more than @n_fds records need to be stored, the number
- * of records that need to be stored.
- *
- * Returns: the number of records actually stored in @fds,
+ * Returns: the number of records actually stored in @fds, or, if more than @n_fds records need to be stored, the number of records that need to be stored.
*/
@@ -23916,9 +23598,7 @@
* is the global default context, this will return that #GMainContext
* (with a ref added to it) rather than returning %NULL.
*
- * with g_main_context_unref() when you are done with it.
- *
- * Returns: (transfer full): the thread-default #GMainContext. Unref
+ * Returns: (transfer full): the thread-default #GMainContext. Unref with g_main_context_unref() when you are done with it.
* Since: 2.32
*/
@@ -23936,6 +23616,7 @@
/**
* g_main_context_remove_poll:
+ * @context: a #GMainContext
* @fd: a #GPollFD descriptor previously added with g_main_context_add_poll()
*
* Removes file descriptor from the set of file descriptors to be
@@ -23979,9 +23660,7 @@
* that owner releases ownership or until @cond is signaled, then
* try again (once) to become the owner.
*
- * this thread is now the owner of @context.
- *
- * Returns: %TRUE if the operation succeeded, and
+ * Returns: %TRUE if the operation succeeded, and this thread is now the owner of @context.
*/
@@ -24009,7 +23688,7 @@
*
* Returns the depth of the stack of calls to
* g_main_context_dispatch() on any #GMainContext in the current thread.
- * That is, when called from the toplevel, it gives 0. When
+ * That is, when called from the toplevel, it gives 0. When
* called from within a callback from g_main_context_iteration()
* (or g_main_loop_run(), etc.) it returns 1. When called from within
* a callback to a recursive call to g_main_context_iteration(),
@@ -24024,28 +23703,28 @@
* gpointer
* allocate_memory (gsize size)
* {
- * gpointer result = g_malloc (size);
- * free_list = g_list_prepend (free_list, result);
- * return result;
+ * gpointer result = g_malloc (size);
+ * free_list = g_list_prepend (free_list, result);
+ * return result;
* }
*
* void
* free_allocated_memory (void)
* {
- * GList *l;
- * for (l = free_list; l; l = l->next);
- * g_free (l->data);
- * g_list_free (free_list);
- * free_list = NULL;
- * }
+ * GList *l;
+ * for (l = free_list; l; l = l->next);
+ * g_free (l->data);
+ * g_list_free (free_list);
+ * free_list = NULL;
+ * }
*
* [...]
*
* while (TRUE);
- * {
- * g_main_context_iteration (NULL, TRUE);
- * free_allocated_memory();
- * }
+ * {
+ * g_main_context_iteration (NULL, TRUE);
+ * free_allocated_memory();
+ * }
* ]|
*
* This works from an application, however, if you want to do the same
@@ -24059,33 +23738,33 @@
* gpointer
* allocate_memory (gsize size)
* {
- * FreeListBlock *block = g_new (FreeListBlock, 1);
- * block->mem = g_malloc (size);
- * block->depth = g_main_depth ();
- * free_list = g_list_prepend (free_list, block);
- * return block->mem;
+ * FreeListBlock *block = g_new (FreeListBlock, 1);
+ * block->mem = g_malloc (size);
+ * block->depth = g_main_depth ();
+ * free_list = g_list_prepend (free_list, block);
+ * return block->mem;
* }
*
* void
* free_allocated_memory (void)
* {
- * GList *l;
- *
- * int depth = g_main_depth ();
- * for (l = free_list; l; );
- * {
- * GList *next = l->next;
- * FreeListBlock *block = l->data;
- * if (block->depth > depth)
- * {
- * g_free (block->mem);
- * g_free (block);
- * free_list = g_list_delete_link (free_list, l);
- * }
- *
- * l = next;
- * }
- * }
+ * GList *l;
+ *
+ * int depth = g_main_depth ();
+ * for (l = free_list; l; );
+ * {
+ * GList *next = l->next;
+ * FreeListBlock *block = l->data;
+ * if (block->depth > depth)
+ * {
+ * g_free (block->mem);
+ * g_free (block);
+ * free_list = g_list_delete_link (free_list, l);
+ * }
+ *
+ * l = next;
+ * }
+ * }
* ]|
*
* There is a temptation to use g_main_depth() to solve
@@ -24101,21 +23780,21 @@
* following techniques:
*
* <orderedlist>
- * <listitem>
- * <para>
- * Use gtk_widget_set_sensitive() or modal dialogs to prevent
- * the user from interacting with elements while the main
- * loop is recursing.
- * </para>
- * </listitem>
- * <listitem>
- * <para>
- * Avoid main loop recursion in situations where you can't handle
- * arbitrary callbacks. Instead, structure your code so that you
- * simply return to the main loop and then get called again when
- * there is more work to do.
- * </para>
- * </listitem>
+ * <listitem>
+ * <para>
+ * Use gtk_widget_set_sensitive() or modal dialogs to prevent
+ * the user from interacting with elements while the main
+ * loop is recursing.
+ * </para>
+ * </listitem>
+ * <listitem>
+ * <para>
+ * Avoid main loop recursion in situations where you can't handle
+ * arbitrary callbacks. Instead, structure your code so that you
+ * simply return to the main loop and then get called again when
+ * there is more work to do.
+ * </para>
+ * </listitem>
* </orderedlist>
*
* Returns: The main loop recursion level in the current thread
@@ -24244,10 +23923,7 @@
* Checks if any events are pending for the default #GMainContext
* (i.e. ready to be processed).
*
- *
- * Deprected: 2.2: Use g_main_context_pending() instead.
- *
- * Returns: %TRUE if any events are pending.
+ * Returns: %TRUE if any events are pending. Deprected: 2.2: Use g_main_context_pending() instead.
*/
@@ -24338,9 +24014,8 @@
* This call existed before #GMappedFile had refcounting and is currently
* exactly the same as g_mapped_file_unref().
*
- * Deprecated:2.22: Use g_mapped_file_unref() instead.
- *
* Since: 2.8
+ * Deprecated: 2.22: Use g_mapped_file_unref() instead.
*/
@@ -24394,9 +24069,7 @@
* size 0 (e.g. device files such as /dev/null), @error will be set
* to the #GFileError value #G_FILE_ERROR_INVAL.
*
- * with g_mapped_file_unref(), or %NULL if the mapping failed.
- *
- * Returns: a newly allocated #GMappedFile which must be unref'd
+ * Returns: a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed.
* Since: 2.8
*/
@@ -24419,9 +24092,7 @@
* will not be modified, or if all modifications of the file are done
* atomically (e.g. using g_file_set_contents()).
*
- * with g_mapped_file_unref(), or %NULL if the mapping failed.
- *
- * Returns: a newly allocated #GMappedFile which must be unref'd
+ * Returns: a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed.
* Since: 2.32
*/
@@ -24608,10 +24279,7 @@
* g_markup_parse_context_new() or to the most recent call
* of g_markup_parse_context_push().
*
- * the markup context and will be freed when
- * g_markup_parse_context_free() is called.
- *
- * Returns: the provided user_data. The returned data belongs to
+ * Returns: the provided user_data. The returned data belongs to the markup context and will be freed when g_markup_parse_context_free() is called.
* Since: 2.18
*/
@@ -24717,39 +24385,39 @@
* |[
* typedef struct
* {
- * gint tag_count;
+ * gint tag_count;
* } CounterData;
*
* static void
* counter_start_element (GMarkupParseContext *context,
- * const gchar *element_name,
- * const gchar **attribute_names,
- * const gchar **attribute_values,
- * gpointer user_data,
- * GError **error)
+ * const gchar *element_name,
+ * const gchar **attribute_names,
+ * const gchar **attribute_values,
+ * gpointer user_data,
+ * GError **error)
* {
- * CounterData *data = user_data;
+ * CounterData *data = user_data;
*
- * data->tag_count++;
+ * data->tag_count++;
* }
*
* static void
* counter_error (GMarkupParseContext *context,
- * GError *error,
- * gpointer user_data)
+ * GError *error,
+ * gpointer user_data)
* {
- * CounterData *data = user_data;
+ * CounterData *data = user_data;
*
- * g_slice_free (CounterData, data);
+ * g_slice_free (CounterData, data);
* }
*
* static GMarkupParser counter_subparser =
* {
- * counter_start_element,
- * NULL,
- * NULL,
- * NULL,
- * counter_error
+ * counter_start_element,
+ * NULL,
+ * NULL,
+ * NULL,
+ * counter_error
* };
* ]|
*
@@ -24760,22 +24428,22 @@
* void
* start_counting (GMarkupParseContext *context)
* {
- * CounterData *data = g_slice_new (CounterData);
+ * CounterData *data = g_slice_new (CounterData);
*
- * data->tag_count = 0;
- * g_markup_parse_context_push (context, &counter_subparser, data);
+ * data->tag_count = 0;
+ * g_markup_parse_context_push (context, &counter_subparser, data);
* }
*
* gint
* end_counting (GMarkupParseContext *context)
* {
- * CounterData *data = g_markup_parse_context_pop (context);
- * int result;
+ * CounterData *data = g_markup_parse_context_pop (context);
+ * int result;
*
- * result = data->tag_count;
- * g_slice_free (CounterData, data);
+ * result = data->tag_count;
+ * g_slice_free (CounterData, data);
*
- * return result;
+ * return result;
* }
* ]|
*
@@ -24784,18 +24452,18 @@
* |[
* static void start_element (context, element_name, ...)
* {
- * if (strcmp (element_name, "count-these") == 0)
- * start_counting (context);
+ * 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, ...)
* {
- * if (strcmp (element_name, "count-these") == 0)
- * g_print ("Counted %d tags\n", end_counting (context));
+ * if (strcmp (element_name, "count-these") == 0)
+ * g_print ("Counted %d tags\n", end_counting (context));
*
- * /* else, handle other tags... */
+ * /* else, handle other tags... */
* }
* ]|
*
@@ -24821,15 +24489,13 @@
* char *output;
*
* output = g_markup_printf_escaped ("<purchase>"
- * "<store>%s</store>"
- * "<item>%s</item>"
- * "</purchase>",
- * store, item);
+ * "<store>%s</store>"
+ * "<item>%s</item>"
+ * "</purchase>",
+ * store, item);
* ]|
*
- * operation. Free with g_free().
- *
- * Returns: newly allocated result from formatting
+ * Returns: newly allocated result from formatting operation. Free with g_free().
* Since: 2.4
*/
@@ -24843,9 +24509,7 @@
* all string and character arguments in the fashion
* of g_markup_escape_text(). See g_markup_printf_escaped().
*
- * operation. Free with g_free().
- *
- * Returns: newly allocated result from formatting
+ * Returns: newly allocated result from formatting operation. Free with g_free().
* Since: 2.4
*/
@@ -24901,9 +24565,7 @@
* The string is fetched from the string passed to the match function,
* so you cannot call this function after freeing the string.
*
- * occurred. You have to free the string yourself
- *
- * Returns: (allow-none): The matched substring, or %NULL if an error
+ * Returns: (allow-none): The matched substring, or %NULL if an error occurred. You have to free the string yourself
* Since: 2.14
*/
@@ -24929,10 +24591,7 @@
* The strings are fetched from the string passed to the match function,
* so you cannot call this function after freeing the string.
*
- * It must be freed using g_strfreev(). If the previous match failed
- * %NULL is returned
- *
- * Returns: (allow-none): a %NULL-terminated array of gchar * pointers.
+ * Returns: (allow-none): a %NULL-terminated array of gchar * pointers. It must be freed using g_strfreev(). If the previous match failed %NULL is returned
* Since: 2.14
*/
@@ -24951,9 +24610,7 @@
* The string is fetched from the string passed to the match function,
* so you cannot call this function after freeing the string.
*
- * occurred. You have to free the string yourself
- *
- * Returns: (allow-none): The matched substring, or %NULL if an error
+ * Returns: (allow-none): The matched substring, or %NULL if an error occurred. You have to free the string yourself
* Since: 2.14
*/
@@ -24971,10 +24628,7 @@
* (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.
*
- * If the position cannot be fetched, @start_pos and @end_pos
- * are left unchanged.
- *
- * Returns: %TRUE if the position was fetched, %FALSE otherwise.
+ * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged.
* Since: 2.14
*/
@@ -25000,10 +24654,7 @@
* substring. Substrings are matched in reverse order of length, so
* 0 is the longest match.
*
- * the position cannot be fetched, @start_pos and @end_pos are left
- * unchanged
- *
- * Returns: %TRUE if the position was fetched, %FALSE otherwise. If
+ * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged
* Since: 2.14
*/
@@ -25111,9 +24762,7 @@
*
* Returns whether the previous match operation succeeded.
*
- * %FALSE otherwise
- *
- * Returns: %TRUE if the previous match operation succeeded,
+ * Returns: %TRUE if the previous match operation succeeded, %FALSE otherwise
* Since: 2.14
*/
@@ -25218,9 +24867,7 @@
* Allocates @byte_size bytes of memory, and copies @byte_size bytes into it
* from @mem. If @mem is %NULL it returns %NULL.
*
- * is %NULL.
- *
- * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem
+ * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem is %NULL.
*/
@@ -25259,9 +24906,7 @@
*
* See your C library manual for more details about mkdir().
*
- * occurred
- *
- * Returns: 0 if the directory was successfully created, -1 if an error
+ * Returns: 0 if the directory was successfully created, -1 if an error occurred
* Since: 2.6
*/
@@ -25274,9 +24919,7 @@
* Create a directory if it doesn't already exist. Create intermediate
* parent directories as needed, too.
*
- * created. Returns -1 if an error occurred, with errno set.
- *
- * Returns: 0 if the directory already exists, or was successfully
+ * Returns: 0 if the directory already exists, or was successfully created. Returns -1 if an error occurred, with errno set.
* Since: 2.8
*/
@@ -25297,10 +24940,7 @@
* The string should be in the GLib file name encoding. Most importantly,
* on Windows it should be in UTF-8.
*
- * to hold the directory name. In case of errors, %NULL is
- * returned and %errno will be set.
- *
- * Returns: A pointer to @tmpl, which has been modified
+ * Returns: A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned and %errno will be set.
* Since: 2.30
*/
@@ -25322,10 +24962,7 @@
* in the GLib file name encoding. Most importantly, on Windows it
* should be in UTF-8.
*
- * to hold the directory name. In case of errors, %NULL is
- * returned, and %errno will be set.
- *
- * Returns: A pointer to @tmpl, which has been modified
+ * Returns: A pointer to @tmpl, which has been modified to hold the directory name. In case of errors, %NULL is returned, and %errno will be set.
* Since: 2.30
*/
@@ -25345,12 +24982,7 @@
* didn't exist. The string should be in the GLib file name encoding.
* Most importantly, on Windows it should be in UTF-8.
*
- * opened for reading and writing. The file is opened in binary
- * mode on platforms where there is a difference. The file handle
- * should be closed with close(). In case of errors, -1 is
- * returned and %errno will be set.
- *
- * Returns: A file handle (as from open()) to the file
+ * Returns: A file handle (as from open()) to the file opened for reading and writing. The file is opened in binary mode on platforms where there is a difference. The file handle should be closed with close(). In case of errors, -1 is returned and %errno will be set.
*/
@@ -25372,11 +25004,7 @@
* The string should be in the GLib file name encoding. Most importantly,
* on Windows it should be in UTF-8.
*
- * opened for reading and writing. The file handle should be
- * closed with close(). In case of errors, -1 is returned
- * and %errno will be set.
- *
- * Returns: A file handle (as from open()) to the file
+ * Returns: A file handle (as from open()) to the file opened for reading and writing. The file handle should be closed with close(). In case of errors, -1 is returned and %errno will be set.
* Since: 2.22
*/
@@ -25409,10 +25037,10 @@
* created that has been statically allocated.
*
* |[
- * typedef struct {
- * GMutex m;
- * ...
- * } Blob;
+ * typedef struct {
+ * GMutex m;
+ * ...
+ * } Blob;
*
* Blob *b;
*
@@ -25552,9 +25180,7 @@
* Gets the position of the first child of a #GNode
* which contains the given data.
*
- * @data, or -1 if the data is not found
- *
- * Returns: the index of the child of @node which contains
+ * Returns: the index of the child of @node which contains @data, or -1 if the data is not found
*/
@@ -25660,9 +25286,7 @@
*
* Gets the first child of a #GNode.
*
- * or has no children
- *
- * Returns: the first child of @node, or %NULL if @node is %NULL
+ * Returns: the first child of @node, or %NULL if @node is %NULL or has no children
*/
@@ -25845,9 +25469,7 @@
*
* Gets the next sibling of a #GNode.
*
- * or %NULL
- *
- * Returns: the next sibling of @node, or %NULL if @node is the last node
+ * Returns: the next sibling of @node, or %NULL if @node is the last node or %NULL
*/
@@ -25892,9 +25514,7 @@
*
* Gets the previous sibling of a #GNode.
*
- * node or %NULL
- *
- * Returns: the previous sibling of @node, or %NULL if @node is the first
+ * Returns: the previous sibling of @node, or %NULL if @node is the first node or %NULL
*/
@@ -25973,25 +25593,25 @@
*
* static void
* log_handler (const gchar *log_domain,
- * GLogLevelFlags log_level,
- * const gchar *message,
- * gpointer user_data)
+ * GLogLevelFlags log_level,
+ * const gchar *message,
+ * gpointer user_data)
* {
- * g_log_default_handler (log_domain, log_level, message, user_data);
+ * g_log_default_handler (log_domain, log_level, message, user_data);
*
- * g_on_error_query (MY_PROGRAM_NAME);
+ * g_on_error_query (MY_PROGRAM_NAME);
* }
*
* int
* main (int argc, char *argv[])
* {
- * g_log_set_handler (MY_LOG_DOMAIN,
- * G_LOG_LEVEL_WARNING |
- * G_LOG_LEVEL_ERROR |
- * G_LOG_LEVEL_CRITICAL,
- * log_handler,
- * NULL);
- * /* ... */
+ * g_log_set_handler (MY_LOG_DOMAIN,
+ * G_LOG_LEVEL_WARNING |
+ * G_LOG_LEVEL_ERROR |
+ * G_LOG_LEVEL_CRITICAL,
+ * log_handler,
+ * NULL);
+ * /* ... */
* ]|
*
* If [E]xit is selected, the application terminates with a call
@@ -26041,15 +25661,15 @@
* @func will lead to a deadlock.
*
* |[
- * gpointer
- * get_debug_flags (void)
- * {
- * static GOnce my_once = G_ONCE_INIT;
+ * gpointer
+ * get_debug_flags (void)
+ * {
+ * static GOnce my_once = G_ONCE_INIT;
*
- * g_once (&my_once, parse_debug_flags, NULL);
+ * g_once (&my_once, parse_debug_flags, NULL);
*
- * return my_once.retval;
- * }
+ * return my_once.retval;
+ * }
* ]|
*
* Since: 2.4
@@ -26071,21 +25691,19 @@
* like this:
*
* |[
- * static gsize initialization_value = 0;
+ * static gsize initialization_value = 0;
*
- * if (g_once_init_enter (&initialization_value))
- * {
- * gsize setup_value = 42; /** initialization code here **/
+ * if (g_once_init_enter (&initialization_value))
+ * {
+ * gsize setup_value = 42; /** initialization code here **/
*
- * g_once_init_leave (&initialization_value, setup_value);
- * }
+ * g_once_init_leave (&initialization_value, setup_value);
+ * }
*
- * /** use initialization_value here **/
+ * /** use initialization_value here **/
* ]|
*
- * %FALSE and blocks otherwise
- *
- * Returns: %TRUE if the initialization section should be entered,
+ * Returns: %TRUE if the initialization section should be entered, %FALSE and blocks otherwise
* Since: 2.14
*/
@@ -26130,9 +25748,7 @@
*
* See your C library manual for more details about open().
*
- * return value can be used exactly like the return value from open().
- *
- * Returns: a new file descriptor, or -1 if an error occurred. The
+ * Returns: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from open().
* Since: 2.6
*/
@@ -26239,10 +25855,7 @@
*
* Returns a pointer to the main group of @context.
*
- * have a main group. Note that group belongs to @context and should
- * not be modified or freed.
- *
- * Returns: the main group of @context, or %NULL if @context doesn't
+ * Returns: the main group of @context, or %NULL if @context doesn't have a main group. Note that group belongs to @context and should not be modified or freed.
* Since: 2.6
*/
@@ -26282,9 +25895,7 @@
* function set with g_option_context_set_translate_func(), so
* it should normally be passed untranslated.
*
- * freed with g_option_context_free() after use.
- *
- * Returns: a newly created #GOptionContext, which must be
+ * Returns: a newly created #GOptionContext, which must be freed with g_option_context_free() after use.
* Since: 2.6
*/
@@ -26319,9 +25930,7 @@
* automatic character set conversion of string and filename
* arguments.
*
- * %FALSE if an error occurred
- *
- * Returns: %TRUE if the parsing was successful,
+ * Returns: %TRUE if the parsing was successful, %FALSE if an error occurred
* Since: 2.6
*/
@@ -26473,9 +26082,7 @@
*
* Creates a new #GOptionGroup.
*
- * to a #GOptionContext or freed with g_option_group_free().
- *
- * Returns: a newly created option group. It should be added
+ * Returns: a newly created option group. It should be added to a #GOptionContext or freed with g_option_group_free().
* Since: 2.6
*/
@@ -26578,9 +26185,7 @@
* separators (and on Windows, possibly a drive letter), a single
* separator is returned. If @file_name is empty, it gets ".".
*
- * component of the filename
- *
- * Returns: a newly allocated string containing the last
+ * Returns: a newly allocated string containing the last component of the filename
*/
@@ -26648,7 +26253,6 @@
* @string_length: the length of @string (in bytes, i.e. strlen(), <emphasis>not</emphasis> g_utf8_strlen())
* @string: the UTF-8 encoded string to match
* @string_reversed: (allow-none): the reverse of @string or %NULL
- * @Returns: %TRUE if @string matches @pspec
*
* Matches a string against a compiled pattern. Passing the correct
* length of the string given is mandatory. The reversed string can be
@@ -26668,6 +26272,8 @@
* only if the string doesn't contain any multibyte characters. GLib
* offers the g_utf8_strreverse() function to reverse UTF-8 encoded
* strings.
+ *
+ * Returns: %TRUE if @string matches @pspec
*/
@@ -26675,12 +26281,13 @@
* g_pattern_match_simple:
* @pattern: the UTF-8 encoded pattern
* @string: the UTF-8 encoded string to match
- * @Returns: %TRUE if @string matches @pspec
*
* Matches a string against a pattern given as a string. If this
* function is to be called in a loop, it's more efficient to compile
* the pattern once with g_pattern_spec_new() and call
* g_pattern_match_string() repeatedly.
+ *
+ * Returns: %TRUE if @string matches @pspec
*/
@@ -26688,11 +26295,12 @@
* g_pattern_match_string:
* @pspec: a #GPatternSpec
* @string: the UTF-8 encoded string to match
- * @Returns: %TRUE if @string matches @pspec
*
* Matches a string against a compiled pattern. If the string is to be
* matched against more than one pattern, consider using
* g_pattern_match() instead while supplying the reversed string.
+ *
+ * Returns: %TRUE if @string matches @pspec
*/
@@ -26700,10 +26308,11 @@
* g_pattern_spec_equal:
* @pspec1: a #GPatternSpec
* @pspec2: another #GPatternSpec
- * @Returns: Whether the compiled patterns are equal
*
* Compares two compiled pattern specs and returns whether they will
* match the same set of strings.
+ *
+ * Returns: Whether the compiled patterns are equal
*/
@@ -26718,9 +26327,10 @@
/**
* g_pattern_spec_new:
* @pattern: a zero-terminated UTF-8 encoded string
- * @Returns: a newly-allocated #GPatternSpec
*
* Compiles a pattern to a #GPatternSpec.
+ *
+ * Returns: a newly-allocated #GPatternSpec
*/
@@ -26794,10 +26404,7 @@
* Windows, the easiest solution is to construct all of your
* #GPollFD<!-- -->s with g_io_channel_win32_make_pollfd().
*
- * were filled in, or 0 if the operation timed out, or -1 on error or
- * if the call was interrupted.
- *
- * Returns: the number of entries in @fds whose %revents fields
+ * Returns: the number of entries in @fds whose %revents fields were filled in, or 0 if the operation timed out, or -1 on error or if the call was interrupted.
* Since: 2.20
*/
@@ -26807,10 +26414,10 @@
* @err: (allow-none): a return location for a #GError, or %NULL
* @format: printf()-style format string
* @...: arguments to @format
- * @err is %NULL (ie: no error variable) then do
*
* Formats a string according to @format and
* prefix it to an existing error message. If
+ * @err is %NULL (ie: no error variable) then do
* nothing.
*
* If * err is %NULL (ie: an error variable is
@@ -26973,7 +26580,6 @@
* g_ptr_array_free:
* @array: a #GPtrArray.
* @free_seg: if %TRUE the actual pointer array is freed as well.
- * @Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. The pointer array should be freed using g_free().
*
* Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
* it frees the memory block holding the elements as well. Pass %FALSE
@@ -26985,6 +26591,8 @@
* <note><para>If array contents point to dynamically-allocated
* memory, they should be freed separately if @free_seg is %TRUE and no
* #GDestroyNotify function has been set for @array.</para></note>
+ *
+ * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. The pointer array should be freed using g_free().
*/
@@ -26992,17 +26600,19 @@
* g_ptr_array_index:
* @array: a #GPtrArray.
* @index_: the index of the pointer to return.
- * @Returns: the pointer at the given index.
*
* Returns the pointer at the given index of the pointer array.
+ *
+ * Returns: the pointer at the given index.
*/
/**
* g_ptr_array_new:
- * @Returns: the new #GPtrArray.
*
* Creates a new #GPtrArray with a reference count of 1.
+ *
+ * Returns: the new #GPtrArray.
*/
@@ -27054,7 +26664,6 @@
* g_ptr_array_remove:
* @array: a #GPtrArray.
* @data: the pointer to remove.
- * @Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found in the array.
*
* Removes the first occurrence of the given pointer from the pointer
* array. The following elements are moved down one place. If @array
@@ -27063,6 +26672,8 @@
*
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
+ *
+ * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is not found in the array.
*/
@@ -27070,7 +26681,6 @@
* g_ptr_array_remove_fast:
* @array: a #GPtrArray.
* @data: the pointer to remove.
- * @Returns: %TRUE if the pointer was found in the array.
*
* Removes the first occurrence of the given pointer from the pointer
* array. The last element in the array is used to fill in the space,
@@ -27080,6 +26690,8 @@
*
* It returns %TRUE if the pointer was removed, or %FALSE if the
* pointer was not found.
+ *
+ * Returns: %TRUE if the pointer was found in the array.
*/
@@ -27087,12 +26699,13 @@
* g_ptr_array_remove_index:
* @array: a #GPtrArray.
* @index_: the index of the pointer to remove.
- * @Returns: the pointer which was removed.
*
* Removes the pointer at the given index from the pointer array. The
* following elements are moved down one place. If @array has a
* non-%NULL #GDestroyNotify function it is called for the removed
* element.
+ *
+ * Returns: the pointer which was removed.
*/
@@ -27100,13 +26713,14 @@
* g_ptr_array_remove_index_fast:
* @array: a #GPtrArray.
* @index_: the index of the pointer to remove.
- * @Returns: the pointer which was removed.
*
* Removes the pointer at the given index from the pointer array. The
* last element in the array is used to fill in the space, so this
* function does not preserve the order of the array. But it is faster
* than g_ptr_array_remove_index(). If @array has a non-%NULL
* #GDestroyNotify function it is called for the removed element.
+ *
+ * Returns: the pointer which was removed.
*/
@@ -27153,12 +26767,13 @@
/**
* g_ptr_array_sized_new:
* @reserved_size: number of pointers preallocated.
- * @Returns: the new #GPtrArray.
*
* Creates a new #GPtrArray with @reserved_size pointers preallocated
* and a reference count of 1. This avoids frequent reallocation, if
* you are going to add many pointers to the array. Note however that
* the size of the array is still 0.
+ *
+ * Returns: the new #GPtrArray.
*/
@@ -27228,7 +26843,6 @@
/**
* g_quark_from_static_string:
* @string: (allow-none): a string.
- * @Returns: the #GQuark identifying the string, or 0 if @string is %NULL.
*
* Gets the #GQuark identifying the given (static) string. If the
* string does not currently have an associated #GQuark, a new #GQuark
@@ -27242,39 +26856,44 @@
* statically allocated memory in dynamically loaded modules, if you
* expect to ever unload the module again (e.g. do not use this
* function in GTK+ theme engines).
+ *
+ * Returns: the #GQuark identifying the string, or 0 if @string is %NULL.
*/
/**
* g_quark_from_string:
* @string: (allow-none): a string.
- * @Returns: the #GQuark identifying the string, or 0 if @string is %NULL.
*
* Gets the #GQuark identifying the given string. If the string does
* not currently have an associated #GQuark, a new #GQuark is created,
* using a copy of the string.
+ *
+ * Returns: the #GQuark identifying the string, or 0 if @string is %NULL.
*/
/**
* g_quark_to_string:
* @quark: a #GQuark.
- * @Returns: the string associated with the #GQuark.
*
* Gets the string associated with the given #GQuark.
+ *
+ * Returns: the string associated with the #GQuark.
*/
/**
* g_quark_try_string:
* @string: (allow-none): a string.
- * @Returns: the #GQuark associated with the string, or 0 if @string is %NULL or there is no #GQuark associated with it.
*
* Gets the #GQuark associated with the given string, or 0 if string is
* %NULL or it has no associated #GQuark.
*
* If you want the GQuark to be created if it doesn't already exist,
* use g_quark_from_string() or g_quark_from_static_string().
+ *
+ * Returns: the #GQuark associated with the string, or 0 if @string is %NULL or there is no #GQuark associated with it.
*/
@@ -27479,9 +27098,7 @@
*
* Returns the position of @link_ in @queue.
*
- * not part of @queue
- *
- * Returns: The position of @link_, or -1 if the link is
+ * Returns: The position of @link_, or -1 if the link is not part of @queue
* Since: 2.4
*/
@@ -27501,9 +27118,7 @@
*
* Returns the first element of the queue.
*
- * is empty.
- *
- * Returns: the data of the first element in the queue, or %NULL if the queue
+ * Returns: the data of the first element in the queue, or %NULL if the queue is empty.
*/
@@ -27525,9 +27140,7 @@
*
* Returns the @n'th element of @queue.
*
- * off the end of @queue.
- *
- * Returns: The data for the @n'th element of @queue, or %NULL if @n is
+ * Returns: The data for the @n'th element of @queue, or %NULL if @n is off the end of @queue.
* Since: 2.4
*/
@@ -27539,9 +27152,7 @@
*
* Returns the link at the given position
*
- * end of the list
- *
- * Returns: The link at the @n'th position, or %NULL if @n is off the
+ * Returns: The link at the @n'th position, or %NULL if @n is off the end of the list
* Since: 2.4
*/
@@ -27552,9 +27163,7 @@
*
* Returns the last element of the queue.
*
- * is empty.
- *
- * Returns: the data of the last element in the queue, or %NULL if the queue
+ * Returns: the data of the last element in the queue, or %NULL if the queue is empty.
*/
@@ -27575,9 +27184,7 @@
*
* Removes the first element of the queue.
*
- * is empty.
- *
- * Returns: the data of the first element in the queue, or %NULL if the queue
+ * Returns: the data of the first element in the queue, or %NULL if the queue is empty.
*/
@@ -27587,9 +27194,7 @@
*
* Removes the first element of the queue.
*
- * is empty.
- *
- * Returns: the #GList element at the head of the queue, or %NULL if the queue
+ * Returns: the #GList element at the head of the queue, or %NULL if the queue is empty.
*/
@@ -27623,9 +27228,7 @@
*
* Removes the last element of the queue.
*
- * is empty.
- *
- * Returns: the data of the last element in the queue, or %NULL if the queue
+ * Returns: the data of the last element in the queue, or %NULL if the queue is empty.
*/
@@ -27635,9 +27238,7 @@
*
* Removes the last element of the queue.
*
- * is empty.
- *
- * Returns: the #GList element at the tail of the queue, or %NULL if the queue
+ * Returns: the #GList element at the tail of the queue, or %NULL if the queue is empty.
*/
@@ -27764,10 +27365,11 @@
/**
* g_rand_boolean:
* @rand_: a #GRand.
- * @Returns: a random #gboolean.
*
* Returns a random #gboolean from @rand_. This corresponds to a
* unbiased coin toss.
+ *
+ * Returns: a random #gboolean.
*/
@@ -27900,9 +27502,10 @@
/**
* g_random_boolean:
- * @Returns: a random #gboolean.
*
* Returns a random #gboolean. This corresponds to a unbiased coin toss.
+ *
+ * Returns: a random #gboolean.
*/
@@ -28017,10 +27620,10 @@
* statically allocated.
*
* |[
- * typedef struct {
- * GRecMutex m;
- * ...
- * } Blob;
+ * typedef struct {
+ * GRecMutex m;
+ * ...
+ * } Blob;
*
* Blob *b;
*
@@ -28201,9 +27804,7 @@
*
* Retrieves the number of the subexpression named @name.
*
- * does not exists
- *
- * Returns: The number of the subexpression or -1 if @name
+ * Returns: The number of the subexpression or -1 if @name does not exists
* Since: 2.14
*/
@@ -28232,21 +27833,21 @@
* static void
* print_uppercase_words (const gchar *string)
* {
- * /* Print all uppercase-only words. */
- * GRegex *regex;
- * GMatchInfo *match_info;
- *
- * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- * g_regex_match (regex, string, 0, &match_info);
- * while (g_match_info_matches (match_info))
- * {
- * gchar *word = g_match_info_fetch (match_info, 0);
- * g_print ("Found: %s\n", word);
- * g_free (word);
- * g_match_info_next (match_info, NULL);
- * }
- * g_match_info_free (match_info);
- * g_regex_unref (regex);
+ * /* Print all uppercase-only words. */
+ * GRegex *regex;
+ * GMatchInfo *match_info;
+ *
+ * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
+ * g_regex_match (regex, string, 0, &match_info);
+ * while (g_match_info_matches (match_info))
+ * {
+ * gchar *word = g_match_info_fetch (match_info, 0);
+ * g_print ("Found: %s\n", word);
+ * g_free (word);
+ * g_match_info_next (match_info, NULL);
+ * }
+ * g_match_info_free (match_info);
+ * g_regex_unref (regex);
* }
* ]|
*
@@ -28374,27 +27975,27 @@
* static void
* print_uppercase_words (const gchar *string)
* {
- * /* Print all uppercase-only words. */
- * GRegex *regex;
- * GMatchInfo *match_info;
- * GError *error = NULL;
- *
- * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
- * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
- * while (g_match_info_matches (match_info))
- * {
- * gchar *word = g_match_info_fetch (match_info, 0);
- * g_print ("Found: %s\n", word);
- * g_free (word);
- * g_match_info_next (match_info, &error);
- * }
- * g_match_info_free (match_info);
- * g_regex_unref (regex);
- * if (error != NULL)
- * {
- * g_printerr ("Error while matching: %s\n", error->message);
- * g_error_free (error);
- * }
+ * /* Print all uppercase-only words. */
+ * GRegex *regex;
+ * GMatchInfo *match_info;
+ * GError *error = NULL;
+ *
+ * regex = g_regex_new ("[A-Z]+", 0, 0, NULL);
+ * g_regex_match_full (regex, string, -1, 0, 0, &match_info, &error);
+ * while (g_match_info_matches (match_info))
+ * {
+ * gchar *word = g_match_info_fetch (match_info, 0);
+ * g_print ("Found: %s\n", word);
+ * g_free (word);
+ * g_match_info_next (match_info, &error);
+ * }
+ * g_match_info_free (match_info);
+ * g_regex_unref (regex);
+ * if (error != NULL)
+ * {
+ * g_printerr ("Error while matching: %s\n", error->message);
+ * g_error_free (error);
+ * }
* }
* ]|
*
@@ -28436,9 +28037,7 @@
* Compiles the regular expression to an internal form, and does
* the initial setup of the #GRegex structure.
*
- * are done with it
- *
- * Returns: a #GRegex structure. Call g_regex_unref() when you
+ * Returns: a #GRegex structure. Call g_regex_unref() when you are done with it
* Since: 2.14
*/
@@ -28539,18 +28138,18 @@
* |[
* static gboolean
* eval_cb (const GMatchInfo *info,
- * GString *res,
- * gpointer data)
+ * GString *res,
+ * gpointer data)
* {
- * gchar *match;
- * gchar *r;
+ * gchar *match;
+ * gchar *r;
*
- * match = g_match_info_fetch (info, 0);
- * r = g_hash_table_lookup ((GHashTable *)data, match);
- * g_string_append (res, r);
- * g_free (match);
+ * match = g_match_info_fetch (info, 0);
+ * r = g_hash_table_lookup ((GHashTable *)data, match);
+ * g_string_append (res, r);
+ * g_free (match);
*
- * return FALSE;
+ * return FALSE;
* }
*
* /* ... */
@@ -28756,9 +28355,7 @@
* fail. Any errno value set by remove() will be overwritten by that
* set by rmdir().
*
- * occurred
- *
- * Returns: 0 if the file was successfully removed, -1 if an error
+ * Returns: 0 if the file was successfully removed, -1 if an error occurred
* Since: 2.6
*/
@@ -28805,9 +28402,7 @@
* See your C library manual for more details about how rmdir() works
* on your system.
*
- * occurred
- *
- * Returns: 0 if the directory was successfully removed, -1 if an error
+ * Returns: 0 if the directory was successfully removed, -1 if an error occurred
* Since: 2.6
*/
@@ -28840,10 +28435,10 @@
* allocated.
*
* |[
- * typedef struct {
- * GRWLock l;
- * ...
- * } Blob;
+ * typedef struct {
+ * GRWLock l;
+ * ...
+ * } Blob;
*
* Blob *b;
*
@@ -29013,9 +28608,7 @@
* Returns %TRUE if the scanner has reached the end of
* the file or text buffer.
*
- * the file or text buffer
- *
- * Returns: %TRUE if the scanner has reached the end of
+ * Returns: %TRUE if the scanner has reached the end of the file or text buffer
*/
@@ -29092,9 +28685,7 @@
* If the symbol is not bound in the current scope, %NULL is
* returned.
*
- * if @symbol is not bound in the current scope
- *
- * Returns: the value of @symbol in the current scope, or %NULL
+ * Returns: the value of @symbol in the current scope, or %NULL if @symbol is not bound in the current scope
*/
@@ -29178,9 +28769,7 @@
* Looks up a symbol in a scope and return its value. If the
* symbol is not bound in the scope, %NULL is returned.
*
- * if @symbol is not bound in the given scope.
- *
- * Returns: the value of @symbol in the given scope, or %NULL
+ * Returns: the value of @symbol in the given scope, or %NULL if @symbol is not bound in the given scope.
*/
@@ -29433,9 +29022,7 @@
*
* The @a and @b iterators must point into the same sequence.
*
- * equal, and a positive number if @a comes after @b.
- *
- * Returns: A negative number if @a comes before @b, 0 if they are
+ * Returns: A negative number if @a comes before @b, 0 if they are equal, and a positive number if @a comes after @b.
* Since: 2.14
*/
@@ -29518,9 +29105,7 @@
* Returns an iterator pointing to the previous position before @iter. If
* @iter is the begin iterator, the begin iterator is returned.
*
- * @iter.
- *
- * Returns: a #GSequenceIter pointing to the previous position before
+ * Returns: a #GSequenceIter pointing to the previous position before @iter.
* Since: 2.14
*/
@@ -29551,9 +29136,7 @@
* doing unsorted insertions.
* </para></note>
*
- * first item found equal to @data according to @cmp_func and @cmp_data.
- *
- * Returns: an #GSequenceIter pointing to the position of the
+ * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data.
* Since: 2.28
*/
@@ -29581,10 +29164,7 @@
* doing unsorted insertions.
* </para></note>
*
- * the first item found equal to @data according to @cmp_func
- * and @cmp_data.
- *
- * Returns: an #GSequenceIter pointing to the position of
+ * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data.
* Since: 2.28
*/
@@ -29659,9 +29239,7 @@
* The @begin and @end iterators must both point to the same sequence and
* @begin must come before or be equal to @end in the sequence.
*
- * (@begin, @end) range.
- *
- * Returns: A #GSequenceIter pointing somewhere in the
+ * Returns: A #GSequenceIter pointing somewhere in the (@begin, @end) range.
* Since: 2.14
*/
@@ -29720,9 +29298,7 @@
* doing unsorted insertions.
* </para></note>
*
- * would have been inserted according to @cmp_func and @cmp_data.
- *
- * Returns: an #GSequenceIter pointing to the position where @data
+ * Returns: an #GSequenceIter pointing to the position where @data would have been inserted according to @cmp_func and @cmp_data.
* Since: 2.14
*/
@@ -29753,10 +29329,7 @@
* doing unsorted insertions.
* </para></note>
*
- * where @data would have been inserted according to @iter_cmp
- * and @cmp_data.
- *
- * Returns: a #GSequenceIter pointing to the position in @seq
+ * Returns: a #GSequenceIter pointing to the position in @seq where @data would have been inserted according to @iter_cmp and @cmp_data.
* Since: 2.14
*/
@@ -30332,11 +29905,12 @@
/**
* g_slist_alloc:
- * @Returns: a pointer to the newly-allocated #GSList element.
*
* Allocates space for one #GSList element. It is called by the
* g_slist_append(), g_slist_prepend(), g_slist_insert() and
* g_slist_insert_sorted() functions and so is rarely used on its own.
+ *
+ * Returns: a pointer to the newly-allocated #GSList element.
*/
@@ -30426,9 +30000,7 @@
* Finds the element in a #GSList which
* contains the given data.
*
- * or %NULL if it is not found
- *
- * Returns: the found #GSList element,
+ * Returns: the found #GSList element, or %NULL if it is not found
*/
@@ -30512,9 +30084,7 @@
* Gets the position of the element containing
* the given data (starting from 0).
*
- * or -1 if the data is not found
- *
- * Returns: the index of the element containing the data,
+ * Returns: the index of the element containing the data, or -1 if the data is not found
*/
@@ -30580,9 +30150,7 @@
* This function iterates over the whole list.
* </para></note>
*
- * or %NULL if the #GSList has no elements
- *
- * Returns: the last element in the #GSList,
+ * Returns: the last element in the #GSList, or %NULL if the #GSList has no elements
*/
@@ -30604,9 +30172,10 @@
/**
* g_slist_next:
* @slist: an element in a #GSList.
- * @Returns: the next element, or %NULL if there are no more elements.
*
* A convenience macro to get the next element in a #GSList.
+ *
+ * Returns: the next element, or %NULL if there are no more elements.
*/
@@ -30617,9 +30186,7 @@
*
* Gets the element at the given position in a #GSList.
*
- * the end of the #GSList
- *
- * Returns: the element, or %NULL if the position is off
+ * Returns: the element, or %NULL if the position is off the end of the #GSList
*/
@@ -30630,9 +30197,7 @@
*
* Gets the data of the element at the given position.
*
- * is off the end of the #GSList
- *
- * Returns: the element's data, or %NULL if the position
+ * Returns: the element's data, or %NULL if the position is off the end of the #GSList
*/
@@ -30644,9 +30209,7 @@
* Gets the position of the given element
* in the #GSList (starting from 0).
*
- * or -1 if the element is not found
- *
- * Returns: the position of the element in the #GSList,
+ * Returns: the position of the element in the #GSList, or -1 if the element is not found
*/
@@ -30772,14 +30335,13 @@
* The format string may contain positional parameters, as specified in
* the Single Unix Specification.
*
- * was large enough.
- *
- * Returns: the number of bytes which would be produced if the buffer
+ * Returns: the number of bytes which would be produced if the buffer was large enough.
*/
/**
* g_source_add_child_source:
+ * @source: a #GSource
* @child_source: a second #GSource that @source should "poll"
*
* Adds @child_source to @source as a "polled" source; when @source is
@@ -30803,6 +30365,7 @@
/**
* g_source_add_poll:
+ * @source: a #GSource
* @fd: a #GPollFD structure holding information about a file descriptor to watch.
*
* Adds a file descriptor to the set of file descriptors polled for
@@ -30821,9 +30384,7 @@
* Adds a #GSource to a @context so that it will be executed within
* that context. Remove it by calling g_source_destroy().
*
- * #GMainContext.
- *
- * Returns: the ID (greater than 0) for the source within the
+ * Returns: the ID (greater than 0) for the source within the #GMainContext.
*/
@@ -30855,10 +30416,7 @@
* Gets the #GMainContext with which the source is associated.
* Calling this function on a destroyed source is an error.
*
- * source is associated, or %NULL if the context has not
- * yet been added to a source.
- *
- * Returns: (transfer none) (allow-none): the #GMainContext with which the
+ * Returns: (transfer none) (allow-none): the #GMainContext with which the source is associated, or %NULL if the context has not yet been added to a source.
*/
@@ -30941,31 +30499,31 @@
* static gboolean
* idle_callback (gpointer data)
* {
- * SomeWidget *self = data;
+ * SomeWidget *self = data;
*
- * GDK_THREADS_ENTER (<!-- -->);
- * /<!-- -->* do stuff with self *<!-- -->/
- * self->idle_id = 0;
- * GDK_THREADS_LEAVE (<!-- -->);
+ * GDK_THREADS_ENTER (<!-- -->);
+ * /<!-- -->* do stuff with self *<!-- -->/
+ * self->idle_id = 0;
+ * GDK_THREADS_LEAVE (<!-- -->);
*
- * return G_SOURCE_REMOVE;
+ * return G_SOURCE_REMOVE;
* }
*
* static void
* some_widget_do_stuff_later (SomeWidget *self)
* {
- * self->idle_id = g_idle_add (idle_callback, self);
+ * self->idle_id = g_idle_add (idle_callback, self);
* }
*
* static void
* some_widget_finalize (GObject *object)
* {
- * SomeWidget *self = SOME_WIDGET (object);
+ * SomeWidget *self = SOME_WIDGET (object);
*
- * if (self->idle_id)
- * g_source_remove (self->idle_id);
+ * if (self->idle_id)
+ * g_source_remove (self->idle_id);
*
- * G_OBJECT_CLASS (parent_class)->finalize (object);
+ * G_OBJECT_CLASS (parent_class)->finalize (object);
* }
* ]|
*
@@ -30979,16 +30537,16 @@
* static gboolean
* idle_callback (gpointer data)
* {
- * SomeWidget *self = data;
+ * SomeWidget *self = data;
*
- * GDK_THREADS_ENTER ();
- * if (!g_source_is_destroyed (g_main_current_source ()))
- * {
- * /<!-- -->* do stuff with self *<!-- -->/
- * }
- * GDK_THREADS_LEAVE ();
+ * GDK_THREADS_ENTER ();
+ * if (!g_source_is_destroyed (g_main_current_source ()))
+ * {
+ * /<!-- -->* do stuff with self *<!-- -->/
+ * }
+ * GDK_THREADS_LEAVE ();
*
- * return FALSE;
+ * return FALSE;
* }
* ]|
*
@@ -31070,6 +30628,7 @@
/**
* g_source_remove_child_source:
+ * @source: a #GSource
* @child_source: a #GSource previously passed to g_source_add_child_source().
*
* Detaches @child_source from @source and destroys it.
@@ -31080,6 +30639,7 @@
/**
* g_source_remove_poll:
+ * @source: a #GSource
* @fd: a #GPollFD structure previously passed to g_source_add_poll().
*
* Removes a file descriptor from the set of file descriptors polled for
@@ -31213,9 +30773,7 @@
* The built-in array of primes ranges from 11 to 13845163 such that
* each prime is approximately 1.5-2 times the previous prime.
*
- * which is larger than @num
- *
- * Returns: the smallest prime number from a built-in array of primes
+ * Returns: the smallest prime number from a built-in array of primes which is larger than @num
*/
@@ -31567,9 +31125,7 @@
*
* See your C library manual for more details about stat().
*
- * occurred
- *
- * Returns: 0 if the information was successfully retrieved, -1 if an error
+ * Returns: 0 if the information was successfully retrieved, -1 if an error occurred
* Since: 2.6
*/
@@ -31660,7 +31216,7 @@
* Modifies @string in place, and return @string itself, not
* a copy. The return value is to allow nesting such as
* |[
- * g_ascii_strup (g_strcanon (str, "abc", '?'))
+ * g_ascii_strup (g_strcanon (str, "abc", '?'))
* ]|
*
* Returns: @string
@@ -31675,12 +31231,8 @@
* A case-insensitive string comparison, corresponding to the standard
* strcasecmp() function on platforms which support it.
*
- * or a positive value if @s1 > @s2.
- *
- * Deprecated:2.2: See g_strncasecmp() for a discussion of why this function
- * is deprecated and how to replace it.
- *
- * Returns: 0 if the strings match, a negative 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.
*/
@@ -31739,9 +31291,7 @@
*
* This function does the reverse conversion of g_strescape().
*
- * character compressed
- *
- * Returns: a newly-allocated copy of @source with all escaped
+ * Returns: a newly-allocated copy of @source with all escaped character compressed
*/
@@ -31777,7 +31327,7 @@
* and returns @string itself, not a copy. The return value is to
* allow nesting such as
* |[
- * g_ascii_strup (g_strdelimit (str, "abc", '?'))
+ * g_ascii_strup (g_strdelimit (str, "abc", '?'))
* ]|
*
* Returns: @string
@@ -31790,12 +31340,8 @@
*
* Converts a string to lower case.
*
- *
- * Deprecated:2.2: This function is totally broken for the reasons discussed
- * in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown()
- * instead.
- *
* Returns: the string
+ * Deprecated: 2.2: This function is totally broken for the reasons discussed in the g_strncasecmp() docs - use g_ascii_strdown() or g_utf8_strdown() instead.
*/
@@ -31864,9 +31410,7 @@
* strerror(), because it returns a string in UTF-8 encoding, and since
* not all platforms support the strerror() function.
*
- * is unknown, it returns "unknown error (<code>)".
- *
- * Returns: a UTF-8 string describing the error code. If the error code
+ * Returns: a UTF-8 string describing the error code. If the error code is unknown, it returns "unknown error (<code>)".
*/
@@ -31884,17 +31428,16 @@
*
* g_strcompress() does the reverse conversion.
*
- * characters escaped. See above.
- *
- * Returns: a newly-allocated copy of @source with certain
+ * Returns: a newly-allocated copy of @source with certain characters escaped. See above.
*/
/**
* g_strfreev:
- * @str_array: a %NULL-terminated array of strings to free Frees a %NULL-terminated array of strings, and the array itself. If called on a %NULL value, g_strfreev() simply returns.
- *
+ * @str_array: a %NULL-terminated array of strings to free
*
+ * Frees a %NULL-terminated array of strings, and the array itself.
+ * If called on a %NULL value, g_strfreev() simply returns.
*/
@@ -32000,10 +31543,7 @@
*
* Converts all uppercase ASCII letters to lowercase ASCII letters.
*
- * uppercase characters converted to lowercase in place,
- * with semantics that exactly match g_ascii_tolower().
- *
- * Returns: passed-in @string pointer, with all the
+ * Returns: passed-in @string pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match g_ascii_tolower().
*/
@@ -32013,10 +31553,7 @@
*
* Converts all lowercase ASCII letters to uppercase ASCII letters.
*
- * lowercase characters converted to uppercase in place,
- * with semantics that exactly match g_ascii_toupper().
- *
- * Returns: passed-in @string pointer, with all the
+ * Returns: passed-in @string pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match g_ascii_toupper().
*/
@@ -32073,9 +31610,7 @@
* by g_string_chunk_insert_const() when looking for
* duplicates.
*
- * the #GStringChunk
- *
- * Returns: a pointer to the copy of @string within
+ * Returns: a pointer to the copy of @string within the #GStringChunk
*/
@@ -32098,9 +31633,7 @@
* pointer to a string added with g_string_chunk_insert(), even
* if they do match.
*
- * within the #GStringChunk
- *
- * Returns: a pointer to the new or existing copy of @string
+ * Returns: a pointer to the new or existing copy of @string within the #GStringChunk
*/
@@ -32141,12 +31674,8 @@
*
* Converts a #GString to lowercase.
*
- *
- * Deprecated:2.2: This function uses the locale-specific
- * tolower() function, which is almost never the right thing.
- * Use g_string_ascii_down() or g_utf8_strdown() instead.
- *
* Returns: the #GString
+ * Deprecated: 2.2: This function uses the locale-specific tolower() function, which is almost never the right thing. Use g_string_ascii_down() or g_utf8_strdown() instead.
*/
@@ -32158,9 +31687,7 @@
* Compares two strings for equality, returning %TRUE if they are equal.
* For use with #GHashTable.
*
- * same bytes
- *
- * Returns: %TRUE if they strings are the same length and contain the
+ * Returns: %TRUE if they strings are the same length and contain the same bytes
*/
@@ -32187,9 +31714,7 @@
* it's %FALSE, the caller gains ownership of the buffer and must
* free it after use with g_free().
*
- * (i.e. %NULL if @free_segment is %TRUE)
- *
- * Returns: the character data of @string
+ * Returns: the character data of @string (i.e. %NULL if @free_segment is %TRUE)
*/
@@ -32459,12 +31984,8 @@
*
* Converts a #GString to uppercase.
*
- *
- * Deprecated:2.2: This function uses the locale-specific
- * toupper() function, which is almost never the right thing.
- * Use g_string_ascii_up() or g_utf8_strup() instead.
- *
* Returns: @string
+ * Deprecated: 2.2: This function uses the locale-specific toupper() function, which is almost never the right thing. Use g_string_ascii_up() or g_utf8_strup() instead.
*/
@@ -32489,10 +32010,7 @@
*
* An auxiliary function for gettext() support (see Q_()).
*
- * and contains a '|' character, in which case a pointer to
- * the substring of msgid after the first '|' character is returned.
- *
- * Returns: @msgval, unless @msgval is identical to @msgid
+ * Returns: @msgval, unless @msgval is identical to @msgid and contains a '|' character, in which case a pointer to the substring of msgid after the first '|' character is returned.
* Since: 2.4
*/
@@ -32506,9 +32024,7 @@
* optional @separator inserted between each of them. The returned string
* should be freed with g_free().
*
- * together, with @separator between them
- *
- * Returns: a newly-allocated string containing all of the strings joined
+ * Returns: a newly-allocated string containing all of the strings joined together, with @separator between them
*/
@@ -32521,9 +32037,7 @@
* optional @separator inserted between each of them. The returned string
* should be freed with g_free().
*
- * together, with @separator between them
- *
- * Returns: a newly-allocated string containing all of the strings joined
+ * Returns: a newly-allocated string containing all of the strings joined together, with @separator between them
*/
@@ -32548,10 +32062,7 @@
* strcat() or strncat(), but for real security g_strconcat() is harder
* to mess up.</para></note>
*
- * (original dest)) + strlen (src), so if retval >= dest_size,
- * truncation occurred.
- *
- * Returns: size of attempted result, which is MIN (dest_size, strlen
+ * Returns: size of attempted result, which is MIN (dest_size, strlen (original dest)) + strlen (src), so if retval >= dest_size, truncation occurred.
*/
@@ -32591,23 +32102,8 @@
* It is similar to g_strcasecmp() except it only compares the first @n
* characters of the strings.
*
- * or a positive value if @s1 > @s2.
- *
- * Deprecated:2.2: The problem with g_strncasecmp() is that it does the
- * comparison by calling toupper()/tolower(). These functions are
- * locale-specific and operate on single bytes. However, it is impossible
- * to handle things correctly from an I18N standpoint by operating on
- * bytes, since characters may be multibyte. Thus g_strncasecmp() is
- * broken if your string is guaranteed to be ASCII, since it's
- * locale-sensitive, and it's broken if your string is localized, since
- * it doesn't work on many encodings at all, including UTF-8, EUC-JP,
- * etc.
- *
- * There are therefore two replacement functions: g_ascii_strncasecmp(),
- * which only works on ASCII and is not locale-sensitive, and
- * g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8.
- *
- * Returns: 0 if the strings match, a negative 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 impossible to handle things correctly from an I18N standpoint by operating on bytes, since characters may be multibyte. Thus g_strncasecmp() is broken if your string is guaranteed to be ASCII, since it's locale-sensitive, and it's broken if your string is localized, since it doesn't work on many encodings at all, including UTF-8, EUC-JP, etc. There are therefore two replacement functions: g_ascii_strncasecmp(), which only works on ASCII and is not locale-sensitive, and g_utf8_casefold(), which is good for case-insensitive sorting of UTF-8.
*/
@@ -32627,9 +32123,7 @@
* g_utf8_strncpy() instead.
* </para></note>
*
- * of @str, nul-terminated
- *
- * Returns: a newly-allocated buffer containing the first @n bytes
+ * Returns: a newly-allocated buffer containing the first @n bytes of @str, nul-terminated
*/
@@ -32669,9 +32163,7 @@
* Searches the string @haystack for the last occurrence
* of the string @needle.
*
- * %NULL if not found.
- *
- * Returns: a pointer to the found occurrence, or
+ * Returns: a pointer to the found occurrence, or %NULL if not found.
*/
@@ -32685,9 +32177,7 @@
* of the string @needle, limiting the length of the search
* to @haystack_len.
*
- * %NULL if not found.
- *
- * Returns: a pointer to the found occurrence, or
+ * Returns: a pointer to the found occurrence, or %NULL if not found.
*/
@@ -32700,9 +32190,7 @@
* returns a string in UTF-8 encoding, and since not all platforms support
* the strsignal() function.
*
- * it returns "unknown signal (<signum>)".
- *
- * Returns: a UTF-8 string describing the signal. If the signal is unknown,
+ * Returns: a UTF-8 string describing the signal. If the signal is unknown, it returns "unknown signal (<signum>)".
*/
@@ -32723,9 +32211,7 @@
* to represent empty elements, you'll need to check for the empty string
* before calling g_strsplit().
*
- * g_strfreev() to free it.
- *
- * Returns: a newly-allocated %NULL-terminated array of strings. Use
+ * Returns: a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
*/
@@ -32757,9 +32243,7 @@
* Note that this function works on bytes not characters, so it can't be used
* to delimit UTF-8 strings for anything but ASCII characters.
*
- * g_strfreev() to free it.
- *
- * Returns: a newly-allocated %NULL-terminated array of strings. Use
+ * Returns: a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it.
* Since: 2.4
*/
@@ -32774,9 +32258,7 @@
* of the string @needle, limiting the length of the search
* to @haystack_len.
*
- * %NULL if not found.
- *
- * Returns: a pointer to the found occurrence, or
+ * Returns: a pointer to the found occurrence, or %NULL if not found.
*/
@@ -32818,11 +32300,8 @@
*
* Converts a string to upper case.
*
- *
- * Deprecated:2.2: This function is totally broken for the reasons discussed
- * in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
- *
* Returns: the string
+ * Deprecated: 2.2: This function is totally broken for the reasons discussed in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead.
*/
@@ -33003,90 +32482,90 @@
* and parsing test related command line args.
* So far, the following arguments are understood:
* <variablelist>
- * <varlistentry>
- * <term><option>-l</option></term>
- * <listitem><para>
- * list test cases available in a test executable.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>--seed=<replaceable>RANDOMSEED</replaceable></option></term>
- * <listitem><para>
- * provide a random seed to reproduce test runs using random numbers.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>--verbose</option></term>
- * <listitem><para>run tests verbosely.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>-q</option>, <option>--quiet</option></term>
- * <listitem><para>run tests quietly.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>-p <replaceable>TESTPATH</replaceable></option></term>
- * <listitem><para>
- * execute all tests matching <replaceable>TESTPATH</replaceable>.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>-m {perf|slow|thorough|quick|undefined|no-undefined}</option></term>
- * <listitem><para>
- * execute tests according to these test modes:
- * <variablelist>
- * <varlistentry>
- * <term>perf</term>
- * <listitem><para>
- * performance tests, may take long and report results.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>slow, thorough</term>
- * <listitem><para>
- * slow and thorough tests, may take quite long and
- * maximize coverage.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>quick</term>
- * <listitem><para>
- * quick tests, should run really quickly and give good coverage.
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>undefined</term>
- * <listitem><para>
- * tests for undefined behaviour, may provoke programming errors
- * under g_test_trap_fork() to check that appropriate assertions
- * or warnings are given
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term>no-undefined</term>
- * <listitem><para>
- * avoid tests for undefined behaviour
- * </para></listitem>
- * </varlistentry>
- * </variablelist>
- * </para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>--debug-log</option></term>
- * <listitem><para>debug test logging output.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>-k</option>, <option>--keep-going</option></term>
- * <listitem><para>gtester-specific argument.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>--GTestLogFD <replaceable>N</replaceable></option></term>
- * <listitem><para>gtester-specific argument.</para></listitem>
- * </varlistentry>
- * <varlistentry>
- * <term><option>--GTestSkipCount <replaceable>N</replaceable></option></term>
- * <listitem><para>gtester-specific argument.</para></listitem>
- * </varlistentry>
- * </variablelist>
+ * <varlistentry>
+ * <term><option>-l</option></term>
+ * <listitem><para>
+ * list test cases available in a test executable.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>--seed=<replaceable>RANDOMSEED</replaceable></option></term>
+ * <listitem><para>
+ * provide a random seed to reproduce test runs using random numbers.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>--verbose</option></term>
+ * <listitem><para>run tests verbosely.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>-q</option>, <option>--quiet</option></term>
+ * <listitem><para>run tests quietly.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>-p <replaceable>TESTPATH</replaceable></option></term>
+ * <listitem><para>
+ * execute all tests matching <replaceable>TESTPATH</replaceable>.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>-m {perf|slow|thorough|quick|undefined|no-undefined}</option></term>
+ * <listitem><para>
+ * execute tests according to these test modes:
+ * <variablelist>
+ * <varlistentry>
+ * <term>perf</term>
+ * <listitem><para>
+ * performance tests, may take long and report results.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>slow, thorough</term>
+ * <listitem><para>
+ * slow and thorough tests, may take quite long and
+ * maximize coverage.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>quick</term>
+ * <listitem><para>
+ * quick tests, should run really quickly and give good coverage.
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>undefined</term>
+ * <listitem><para>
+ * tests for undefined behaviour, may provoke programming errors
+ * under g_test_trap_fork() to check that appropriate assertions
+ * or warnings are given
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>no-undefined</term>
+ * <listitem><para>
+ * avoid tests for undefined behaviour
+ * </para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>--debug-log</option></term>
+ * <listitem><para>debug test logging output.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>-k</option>, <option>--keep-going</option></term>
+ * <listitem><para>gtester-specific argument.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>--GTestLogFD <replaceable>N</replaceable></option></term>
+ * <listitem><para>gtester-specific argument.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><option>--GTestSkipCount <replaceable>N</replaceable></option></term>
+ * <listitem><para>gtester-specific argument.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
*
* Since: 2.16
*/
@@ -33528,19 +33007,19 @@
* termination and validates child program outputs.
*
* |[
- * static void
- * test_fork_patterns (void)
- * {
- * if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
- * {
- * g_print ("some stdout text: somagic17\n");
- * g_printerr ("some stderr text: semagic43\n");
- * exit (0); /* successful test run */
- * }
- * g_test_trap_assert_passed();
- * g_test_trap_assert_stdout ("*somagic17*");
- * g_test_trap_assert_stderr ("*semagic43*");
- * }
+ * static void
+ * test_fork_patterns (void)
+ * {
+ * if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR))
+ * {
+ * g_print ("some stdout text: somagic17\n");
+ * g_printerr ("some stderr text: semagic43\n");
+ * exit (0); /* successful test run */
+ * }
+ * g_test_trap_assert_passed();
+ * g_test_trap_assert_stdout ("*somagic17*");
+ * g_test_trap_assert_stderr ("*semagic43*");
+ * }
* ]|
*
* This function is implemented only on Unix platforms.
@@ -33606,10 +33085,10 @@
* returning @retval from the function @func, as given to g_thread_new().
*
* <note><para>
- * You must only call g_thread_exit() from a thread that you created
- * yourself with g_thread_new() or related APIs. You must not call
- * this function from a thread created with another threading library
- * or or from within a #GThreadPool.
+ * You must only call g_thread_exit() from a thread that you created
+ * yourself with g_thread_new() or related APIs. You must not call
+ * this function from a thread created with another threading library
+ * or or from within a #GThreadPool.
* </para></note>
*/
@@ -33698,10 +33177,7 @@
* If this function returns 0, threads waiting in the thread
* pool for new work are not stopped.
*
- * for new tasks in the thread pool before stopping the
- * thread
- *
- * Returns: the maximum @interval (milliseconds) to wait
+ * Returns: the maximum @interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread
* Since: 2.10
*/
@@ -34132,9 +33608,7 @@
* arrive at local time for @tz (ie: negative numbers for time zones
* west of GMT, positive numbers for east).
*
- * local time in @tz
- *
- * Returns: the number of seconds that should be added to UTC to get the
+ * Returns: the number of seconds that should be added to UTC to get the local time in @tz
* Since: 2.26
*/
@@ -34455,7 +33929,6 @@
* g_timer_elapsed:
* @timer: a #GTimer.
* @microseconds: return location for the fractional part of seconds elapsed, in microseconds (that is, the total number of microseconds elapsed, modulo 1000000), or %NULL
- * @Returns: seconds elapsed as a floating point value, including any fractional part.
*
* If @timer has been started but not stopped, obtains the time since
* the timer was started. If @timer has been stopped, obtains the
@@ -34463,15 +33936,18 @@
* stopped. The return value is the number of seconds elapsed,
* including any fractional part. The @microseconds out parameter is
* essentially useless.
+ *
+ * Returns: seconds elapsed as a floating point value, including any fractional part.
*/
/**
* g_timer_new:
- * @Returns: a new #GTimer.
*
* Creates a new timer, and starts timing (i.e. g_timer_start() is
* implicitly called for you).
+ *
+ * Returns: a new #GTimer.
*/
@@ -34618,9 +34094,7 @@
* automatically balanced as key/value pairs are added, key lookup is very
* fast.
*
- * not found.
- *
- * Returns: the value corresponding to the key, or %NULL if the key was
+ * Returns: the value corresponding to the key, or %NULL if the key was not found.
*/
@@ -34711,9 +34185,7 @@
* make sure that any dynamically allocated values are freed yourself.
* If the key does not exist in the #GTree, the function does nothing.
*
- * nothing)
- *
- * Returns: %TRUE if the key was found (prior to 2.8, this function returned
+ * Returns: %TRUE if the key was found (prior to 2.8, this function returned nothing)
*/
@@ -34751,9 +34223,7 @@
* @search_func returns 1, searching will proceed among the key/value
* pairs that have a larger key.
*
- * the key was not found.
- *
- * Returns: the value corresponding to the found key, or %NULL if
+ * Returns: the value corresponding to the found key, or %NULL if the key was not found.
*/
@@ -34767,9 +34237,7 @@
*
* If the key does not exist in the #GTree, the function does nothing.
*
- * nothing)
- *
- * Returns: %TRUE if the key was found (prior to 2.8, this function returned
+ * Returns: %TRUE if the key was found (prior to 2.8, this function returned nothing)
*/
@@ -34782,10 +34250,7 @@
*
* Calls the given function for each node in the #GTree.
*
- * 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>.
+ * 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>.
*/
@@ -34939,11 +34404,7 @@
* Convert a string from UCS-4 to UTF-16. A 0 character will be
* added to the result after the converted text.
*
- * This value must be freed with g_free(). If an
- * error occurs, %NULL will be returned and
- * @error set.
- *
- * Returns: a pointer to a newly allocated UTF-16 string.
+ * Returns: a pointer to a newly allocated UTF-16 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set.
*/
@@ -34958,13 +34419,7 @@
* Convert a string from a 32-bit fixed width representation as UCS-4.
* to UTF-8. The result will be terminated with a 0 byte.
*
- * This value must be freed with g_free(). If an
- * error occurs, %NULL will be returned and
- * @error set. In that case, @items_read will be
- * set to the position of the first invalid input
- * character.
- *
- * Returns: a pointer to a newly allocated UTF-8 string.
+ * Returns: a pointer to a newly allocated UTF-8 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set. In that case, @items_read will be set to the position of the first invalid input character.
*/
@@ -35062,9 +34517,7 @@
* Determines the numeric value of a character as a decimal
* digit.
*
- * g_unichar_isdigit()), its numeric value. Otherwise, -1.
- *
- * Returns: If @c is a decimal digit (according to
+ * Returns: If @c is a decimal digit (according to g_unichar_isdigit()), its numeric value. Otherwise, -1.
*/
@@ -35383,10 +34836,7 @@
*
* Converts a character to lower case.
*
- * If @c is not an upperlower or titlecase character,
- * or has no lowercase equivalent @c is returned unchanged.
- *
- * Returns: the result of converting @c to lower case.
+ * Returns: the result of converting @c to lower case. If @c is not an upperlower or titlecase character, or has no lowercase equivalent @c is returned unchanged.
*/
@@ -35396,10 +34846,7 @@
*
* Converts a character to the titlecase.
*
- * If @c is not an uppercase or lowercase character,
- * @c is returned unchanged.
- *
- * Returns: the result of converting @c to titlecase.
+ * Returns: the result of converting @c to titlecase. If @c is not an uppercase or lowercase character, @c is returned unchanged.
*/
@@ -35409,10 +34856,7 @@
*
* Converts a character to uppercase.
*
- * If @c is not an lowercase or titlecase character,
- * or has no upper case equivalent @c is returned unchanged.
- *
- * Returns: the result of converting @c to uppercase.
+ * Returns: the result of converting @c to uppercase. If @c is not an lowercase or titlecase character, or has no upper case equivalent @c is returned unchanged.
*/
@@ -35445,9 +34889,7 @@
* Determines the numeric value of a character as a hexidecimal
* digit.
*
- * g_unichar_isxdigit()), its numeric value. Otherwise, -1.
- *
- * Returns: If @c is a hex digit (according to
+ * Returns: If @c is a hex digit (according to g_unichar_isxdigit()), its numeric value. Otherwise, -1.
*/
@@ -35458,12 +34900,8 @@
*
* Computes the canonical decomposition of a Unicode character.
*
- * @result_len is set to the resulting length of the string.
- *
- * instead.
- *
- * Returns: a newly allocated string of Unicode characters.
- * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose()
+ * Returns: a newly allocated string of Unicode characters. @result_len is set to the resulting length of the string.
+ * Deprecated: 2.30: Use the more flexible g_unichar_fully_decompose() instead.
*/
@@ -35492,10 +34930,7 @@
* See <ulink url="http://unicode.org/iso15924/codelists.html";>Codes for the
* representation of names of scripts</ulink> for details.
*
- * of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and
- * %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown.
- *
- * Returns: the Unicode script for @iso15924, or
+ * Returns: the Unicode script for @iso15924, or of %G_UNICODE_SCRIPT_INVALID_CODE if @iso15924 is zero and %G_UNICODE_SCRIPT_UNKNOWN if @iso15924 is unknown.
* Since: 2.30
*/
@@ -35513,10 +34948,7 @@
* See <ulink url="http://unicode.org/iso15924/codelists.html";>Codes for the
* representation of names of scripts</ulink> for details.
*
- * of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or
- * ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood.
- *
- * Returns: the ISO 15924 code for @script, encoded as an integer,
+ * Returns: the ISO 15924 code for @script, encoded as an integer, of zero if @script is %G_UNICODE_SCRIPT_INVALID_CODE or ISO 15924 code 'Zzzz' (script code for UNKNOWN) if @script is not understood.
* Since: 2.30
*/
@@ -35634,9 +35066,7 @@
* that on Windows, it is in general not possible to delete files that
* are open to some process, or mapped into memory.
*
- * occurred
- *
- * Returns: 0 if the name was successfully deleted, -1 if an error
+ * Returns: 0 if the name was successfully deleted, -1 if an error occurred
* Since: 2.6
*/
@@ -35684,9 +35114,7 @@
* specification, since those are allowed unescaped in some portions of
* a URI.
*
- * freed when no longer needed.
- *
- * Returns: an escaped version of @unescaped. The returned string should be
+ * Returns: an escaped version of @unescaped. The returned string should be freed when no longer needed.
* Since: 2.16
*/
@@ -35699,10 +35127,7 @@
* mime type defined in RFC 2483 into individual URIs,
* discarding any comments. The URIs are not validated.
*
- * strings holding the individual URIs. The array should
- * be freed with g_strfreev().
- *
- * Returns: a newly allocated %NULL-terminated list of
+ * Returns: a newly allocated %NULL-terminated list of strings holding the individual URIs. The array should be freed with g_strfreev().
* Since: 2.6
*/
@@ -35717,9 +35142,7 @@
* </programlisting>
* Common schemes include "file", "http", "svn+ssh", etc.
*
- * The returned string should be freed when no longer needed.
- *
- * Returns: The "Scheme" component of the URI, or %NULL on error.
+ * Returns: The "Scheme" component of the URI, or %NULL on error. The returned string should be freed when no longer needed.
* Since: 2.16
*/
@@ -35738,11 +35161,7 @@
* slash being expanded in an escaped path element, which might confuse pathname
* handling.
*
- * The returned string should be freed when no longer needed. As a
- * special case if %NULL is given for @escaped_string, this function
- * will return %NULL.
- *
- * Returns: an unescaped version of @escaped_string or %NULL on error.
+ * Returns: an unescaped version of @escaped_string or %NULL on error. The returned string should be freed when no longer needed. As a special case if %NULL is given for @escaped_string, this function will return %NULL.
* Since: 2.16
*/
@@ -35760,9 +35179,7 @@
* slash being expanded in an escaped path element, which might confuse pathname
* handling.
*
- * should be freed when no longer needed.
- *
- * Returns: an unescaped version of @escaped_string. The returned string
+ * Returns: an unescaped version of @escaped_string. The returned string should be freed when no longer needed.
* Since: 2.16
*/
@@ -35791,11 +35208,7 @@
* Convert a string from UTF-16 to UCS-4. The result will be
* nul-terminated.
*
- * This value must be freed with g_free(). If an
- * error occurs, %NULL will be returned and
- * @error set.
- *
- * Returns: a pointer to a newly allocated UCS-4 string.
+ * Returns: a pointer to a newly allocated UCS-4 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set.
*/
@@ -35821,11 +35234,7 @@
* be correctly interpreted as UTF-16, i.e. it doesn't contain
* things unpaired surrogates.
*
- * This value must be freed with g_free(). If an
- * error occurs, %NULL will be returned and
- * @error set.
- *
- * Returns: a pointer to a newly allocated UTF-8 string.
+ * Returns: a pointer to a newly allocated UTF-8 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set.
*/
@@ -35846,9 +35255,7 @@
* takes case sensitivity into account. GLib does not currently
* provide such a function.
*
- * case independent form of @str.
- *
- * Returns: a newly allocated string, that is a
+ * Returns: a newly allocated string, that is a case independent form of @str.
*/
@@ -35864,9 +35271,7 @@
* compare the keys with strcmp() when sorting instead of sorting
* the original strings.
*
- * 0 if they compare equal, > 0 if @str1 compares after @str2.
- *
- * Returns: < 0 if @str1 compares before @str2,
+ * Returns: < 0 if @str1 compares before @str2, 0 if they compare equal, > 0 if @str1 compares after @str2.
*/
@@ -35886,9 +35291,7 @@
* Note that this function depends on the
* <link linkend="setlocale">current locale</link>.
*
- * be freed with g_free() when you are done with it.
- *
- * Returns: a newly allocated string. This string should
+ * Returns: a newly allocated string. This string should be freed with g_free() when you are done with it.
*/
@@ -35910,9 +35313,7 @@
* Note that this function depends on the
* <link linkend="setlocale">current locale</link>.
*
- * be freed with g_free() when you are done with it.
- *
- * Returns: a newly allocated string. This string should
+ * Returns: a newly allocated string. This string should be freed with g_free() when you are done with it.
* Since: 2.8
*/
@@ -35973,12 +35374,7 @@
* such as characters that are out of the range of Unicode, and for
* overlong encodings of valid characters.
*
- * sequence at the end of a string that could begin a valid
- * character (or if @max_len is zero), returns (gunichar)-2;
- * otherwise, if @p does not point to a valid UTF-8 encoded
- * Unicode character, returns (gunichar)-1.
- *
- * Returns: the resulting character. If @p points to a partial
+ * Returns: the resulting character. If @p points to a partial sequence at the end of a string that could begin a valid character (or if @max_len is zero), returns (gunichar)-2; otherwise, if @p does not point to a valid UTF-8 encoded Unicode character, returns (gunichar)-1.
*/
@@ -36027,10 +35423,7 @@
* a legacy encoding or pass it to a system with
* less capable Unicode handling.
*
- * normalized form of @str, or %NULL if @str is not
- * valid UTF-8.
- *
- * Returns: a newly allocated string, that is the
+ * Returns: a newly allocated string, that is the normalized form of @str, or %NULL if @str is not valid UTF-8.
*/
@@ -36100,10 +35493,7 @@
* in a UTF-8 encoded string, while limiting the search to @len bytes.
* If @len is -1, allow unbounded search.
*
- * otherwise, a pointer to the start of the leftmost occurrence of
- * the character in the string.
- *
- * Returns: %NULL if the string does not contain the character,
+ * Returns: %NULL if the string does not contain the character, otherwise, a pointer to the start of the leftmost occurrence of the character in the string.
*/
@@ -36117,9 +35507,7 @@
* on the current locale, and may result in the number of
* characters in the string changing.
*
- * converted to lowercase.
- *
- * Returns: a newly allocated string, with all characters
+ * Returns: a newly allocated string, with all characters converted to lowercase.
*/
@@ -36162,10 +35550,7 @@
* in a UTF-8 encoded string, while limiting the search to @len bytes.
* If @len is -1, allow unbounded search.
*
- * otherwise, a pointer to the start of the rightmost occurrence of the
- * character in the string.
- *
- * Returns: %NULL if the string does not contain the character,
+ * Returns: %NULL if the string does not contain the character, otherwise, a pointer to the start of the rightmost occurrence of the character in the string.
*/
@@ -36204,9 +35589,7 @@
* characters in the string increasing. (For instance, the
* German ess-zet will be changed to SS.)
*
- * converted to uppercase.
- *
- * Returns: a newly allocated string, with all characters
+ * Returns: a newly allocated string, with all characters converted to uppercase.
*/
@@ -36220,9 +35603,7 @@
* The substring will contain @end_pos - @start_pos
* characters.
*
- * substring. Free with g_free() when no longer needed.
- *
- * Returns: a newly allocated copy of the requested
+ * Returns: a newly allocated copy of the requested substring. Free with g_free() when no longer needed.
* Since: 2.30
*/
@@ -36239,11 +35620,7 @@
* representation as UCS-4. A trailing 0 character will be added to the
* string after the converted text.
*
- * This value must be freed with g_free(). If an
- * error occurs, %NULL will be returned and
- * @error set.
- *
- * Returns: a pointer to a newly allocated UCS-4 string.
+ * Returns: a pointer to a newly allocated UCS-4 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set.
*/
@@ -36259,9 +35636,7 @@
* but does no error checking on the input. A trailing 0 character
* will be added to the string after the converted text.
*
- * This value must be freed with g_free().
- *
- * Returns: a pointer to a newly allocated UCS-4 string.
+ * Returns: a pointer to a newly allocated UCS-4 string. This value must be freed with g_free().
*/
@@ -36276,11 +35651,7 @@
* Convert a string from UTF-8 to UTF-16. A 0 character will be
* added to the result after the converted text.
*
- * This value must be freed with g_free(). If an
- * error occurs, %NULL will be returned and
- * @error set.
- *
- * Returns: a pointer to a newly allocated UTF-16 string.
+ * Returns: a pointer to a newly allocated UTF-16 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set.
*/
@@ -36321,9 +35692,7 @@
* See your C library manual for more details about how utime() works
* on your system.
*
- * occurred
- *
- * Returns: 0 if the operation was successful, -1 if an error
+ * Returns: 0 if the operation was successful, -1 if an error occurred
* Since: 2.18
*/
@@ -36345,19 +35714,19 @@
* GVariant *
* make_pointless_dictionary (void)
* {
- * GVariantBuilder *builder;
- * int i;
+ * GVariantBuilder *builder;
+ * int i;
*
- * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
- * for (i = 0; i < 16; i++)
- * {
- * gchar buf[3];
+ * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
+ * for (i = 0; i < 16; i++)
+ * {
+ * gchar buf[3];
*
- * sprintf (buf, "%d", i);
- * g_variant_builder_add (builder, "{is}", i, buf);
- * }
+ * sprintf (buf, "%d", i);
+ * g_variant_builder_add (builder, "{is}", i, buf);
+ * }
*
- * return g_variant_builder_end (builder);
+ * return g_variant_builder_end (builder);
* }
* </programlisting>
*
@@ -36383,14 +35752,14 @@
* GVariant *
* make_pointless_dictionary (void)
* {
- * GVariantBuilder *builder;
- * int i;
- *
- * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
- * g_variant_builder_add_parsed (builder, "{'width', <%i>}", 600);
- * g_variant_builder_add_parsed (builder, "{'title', <%s>}", "foo");
- * g_variant_builder_add_parsed (builder, "{'transparency', <0.5>}");
- * return g_variant_builder_end (builder);
+ * GVariantBuilder *builder;
+ * int i;
+ *
+ * builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
+ * g_variant_builder_add_parsed (builder, "{'width', <%i>}", 600);
+ * g_variant_builder_add_parsed (builder, "{'title', <%s>}", "foo");
+ * g_variant_builder_add_parsed (builder, "{'transparency', <0.5>}");
+ * return g_variant_builder_end (builder);
* }
* </programlisting>
*
@@ -36641,10 +36010,7 @@
* If you only require an equality comparison, g_variant_equal() is more
* general.
*
- * zero if a = b;
- * positive value if a > b.
- *
- * Returns: negative value if a < b;
+ * Returns: negative value if a < b; zero if a = b; positive value if a > b.
* Since: 2.26
*/
@@ -36659,9 +36025,7 @@
*
* The return value must be freed using g_free().
*
- * (element-type guint8): a newly allocated string
- *
- * Returns: (transfer full) (array zero-terminated=1 length=length)
+ * Returns: (transfer full) (array length=length zero-terminated=1) (element-type guint8): a newly allocated string
* Since: 2.26
*/
@@ -36831,9 +36195,7 @@
*
* The return value remains valid as long as @value exists.
*
- * the constant string
- *
- * Returns: (transfer none) (array zero-terminated=1) (element-type guint8):
+ * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): the constant string
* Since: 2.26
*/
@@ -36973,9 +36335,9 @@
* <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>
+ * <entry>#gint16 (etc.)</entry></row>
* <row><entry>%G_VARIANT_TYPE_BOOLEAN</entry>
- * <entry>#guchar (not #gboolean!)</entry></row>
+ * <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>
@@ -36991,9 +36353,7 @@
* @n_elements, which must be non-%NULL is set equal to the number of
* items in the array.
*
- * the fixed array
- *
- * Returns: (array length=n_elements) (transfer none): a pointer to
+ * Returns: (array length=n_elements) (transfer none): a pointer to the fixed array
* Since: 2.24
*/
@@ -37494,27 +36854,27 @@
* Format Strings</link>.
*
* <example>
- * <title>Memory management with g_variant_iter_loop()</title>
- * <programlisting>
- * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
- * void
- * iterate_dictionary (GVariant *dictionary)
- * {
- * GVariantIter iter;
- * GVariant *value;
- * gchar *key;
- *
- * g_variant_iter_init (&iter, dictionary);
- * while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
- * {
- * 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 *<!-- -->/
- * }
- * }
- * </programlisting>
+ * <title>Memory management with g_variant_iter_loop()</title>
+ * <programlisting>
+ * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
+ * void
+ * iterate_dictionary (GVariant *dictionary)
+ * {
+ * GVariantIter iter;
+ * GVariant *value;
+ * gchar *key;
+ *
+ * g_variant_iter_init (&iter, dictionary);
+ * while (g_variant_iter_loop (&iter, "{sv}", &key, &value))
+ * {
+ * 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 *<!-- -->/
+ * }
+ * }
+ * </programlisting>
* </example>
*
* For most cases you should use g_variant_iter_next().
@@ -37528,9 +36888,7 @@
* types, use the '&' prefix to avoid allocating any memory at all (and
* thereby avoiding the need to free anything as well).
*
- * value
- *
- * Returns: %TRUE if a value was unpacked, or %FALSE if there was no
+ * Returns: %TRUE if a value was unpacked, or %FALSE if there was no value
* Since: 2.24
*/
@@ -37588,28 +36946,28 @@
* Format Strings</link>.
*
* <example>
- * <title>Memory management with g_variant_iter_next()</title>
- * <programlisting>
- * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
- * void
- * iterate_dictionary (GVariant *dictionary)
- * {
- * GVariantIter iter;
- * GVariant *value;
- * gchar *key;
- *
- * g_variant_iter_init (&iter, dictionary);
- * while (g_variant_iter_next (&iter, "{sv}", &key, &value))
- * {
- * g_print ("Item '%s' has type '%s'\n", key,
- * g_variant_get_type_string (value));
- *
- * /<!-- -->* must free data for ourselves *<!-- -->/
- * g_variant_unref (value);
- * g_free (key);
- * }
- * }
- * </programlisting>
+ * <title>Memory management with g_variant_iter_next()</title>
+ * <programlisting>
+ * /<!-- -->* Iterates a dictionary of type 'a{sv}' *<!-- -->/
+ * void
+ * iterate_dictionary (GVariant *dictionary)
+ * {
+ * GVariantIter iter;
+ * GVariant *value;
+ * gchar *key;
+ *
+ * g_variant_iter_init (&iter, dictionary);
+ * while (g_variant_iter_next (&iter, "{sv}", &key, &value))
+ * {
+ * g_print ("Item '%s' has type '%s'\n", key,
+ * g_variant_get_type_string (value));
+ *
+ * /<!-- -->* must free data for ourselves *<!-- -->/
+ * g_variant_unref (value);
+ * g_free (key);
+ * }
+ * }
+ * </programlisting>
* </example>
*
* For a solution that is likely to be more convenient to C programmers
@@ -37631,26 +36989,26 @@
* you no longer need it.
*
* <example>
- * <title>Iterating with g_variant_iter_next_value()</title>
- * <programlisting>
- * /<!-- -->* recursively iterate a container *<!-- -->/
- * void
- * iterate_container_recursive (GVariant *container)
- * {
- * GVariantIter iter;
- * GVariant *child;
- *
- * g_variant_iter_init (&iter, container);
- * while ((child = g_variant_iter_next_value (&iter)))
- * {
- * g_print ("type '%s'\n", g_variant_get_type_string (child));
- *
- * if (g_variant_is_container (child))
- * iterate_container_recursive (child);
- *
- * g_variant_unref (child);
- * }
- * }
+ * <title>Iterating with g_variant_iter_next_value()</title>
+ * <programlisting>
+ * /<!-- -->* recursively iterate a container *<!-- -->/
+ * void
+ * iterate_container_recursive (GVariant *container)
+ * {
+ * GVariantIter iter;
+ * GVariant *child;
+ *
+ * g_variant_iter_init (&iter, container);
+ * while ((child = g_variant_iter_next_value (&iter)))
+ * {
+ * g_print ("type '%s'\n", g_variant_get_type_string (child));
+ *
+ * if (g_variant_is_container (child))
+ * iterate_container_recursive (child);
+ *
+ * g_variant_unref (child);
+ * }
+ * }
* </programlisting>
* </example>
*
@@ -38035,10 +37393,10 @@
* g_variant_new_parsed:
* @format: a text format #GVariant
* @...: arguments as per @format
- * @format must be a text format #GVariant with one extension: at any
*
* Parses @format and returns the result.
*
+ * @format must be a text format #GVariant with one extension: at any
* point that a value may appear in the text, a '%' character followed
* by a GVariant format string (as per g_variant_new()) may appear. In
* that case, the same arguments are collected from the argument list as
@@ -38047,7 +37405,7 @@
* Consider this simple example:
*
* <informalexample><programlisting>
- * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
+ * g_variant_new_parsed ("[('one', 1), ('two', %i), (%s, 3)]", 2, "three");
* </programlisting></informalexample>
*
* In the example, the variable argument parameters are collected and
@@ -38253,7 +37611,6 @@
* @limit: (allow-none): a pointer to the end of @text, or %NULL
* @endptr: (allow-none): a location to store the end pointer, or %NULL
* @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
- * @Returns: a reference to a #GVariant, or %NULL
*
* Parses a #GVariant from a text representation.
*
@@ -38285,6 +37642,8 @@
*
* Officially, the language understood by the parser is "any string
* produced by g_variant_print()".
+ *
+ * Returns: a reference to a #GVariant, or %NULL
*/
@@ -38434,10 +37793,7 @@
* Makes a copy of a #GVariantType. It is appropriate to call
* g_variant_type_free() on the return value. @type may not be %NULL.
*
- *
- * Since 2.24
- *
- * Returns: (transfer full): a new #GVariantType
+ * Returns: (transfer full): a new #GVariantType Since 2.24
*/
@@ -38449,10 +37805,7 @@
* @type. The returned string is nul-terminated. It is appropriate to
* call g_free() on the return value.
*
- *
- * Since 2.24
- *
- * Returns: (transfer full): the corresponding type string
+ * Returns: (transfer full): the corresponding type string Since 2.24
*/
@@ -38464,10 +37817,7 @@
*
* This function may only be used with array or maybe types.
*
- *
- * Since 2.24
- *
- * Returns: (transfer none): the element type of @type
+ * Returns: (transfer none): the element type of @type Since 2.24
*/
@@ -38487,10 +37837,7 @@
* allow use with #GHashTable without function pointer casting. For
* both arguments, a valid #GVariantType must be provided.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type1 and @type2 are exactly equal
+ * Returns: %TRUE if @type1 and @type2 are exactly equal Since 2.24
*/
@@ -38513,10 +37860,7 @@
* This call, together with g_variant_type_next() provides an iterator
* interface over tuple and dictionary entry types.
*
- *
- * Since 2.24
- *
- * Returns: (transfer none): the first item type of @type, or %NULL
+ * Returns: (transfer none): the first item type of @type, or %NULL Since 2.24
*/
@@ -38542,10 +37886,7 @@
* @type. This function must be used to determine the valid extent of
* the memory region returned by g_variant_type_peek_string().
*
- *
- * Since 2.24
- *
- * Returns: the length of the corresponding type string
+ * Returns: the length of the corresponding type string Since 2.24
*/
@@ -38559,10 +37900,7 @@
* #GHashTable without function pointer casting. A valid
* #GVariantType must be provided.
*
- *
- * Since 2.24
- *
- * Returns: the hash value
+ * Returns: the hash value Since 2.24
*/
@@ -38577,10 +37915,7 @@
* definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
* example.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is an array type
+ * Returns: %TRUE if @type is an array type Since 2.24
*/
@@ -38598,10 +37933,7 @@
* This function returns %FALSE for all indefinite types except
* %G_VARIANT_TYPE_BASIC.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is a basic type
+ * Returns: %TRUE if @type is a basic type Since 2.24
*/
@@ -38618,10 +37950,7 @@
* definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
* example.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is a container type
+ * Returns: %TRUE if @type is a container type Since 2.24
*/
@@ -38640,10 +37969,7 @@
* indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
* %FALSE being returned.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is definite
+ * Returns: %TRUE if @type is definite Since 2.24
*/
@@ -38658,10 +37984,7 @@
* definite subtype is a dictionary entry type --
* %G_VARIANT_TYPE_DICT_ENTRY, for example.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is a dictionary entry type
+ * Returns: %TRUE if @type is a dictionary entry type Since 2.24
*/
@@ -38676,10 +37999,7 @@
* definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
* example.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is a maybe type
+ * Returns: %TRUE if @type is a maybe type Since 2.24
*/
@@ -38694,10 +38014,7 @@
* types are considered to be subtypes of themselves. Aside from that,
* only indefinite types can have subtypes.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is a subtype of @supertype
+ * Returns: %TRUE if @type is a subtype of @supertype Since 2.24
*/
@@ -38713,10 +38030,7 @@
* definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
* example.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is a tuple type
+ * Returns: %TRUE if @type is a tuple type Since 2.24
*/
@@ -38726,10 +38040,7 @@
*
* Determines if the given @type is the variant type.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type is the variant type
+ * Returns: %TRUE if @type is the variant type Since 2.24
*/
@@ -38743,10 +38054,7 @@
* than the additional restriction, this call is equivalent to
* g_variant_type_first().
*
- *
- * Since 2.24
- *
- * Returns: (transfer none): the key type of the dictionary entry
+ * Returns: (transfer none): the key type of the dictionary entry Since 2.24
*/
@@ -38764,10 +38072,7 @@
* In the case of a dictionary entry type, this function will always
* return 2.
*
- *
- * Since 2.24
- *
- * Returns: the number of items in @type
+ * Returns: the number of items in @type Since 2.24
*/
@@ -38796,10 +38101,7 @@
*
* It is appropriate to call g_variant_type_free() on the return value.
*
- *
- * Since 2.24
- *
- * Returns: (transfer full): a new array #GVariantType
+ * Returns: (transfer full): a new array #GVariantType Since 2.24
*/
@@ -38813,10 +38115,7 @@
*
* It is appropriate to call g_variant_type_free() on the return value.
*
- *
- * Since 2.24
- *
- * Returns: (transfer full): a new dictionary entry #GVariantType
+ * Returns: (transfer full): a new dictionary entry #GVariantType Since 2.24
*/
@@ -38829,10 +38128,7 @@
*
* It is appropriate to call g_variant_type_free() on the return value.
*
- *
- * Since 2.24
- *
- * Returns: (transfer full): a new maybe #GVariantType
+ * Returns: (transfer full): a new maybe #GVariantType Since 2.24
*/
@@ -38848,10 +38144,7 @@
*
* It is appropriate to call g_variant_type_free() on the return value.
*
- *
- * Since 2.24
- *
- * Returns: (transfer full): a new tuple #GVariantType
+ * Returns: (transfer full): a new tuple #GVariantType Since 2.24
*/
@@ -38871,10 +38164,7 @@
*
* For tuples, %NULL is returned when @type is the last item in a tuple.
*
- *
- * Since 2.24
- *
- * Returns: (transfer none): the next #GVariantType after @type, or %NULL
+ * Returns: (transfer none): the next #GVariantType after @type, or %NULL Since 2.24
*/
@@ -38888,10 +38178,7 @@
*
* To get a nul-terminated string, see g_variant_type_dup_string().
*
- *
- * Since 2.24
- *
- * Returns: the corresponding type string (not nul-terminated)
+ * Returns: the corresponding type string (not nul-terminated) Since 2.24
*/
@@ -38903,10 +38190,7 @@
* equivalent to calling g_variant_type_string_scan() and confirming
* that the following character is a nul terminator.
*
- *
- * Since 2.24
- *
- * Returns: %TRUE if @type_string is exactly one valid type string
+ * Returns: %TRUE if @type_string is exactly one valid type string Since 2.24
*/
@@ -38943,10 +38227,7 @@
*
* This function may only be used with a dictionary entry type.
*
- *
- * Since 2.24
- *
- * Returns: (transfer none): the value type of the dictionary entry
+ * Returns: (transfer none): the value type of the dictionary entry Since 2.24
*/
@@ -39030,9 +38311,7 @@
* The format string may contain positional parameters, as specified in
* the Single Unix Specification.
*
- * was large enough.
- *
- * Returns: the number of bytes which would be produced if the buffer
+ * Returns: the number of bytes which would be produced if the buffer was large enough.
*/
@@ -39212,14 +38491,8 @@
* the main executable of the process was loaded is used instead in
* the same way as above.
*
- * @package. The string is in the GLib file name encoding,
- * i.e. UTF-8. The return value should be freed with g_free() when not
- * needed any longer. If the function fails %NULL is returned.
- *
- * g_win32_get_package_installation_directory_of_module() instead.
- *
- * Returns: a string containing the installation directory for
- * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to
+ * Returns: a string containing the installation directory for @package. The string is in the GLib file name encoding, i.e. UTF-8. The return value should be freed with g_free() when not needed any longer. If the function fails %NULL is returned.
+ * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to g_win32_get_package_installation_directory_of_module() instead.
*/
@@ -39251,12 +38524,7 @@
* construct names of files in the installation tree it calls this
* function passing the DLL handle.
*
- * the software package @hmodule is from. The string is in the GLib
- * file name encoding, i.e. UTF-8. The return value should be freed
- * with g_free() when not needed any longer. If the function fails
- * %NULL is returned.
- *
- * Returns: a string containing the guessed installation directory for
+ * Returns: a string containing the guessed installation directory for the software package @hmodule is from. The string is in the GLib file name encoding, i.e. UTF-8. The return value should be freed with g_free() when not needed any longer. If the function fails %NULL is returned.
* Since: 2.16
*/
@@ -39279,16 +38547,8 @@
* particular, note that it is deprecated to pass anything except NULL
* as @package.
*
- * the installation directory of @package. The returned string is in
- * the GLib file name encoding, i.e. UTF-8. The return value should be
- * freed with g_free() when no longer needed. If something goes wrong,
- * %NULL is returned.
- *
- * g_win32_get_package_installation_directory_of_module() instead, and
- * then construct a subdirectory pathname with g_build_filename().
- *
- * Returns: a string containing the complete path to @subdir inside
- * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to
+ * Returns: a string containing the complete path to @subdir inside the installation directory of @package. The returned string is in the GLib file name encoding, i.e. UTF-8. The return value should be freed with g_free() when no longer needed. If something goes wrong, %NULL is returned.
+ * Deprecated: 2.18: Pass the HMODULE of a DLL or EXE to g_win32_get_package_installation_directory_of_module() instead, and then construct a subdirectory pathname with g_build_filename().
*/
@@ -39349,9 +38609,7 @@
* The return value is dynamically allocated and should be freed with
* g_free() when no longer needed.
*
- * failure and lack of short names.
- *
- * Returns: The converted filename, or %NULL on conversion
+ * Returns: The converted filename, or %NULL on conversion failure and lack of short names.
* Since: 2.8
*/
@@ -39503,11 +38761,7 @@
* version @required_major required_minor required_micro
* (same major version.)
*
- * given version, or a string describing the version mismatch.
- * The returned string is owned by GLib and must not be modified
- * or freed.
- *
- * Returns: %NULL if the GLib library is compatible with the
+ * Returns: %NULL if the GLib library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GLib and must not be modified or freed.
* Since: 2.6
*/
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index af3cdcb..5f9becf 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -113,9 +113,7 @@
* from @source_value into the target property of @target
* using @target_value.
*
- * otherwise
- *
- * Returns: %TRUE if the transformation was successful, and %FALSE
+ * Returns: %TRUE if the transformation was successful, and %FALSE otherwise
* Since: 2.26
*/
@@ -246,19 +244,19 @@
* The initialization process of a class involves:
* <itemizedlist>
* <listitem><para>
- * 1 - Copying common members from the parent class over to the
- * derived class structure.
+ * 1 - Copying common members from the parent class over to the
+ * derived class structure.
* </para></listitem>
* <listitem><para>
- * 2 - Zero initialization of the remaining members not copied
- * over from the parent class.
+ * 2 - Zero initialization of the remaining members not copied
+ * over from the parent class.
* </para></listitem>
* <listitem><para>
- * 3 - Invocation of the GBaseInitFunc() initializers of all parent
- * types and the class' type.
+ * 3 - Invocation of the GBaseInitFunc() initializers of all parent
+ * types and the class' type.
* </para></listitem>
* <listitem><para>
- * 4 - Invocation of the class' GClassInitFunc() initializer.
+ * 4 - Invocation of the class' GClassInitFunc() initializer.
* </para></listitem>
* </itemizedlist>
* Since derived classes are partially initialized through a memory copy
@@ -276,45 +274,45 @@
*
* |[
* typedef struct {
- * GObjectClass parent_class;
- * gint static_integer;
- * gchar *dynamic_string;
+ * GObjectClass parent_class;
+ * gint static_integer;
+ * gchar *dynamic_string;
* } TypeAClass;
* static void
* type_a_base_class_init (TypeAClass *class)
* {
- * class->dynamic_string = g_strdup ("some string");
+ * class->dynamic_string = g_strdup ("some string");
* }
* static void
* type_a_base_class_finalize (TypeAClass *class)
* {
- * g_free (class->dynamic_string);
+ * g_free (class->dynamic_string);
* }
* static void
* type_a_class_init (TypeAClass *class)
* {
- * class->static_integer = 42;
+ * class->static_integer = 42;
* }
*
* typedef struct {
- * TypeAClass parent_class;
- * gfloat static_float;
- * GString *dynamic_gstring;
+ * TypeAClass parent_class;
+ * gfloat static_float;
+ * GString *dynamic_gstring;
* } TypeBClass;
* static void
* type_b_base_class_init (TypeBClass *class)
* {
- * class->dynamic_gstring = g_string_new ("some other string");
+ * class->dynamic_gstring = g_string_new ("some other string");
* }
* static void
* type_b_base_class_finalize (TypeBClass *class)
* {
- * g_string_free (class->dynamic_gstring);
+ * g_string_free (class->dynamic_gstring);
* }
* static void
* type_b_class_init (TypeBClass *class)
* {
- * class->static_float = 3.14159265358979323846;
+ * class->static_float = 3.14159265358979323846;
* }
* ]|
* Initialization of TypeBClass will first cause initialization of
@@ -582,31 +580,6 @@
/**
- * GLIB_CHECK_VERSION:
- * @major: the major version to check for
- * @minor: the minor version to check for
- * @micro: the micro version to check for
- *
- * Checks the version of the GLib library that is being compiled
- * against.
- *
- * <example>
- * <title>Checking the version of the GLib library</title>
- * <programlisting>
- * if (!GLIB_CHECK_VERSION (1, 2, 0))
- * g_error ("GLib version 1.2.0 or above is needed");
- * </programlisting>
- * </example>
- *
- * See glib_check_version() for a runtime check.
- *
- * is the same as or newer than the passed-in version.
- *
- * Returns: %TRUE if the version of the GLib header files
- */
-
-
-/**
* GLIB_VERSION_2_26:
*
* A macro that evaluates to the 2.26 version of GLib, in a format
@@ -809,8 +782,8 @@
* g_signal_connect() call, like this:
* |[
* g_signal_connect (text_view->buffer, "notify::paste-target-list",
- * G_CALLBACK (gtk_text_view_target_list_notify),
- * text_view)
+ * G_CALLBACK (gtk_text_view_target_list_notify),
+ * text_view)
* ]|
* It is important to note that you must use
* <link linkend="canonical-parameter-name">canonical</link> parameter names as
@@ -839,22 +812,22 @@
*
* static GObject*
* my_singleton_constructor (GType type,
- * guint n_construct_params,
- * GObjectConstructParam *construct_params)
- * {
- * GObject *object;
- *
- * if (!the_singleton)
+ * guint n_construct_params,
+ * GObjectConstructParam *construct_params)
* {
- * object = G_OBJECT_CLASS (parent_class)->constructor (type,
- * n_construct_params,
- * construct_params);
- * the_singleton = MY_SINGLETON (object);
- * }
- * else
- * object = g_object_ref (G_OBJECT (the_singleton));
- *
- * return object;
+ * GObject *object;
+ *
+ * if (!the_singleton)
+ * {
+ * object = G_OBJECT_CLASS (parent_class)->constructor (type,
+ * n_construct_params,
+ * construct_params);
+ * the_singleton = MY_SINGLETON (object);
+ * }
+ * else
+ * object = g_object_ref (G_OBJECT (the_singleton));
+ *
+ * return object;
* }
* </programlisting></example>
*/
@@ -931,9 +904,7 @@
* The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK
* options.
*
- * occurred, in which case @error should be set with g_set_error()
- *
- * Returns: %TRUE if the option was successfully parsed, %FALSE if an error
+ * Returns: %TRUE if the option was successfully parsed, %FALSE if an error occurred, in which case @error should be set with g_set_error()
*/
@@ -1019,9 +990,7 @@
*
* The type of function that can be called before and after parsing.
*
- * occurred, in which case @error should be set with g_set_error()
- *
- * Returns: %TRUE if the function completed successfully, %FALSE if an error
+ * Returns: %TRUE if the function completed successfully, %FALSE if an error occurred, in which case @error should be set with g_set_error()
*/
@@ -1036,7 +1005,7 @@
* @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8
* @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8
* @G_PARAM_PRIVATE: internal
- * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26
+ * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since 2.26
*
* Through the #GParamFlags flag values, certain aspects of parameters
* can be configured.
@@ -1394,9 +1363,7 @@
* Specifies the type of function passed to g_main_context_set_poll_func().
* The semantics of the function should match those of the poll() system call.
*
- * reported, or -1 if an error occurred.
- *
- * Returns: the number of #GPollFD elements which have events or errors
+ * Returns: the number of #GPollFD elements which have events or errors reported, or -1 if an error occurred.
*/
@@ -1439,7 +1406,8 @@
* @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater.
* @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set.
* @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern.
- * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
+ * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes.
+ * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way).
* @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches.
* @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched.
* @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'.
@@ -1551,10 +1519,7 @@
* values is performed. The return value of signal emissions is then the
* value returned by the last callback.
*
- * should be aborted. Returning %FALSE means to abort the
- * current emission and %TRUE is returned for continuation.
- *
- * Returns: The accumulator function returns whether the signal emission
+ * Returns: The accumulator function returns whether the signal emission should be aborted. Returning %FALSE means to abort the current emission and %TRUE is returned for continuation.
*/
@@ -1591,9 +1556,7 @@
*
* You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
*
- * hook is disconnected (and destroyed).
- *
- * Returns: whether it wants to stay connected. If it returns %FALSE, the signal
+ * Returns: whether it wants to stay connected. If it returns %FALSE, the signal hook is disconnected (and destroyed).
*/
@@ -1668,9 +1631,10 @@
* GSourceCallbackFuncs:
* @ref: Called when a reference is added to the callback object
* @unref: Called when a reference to the callback object is dropped
- * @get: Called to extract the callback function and data from the callback object. The <structname>GSourceCallbackFuncs</structname> struct contains functions for managing callback objects.
- *
+ * @get: Called to extract the callback function and data from the callback object.
*
+ * The <structname>GSourceCallbackFuncs</structname> struct contains
+ * functions for managing callback objects.
*/
@@ -1869,9 +1833,7 @@
* The type of functions which are used to translate user-visible
* strings, for <option>--help</option> output.
*
- * The returned string is owned by GLib and must not be freed.
- *
- * Returns: a translation of the string for the current locale.
+ * Returns: a translation of the string for the current locale. The returned string is owned by GLib and must not be freed.
*/
@@ -1917,9 +1879,7 @@
* whether they actually want to cache the class of this type, since all
* classes are routed through the same #GTypeClassCacheFunc chain.
*
- * called, %FALSE to continue.
- *
- * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being
+ * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being called, %FALSE to continue.
*/
@@ -2181,6 +2141,7 @@
/**
* GUnicodeScript:
+ * @G_UNICODE_SCRIPT_INVALID_CODE: a value never returned from g_unichar_get_script()
* @G_UNICODE_SCRIPT_COMMON: a character used by multiple different scripts
* @G_UNICODE_SCRIPT_INHERITED: a mark glyph that takes its script from the i base glyph to which it is attached
* @G_UNICODE_SCRIPT_ARABIC: Arabic
@@ -2220,7 +2181,8 @@
* @G_UNICODE_SCRIPT_TELUGU: Telugu
* @G_UNICODE_SCRIPT_THAANA: Thaana
* @G_UNICODE_SCRIPT_THAI: Thai
- * @G_UNICODE_SCRIPT_TIBETAN: Tibetan Canadian Aboriginal
+ * @G_UNICODE_SCRIPT_TIBETAN: Tibetan
+ * @G_UNICODE_SCRIPT_CANADIAN_ABORIGINAL: Canadian Aboriginal
* @G_UNICODE_SCRIPT_YI: Yi
* @G_UNICODE_SCRIPT_TAGALOG: Tagalog
* @G_UNICODE_SCRIPT_HANUNOO: Hanunoo
@@ -2233,10 +2195,13 @@
* @G_UNICODE_SCRIPT_SHAVIAN: Shavian
* @G_UNICODE_SCRIPT_LINEAR_B: Linear B
* @G_UNICODE_SCRIPT_TAI_LE: Tai Le
- * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic New Tai Lue
+ * @G_UNICODE_SCRIPT_UGARITIC: Ugaritic
+ * @G_UNICODE_SCRIPT_NEW_TAI_LUE: New Tai Lue
* @G_UNICODE_SCRIPT_BUGINESE: Buginese
* @G_UNICODE_SCRIPT_GLAGOLITIC: Glagolitic
- * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh Syloti Nagri Old Persian
+ * @G_UNICODE_SCRIPT_TIFINAGH: Tifinagh
+ * @G_UNICODE_SCRIPT_SYLOTI_NAGRI: Syloti Nagri
+ * @G_UNICODE_SCRIPT_OLD_PERSIAN: Old Persian
* @G_UNICODE_SCRIPT_KHAROSHTHI: Kharoshthi
* @G_UNICODE_SCRIPT_UNKNOWN: an unassigned code point
* @G_UNICODE_SCRIPT_BALINESE: Balinese
@@ -2256,10 +2221,16 @@
* @G_UNICODE_SCRIPT_LYCIAN: Lycian. Since 2.16.3
* @G_UNICODE_SCRIPT_LYDIAN: Lydian. Since 2.16.3
* @G_UNICODE_SCRIPT_AVESTAN: Avestan. Since 2.26
- * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26 Egyptian Hieroglpyhs. Since 2.26 Imperial Aramaic. Since 2.26 Inscriptional Pahlavi. Since 2.26 Inscriptional Parthian. Since 2.26
+ * @G_UNICODE_SCRIPT_BAMUM: Bamum. Since 2.26
+ * @G_UNICODE_SCRIPT_EGYPTIAN_HIEROGLYPHS: Egyptian Hieroglpyhs. Since 2.26
+ * @G_UNICODE_SCRIPT_IMPERIAL_ARAMAIC: Imperial Aramaic. Since 2.26
+ * @G_UNICODE_SCRIPT_INSCRIPTIONAL_PAHLAVI: Inscriptional Pahlavi. Since 2.26
+ * @G_UNICODE_SCRIPT_INSCRIPTIONAL_PARTHIAN: Inscriptional Parthian. Since 2.26
* @G_UNICODE_SCRIPT_JAVANESE: Javanese. Since 2.26
* @G_UNICODE_SCRIPT_KAITHI: Kaithi. Since 2.26
- * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26 Meetei Mayek. Since 2.26 Old South Arabian. Since 2.26
+ * @G_UNICODE_SCRIPT_LISU: Lisu. Since 2.26
+ * @G_UNICODE_SCRIPT_MEETEI_MAYEK: Meetei Mayek. Since 2.26
+ * @G_UNICODE_SCRIPT_OLD_SOUTH_ARABIAN: Old South Arabian. Since 2.26
* @G_UNICODE_SCRIPT_OLD_TURKIC: Old Turkic. Since 2.28
* @G_UNICODE_SCRIPT_SAMARITAN: Samaritan. Since 2.26
* @G_UNICODE_SCRIPT_TAI_THAM: Tai Tham. Since 2.26
@@ -2268,8 +2239,7 @@
* @G_UNICODE_SCRIPT_BRAHMI: Brahmi. Since 2.28
* @G_UNICODE_SCRIPT_MANDAIC: Mandaic. Since 2.28
* @G_UNICODE_SCRIPT_CHAKMA: Chakma. Since: 2.32
- * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32
- * @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32
+ * @G_UNICODE_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 2.32 @G_UNICODE_SCRIPT_MEROITIC_HIEROGLYPHS, Meroitic Hieroglyphs. Since: 2.32
* @G_UNICODE_SCRIPT_MIAO: Miao. Since: 2.32
* @G_UNICODE_SCRIPT_SHARADA: Sharada. Since: 2.32
* @G_UNICODE_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 2.32
@@ -2486,9 +2456,7 @@
*
* Check if the closure still needs a marshaller. See g_closure_set_marshal().
*
- * @closure.
- *
- * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on
+ * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on @closure.
*/
@@ -2617,11 +2585,11 @@
*
* |[
* G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_THING,
- * 0,
- * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
+ * gtk_gadget,
+ * GTK_TYPE_THING,
+ * 0,
+ * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
* ]|
* expands to
* |[
@@ -2634,42 +2602,42 @@
*
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
*
* GType
* gtk_gadget_get_type (void)
* {
- * return gtk_gadget_type_id;
+ * return gtk_gadget_type_id;
* }
*
* static void
* gtk_gadget_register_type (GTypeModule *type_module)
* {
- * const GTypeInfo g_define_type_info = {
- * sizeof (GtkGadgetClass),
- * (GBaseInitFunc) NULL,
- * (GBaseFinalizeFunc) NULL,
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * (GClassFinalizeFunc) gtk_gadget_class_finalize,
- * NULL, // class_data
- * sizeof (GtkGadget),
- * 0, // n_preallocs
- * (GInstanceInitFunc) gtk_gadget_init,
- * NULL // value_table
- * };
- * gtk_gadget_type_id = g_type_module_register_type (type_module,
- * GTK_TYPE_THING,
- * GtkGadget,
- * &g_define_type_info,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
+ * const GTypeInfo g_define_type_info = {
+ * sizeof (GtkGadgetClass),
+ * (GBaseInitFunc) NULL,
+ * (GBaseFinalizeFunc) NULL,
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * (GClassFinalizeFunc) gtk_gadget_class_finalize,
+ * NULL, // class_data
+ * sizeof (GtkGadget),
+ * 0, // n_preallocs
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * NULL // value_table
+ * };
+ * gtk_gadget_type_id = g_type_module_register_type (type_module,
+ * GTK_TYPE_THING,
+ * GtkGadget,
+ * &g_define_type_info,
+ * (GTypeFlags) flags);
+ * {
+ * const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
* }
* ]|
*
@@ -2767,11 +2735,11 @@
*
* |[
* G_DEFINE_TYPE_EXTENDED (GtkGadget,
- * gtk_gadget,
- * GTK_TYPE_WIDGET,
- * 0,
- * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
- * gtk_gadget_gizmo_init));
+ * gtk_gadget,
+ * GTK_TYPE_WIDGET,
+ * 0,
+ * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
* ]|
* expands to
* |[
@@ -2780,33 +2748,33 @@
* static gpointer gtk_gadget_parent_class = NULL;
* static void gtk_gadget_class_intern_init (gpointer klass)
* {
- * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
- * gtk_gadget_class_init ((GtkGadgetClass*) klass);
+ * gtk_gadget_parent_class = g_type_class_peek_parent (klass);
+ * gtk_gadget_class_init ((GtkGadgetClass*) klass);
* }
*
* GType
* gtk_gadget_get_type (void)
* {
- * static volatile gsize g_define_type_id__volatile = 0;
- * if (g_once_init_enter (&g_define_type_id__volatile))
- * {
- * GType g_define_type_id =
- * g_type_register_static_simple (GTK_TYPE_WIDGET,
- * g_intern_static_string ("GtkGadget"),
- * sizeof (GtkGadgetClass),
- * (GClassInitFunc) gtk_gadget_class_intern_init,
- * sizeof (GtkGadget),
- * (GInstanceInitFunc) gtk_gadget_init,
- * (GTypeFlags) flags);
- * {
- * const GInterfaceInfo g_implement_interface_info = {
- * (GInterfaceInitFunc) gtk_gadget_gizmo_init
- * };
- * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
- * }
- * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
- * }
- * return g_define_type_id__volatile;
+ * static volatile gsize g_define_type_id__volatile = 0;
+ * if (g_once_init_enter (&g_define_type_id__volatile))
+ * {
+ * GType g_define_type_id =
+ * g_type_register_static_simple (GTK_TYPE_WIDGET,
+ * g_intern_static_string ("GtkGadget"),
+ * sizeof (GtkGadgetClass),
+ * (GClassInitFunc) gtk_gadget_class_intern_init,
+ * sizeof (GtkGadget),
+ * (GInstanceInitFunc) gtk_gadget_init,
+ * (GTypeFlags) flags);
+ * {
+ * const GInterfaceInfo g_implement_interface_info = {
+ * (GInterfaceInitFunc) gtk_gadget_gizmo_init
+ * };
+ * g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
+ * }
+ * g_once_init_leave (&g_define_type_id__volatile, g_define_type_id);
+ * }
+ * return g_define_type_id__volatile;
* }
* ]|
* The only pieces which have to be manually provided are the definitions of
@@ -3280,9 +3248,7 @@
*
* Returns %TRUE if a #GNode is a leaf node.
*
- * (i.e. it has no children)
- *
- * Returns: %TRUE if the #GNode is a leaf node
+ * Returns: %TRUE if the #GNode is a leaf node (i.e. it has no children)
*/
@@ -3292,9 +3258,7 @@
*
* Returns %TRUE if a #GNode is the root of a tree.
*
- * (i.e. it has no parent or siblings)
- *
- * Returns: %TRUE if the #GNode is the root of a tree
+ * Returns: %TRUE if the #GNode is the root of a tree (i.e. it has no parent or siblings)
*/
@@ -3322,9 +3286,7 @@
*
* Return the name of a class structure's type.
*
- * should not be freed.
- *
- * Returns: Type name of @class. The string is owned by the type system and
+ * Returns: Type name of @class. The string is owned by the type system and should not be freed.
*/
@@ -3364,9 +3326,7 @@
*
* Get the name of an object's type.
*
- * should not be freed.
- *
- * Returns: Type name of @object. The string is owned by the type system and
+ * Returns: Type name of @object. The string is owned by the type system and should not be freed.
*/
@@ -3784,13 +3744,13 @@
* of g_signal_new().
* |[
* g_signal_new ("size_request",
- * G_TYPE_FROM_CLASS (gobject_class),
- * G_SIGNAL_RUN_FIRST,
- * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
- * NULL, NULL,
- * _gtk_marshal_VOID__BOXED,
- * G_TYPE_NONE, 1,
- * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
+ * G_TYPE_FROM_CLASS (gobject_class),
+ * G_SIGNAL_RUN_FIRST,
+ * G_STRUCT_OFFSET (GtkWidgetClass, size_request),
+ * NULL, NULL,
+ * _gtk_marshal_VOID__BOXED,
+ * G_TYPE_NONE, 1,
+ * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE);
* ]|
*/
@@ -4792,12 +4752,12 @@
*
* |[
* g_object_class_install_property (object_class,
- * PROP_AUTHORS,
- * g_param_spec_boxed ("authors",
- * _("Authors"),
- * _("List of authors"),
- * G_TYPE_STRV,
- * G_PARAM_READWRITE));
+ * PROP_AUTHORS,
+ * g_param_spec_boxed ("authors",
+ * _("Authors"),
+ * _("List of authors"),
+ * G_TYPE_STRV,
+ * G_PARAM_READWRITE));
*
* gchar *authors[] = { "Owen", "Tim", NULL };
* g_object_set (obj, "authors", authors, NULL);
@@ -5217,7 +5177,7 @@
* but it cannot be assigned to a variable.
*
* |[
- * GValue value = G_VALUE_INIT;
+ * GValue value = G_VALUE_INIT;
* ]|
*
* Since: 2.30
@@ -5513,7 +5473,8 @@
/**
* SECTION:enumerations_flags
* @short_description: Enumeration and flags types
- * @title: Enumeration and Flag Types g_param_spec_flags()
+ * @title: Enumeration and Flag Types
+ * @see_also: #GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags()
*
* The GLib type system provides fundamental types for enumeration and
* flags types. (Flags types are like enumerations, but allow their
@@ -5545,9 +5506,9 @@
* binding:
*
* |[
- * g_object_bind_property (object1, "property-a",
- * object2, "property-b",
- * G_BINDING_DEFAULT);
+ * g_object_bind_property (object1, "property-a",
+ * object2, "property-b",
+ * G_BINDING_DEFAULT);
* ]|
*
* will cause <emphasis>object2:property-b</emphasis> to be updated every
@@ -5559,9 +5520,9 @@
* other is updated as well, for instance:
*
* |[
- * g_object_bind_property (object1, "property-a",
- * object2, "property-b",
- * G_BINDING_BIDIRECTIONAL);
+ * g_object_bind_property (object1, "property-a",
+ * object2, "property-b",
+ * G_BINDING_BIDIRECTIONAL);
* ]|
*
* will keep the two properties in sync.
@@ -5572,12 +5533,12 @@
* applying it; for instance, the following binding:
*
* |[
- * g_object_bind_property_full (adjustment1, "value",
- * adjustment2, "value",
- * G_BINDING_BIDIRECTIONAL,
- * celsius_to_fahrenheit,
- * fahrenheit_to_celsius,
- * NULL, NULL);
+ * g_object_bind_property_full (adjustment1, "value",
+ * adjustment2, "value",
+ * G_BINDING_BIDIRECTIONAL,
+ * celsius_to_fahrenheit,
+ * fahrenheit_to_celsius,
+ * NULL, NULL);
* ]|
*
* will keep the <emphasis>value</emphasis> property of the two adjustments
@@ -5593,9 +5554,9 @@
* Note that #GBinding does not resolve cycles by itself; a cycle like
*
* |[
- * object1:propertyA -> object2:propertyB
- * object2:propertyB -> object3:propertyC
- * object3:propertyC -> object1:propertyA
+ * object1:propertyA -> object2:propertyB
+ * object2:propertyB -> object3:propertyC
+ * object3:propertyC -> object1:propertyA
* ]|
*
* might lead to an infinite loop. The loop, in this particular case,
@@ -5710,55 +5671,55 @@
*
* static void
* int2string (const GValue *src_value,
- * GValue *dest_value)
+ * GValue *dest_value)
* {
- * if (g_value_get_int (src_value) == 42)
- * g_value_set_static_string (dest_value, "An important number");
- * else
- * g_value_set_static_string (dest_value, "What's that?");
+ * if (g_value_get_int (src_value) == 42)
+ * g_value_set_static_string (dest_value, "An important number");
+ * else
+ * g_value_set_static_string (dest_value, "What's that?");
* }
*
* int
* main (int argc,
- * char *argv[])
+ * char *argv[])
* {
- * /* GValues must be initialized */
- * GValue a = G_VALUE_INIT;
- * GValue b = G_VALUE_INIT;
- * const gchar *message;
+ * /* GValues must be initialized */
+ * GValue a = G_VALUE_INIT;
+ * GValue b = G_VALUE_INIT;
+ * const gchar *message;
*
- * g_type_init ();
+ * g_type_init ();
*
- * /* The GValue starts empty */
- * g_assert (!G_VALUE_HOLDS_STRING (&a));
+ * /* The GValue starts empty */
+ * g_assert (!G_VALUE_HOLDS_STRING (&a));
*
- * /* Put a string in it */
- * g_value_init (&a, G_TYPE_STRING);
- * g_assert (G_VALUE_HOLDS_STRING (&a));
- * g_value_set_static_string (&a, "Hello, world!");
- * g_printf ("%s\n", g_value_get_string (&a));
+ * /* 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 */
- * g_value_unset (&a);
+ * /* Reset it to its pristine state */
+ * g_value_unset (&a);
*
- * /* It can then be reused for another type */
- * g_value_init (&a, G_TYPE_INT);
- * g_value_set_int (&a, 42);
+ * /* 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 */
- * g_value_init (&b, G_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 */
- * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
+ * /* An INT is transformable to a STRING */
+ * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING));
*
- * g_value_transform (&a, &b);
- * g_printf ("%s\n", g_value_get_string (&b));
+ * g_value_transform (&a, &b);
+ * g_printf ("%s\n", g_value_get_string (&b));
*
- * /* Attempt to transform it again using a custom transform function */
- * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string);
- * g_value_transform (&a, &b);
- * g_printf ("%s\n", g_value_get_string (&b));
- * return 0;
+ * /* 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));
+ * return 0;
* }
* ]|
*/
@@ -5786,6 +5747,7 @@
/**
* SECTION:gtype
* @short_description: The GLib Runtime type identification and management system
+ * @title: Type Information
*
* The GType API is the foundation of the GObject system. It provides the
* facilities for registering and managing all fundamental data types,
@@ -5829,7 +5791,8 @@
/**
* SECTION:gtypemodule
- * @short_description: Type loading modules <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist>
+ * @short_description: Type loading modules
+ * @see_also: <variablelist> <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist>
* @title: GTypeModule
*
* #GTypeModule provides a simple implementation of the #GTypePlugin
@@ -5874,41 +5837,41 @@
*
* <orderedlist>
* <listitem><para>
- * The type is initially introduced (usually upon loading the module
- * the first time, or by your main application that knows what modules
- * introduces what types), like this:
- * |[
- * new_type_id = g_type_register_dynamic (parent_type_id,
- * "TypeName",
- * new_type_plugin,
- * type_flags);
- * ]|
- * where <literal>new_type_plugin</literal> is an implementation of the
- * #GTypePlugin interface.
+ * The type is initially introduced (usually upon loading the module
+ * the first time, or by your main application that knows what modules
+ * introduces what types), like this:
+ * |[
+ * new_type_id = g_type_register_dynamic (parent_type_id,
+ * "TypeName",
+ * new_type_plugin,
+ * type_flags);
+ * ]|
+ * where <literal>new_type_plugin</literal> is an implementation of the
+ * #GTypePlugin interface.
* </para></listitem>
* <listitem><para>
- * The type's implementation is referenced, e.g. through
- * g_type_class_ref() or through g_type_create_instance() (this is
- * being called by g_object_new()) or through one of the above done on
- * a type derived from <literal>new_type_id</literal>.
+ * The type's implementation is referenced, e.g. through
+ * g_type_class_ref() or through g_type_create_instance() (this is
+ * being called by g_object_new()) or through one of the above done on
+ * a type derived from <literal>new_type_id</literal>.
* </para></listitem>
* <listitem><para>
- * This causes the type system to load the type's implementation by calling
- * g_type_plugin_use() and g_type_plugin_complete_type_info() on
- * <literal>new_type_plugin</literal>.
+ * This causes the type system to load the type's implementation by calling
+ * g_type_plugin_use() and g_type_plugin_complete_type_info() on
+ * <literal>new_type_plugin</literal>.
* </para></listitem>
* <listitem><para>
- * At some point the type's implementation isn't required anymore, e.g. after
- * g_type_class_unref() or g_type_free_instance() (called when the reference
- * count of an instance drops to zero).
+ * At some point the type's implementation isn't required anymore, e.g. after
+ * g_type_class_unref() or g_type_free_instance() (called when the reference
+ * count of an instance drops to zero).
* </para></listitem>
* <listitem><para>
- * This causes the type system to throw away the information retrieved from
- * g_type_plugin_complete_type_info() and then it calls
- * g_type_plugin_unuse() on <literal>new_type_plugin</literal>.
+ * This causes the type system to throw away the information retrieved from
+ * g_type_plugin_complete_type_info() and then it calls
+ * g_type_plugin_unuse() on <literal>new_type_plugin</literal>.
* </para></listitem>
* <listitem><para>
- * Things may repeat from the second step.
+ * Things may repeat from the second step.
* </para></listitem>
* </orderedlist>
*
@@ -5986,7 +5949,7 @@
* ...;
* /* restore floating state */
* if (was_floating)
- * g_object_force_floating (object);
+ * g_object_force_floating (object);
* g_object_unref (object); /* release previously acquired reference */
* ]|
*/
@@ -6041,19 +6004,19 @@
* A signal emission consists of five stages, unless prematurely stopped:
* <variablelist>
* <varlistentry><term></term><listitem><para>
- * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
+ * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
* </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para>
- * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
+ * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
* </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para>
- * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
+ * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
* </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para>
- * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
+ * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
* </para></listitem></varlistentry>
* <varlistentry><term></term><listitem><para>
- * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
+ * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
* </para></listitem></varlistentry>
* </variablelist>
* The user-provided signal handlers are called in the order they were
@@ -6094,14 +6057,14 @@
* for instance, the following code:
*
* |[
- * GValueArray *array = g_value_array_new (10);
+ * GValueArray *array = g_value_array_new (10);
* ]|
*
* can be replaced by:
*
* |[
- * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
- * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
+ * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
+ * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
* ]|
*/
@@ -6127,31 +6090,31 @@
* function present on most UNIX variants.
* Thus it provides the same advantages and pitfalls as alloca():
* <variablelist>
- * <varlistentry><term></term><listitem><para>
- * + alloca() is very fast, as on most systems it's implemented by just adjusting
- * the stack pointer register.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
- * blocks just build up and are released together at function end.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation sizes have to fit into the current stack frame. For instance in a
- * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
- * so be sparse with alloca() uses.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Allocation failure due to insufficient stack space is not indicated with a %NULL
- * return like e.g. with malloc(). Instead, most systems probably handle it the same
- * way as out of stack space situations from infinite function recursion, i.e.
- * with a segmentation fault.
- * </para></listitem></varlistentry>
- * <varlistentry><term></term><listitem><para>
- * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
- * Stack space allocated with alloca() in the same scope as a variable sized array
- * will be freed together with the variable sized array upon exit of that scope, and
- * not upon exit of the enclosing function scope.
- * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * + alloca() is very fast, as on most systems it's implemented by just adjusting
+ * the stack pointer register.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * + It doesn't cause any memory fragmentation, within its scope, separate alloca()
+ * blocks just build up and are released together at function end.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation sizes have to fit into the current stack frame. For instance in a
+ * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
+ * so be sparse with alloca() uses.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Allocation failure due to insufficient stack space is not indicated with a %NULL
+ * return like e.g. with malloc(). Instead, most systems probably handle it the same
+ * way as out of stack space situations from infinite function recursion, i.e.
+ * with a segmentation fault.
+ * </para></listitem></varlistentry>
+ * <varlistentry><term></term><listitem><para>
+ * - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
+ * Stack space allocated with alloca() in the same scope as a variable sized array
+ * will be freed together with the variable sized array upon exit of that scope, and
+ * not upon exit of the enclosing function scope.
+ * </para></listitem></varlistentry>
* </variablelist>
*
* Returns: space for @size bytes, allocated on the stack
@@ -6765,32 +6728,32 @@
* typedef struct _MyClosure MyClosure;
* struct _MyClosure
* {
- * GClosure closure;
- * // extra data goes here
+ * GClosure closure;
+ * // extra data goes here
* };
*
* static void
* my_closure_finalize (gpointer notify_data,
- * GClosure *closure)
+ * GClosure *closure)
* {
- * MyClosure *my_closure = (MyClosure *)closure;
+ * MyClosure *my_closure = (MyClosure *)closure;
*
- * // free extra data here
+ * // free extra data here
* }
*
* MyClosure *my_closure_new (gpointer data)
* {
- * GClosure *closure;
- * MyClosure *my_closure;
+ * GClosure *closure;
+ * MyClosure *my_closure;
*
- * closure = g_closure_new_simple (sizeof (MyClosure), data);
- * my_closure = (MyClosure *) closure;
+ * 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);
- * return my_closure;
+ * g_closure_add_finalize_notifier (closure, notify_data,
+ * my_closure_finalize);
+ * return my_closure;
* }
* ]|
*
@@ -6901,14 +6864,14 @@
* void
* foo_notify_set_closure (GClosure *closure)
* {
- * if (notify_closure)
- * g_closure_unref (notify_closure);
- * notify_closure = closure;
- * if (notify_closure)
- * {
- * g_closure_ref (notify_closure);
- * g_closure_sink (notify_closure);
- * }
+ * if (notify_closure)
+ * g_closure_unref (notify_closure);
+ * notify_closure = closure;
+ * if (notify_closure)
+ * {
+ * g_closure_ref (notify_closure);
+ * g_closure_sink (notify_closure);
+ * }
* }
* ]|
*
@@ -6941,17 +6904,17 @@
* |[
* static void
* my_enum_complete_type_info (GTypePlugin *plugin,
- * GType g_type,
- * GTypeInfo *info,
- * GTypeValueTable *value_table)
+ * GType g_type,
+ * GTypeInfo *info,
+ * GTypeValueTable *value_table)
* {
- * static const GEnumValue values[] = {
- * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
- * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
- * { 0, NULL, NULL }
- * };
+ * static const GEnumValue values[] = {
+ * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
+ * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" },
+ * { 0, NULL, NULL }
+ * };
*
- * g_enum_complete_type_info (type, info, values);
+ * g_enum_complete_type_info (type, info, values);
* }
* ]|
*/
@@ -6964,9 +6927,7 @@
*
* Returns the #GEnumValue for a value.
*
- * member of the enumeration
- *
- * Returns: the #GEnumValue for @value, or %NULL if @value is not a
+ * Returns: the #GEnumValue for @value, or %NULL if @value is not a member of the enumeration
*/
@@ -6977,9 +6938,7 @@
*
* Looks up a #GEnumValue by name.
*
- * enumeration doesn't have a member with that name
- *
- * Returns: the #GEnumValue with name @name, or %NULL if the
+ * Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn't have a member with that name
*/
@@ -6990,9 +6949,7 @@
*
* Looks up a #GEnumValue by nickname.
*
- * enumeration doesn't have a member with that nickname
- *
- * Returns: the #GEnumValue with nickname @nick, or %NULL if the
+ * Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn't have a member with that nickname
*/
@@ -7031,9 +6988,7 @@
*
* Returns the first #GFlagsValue which is set in @value.
*
- * none is set
- *
- * Returns: the first #GFlagsValue which is set in @value, or %NULL if
+ * Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set
*/
@@ -7044,9 +6999,7 @@
*
* Looks up a #GFlagsValue by name.
*
- * flag with that name
- *
- * Returns: the #GFlagsValue with name @name, or %NULL if there is no
+ * Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with that name
*/
@@ -7057,9 +7010,7 @@
*
* Looks up a #GFlagsValue by nickname.
*
- * no flag with that nickname
- *
- * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is
+ * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag with that nickname
*/
@@ -7128,10 +7079,7 @@
* Checks if any events are pending for the default #GMainContext
* (i.e. ready to be processed).
*
- *
- * Deprected: 2.2: Use g_main_context_pending() instead.
- *
- * Returns: %TRUE if any events are pending.
+ * Returns: %TRUE if any events are pending. Deprected: 2.2: Use g_main_context_pending() instead.
*/
@@ -7242,9 +7190,7 @@
*
* Gets the first child of a #GNode.
*
- * or has no children
- *
- * Returns: the first child of @node, or %NULL if @node is %NULL
+ * Returns: the first child of @node, or %NULL if @node is %NULL or has no children
*/
@@ -7290,9 +7236,7 @@
*
* Gets the next sibling of a #GNode.
*
- * or %NULL
- *
- * Returns: the next sibling of @node, or %NULL if @node is the last node
+ * Returns: the next sibling of @node, or %NULL if @node is the last node or %NULL
*/
@@ -7313,9 +7257,7 @@
*
* Gets the previous sibling of a #GNode.
*
- * node or %NULL
- *
- * Returns: the previous sibling of @node, or %NULL if @node is the first
+ * Returns: the previous sibling of @node, or %NULL if @node is the first node or %NULL
*/
@@ -7388,7 +7330,7 @@
* updated using the same value. For instance:
*
* |[
- * g_object_bind_property (action, "active", widget, "sensitive", 0);
+ * g_object_bind_property (action, "active", widget, "sensitive", 0);
* ]|
*
* Will result in the "sensitive" property of the widget #GObject instance to be
@@ -7406,10 +7348,7 @@
*
* A #GObject can have multiple bindings.
*
- * binding between the two #GObject instances. The binding is released
- * whenever the #GBinding reference count reaches zero.
- *
- * Returns: (transfer none): the #GBinding instance representing the
+ * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero.
* Since: 2.26
*/
@@ -7450,10 +7389,7 @@
* for each transformation function, please use
* g_object_bind_property_with_closures() instead.</note>
*
- * binding between the two #GObject instances. The binding is released
- * whenever the #GBinding reference count reaches zero.
- *
- * Returns: (transfer none): the #GBinding instance representing the
+ * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero.
* Since: 2.26
*/
@@ -7476,12 +7412,8 @@
* g_object_bind_property_full(), using #GClosure<!-- -->s instead of
* function pointers.
*
- *
- * binding between the two #GObject instances. The binding is released
- * whenever the #GBinding reference count reaches zero.
- *
* Rename to: g_object_bind_property_full
- * Returns: (transfer none): the #GBinding instance representing the
+ * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero.
* Since: 2.26
*/
@@ -7493,9 +7425,7 @@
*
* Looks up the #GParamSpec for a property of a class.
*
- * %NULL if the class doesn't have a property of that name
- *
- * Returns: (transfer none): the #GParamSpec for the property, or
+ * Returns: (transfer none): the #GParamSpec for the property, or %NULL if the class doesn't have a property of that name
*/
@@ -7520,7 +7450,7 @@
*
* |[
* enum {
- * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES
+ * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES
* };
*
* static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, };
@@ -7528,24 +7458,24 @@
* static void
* my_object_class_init (MyObjectClass *klass)
* {
- * GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
- *
- * obj_properties[PROP_FOO] =
- * g_param_spec_int ("foo", "Foo", "Foo",
- * -1, G_MAXINT,
- * 0,
- * G_PARAM_READWRITE);
- *
- * obj_properties[PROP_BAR] =
- * g_param_spec_string ("bar", "Bar", "Bar",
- * NULL,
- * G_PARAM_READWRITE);
- *
- * gobject_class->set_property = my_object_set_property;
- * gobject_class->get_property = my_object_get_property;
- * g_object_class_install_properties (gobject_class,
- * N_PROPERTIES,
- * obj_properties);
+ * GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
+ *
+ * obj_properties[PROP_FOO] =
+ * g_param_spec_int ("foo", "Foo", "Foo",
+ * -1, G_MAXINT,
+ * 0,
+ * G_PARAM_READWRITE);
+ *
+ * obj_properties[PROP_BAR] =
+ * g_param_spec_string ("bar", "Bar", "Bar",
+ * NULL,
+ * G_PARAM_READWRITE);
+ *
+ * gobject_class->set_property = my_object_set_property;
+ * gobject_class->get_property = my_object_get_property;
+ * g_object_class_install_properties (gobject_class,
+ * N_PROPERTIES,
+ * obj_properties);
* }
* ]|
*
@@ -7555,12 +7485,12 @@
* void
* my_object_set_foo (MyObject *self, gint foo)
* {
- * if (self->foo != foo)
- * {
- * self->foo = foo;
- * g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]);
- * }
- * }
+ * if (self->foo != foo)
+ * {
+ * self->foo = foo;
+ * g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]);
+ * }
+ * }
* ]|
*
* Since: 2.26
@@ -7588,9 +7518,7 @@
*
* Get an array of #GParamSpec* for all properties of a class.
*
- * #GParamSpec* which should be freed after use
- *
- * Returns: (array length=n_properties) (transfer container): an array of
+ * Returns: (array length=n_properties) (transfer container): an array of #GParamSpec* which should be freed after use
*/
@@ -7692,14 +7620,14 @@
* </variablelist>
*
* |[
- * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
- * "type", GTK_WINDOW_POPUP,
- * "child", menu,
- * NULL),
- * "signal::event", gtk_menu_window_event, menu,
- * "signal::size_request", gtk_menu_window_size_request, menu,
- * "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
- * NULL);
+ * menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
+ * "type", GTK_WINDOW_POPUP,
+ * "child", menu,
+ * NULL),
+ * "signal::event", gtk_menu_window_event, menu,
+ * "signal::size_request", gtk_menu_window_size_request, menu,
+ * "signal::destroy", gtk_widget_destroyed, &menu->toplevel,
+ * NULL);
* ]|
*
* Returns: (transfer none): @object
@@ -7767,20 +7695,20 @@
* of three properties - one of type #G_TYPE_INT,
* one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
* <programlisting>
- * gint intval;
- * gchar *strval;
- * GObject *objval;
+ * gint intval;
+ * gchar *strval;
+ * GObject *objval;
*
- * g_object_get (my_object,
- * "int-property", &intval,
- * "str-property", &strval,
- * "obj-property", &objval,
- * NULL);
+ * g_object_get (my_object,
+ * "int-property", &intval,
+ * "str-property", &strval,
+ * "obj-property", &objval,
+ * NULL);
*
- * // Do something with intval, strval, objval
+ * // Do something with intval, strval, objval
*
- * g_free (strval);
- * g_object_unref (objval);
+ * g_free (strval);
+ * g_object_unref (objval);
* </programlisting>
* </example>
*/
@@ -7854,12 +7782,8 @@
* if you know the interface has already been loaded,
* g_type_default_interface_peek().
*
- *
- * interface with the name @property_name, or %NULL if no
- * such property exists.
- *
* Since: 2.4
- * Returns: (transfer none): the #GParamSpec for the property of the
+ * Returns: (transfer none): the #GParamSpec for the property of the interface with the name @property_name, or %NULL if no such property exists.
*/
@@ -7897,14 +7821,8 @@
* g_type_default_interface_ref(), or, if you know the interface has
* already been loaded, g_type_default_interface_peek().
*
- *
- * pointer to an array of pointers to #GParamSpec
- * structures. The paramspecs are owned by GLib, but the
- * array should be freed with g_free() when you are done with
- * it.
- *
* Since: 2.4
- * Returns: (array length=n_properties_p) (transfer container): a
+ * Returns: (array length=n_properties_p) (transfer container): a pointer to an array of pointers to #GParamSpec structures. The paramspecs are owned by GLib, but the array should be freed with g_free() when you are done with it.
*/
@@ -7961,10 +7879,8 @@
* Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
* which are not explicitly specified are set to their default values.
*
- * @object_type
- *
* Rename to: g_object_new
- * Returns: (type GObject.Object) (transfer full): a new instance of
+ * Returns: (type GObject.Object) (transfer full): a new instance of @object_type
*/
@@ -7997,32 +7913,32 @@
* g_object_class_install_property() inside a static array, e.g.:
*
* |[
- * enum
- * {
- * PROP_0,
- * PROP_FOO,
- * PROP_LAST
- * };
- *
- * static GParamSpec *properties[PROP_LAST];
- *
- * static void
- * my_object_class_init (MyObjectClass *klass)
- * {
- * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
- * 0, 100,
- * 50,
- * G_PARAM_READWRITE);
- * g_object_class_install_property (gobject_class,
- * PROP_FOO,
- * properties[PROP_FOO]);
- * }
+ * enum
+ * {
+ * PROP_0,
+ * PROP_FOO,
+ * PROP_LAST
+ * };
+ *
+ * static GParamSpec *properties[PROP_LAST];
+ *
+ * static void
+ * my_object_class_init (MyObjectClass *klass)
+ * {
+ * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo",
+ * 0, 100,
+ * 50,
+ * G_PARAM_READWRITE);
+ * g_object_class_install_property (gobject_class,
+ * PROP_FOO,
+ * properties[PROP_FOO]);
+ * }
* ]|
*
* and then notify a change on the "foo" property with:
*
* |[
- * g_object_notify_by_pspec (self, properties[PROP_FOO]);
+ * g_object_notify_by_pspec (self, properties[PROP_FOO]);
* ]|
*
* Since: 2.26
@@ -8210,26 +8126,26 @@
* |[
* void
* object_add_to_user_list (GObject *object,
- * const gchar *new_string)
+ * const gchar *new_string)
* {
- * // the quark, naming the object data
- * GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
- * // retrive the old string list
- * GList *list = g_object_steal_qdata (object, quark_string_list);
- *
- * // prepend new string
- * list = g_list_prepend (list, g_strdup (new_string));
- * // this changed 'list', so we need to set it again
- * g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
+ * // the quark, naming the object data
+ * GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
+ * // retrive the old string list
+ * GList *list = g_object_steal_qdata (object, quark_string_list);
+ *
+ * // prepend new string
+ * list = g_list_prepend (list, g_strdup (new_string));
+ * // this changed 'list', so we need to set it again
+ * g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
* }
* static void
* free_string_list (gpointer data)
* {
- * GList *node, *list = data;
+ * GList *node, *list = data;
*
- * for (node = list; node; node = node->next)
- * g_free (node->data);
- * g_list_free (list);
+ * for (node = list; node; node = node->next)
+ * g_free (node->data);
+ * g_list_free (list);
* }
* ]|
* Using g_object_get_qdata() in the above example, instead of
@@ -8487,11 +8403,8 @@
* of type #GParamSpecOverride. See g_object_class_override_property()
* for an example of the use of this capability.
*
- *
- * paramspec should be redirected, or %NULL if none.
- *
* Since: 2.4
- * Returns: (transfer none): paramspec to which requests on this
+ * Returns: (transfer none): paramspec to which requests on this paramspec should be redirected, or %NULL if none.
*/
@@ -8679,10 +8592,7 @@
* Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in
* the pool.
*
- * allocated array containing pointers to all #GParamSpecs
- * owned by @owner_type in the pool
- *
- * Returns: (array length=n_pspecs_p) (transfer container): a newly
+ * Returns: (array length=n_pspecs_p) (transfer container): a newly allocated array containing pointers to all #GParamSpecs owned by @owner_type in the pool
*/
@@ -8694,10 +8604,7 @@
* Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in
* the pool.
*
- * #GList of all #GParamSpec<!-- -->s owned by @owner_type in
- * the pool#GParamSpec<!-- -->s.
- *
- * Returns: (transfer container) (element-type GObject.ParamSpec): a
+ * Returns: (transfer container) (element-type GObject.ParamSpec): a #GList of all #GParamSpec<!-- -->s owned by @owner_type in the pool#GParamSpec<!-- -->s.
*/
@@ -8710,9 +8617,7 @@
*
* Looks up a #GParamSpec in the pool.
*
- * matching #GParamSpec was found.
- *
- * Returns: (transfer none): The found #GParamSpec, or %NULL if no
+ * Returns: (transfer none): The found #GParamSpec, or %NULL if no matching #GParamSpec was found.
*/
@@ -9002,9 +8907,7 @@
* See also g_value_type_transformable(), g_value_transform() and
* g_param_value_validate().
*
- * %FALSE otherwise and @dest_value is left untouched.
- *
- * Returns: %TRUE if transformation and validation were successful,
+ * Returns: %TRUE if transformation and validation were successful, %FALSE otherwise and @dest_value is left untouched.
*/
@@ -9145,7 +9048,7 @@
/**
* g_signal_chain_from_overridden:
- * @instance_and_params: (array) the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal.
+ * @instance_and_params: (array): the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal.
* @return_value: Location for the return value.
*
* Calls the original class closure of a signal. This function should only
@@ -9272,8 +9175,8 @@
* continue to work with future versions of GObject by checking
* that the signal handler is still connected before disconnected it:
* <informalexample><programlisting>
- * if (g_signal_handler_is_connected (instance, id))
- * g_signal_handler_disconnect (instance, id);
+ * if (g_signal_handler_is_connected (instance, id))
+ * g_signal_handler_disconnect (instance, id);
* </programlisting></informalexample>
*
* Returns: the handler id.
@@ -9574,9 +9477,7 @@
* emit the signal if no one is attached anyway, thus saving the cost
* of building the arguments.
*
- * otherwise.
- *
- * Returns: %TRUE if a handler is connected to the signal, %FALSE
+ * Returns: %TRUE if a handler is connected to the signal, %FALSE otherwise.
*/
@@ -10024,10 +9925,11 @@
/**
* g_type_check_instance:
* @instance: A valid #GTypeInstance structure.
- * @Returns: #TRUE if @instance is valid, #FALSE otherwise.
*
* Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE()
* macro.
+ *
+ * Returns: %TRUE if @instance is valid, %FALSE otherwise.
*/
@@ -10039,9 +9941,7 @@
* Return a newly allocated and 0-terminated array of type IDs, listing the
* child types of @type. The return value has to be g_free()ed after use.
*
- * and 0-terminated array of child types.
- *
- * Returns: (array length=n_children) (transfer full): Newly allocated
+ * Returns: (array length=n_children) (transfer full): Newly allocated and 0-terminated array of child types.
*/
@@ -10077,39 +9977,39 @@
* typedef struct _MyObjectPrivate MyObjectPrivate;
*
* struct _MyObject {
- * GObject parent;
+ * GObject parent;
*
- * MyObjectPrivate *priv;
+ * MyObjectPrivate *priv;
* };
*
* struct _MyObjectPrivate {
- * int some_field;
+ * int some_field;
* };
*
* static void
* my_object_class_init (MyObjectClass *klass)
* {
- * g_type_class_add_private (klass, sizeof (MyObjectPrivate));
+ * g_type_class_add_private (klass, sizeof (MyObjectPrivate));
* }
*
* static void
* my_object_init (MyObject *my_object)
* {
- * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object,
- * MY_TYPE_OBJECT,
- * MyObjectPrivate);
+ * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object,
+ * MY_TYPE_OBJECT,
+ * MyObjectPrivate);
* }
*
* static int
* my_object_get_some_field (MyObject *my_object)
* {
- * MyObjectPrivate *priv;
+ * MyObjectPrivate *priv;
*
- * g_return_val_if_fail (MY_IS_OBJECT (my_object), 0);
+ * g_return_val_if_fail (MY_IS_OBJECT (my_object), 0);
*
- * priv = my_object->priv;
+ * priv = my_object->priv;
*
- * return priv->some_field;
+ * return priv->some_field;
* }
* ]|
*
@@ -10126,10 +10026,7 @@
* may return %NULL if the class of the type passed in does not currently
* exist (hasn't been referenced before).
*
- * structure for the given type ID or %NULL if the class does not
- * currently exist.
- *
- * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
+ * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID or %NULL if the class does not currently exist.
*/
@@ -10148,9 +10045,7 @@
* g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
* </programlisting>
*
- * of @g_class.
- *
- * Returns: (type GObject.TypeClass) (transfer none): The parent class
+ * Returns: (type GObject.TypeClass) (transfer none): The parent class of @g_class.
*/
@@ -10161,11 +10056,8 @@
* A more efficient version of g_type_class_peek() which works only for
* static types.
*
- * structure for the given type ID or %NULL if the class does not
- * currently exist or is dynamically loaded.
- *
* Since: 2.4
- * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
+ * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID or %NULL if the class does not currently exist or is dynamically loaded.
*/
@@ -10177,9 +10069,7 @@
* @type. This function will demand-create the class if it doesn't
* exist already.
*
- * structure for the given type ID.
- *
- * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass
+ * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID.
*/
@@ -10223,9 +10113,7 @@
* type. Also language bindings should <emphasis>not</emphasis> use
* this function but g_object_new() instead.
*
- * treatment by the fundamental type implementation.
- *
- * Returns: An allocated and initialized instance, subject to further
+ * Returns: An allocated and initialized instance, subject to further treatment by the fundamental type implementation.
*/
@@ -10236,12 +10124,8 @@
* If the interface type @g_type is currently in use, returns its
* default interface vtable.
*
- *
- * vtable for the interface, or %NULL if the type is not currently in
- * use.
- *
* Since: 2.4
- * Returns: (type GObject.TypeInterface) (transfer none): the default
+ * Returns: (type GObject.TypeInterface) (transfer none): the default vtable for the interface, or %NULL if the type is not currently in use.
*/
@@ -10261,12 +10145,8 @@
* want to make sure that signals and properties for an interface
* have been installed.
*
- *
- * vtable for the interface; call g_type_default_interface_unref()
- * when you are done using the interface.
- *
* Since: 2.4
- * Returns: (type GObject.TypeInterface) (transfer none): the default
+ * Returns: (type GObject.TypeInterface) (transfer none): the default vtable for the interface; call g_type_default_interface_unref() when you are done using the interface.
*/
@@ -10340,9 +10220,7 @@
* The returned type ID represents the highest currently registered
* fundamental type identifier.
*
- * or 0 if the type system ran out of fundamental type IDs.
- *
- * Returns: The nextmost fundamental type ID to be registered,
+ * Returns: The nextmost fundamental type ID to be registered, or 0 if the type system ran out of fundamental type IDs.
*/
@@ -10353,9 +10231,7 @@
* Returns the #GTypePlugin structure for @type or
* %NULL if @type does not have a #GTypePlugin structure.
*
- * dynamic type, %NULL otherwise.
- *
- * Returns: (transfer none): The corresponding plugin if @type is a
+ * Returns: (transfer none): The corresponding plugin if @type is a dynamic type, %NULL otherwise.
*/
@@ -10422,9 +10298,7 @@
* @interface_type has not been added to @instance_type or does not
* have a #GTypePlugin structure. See g_type_add_interface_dynamic().
*
- * interface @interface_type of @instance_type.
- *
- * Returns: (transfer none): the #GTypePlugin for the dynamic
+ * Returns: (transfer none): the #GTypePlugin for the dynamic interface @interface_type of @instance_type.
*/
@@ -10436,10 +10310,7 @@
* Returns the #GTypeInterface structure of an interface to which the
* passed in class conforms.
*
- * structure of iface_type if implemented by @instance_class, %NULL
- * otherwise
- *
- * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface
+ * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface structure of iface_type if implemented by @instance_class, %NULL otherwise
*/
@@ -10452,11 +10323,7 @@
* deriving the implementation of an interface from the parent type and
* then possibly overriding some methods.
*
- * corresponding #GTypeInterface structure of the parent type of the
- * instance type to which @g_iface belongs, or %NULL if the parent
- * type doesn't conform to the interface.
- *
- * Returns: (transfer none) (type GObject.TypeInterface): The
+ * Returns: (transfer none) (type GObject.TypeInterface): The corresponding #GTypeInterface structure of the parent type of the instance type to which @g_iface belongs, or %NULL if the parent type doesn't conform to the interface.
*/
@@ -10467,12 +10334,8 @@
*
* Returns the prerequisites of an interfaces type.
*
- *
- * newly-allocated zero-terminated array of #GType containing
- * the prerequisites of @interface_type
- *
* Since: 2.2
- * Returns: (array length=n_prerequisites) (transfer full): a
+ * Returns: (array length=n_prerequisites) (transfer full): a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type
*/
@@ -10485,9 +10348,7 @@
* interface types that @type conforms to. The return value has to be
* g_free()ed after use.
*
- * allocated and 0-terminated array of interface types.
- *
- * Returns: (array length=n_interfaces) (transfer full): Newly
+ * Returns: (array length=n_interfaces) (transfer full): Newly allocated and 0-terminated array of interface types.
*/
@@ -10612,9 +10473,7 @@
* If loading the plugin fails, the use count is reset to
* its prior value.
*
- * loading the plugin failed.
- *
- * Returns: %FALSE if the plugin needed to be loaded and
+ * Returns: %FALSE if the plugin needed to be loaded and loading the plugin failed.
*/
@@ -10846,9 +10705,7 @@
* that implements or has internal knowledge of the implementation of
* @type.</emphasis>
*
- * %NULL if there is no #GTypeValueTable associated with @type.
- *
- * Returns: Location of the #GTypeValueTable associated with @type or
+ * Returns: Location of the #GTypeValueTable associated with @type or %NULL if there is no #GTypeValueTable associated with @type.
*/
@@ -11026,9 +10883,7 @@
* its reference count. If the contents of the #GValue are %NULL, then
* %NULL will be returned.
*
- * should be unreferenced when no longer needed.
- *
- * Returns: (type GObject.Object) (transfer full): object content of @value,
+ * Returns: (type GObject.Object) (transfer full): object content of @value, should be unreferenced when no longer needed.
*/
@@ -11039,9 +10894,7 @@
* Get the contents of a %G_TYPE_PARAM #GValue, increasing its
* reference count.
*
- * no longer needed.
- *
- * Returns: #GParamSpec content of @value, should be unreferenced when
+ * Returns: #GParamSpec content of @value, should be unreferenced when no longer needed.
*/
@@ -11061,9 +10914,7 @@
*
* Get the contents of a variant #GValue, increasing its refcount.
*
- * g_variant_unref() when no longer needed
- *
- * Returns: variant contents of @value, should be unrefed using
+ * Returns: variant contents of @value, should be unrefed using g_variant_unref() when no longer needed
* Since: 2.26
*/
@@ -11311,11 +11162,9 @@
* g_value_peek_pointer:
* @value: An initialized #GValue structure.
*
- * function asserts that g_value_fits_pointer() returned %TRUE for the
- * passed in value. This is an internal function introduced mainly
- * for C marshallers.
*
- * Returns: (transfer none): the value contents as pointer. This
+ *
+ * Returns: (transfer none): the value contents as pointer. This function asserts that g_value_fits_pointer() returned %TRUE for the passed in value. This is an internal function introduced mainly for C marshallers.
*/
@@ -11715,9 +11564,7 @@
* results and shouldn't be relied upon for production code (such
* as rcfile value or object property serialization).
*
- * Upon failing transformations, @dest_value is left untouched.
- *
- * Returns: Whether a transformation rule was found and could be applied.
+ * Returns: Whether a transformation rule was found and could be applied. Upon failing transformations, @dest_value is left untouched.
*/
@@ -11813,9 +11660,7 @@
* The caller should release the resulting reference in the usual way,
* by using g_object_unref().
*
- * by @weak_ref, or %NULL if it was empty
- *
- * Returns: (transfer full) (type GObject.Object): the object pointed to
+ * Returns: (transfer full) (type GObject.Object): the object pointed to by @weak_ref, or %NULL if it was empty
* Since: 2.32
*/
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
