diff options
| author | Dieter Verfaillie <dieterv@optionexplicit.be> | 2013-08-14 17:00:39 +0200 |
|---|---|---|
| committer | Dieter Verfaillie <dieterv@optionexplicit.be> | 2013-10-08 20:56:28 +0200 |
| commit | ba425f1fd48df193fe7a8c6cc559f0b408160604 (patch) | |
| tree | 39d726ef89cd8925eea02bc46e41255987b9544d | |
| parent | 23dddc02594e733b65f9be76dbf0a0a1e54bc67c (diff) | |
| download | gobject-introspection-ba425f1fd48df193fe7a8c6cc559f0b408160604.tar.gz | |
giscanner: honor line and paragraph breaks in description fields
GTK-Doc parameter description fields are allowed to span
multiple lines, tag description fields are allowed to span
multiple lines and paragraphs. A tool fixing/rewriting
GTK-Doc comment blocks in source files would need to have
description fields parsed and stored (almost) exactly as
they appear in the source file.
30 files changed, 4403 insertions, 1826 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index e7e69417..e5441a40 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -56,10 +56,17 @@ /** * GActionEntry: * @name: the name of the action - * @activate: the callback to connect to the "activate" signal of the action - * @parameter_type: the type of the parameter that must be passed to the activate function for this action, given as a single GVariant type string (or %NULL for no parameter) - * @state: the initial state for this action, given in GVariant text format. The state is parsed with no extra type information, so type tags must be added to the string if they are necessary. - * @change_state: the callback to connect to the "change-state" signal of the action + * @activate: the callback to connect to the "activate" signal of the + * action + * @parameter_type: the type of the parameter that must be passed to the + * activate function for this action, given as a single + * GVariant type string (or %NULL for no parameter) + * @state: the initial state for this action, given in GVariant text + * format. The state is parsed with no extra type information, + * so type tags must be added to the string if they are + * necessary. + * @change_state: the callback to connect to the "change-state" signal + * of the action * * This struct defines a single action. It is for use with * g_action_map_add_action_entries(). @@ -156,7 +163,8 @@ * @get_enabled: the virtual function pointer for g_action_get_enabled() * @get_state: the virtual function pointer for g_action_get_state() * @change_state: the virtual function pointer for g_action_change_state() - * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an 'activate' signal but that implementations of it may have one. + * @activate: the virtual function pointer for g_action_activate(). Note that #GAction does not have an + * 'activate' signal but that implementations of it may have one. * * The virtual function table for #GAction. * @@ -188,13 +196,15 @@ /** * GApplication::command-line: * @application: the application - * @command_line: a #GApplicationCommandLine representing the passed commandline + * @command_line: a #GApplicationCommandLine representing the + * passed commandline * * The ::command-line signal is emitted on the primary instance when * a commandline is not handled locally. See g_application_run() and * the #GApplicationCommandLine documentation for more information. * - * Returns: An integer that is set as the exit status for the calling process. See g_application_command_line_set_exit_status(). + * Returns: An integer that is set as the exit status for the calling + * process. See g_application_command_line_set_exit_status(). */ @@ -231,18 +241,42 @@ /** * GApplicationClass: * @startup: invoked on the primary instance immediately after registration - * @shutdown: invoked only on the registered primary instance immediately after the main loop terminates + * @shutdown: invoked only on the registered primary instance immediately + * after the main loop terminates * @activate: invoked on the primary instance when an activation occurs * @open: invoked on the primary instance when there are files to open - * @command_line: invoked on the primary instance when a command-line is not handled locally - * @local_command_line: invoked (locally) when the process has been invoked via commandline execution (as opposed to, say, D-Bus activation - which is not currently supported by GApplication). The virtual function has the chance to inspect (and possibly replace) the list of command line arguments. See g_application_run() for more information. - * @before_emit: invoked on the primary instance before 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance - * @after_emit: invoked on the primary instance after 'activate', 'open', 'command-line' or any action invocation, gets the 'platform data' from the calling instance - * @add_platform_data: invoked (locally) to add 'platform data' to be sent to the primary instance when activating, opening or invoking actions - * @quit_mainloop: Used to be invoked on the primary instance when the use count of the application drops to zero (and after any inactivity timeout, if requested). Not used anymore since 2.32 - * @run_mainloop: Used to be invoked on the primary instance from g_application_run() if the use-count is non-zero. Since 2.32, GApplication is iterating the main context directly and is not using @run_mainloop anymore - * @dbus_register: invoked locally during registration, if the application is using its D-Bus backend. You can use this to export extra objects on the bus, that need to exist before the application tries to own the bus name. The function is passed the #GDBusConnection to to session bus, and the object path that #GApplication will use to export is D-Bus API. If this function returns %TRUE, registration will proceed; otherwise registration will abort. Since: 2.34 - * @dbus_unregister: invoked locally during unregistration, if the application is using its D-Bus backend. Use this to undo anything done by the @dbus_register vfunc. Since: 2.34 + * @command_line: invoked on the primary instance when a command-line is + * not handled locally + * @local_command_line: invoked (locally) when the process has been invoked + * via commandline execution (as opposed to, say, D-Bus activation - which + * is not currently supported by GApplication). The virtual function has + * the chance to inspect (and possibly replace) the list of command line + * arguments. See g_application_run() for more information. + * @before_emit: invoked on the primary instance before 'activate', 'open', + * 'command-line' or any action invocation, gets the 'platform data' from + * the calling instance + * @after_emit: invoked on the primary instance after 'activate', 'open', + * 'command-line' or any action invocation, gets the 'platform data' from + * the calling instance + * @add_platform_data: invoked (locally) to add 'platform data' to be sent to + * the primary instance when activating, opening or invoking actions + * @quit_mainloop: Used to be invoked on the primary instance when the use + * count of the application drops to zero (and after any inactivity + * timeout, if requested). Not used anymore since 2.32 + * @run_mainloop: Used to be invoked on the primary instance from + * g_application_run() if the use-count is non-zero. Since 2.32, + * GApplication is iterating the main context directly and is not + * using @run_mainloop anymore + * @dbus_register: invoked locally during registration, if the application is + * using its D-Bus backend. You can use this to export extra objects on the + * bus, that need to exist before the application tries to own the bus name. + * The function is passed the #GDBusConnection to to session bus, and the + * object path that #GApplication will use to export is D-Bus API. + * If this function returns %TRUE, registration will proceed; otherwise + * registration will abort. Since: 2.34 + * @dbus_unregister: invoked locally during unregistration, if the application + * is using its D-Bus backend. Use this to undo anything done by the + * @dbus_register vfunc. Since: 2.34 * * Virtual function table for #GApplication. * @@ -423,7 +457,8 @@ /** * GDBusConnection::closed: * @connection: The #GDBusConnection emitting the signal. - * @remote_peer_vanished: %TRUE if @connection is closed because the remote peer closed its end of the connection. + * @remote_peer_vanished: %TRUE if @connection is closed because the + * remote peer closed its end of the connection. * @error: (allow-none): A #GError with more details about the event or %NULL. * * Emitted when the connection is closed. @@ -1136,7 +1171,8 @@ * that it's suitable to call g_dbus_connection_register_object() or * similar from the signal handler. * - * Returns: %TRUE to claim @connection, %FALSE to let other handlers run. + * Returns: %TRUE to claim @connection, %FALSE to let other handlers + * run. * Since: 2.26 */ @@ -1682,7 +1718,8 @@ * GMountOperation::show-processes: * @op: a #GMountOperation. * @message: string containing a message to display to the user. - * @processes: (element-type GPid): an array of #GPid for processes blocking the operation. + * @processes: (element-type GPid): an array of #GPid for processes + * blocking the operation. * @choices: an array of strings for each possible choice. * * Emitted when one or more processes are blocking an operation @@ -1706,8 +1743,11 @@ * GMountOperation::show-unmount-progress: * @op: a #GMountOperation: * @message: string containing a mesage to display to the user - * @time_left: the estimated time left before the operation completes, in microseconds, or -1 - * @bytes_left: the amount of bytes to be written before the operation completes (or -1 if such amount is not known), or zero if the operation is completed + * @time_left: the estimated time left before the operation completes, + * in microseconds, or -1 + * @bytes_left: the amount of bytes to be written before the operation + * completes (or -1 if such amount is not known), or zero if the operation + * is completed * * Emitted when an unmount operation has been busy for more than some time * (typically 1.5 seconds). @@ -2036,7 +2076,8 @@ /** * 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 @@ -2055,7 +2096,8 @@ * for each affected key. If any other connected handler returns * %TRUE then this default functionality will be suppressed. * - * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. + * Returns: %TRUE to stop other handlers from being invoked for the + * event. FALSE to propagate the event further. */ @@ -2098,7 +2140,8 @@ * connected handler returns %TRUE then this default functionality * will be suppressed. * - * Returns: %TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further. + * Returns: %TRUE to stop other handlers from being invoked for the + * event. FALSE to propagate the event further. */ @@ -2162,7 +2205,8 @@ * '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. */ @@ -2556,7 +2600,8 @@ * GSocketService::incoming: * @service: the #GSocketService * @connection: a new #GSocketConnection object - * @source_object: (allow-none): the source_object passed to g_socket_listener_add_address() + * @source_object: (allow-none): the source_object passed to + * g_socket_listener_add_address() * * The ::incoming signal is emitted when a new incoming connection * to @service needs to be handled. The handler must initiate the @@ -2893,7 +2938,10 @@ * need to worry about this, and can simply block in the signal * handler until the UI thread returns an answer. * - * 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. + * 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 */ @@ -3042,9 +3090,15 @@ /** * GTlsInteractionClass: - * @ask_password: ask for a password synchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument should have been filled in by using g_tls_password_set_value() or a similar function. + * @ask_password: ask for a password synchronously. If the implementation + * returns %G_TLS_INTERACTION_HANDLED, then the password argument should + * have been filled in by using g_tls_password_set_value() or a similar + * function. * @ask_password_async: ask for a password asynchronously. - * @ask_password_finish: complete operation to ask for a password asynchronously. If the implementation returns %G_TLS_INTERACTION_HANDLED, then the password argument of the async method should have been filled in by using g_tls_password_set_value() or a similar function. + * @ask_password_finish: complete operation to ask for a password asynchronously. + * If the implementation returns %G_TLS_INTERACTION_HANDLED, then the + * password argument of the async method should have been filled in by using + * g_tls_password_set_value() or a similar function. * * The class for #GTlsInteraction. Derived classes implement the various * virtual interaction methods to handle TLS interactions. @@ -3160,7 +3214,9 @@ * * Whether or not this is an abstract address * - * Deprecated: Use #GUnixSocketAddress:address-type, which distinguishes between zero-padded and non-zero-padded abstract addresses. + * Deprecated: Use #GUnixSocketAddress:address-type, which + * distinguishes between zero-padded and non-zero-padded + * abstract addresses. */ @@ -5909,7 +5965,8 @@ /** * SECTION:gpermission * @title: GPermission - * @short_description: An object representing the permission to perform a certain action + * @short_description: An object representing the permission to perform + * a certain action * * A #GPermission represents the status of the caller's permission to * perform a certain action. @@ -6446,7 +6503,8 @@ /** * SECTION:gsettingsschema - * @short_description: Introspecting and controlling the loading of GSettings schemas + * @short_description: Introspecting and controlling the loading of + * GSettings schemas * * The #GSettingsSchemaSource and #GSettingsSchema APIs provide a * mechanism for advanced control over the loading of schemas and a @@ -6835,7 +6893,8 @@ /** * SECTION:gsocketaddress - * @short_description: Abstract base class representing endpoints for socket communication + * @short_description: Abstract base class representing endpoints for + * socket communication * * #GSocketAddress is the equivalent of <type>struct sockaddr</type> * in the BSD sockets API. This is an abstract class; use @@ -9635,8 +9694,10 @@ /** * _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. - * @verify_func: (allow-none): a function to call to verify that a given implementation is usable in the current environment. + * @envvar: (allow-none): the name of an environment variable to + * override the default implementation. + * @verify_func: (allow-none): a function to call to verify that + * a given implementation is usable in the current environment. * * Retrieves the default object implementing @extension_point. * @@ -9654,14 +9715,17 @@ * The result is cached after it is generated the first time, and * the function is thread-safe. * - * Returns: (transfer none): an object implementing @extension_point, or %NULL if there are no usable implementations. + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. */ /** * _g_io_module_get_default_type: * @extension_point: the name of an extension point - * @envvar: (allow-none): the name of an environment variable to override the default implementation. + * @envvar: (allow-none): the name of an environment variable to + * override the default implementation. * @is_supported_offset: a vtable offset, or zero * * Retrieves the default class implementing @extension_point. @@ -9679,7 +9743,9 @@ * The result is cached after it is generated the first time, and * the function is thread-safe. * - * Returns: (transfer none): an object implementing @extension_point, or %NULL if there are no usable implementations. + * Returns: (transfer none): an object implementing + * @extension_point, or %NULL if there are no usable + * implementations. */ @@ -10059,7 +10125,8 @@ * The caller is responsible for freeing the list with g_strfreev() when * it is no longer required. * - * Returns: (transfer full): a %NULL-terminated array of the names of the actions in the groupb + * Returns: (transfer full): a %NULL-terminated array of the names of the + * actions in the groupb * Since: 2.28 */ @@ -10126,7 +10193,8 @@ /** * g_action_map_add_action_entries: * @action_map: a #GActionMap - * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to the first item in an array of #GActionEntry structs + * @entries: (array length=n_entries) (element-type GActionEntry): a pointer to + * the first item in an array of #GActionEntry structs * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated * @user_data: the user data for signal connections * @@ -10309,7 +10377,8 @@ * * Checks if a supported content type can be removed from an application. * - * Returns: %TRUE if it is possible to remove supported content types from a given @appinfo, %FALSE if not. + * Returns: %TRUE if it is possible to remove supported + * content types from a given @appinfo, %FALSE if not. */ @@ -10394,7 +10463,8 @@ * g_app_info_get_recommended_for_type() and * g_app_info_get_fallback_for_type(). * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. */ @@ -10405,7 +10475,8 @@ * Gets the commandline with which the application will be * started. * - * Returns: a string containing the @appinfo's commandline, or %NULL if this information is not available + * Returns: a string containing the @appinfo's commandline, + * or %NULL if this information is not available * Since: 2.20 */ @@ -10413,11 +10484,13 @@ /** * g_app_info_get_default_for_type: * @content_type: the content type to find a #GAppInfo for - * @must_support_uris: if %TRUE, the #GAppInfo is expected to support URIs + * @must_support_uris: if %TRUE, the #GAppInfo is expected to + * support URIs * * Gets the default #GAppInfo for a given content type. * - * Returns: (transfer full): #GAppInfo for given @content_type or %NULL on error. + * Returns: (transfer full): #GAppInfo for given @content_type or + * %NULL on error. */ @@ -10440,7 +10513,8 @@ * * Gets a human-readable description of an installed application. * - * Returns: a string containing a description of the application @appinfo, or %NULL if none. + * Returns: a string containing a description of the + * application @appinfo, or %NULL if none. */ @@ -10451,7 +10525,8 @@ * Gets the display name of the application. The display name is often more * descriptive to the user than the name itself. * - * Returns: the display name of the application for @appinfo, or the name if no display name is available. + * Returns: the display name of the application for @appinfo, or the name if + * no display name is available. * Since: 2.24 */ @@ -10462,7 +10537,8 @@ * * Gets the executable's name for the installed application. * - * Returns: a string containing the @appinfo's application binaries name + * Returns: a string containing the @appinfo's application + * binaries name */ @@ -10474,7 +10550,8 @@ * those applications which claim to support the given content type * by MIME type subclassing and not directly. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. * Since: 2.28 */ @@ -10485,7 +10562,8 @@ * * Gets the icon for the application. * - * Returns: (transfer none): the default #GIcon for @appinfo or %NULL if there is no default icon. + * Returns: (transfer none): the default #GIcon for @appinfo or %NULL + * if there is no default icon. */ @@ -10526,7 +10604,8 @@ * the last one for which g_app_info_set_as_last_used_for_type() has been * called. * - * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos for given @content_type or %NULL on error. + * Returns: (element-type GAppInfo) (transfer full): #GList of #GAppInfos + * for given @content_type or %NULL on error. * Since: 2.28 */ @@ -10542,7 +10621,8 @@ * g_app_info_add_supports_type(), but only those exported directly by * the application. * - * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): a list of content types. + * Returns: (transfer none) (array zero-terminated=1) (element-type utf8): + * a list of content types. * Since: 2.34 */ @@ -10743,7 +10823,8 @@ * This is a %NULL-terminated array of strings, where each string has * the form <literal>KEY=VALUE</literal>. * - * Returns: (array zero-terminated=1) (transfer full): the child's environment + * Returns: (array zero-terminated=1) (transfer full): the + * child's environment * Since: 2.32 */ @@ -10762,7 +10843,8 @@ * url="http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt"> * FreeDesktop.Org Startup Notifications standard</ulink>. * - * Returns: a startup notification ID for the application, or %NULL if not supported. + * Returns: a startup notification ID for the application, or %NULL if + * not supported. */ @@ -10855,7 +10937,8 @@ * The return value is %NULL-terminated and should be freed using * g_strfreev(). * - * Returns: (array length=argc) (transfer full): the string array containing the arguments (the argv) + * Returns: (array length=argc) (transfer full): the string array + * containing the arguments (the argv) * Since: 2.28 */ @@ -10898,7 +10981,8 @@ * See g_application_command_line_getenv() if you are only interested * in the value of a single environment variable. * - * Returns: (array zero-terminated=1) (transfer none): the environment strings, or %NULL if they were not sent + * Returns: (array zero-terminated=1) (transfer none): the environment + * strings, or %NULL if they were not sent * Since: 2.28 */ @@ -11455,7 +11539,11 @@ * Now there is #GActionMap for that. * * 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. + * 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. */ @@ -11544,7 +11632,8 @@ /** * g_async_initable_init_async: * @initable: a #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the operation. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -11591,12 +11680,14 @@ * g_async_initable_init_finish: * @initable: a #GAsyncInitable. * @res: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes asynchronous initialization and returns the result. * See g_async_initable_init_async(). * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. * Since: 2.22 */ @@ -11604,12 +11695,16 @@ /** * g_async_initable_new_async: * @object_type: a #GType supporting #GAsyncInitable. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the operation. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function - * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties - * @...: the value of the first property, followed by other property value pairs, and ended by %NULL. + * @first_property_name: (allow-none): the name of the first property, or %NULL if no + * properties + * @...: the value of the first property, followed by other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GAsyncInitable object. This is * similar to g_object_new() but also initializes the object asynchronously. @@ -11631,7 +11726,8 @@ * Finishes the async construction for the various g_async_initable_new * calls, returning the created object or %NULL on error. * - * Returns: (type GObject.Object) (transfer full): a newly created #GObject, or %NULL on error. Free with g_object_unref(). + * Returns: (type GObject.Object) (transfer full): a newly created #GObject, + * or %NULL on error. Free with g_object_unref(). * Since: 2.22 */ @@ -11639,11 +11735,14 @@ /** * g_async_initable_new_valist_async: * @object_type: a #GType supporting #GAsyncInitable. - * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. + * @first_property_name: the name of the first property, followed by + * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the operation. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function * * Helper function for constructing #GAsyncInitable object. This is @@ -11663,9 +11762,11 @@ * @object_type: a #GType supporting #GAsyncInitable. * @n_parameters: the number of parameters in @parameters * @parameters: the parameters to use to construct the object - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the operation. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the operation. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @callback: a #GAsyncReadyCallback to call when the initialization is finished + * @callback: a #GAsyncReadyCallback to call when the initialization is + * finished * @user_data: the data to pass to callback function * * Helper function for constructing #GAsyncInitable object. This is @@ -11685,7 +11786,8 @@ * * Gets the source object from a #GAsyncResult. * - * Returns: (transfer full): a new reference to the source object for the @res, or %NULL if there is none. + * Returns: (transfer full): a new reference to the source object for the @res, + * or %NULL if there is none. */ @@ -11707,7 +11809,8 @@ * Checks if @res has the given @source_tag (generally a function * pointer indicating the function @res was created by). * - * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if not. + * Returns: %TRUE if @res has the indicated @source_tag, %FALSE if + * not. * Since: 2.34 */ @@ -11729,7 +11832,8 @@ * also be extracted by virtual methods, to enable subclasses to chain * up correctly. * - * Returns: %TRUE if @error is has been filled in with an error from @res, %FALSE if not. + * Returns: %TRUE if @error is has been filled in with an error from + * @res, %FALSE if not. * Since: 2.34 */ @@ -11766,7 +11870,8 @@ * For the asynchronous, non-blocking, version of this function, see * g_buffered_input_stream_fill_async(). * - * Returns: the number of bytes read into @stream's buffer, up to @count, or -1 on error. + * Returns: the number of bytes read into @stream's buffer, up to @count, + * or -1 on error. */ @@ -11774,7 +11879,8 @@ * g_buffered_input_stream_fill_async: * @stream: a #GBufferedInputStream * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request * @cancellable: (allow-none): optional #GCancellable object * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer @@ -11846,7 +11952,8 @@ /** * g_buffered_input_stream_peek: * @stream: a #GBufferedInputStream - * @buffer: (array length=count) (element-type guint8): a pointer to an allocated chunk of memory + * @buffer: (array length=count) (element-type guint8): a pointer to + * an allocated chunk of memory * @offset: a #gsize * @count: a #gsize * @@ -11866,7 +11973,8 @@ * buffer must not be modified and will become invalid when reading from * the stream or filling the buffer. * - * Returns: (array length=count) (element-type guint8) (transfer none): read-only buffer + * Returns: (array length=count) (element-type guint8) (transfer none): + * read-only buffer */ @@ -11911,7 +12019,8 @@ * * Checks if the buffer automatically grows as data is added. * - * Returns: %TRUE if the @stream's buffer automatically grows, %FALSE otherwise. + * Returns: %TRUE if the @stream's buffer automatically grows, + * %FALSE otherwise. */ @@ -12097,7 +12206,8 @@ * Simply register objects to be exported in @bus_acquired_handler and * unregister the objects (if any) in @name_lost_handler. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ @@ -12115,7 +12225,8 @@ * Like g_bus_own_name() but takes a #GDBusConnection instead of a * #GBusType. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ @@ -12125,13 +12236,16 @@ * @connection: A #GDBusConnection. * @name: The well-known name to own. * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is + * acquired or %NULL. + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or + * %NULL. * * Version of g_bus_own_name_on_connection() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ @@ -12141,14 +12255,18 @@ * @bus_type: The type of bus to own a name on. * @name: The well-known name to own. * @flags: A set of flags from the #GBusNameOwnerFlags enumeration. - * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to the bus of type @bus_type or %NULL. - * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is acquired or %NULL. - * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or %NULL. + * @bus_acquired_closure: (allow-none): #GClosure to invoke when connected to + * the bus of type @bus_type or %NULL. + * @name_acquired_closure: (allow-none): #GClosure to invoke when @name is + * acquired or %NULL. + * @name_lost_closure: (allow-none): #GClosure to invoke when @name is lost or + * %NULL. * * Version of g_bus_own_name() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unown_name() to stop owning the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unown_name() to stop owning the name. * Since: 2.26 */ @@ -12213,7 +12331,8 @@ * should create object proxies in @name_appeared_handler and destroy * them again (if any) in @name_vanished_handler. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ @@ -12231,7 +12350,8 @@ * Like g_bus_watch_name() but takes a #GDBusConnection instead of a * #GBusType. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ @@ -12241,13 +12361,16 @@ * @connection: A #GDBusConnection. * @name: The name (well-known or unique) to watch. * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known + * to not exist or %NULL. * * Version of g_bus_watch_name_on_connection() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ @@ -12257,13 +12380,16 @@ * @bus_type: The type of bus to watch a name on. * @name: The name (well-known or unique) to watch. * @flags: Flags from the #GBusNameWatcherFlags enumeration. - * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known to exist or %NULL. - * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known to not exist or %NULL. + * @name_appeared_closure: (allow-none): #GClosure to invoke when @name is known + * to exist or %NULL. + * @name_vanished_closure: (allow-none): #GClosure to invoke when @name is known + * to not exist or %NULL. * * Version of g_bus_watch_name() using closures instead of callbacks for * easier binding in other languages. * - * Returns: An identifier (never 0) that an be used with g_bus_unwatch_name() to stop watching the name. + * Returns: An identifier (never 0) that an be used with + * g_bus_unwatch_name() to stop watching the name. * Since: 2.26 */ @@ -12285,7 +12411,8 @@ * * Creates a new icon for a bytes. * - * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given @bytes, or %NULL on error. + * Returns: (transfer full) (type GBytesIcon): a #GIcon for the given + * @bytes, or %NULL on error. * Since: 2.38 */ @@ -12332,7 +12459,8 @@ * * See #GCancellable::cancelled for details on how to use this. * - * Returns: The id of the signal handler or 0 if @cancellable has already been cancelled. + * Returns: The id of the signal handler or 0 if @cancellable has already + * been cancelled. * Since: 2.22 */ @@ -12366,7 +12494,8 @@ * * Gets the top cancellable from the stack. * - * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL if the stack is empty. + * Returns: (transfer none): a #GCancellable from the top of the stack, or %NULL + * if the stack is empty. */ @@ -12388,7 +12517,8 @@ * * See also g_cancellable_make_pollfd(). * - * Returns: A valid file descriptor. %-1 if the file descriptor is not supported, or on errors. + * Returns: A valid file descriptor. %-1 if the file descriptor + * is not supported, or on errors. */ @@ -12398,7 +12528,8 @@ * * Checks if a cancellable job has been cancelled. * - * Returns: %TRUE if @cancellable is cancelled, FALSE if called with %NULL or if item is not cancelled. + * Returns: %TRUE if @cancellable is cancelled, + * FALSE if called with %NULL or if item is not cancelled. */ @@ -12426,7 +12557,8 @@ * readable status. Reading to unset the readable status is done * with g_cancellable_reset(). * - * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on failure to prepare the cancellable. + * Returns: %TRUE if @pollfd was successfully initialized, %FALSE on + * failure to prepare the cancellable. * Since: 2.22 */ @@ -12582,7 +12714,8 @@ * 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). * - * Returns: %TRUE if the file type corresponds to a type that can be executable, %FALSE otherwise. + * Returns: %TRUE if the file type corresponds to a type that + * can be executable, %FALSE otherwise. */ @@ -12593,7 +12726,8 @@ * * Compares two content types for equality. * - * Returns: %TRUE if the two strings are identical or equivalent, %FALSE otherwise. + * Returns: %TRUE if the two strings are identical or equivalent, + * %FALSE otherwise. */ @@ -12603,7 +12737,8 @@ * * Tries to find a content type based on the mime type name. * - * Returns: (allow-none): Newly allocated string with content type or %NULL. Free with g_free() + * Returns: (allow-none): Newly allocated string with content type + * or %NULL. Free with g_free() * Since: 2.18 */ @@ -12614,7 +12749,8 @@ * * Gets the human readable description of the content type. * - * Returns: a short description of the content type @type. Free the returned string with g_free() + * Returns: a short description of the content type @type. Free the + * returned string with g_free() */ @@ -12627,7 +12763,8 @@ * See the <ulink url="http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec">shared-mime-info</ulink> * specification for more on the generic icon name. * - * Returns: (allow-none): the registered generic icon name for the given @type, or %NULL if unknown. Free with g_free() + * Returns: (allow-none): the registered generic icon name for the given @type, + * or %NULL if unknown. Free with g_free() * Since: 2.34 */ @@ -12638,7 +12775,8 @@ * * Gets the icon for a content type. * - * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned object with g_object_unref() + * Returns: (transfer full): #GIcon corresponding to the content type. Free the returned + * object with g_object_unref() */ @@ -12648,7 +12786,8 @@ * * Gets the mime type for the content type, if one is registered. * - * Returns: (allow-none): the registered mime type for the given @type, or %NULL if unknown. + * Returns: (allow-none): the registered mime type for the given @type, + * or %NULL if unknown. */ @@ -12658,7 +12797,8 @@ * * Gets the symbolic icon for a content type. * - * Returns: (transfer full): symbolic #GIcon corresponding to the content type. Free the returned object with g_object_unref() + * Returns: (transfer full): symbolic #GIcon corresponding to the content type. + * Free the returned object with g_object_unref() * Since: 2.34 */ @@ -12668,14 +12808,16 @@ * @filename: (allow-none): a string, or %NULL * @data: (allow-none) (array length=data_size): a stream of data, or %NULL * @data_size: the size of @data - * @result_uncertain: (allow-none) (out): return location for the certainty of the result, or %NULL + * @result_uncertain: (allow-none) (out): return location for the certainty + * of the result, or %NULL * * Guesses the content type based on example data. If the function is * uncertain, @result_uncertain will be set to %TRUE. Either @filename * or @data may be %NULL, in which case the guess will be based solely * on the other argument. * - * Returns: a string indicating a guessed content type for the given data. Free with g_free() + * Returns: a string indicating a guessed content type for the + * given data. Free with g_free() */ @@ -12695,7 +12837,8 @@ * This function is useful in the implementation of * g_mount_guess_content_type(). * - * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated array of zero or more content types. Free with g_strfreev() + * Returns: (transfer full) (array zero-terminated=1): an %NULL-terminated + * array of zero or more content types. Free with g_strfreev() * Since: 2.18 */ @@ -12707,7 +12850,8 @@ * * Determines if @type is a subset of @supertype. * - * Returns: %TRUE if @type is a kind of @supertype, %FALSE otherwise. + * Returns: %TRUE if @type is a kind of @supertype, + * %FALSE otherwise. */ @@ -12739,7 +12883,8 @@ /** * g_converter_convert: * @converter: a #GConverter. - * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer containing the data to convert. + * @inbuf: (array length=inbuf_size) (element-type guint8): the buffer + * containing the data to convert. * @inbuf_size: the number of bytes in @inbuf * @outbuf: a buffer to write converted data in. * @outbuf_size: the number of bytes in @outbuf, must be at least one @@ -12904,7 +13049,10 @@ * logged) to use this method if there is no #GCredentials support for * the OS or if @native_type isn't supported by the OS. * - * 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. + * 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 */ @@ -12954,7 +13102,8 @@ * This operation can fail if #GCredentials is not supported on the * the OS. * - * Returns: %TRUE if @credentials and @other_credentials has the same user, %FALSE otherwise or if @error is set. + * Returns: %TRUE if @credentials and @other_credentials has the same + * user, %FALSE otherwise or if @error is set. * Since: 2.26 */ @@ -13057,7 +13206,8 @@ * * Reads an unsigned 8-bit/1-byte value from @stream. * - * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0 + * if an error occurred. */ @@ -13072,7 +13222,8 @@ * 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(). * - * Returns: a signed 16-bit/2-byte value read from @stream or %0 if an error occurred. + * Returns: a signed 16-bit/2-byte value read from @stream or %0 if + * an error occurred. */ @@ -13091,7 +13242,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if an error occurred. + * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. */ @@ -13110,7 +13262,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a signed 64-bit/8-byte value read from @stream or %0 if an error occurred. + * Returns: a signed 64-bit/8-byte value read from @stream or %0 if + * an error occurred. */ @@ -13129,14 +13282,20 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * 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. + * 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. */ /** * g_data_input_stream_read_line_async: * @stream: a given #GDataInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -13164,7 +13323,12 @@ * string encoding in g_data_input_stream_read_line() applies here as * well. * - * 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. + * 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 */ @@ -13179,7 +13343,12 @@ * Finish an asynchronous call started by * g_data_input_stream_read_line_async(). * - * 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. + * 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 */ @@ -13197,7 +13366,12 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * 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. + * 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 */ @@ -13213,7 +13387,8 @@ * 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(). * - * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if + * an error occurred. */ @@ -13232,7 +13407,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if an error occurred. + * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if + * an error occurred. */ @@ -13251,7 +13427,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if an error occurred. + * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if + * an error occurred. */ @@ -13275,7 +13452,10 @@ * g_data_input_stream_read_upto() instead, but note that that function * does not consume the stop character. * - * 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. + * 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. */ @@ -13283,7 +13463,8 @@ * g_data_input_stream_read_until_async: * @stream: a given #GDataInputStream. * @stop_chars: characters to terminate the read. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied. * @user_data: (closure): the data to pass to callback function. @@ -13319,7 +13500,10 @@ * g_data_input_stream_read_until_async(). * * Since: 2.20 - * 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. + * 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. */ @@ -13327,7 +13511,8 @@ * g_data_input_stream_read_upto: * @stream: a #GDataInputStream * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is + * nul-terminated * @length: (out): a #gsize to get the length of the data read in * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @error: #GError for error reporting @@ -13343,7 +13528,10 @@ * Note that @stop_chars may contain '\0' if @stop_chars_len is * specified. * - * 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 + * 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 */ @@ -13352,8 +13540,10 @@ * g_data_input_stream_read_upto_async: * @stream: a #GDataInputStream * @stop_chars: characters to terminate the read - * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is nul-terminated - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @stop_chars_len: length of @stop_chars. May be -1 if @stop_chars is + * nul-terminated + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -13391,7 +13581,10 @@ * stop character. You have to use g_data_input_stream_read_byte() to * get it before calling g_data_input_stream_read_upto_async() again. * - * Returns: (transfer full): a string with the data that was read before encountering any of the stop characters. Set @length to 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 + * 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 */ @@ -13579,7 +13772,8 @@ /** * g_dbus_address_escape_value: - * @string: an unescaped string to be included in a D-Bus address as the value in a key-value pair + * @string: an unescaped string to be included in a D-Bus address + * as the value in a key-value pair * * Escape @string so it can appear in a D-Bus address as the value * part of a key-value pair. @@ -13589,7 +13783,8 @@ * which could be used in a D-Bus address like * <code>unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0</code>. * - * Returns: (transfer full): a copy of @string with all non-optionally-escaped bytes escaped + * Returns: (transfer full): a copy of @string with all + * non-optionally-escaped bytes escaped * Since: 2.36 */ @@ -13765,7 +13960,8 @@ * @connection: A #GDBusConnection. * @filter_function: A filter function. * @user_data: User data to pass to @filter_function. - * @user_data_free_func: Function to free @user_data with when filter is removed or %NULL. + * @user_data_free_func: Function to free @user_data with when filter + * is removed or %NULL. * * Adds a message filter. Filters are handlers that are run on all * incoming and outgoing messages, prior to standard dispatch. Filters @@ -13788,7 +13984,8 @@ * message. Similary, if a filter consumes an outgoing message, the * message will not be sent to the other peer. * - * Returns: A filter identifier that can be used with g_dbus_connection_remove_filter(). + * Returns: A filter identifier that can be used with + * g_dbus_connection_remove_filter(). * Since: 2.26 */ @@ -13796,16 +13993,21 @@ /** * g_dbus_connection_call: * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. + * @bus_name: (allow-none): A unique or well-known bus name or %NULL if + * @connection is not a message bus connection. * @object_path: Path of remote object. * @interface_name: D-Bus interface to invoke method on. * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the method + * or %NULL if not passing parameters. * @reply_type: (allow-none): The expected type of the reply, or %NULL. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. + * @timeout_msec: The timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't care about the result of the + * method invocation. * @user_data: The data to pass to @callback. * * Asynchronously invokes the @method_name method on the @@ -13863,7 +14065,8 @@ * * Finishes an operation started with g_dbus_connection_call(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -13871,14 +14074,17 @@ /** * g_dbus_connection_call_sync: * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. + * @bus_name: (allow-none): A unique or well-known bus name or %NULL if + * @connection is not a message bus connection. * @object_path: Path of remote object. * @interface_name: D-Bus interface to invoke method on. * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the method + * or %NULL if not passing parameters. * @reply_type: (allow-none): The expected type of the reply, or %NULL. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. + * @timeout_msec: The timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. * @error: Return location for error or %NULL. * @@ -13919,7 +14125,8 @@ * g_dbus_connection_call() for the asynchronous version of * this method. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -13927,17 +14134,22 @@ /** * g_dbus_connection_call_with_unix_fd_list: * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. + * @bus_name: (allow-none): A unique or well-known bus name or %NULL if + * @connection is not a message bus connection. * @object_path: Path of remote object. * @interface_name: D-Bus interface to invoke method on. * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the method + * or %NULL if not passing parameters. * @reply_type: (allow-none): The expected type of the reply, or %NULL. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. + * @timeout_msec: The timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't * care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't * care about the result of the + * method invocation. * @user_data: The data to pass to @callback. * * Like g_dbus_connection_call() but also takes a #GUnixFDList object. @@ -13957,7 +14169,8 @@ * * Finishes an operation started with g_dbus_connection_call_with_unix_fd_list(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -13965,14 +14178,17 @@ /** * g_dbus_connection_call_with_unix_fd_list_sync: * @connection: A #GDBusConnection. - * @bus_name: (allow-none): A unique or well-known bus name or %NULL if @connection is not a message bus connection. + * @bus_name: (allow-none): A unique or well-known bus name or %NULL if + * @connection is not a message bus connection. * @object_path: Path of remote object. * @interface_name: D-Bus interface to invoke method on. * @method_name: The name of the method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the method or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the method + * or %NULL if not passing parameters. * @reply_type: (allow-none): The expected type of the reply, or %NULL. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. + * @timeout_msec: The timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. @@ -13982,7 +14198,8 @@ * * This method is only available on UNIX. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -13991,7 +14208,8 @@ * g_dbus_connection_close: * @connection: A #GDBusConnection. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't care about the result. * @user_data: The data to pass to @callback. * * Closes @connection. Note that this never causes the process to @@ -14055,11 +14273,13 @@ /** * g_dbus_connection_emit_signal: * @connection: A #GDBusConnection. - * @destination_bus_name: (allow-none): The unique bus name for the destination for the signal or %NULL to emit to all listeners. + * @destination_bus_name: (allow-none): The unique bus name for the destination + * for the signal or %NULL to emit to all listeners. * @object_path: Path of remote object. * @interface_name: D-Bus interface to emit a signal on. * @signal_name: The name of the signal to emit. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters. * @error: Return location for error or %NULL. * * Emits a signal. @@ -14136,7 +14356,8 @@ * g_dbus_connection_flush: * @connection: A #GDBusConnection. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't care about the result. * @user_data: The data to pass to @callback. * * Asynchronously flushes @connection, that is, writes all queued @@ -14207,7 +14428,8 @@ * closed by the remote peer. See * #GDBusConnection:exit-on-close for more details. * - * Returns: Whether the process is terminated when @connection is closed by the remote peer. + * Returns: Whether the process is terminated when @connection is + * closed by the remote peer. * Since: 2.26 */ @@ -14219,7 +14441,8 @@ * The GUID of the peer performing the role of server when * authenticating. See #GDBusConnection:guid for more details. * - * Returns: The GUID. Do not free this string, it is owned by @connection. + * Returns: The GUID. Do not free this string, it is owned by + * @connection. * Since: 2.26 */ @@ -14234,7 +14457,8 @@ * high-level API such as g_dbus_connection_emit_signal(), * g_dbus_connection_call() or g_dbus_proxy_call(). * - * Returns: the last used serial or zero when no message has been sent within the current thread. + * Returns: the last used serial or zero when no message has been sent + * within the current thread. * Since: 2.34 */ @@ -14253,7 +14477,8 @@ * each application is a client. So this method will always return * %NULL for message bus clients. * - * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free this object, it is owned by @connection. + * Returns: (transfer none): A #GCredentials or %NULL if not available. Do not free + * this object, it is owned by @connection. * Since: 2.26 */ @@ -14281,7 +14506,9 @@ * bus. This can also be used to figure out if @connection is a * message bus connection. * - * Returns: The unique name or %NULL if @connection is not a message bus connection. Do not free this string, it is owned by @connection. + * Returns: The unique name or %NULL if @connection is not a message + * bus connection. Do not free this string, it is owned by + * @connection. * Since: 2.26 */ @@ -14498,7 +14725,8 @@ * * See <xref linkend="gdbus-server"/> for an example of how to use this method. * - * Returns: 0 if @error is set, otherwise a registration id (never 0) that can be used with g_dbus_connection_unregister_object() . + * 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 */ @@ -14548,7 +14776,8 @@ * * See <xref linkend="gdbus-subtree-server"/> for an example of how to use this method. * - * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) that can be used with g_dbus_connection_unregister_subtree() . + * 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 */ @@ -14569,7 +14798,8 @@ * @connection: A #GDBusConnection. * @message: A #GDBusMessage * @flags: Flags affecting how the message is sent. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. + * @out_serial: (out) (allow-none): Return location for serial number assigned + * to @message when sending it or %NULL. * @error: Return location for error or %NULL. * * Asynchronously sends @message to the peer represented by @connection. @@ -14592,7 +14822,8 @@ * Note that @message must be unlocked, unless @flags contain the * %G_DBUS_SEND_MESSAGE_FLAGS_PRESERVE_SERIAL flag. * - * Returns: %TRUE if the message was well-formed and queued for transmission, %FALSE if @error is set. + * Returns: %TRUE if the message was well-formed and queued for + * transmission, %FALSE if @error is set. * Since: 2.26 */ @@ -14602,10 +14833,13 @@ * @connection: A #GDBusConnection. * @message: A #GDBusMessage. * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. + * @timeout_msec: The timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout. + * @out_serial: (out) (allow-none): Return location for serial number assigned + * to @message when sending it or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is + * satisfied or %NULL if you don't care about the result. * @user_data: The data to pass to @callback. * * Asynchronously sends @message to the peer represented by @connection. @@ -14666,8 +14900,10 @@ * @connection: A #GDBusConnection. * @message: A #GDBusMessage. * @flags: Flags affecting how the message is sent. - * @timeout_msec: The timeout in milliseconds, -1 to use the default timeout or %G_MAXINT for no timeout. - * @out_serial: (out) (allow-none): Return location for serial number assigned to @message when sending it or %NULL. + * @timeout_msec: The timeout in milliseconds, -1 to use the default + * timeout or %G_MAXINT for no timeout. + * @out_serial: (out) (allow-none): Return location for serial number assigned + * to @message when sending it or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. * @error: Return location for error or %NULL. * @@ -14708,7 +14944,8 @@ /** * g_dbus_connection_set_exit_on_close: * @connection: A #GDBusConnection. - * @exit_on_close: Whether the process should be terminated when @connection is closed by the remote peer. + * @exit_on_close: Whether the process should be terminated + * when @connection is closed by the remote peer. * * Sets whether the process should be terminated when @connection is * closed by the remote peer. See #GDBusConnection:exit-on-close for @@ -14728,15 +14965,19 @@ /** * g_dbus_connection_signal_subscribe: * @connection: A #GDBusConnection. - * @sender: (allow-none): Sender name to match on (unique or well-known name) or %NULL to listen from all senders. - * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to match on all interfaces. + * @sender: (allow-none): Sender name to match on (unique or well-known name) + * or %NULL to listen from all senders. + * @interface_name: (allow-none): D-Bus interface name to match on or %NULL to + * match on all interfaces. * @member: (allow-none): D-Bus signal name to match on or %NULL to match on all signals. * @object_path: (allow-none): Object path to match on or %NULL to match on all object paths. - * @arg0: (allow-none): Contents of first string argument to match on or %NULL to match on all kinds of arguments. + * @arg0: (allow-none): Contents of first string argument to match on or %NULL + * to match on all kinds of arguments. * @flags: Flags describing how to subscribe to the signal (currently unused). * @callback: Callback to invoke when there is a signal matching the requested data. * @user_data: User data to pass to @callback. - * @user_data_free_func: (allow-none): Function to free @user_data with when subscription is removed or %NULL. + * @user_data_free_func: (allow-none): Function to free @user_data with when + * subscription is removed or %NULL. * * Subscribes to signals on @connection and invokes @callback with a * whenever the signal is received. Note that @callback @@ -14888,7 +15129,8 @@ * 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. * - * Returns: %TRUE if @error represents an error from a remote peer, %FALSE otherwise. + * Returns: %TRUE if @error represents an error from a remote peer, + * %FALSE otherwise. * Since: 2.26 */ @@ -14942,7 +15184,8 @@ * This is typically done in the routine that returns the #GQuark for * an error domain. * - * Returns: %TRUE if the association was created, %FALSE if it already exists. + * Returns: %TRUE if the association was created, %FALSE if it already + * exists. * Since: 2.26 */ @@ -15108,7 +15351,9 @@ * See the g_dbus_gvariant_to_gvalue() function for how to convert a * #GVariant to a #GValue. * - * Returns: A #GVariant (never floating) of #GVariantType @type holding the data from @gvalue or %NULL in case of failure. Free with g_variant_unref(). + * Returns: A #GVariant (never floating) of #GVariantType + * @type holding the data from @gvalue or %NULL in case of + * failure. Free with g_variant_unref(). * Since: 2.30 */ @@ -15136,7 +15381,8 @@ * * Gets the #GDBusObject that @interface_ belongs to, if any. * - * Returns: (transfer full): A #GDBusObject or %NULL. The returned reference should be freed with g_object_unref(). + * Returns: (transfer full): A #GDBusObject or %NULL. The returned + * reference should be freed with g_object_unref(). * Since: 2.32 */ @@ -15164,7 +15410,8 @@ * g_dbus_interface_dup_object() for a thread-safe * alternative.</warning> * - * Returns: (transfer none): A #GDBusObject or %NULL. The returned reference belongs to @interface_ and should not be freed. + * Returns: (transfer none): A #GDBusObject or %NULL. The returned + * reference belongs to @interface_ and should not be freed. * Since: 2.30 */ @@ -15314,7 +15561,8 @@ * * Use g_dbus_interface_skeleton_unexport() to unexport the object. * - * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with @error set. + * Returns: %TRUE if the interface was exported on @connection, otherwise %FALSE with + * @error set. * Since: 2.30 */ @@ -15342,7 +15590,8 @@ * * Gets the first connection that @interface_ is exported on, if any. * - * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is not exported anywhere. Do not free, the object belongs to @interface_. + * Returns: (transfer none): A #GDBusConnection or %NULL if @interface_ is + * not exported anywhere. Do not free, the object belongs to @interface_. * Since: 2.30 */ @@ -15353,7 +15602,10 @@ * * Gets a list of the connections that @interface_ is exported on. * - * 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(). + * 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 */ @@ -15388,7 +15640,8 @@ * * Gets the object path that @interface_ is exported on, if any. * - * Returns: A string owned by @interface_ or %NULL if @interface_ is not exported anywhere. Do not free, the string belongs to @interface_. + * 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 */ @@ -15538,7 +15791,8 @@ * transports in @string and that key/value pairs for each transport * are valid. * - * Returns: %TRUE if @string is a valid D-Bus address that is supported by this library, %FALSE if @error is set. + * Returns: %TRUE if @string is a valid D-Bus address that is + * supported by this library, %FALSE if @error is set. * Since: 2.26 */ @@ -15569,7 +15823,8 @@ * (and linked models) must also originate from this same context, with * the thread default main context unchanged. * - * Returns: (transfer full): a #GDBusMenuModel object. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusMenuModel object. Free with + * g_object_unref(). * Since: 2.32 */ @@ -15583,7 +15838,9 @@ * Utility function to calculate how many bytes are needed to * completely deserialize the D-Bus message stored at @blob. * - * 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). + * 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 */ @@ -15600,7 +15857,8 @@ * This operation can fail if e.g. @message contains file descriptors * and the per-process or system-wide open files limit is reached. * - * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): A new #GDBusMessage or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ @@ -15611,7 +15869,8 @@ * * Convenience to get the first item in the body of @message. * - * Returns: The string item or %NULL if the first item in the body of @message is not a string. + * Returns: The string item or %NULL if the first item in the body of + * @message is not a string. * Since: 2.26 */ @@ -15677,7 +15936,8 @@ * * Gets a header field on @message. * - * Returns: A #GVariant with the value if the header was found, %NULL otherwise. Do not free, it is owned by @message. + * Returns: A #GVariant with the value if the header was found, %NULL + * otherwise. Do not free, it is owned by @message. * Since: 2.26 */ @@ -15688,7 +15948,9 @@ * * Gets an array of all header fields on @message that are set. * - * 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(). + * 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 */ @@ -15813,7 +16075,8 @@ * * This method is only available on UNIX. * - * Returns: (transfer none): A #GUnixFDList or %NULL if no file descriptors are associated. Do not free, this object is owned by @message. + * 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 */ @@ -15849,7 +16112,8 @@ * order that the message was in can be retrieved using * g_dbus_message_get_byte_order(). * - * Returns: A new #GDBusMessage or %NULL if @error is set. Free with g_object_unref(). + * Returns: A new #GDBusMessage or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ @@ -15870,7 +16134,8 @@ /** * g_dbus_message_new_method_error: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message_format: The D-Bus error message in a printf() format. * @...: Arguments for @error_message_format. @@ -15884,7 +16149,8 @@ /** * g_dbus_message_new_method_error_literal: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message: The D-Bus error message. * @@ -15897,7 +16163,8 @@ /** * g_dbus_message_new_method_error_valist: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * @error_name: A valid D-Bus error name. * @error_message_format: The D-Bus error message in a printf() format. * @var_args: Arguments for @error_message_format. @@ -15911,7 +16178,8 @@ /** * g_dbus_message_new_method_reply: - * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to create a reply message to. + * @method_call_message: A message of type %G_DBUS_MESSAGE_TYPE_METHOD_CALL to + * create a reply message to. * * Creates a new #GDBusMessage that is a reply to @method_call_message. * @@ -16027,7 +16295,8 @@ /** * g_dbus_message_set_flags: * @message: A #GDBusMessage. - * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags enumeration bitwise ORed together). + * @flags: Flags for @message that are set (typically values from the #GDBusMessageFlags + * enumeration bitwise ORed together). * * Sets the flags to set on @message. * @@ -16174,7 +16443,9 @@ * Serializes @message to a blob. The byte order returned by * g_dbus_message_get_byte_order() will be used. * - * 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(). + * 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 */ @@ -16536,7 +16807,8 @@ * <link linkend="glib-Simple-XML-Subset-Parser.description">GMarkup</link>-based * parser that only accepts a subset of valid XML documents. * - * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free with g_dbus_node_info_unref(). + * Returns: A #GDBusNodeInfo structure or %NULL if @error is set. Free + * with g_dbus_node_info_unref(). * Since: 2.26 */ @@ -16573,7 +16845,8 @@ * Gets the D-Bus interface with name @interface_name associated with * @object, if any. * - * Returns: (transfer full): %NULL if not found, otherwise a #GDBusInterface that must be freed with g_object_unref(). + * Returns: (transfer full): %NULL if not found, otherwise a + * #GDBusInterface that must be freed with g_object_unref(). * Since: 2.30 */ @@ -16584,7 +16857,9 @@ * * Gets the D-Bus interfaces associated with @object. * - * 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(). + * 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 */ @@ -16606,7 +16881,8 @@ * * Gets the #GDBusConnection used by @manager. * - * Returns: (transfer none): A #GDBusConnection object. Do not free, the object belongs to @manager. + * Returns: (transfer none): A #GDBusConnection object. Do not free, + * the object belongs to @manager. * Since: 2.30 */ @@ -16617,7 +16893,8 @@ * * Gets the flags that @manager was constructed with. * - * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags enumeration. + * Returns: Zero of more flags from the #GDBusObjectManagerClientFlags + * enumeration. * Since: 2.30 */ @@ -16629,7 +16906,8 @@ * Gets the name that @manager is for, or %NULL if not a message bus * connection. * - * Returns: A unique or well-known name. Do not free, the string belongs to @manager. + * Returns: A unique or well-known name. Do not free, the string + * belongs to @manager. * Since: 2.30 */ @@ -16643,7 +16921,8 @@ * #GObject::notify signal to track changes to the * #GDBusObjectManagerClient:name-owner property. * - * Returns: The name owner or %NULL if no name owner exists. Free with g_free(). + * Returns: The name owner or %NULL if no name owner exists. Free with + * g_free(). * Since: 2.30 */ @@ -16681,7 +16960,9 @@ * * Finishes an operation started with g_dbus_object_manager_client_new(). * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -16720,7 +17001,9 @@ * * Finishes an operation started with g_dbus_object_manager_client_new_for_bus(). * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -16744,7 +17027,9 @@ * blocked until a reply is received. See g_dbus_object_manager_client_new_for_bus() * for the asynchronous version. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -16767,7 +17052,9 @@ * blocked until a reply is received. See g_dbus_object_manager_client_new() * for the asynchronous version. * - * Returns: (transfer full) (type GDBusObjectManagerClient): A #GDBusObjectManagerClient object or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full) (type GDBusObjectManagerClient): A + * #GDBusObjectManagerClient object or %NULL if @error is set. Free + * with g_object_unref(). * Since: 2.30 */ @@ -16781,7 +17068,8 @@ * Gets the interface proxy for @interface_name at @object_path, if * any. * - * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free with g_object_unref(). + * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free + * with g_object_unref(). * Since: 2.30 */ @@ -16793,7 +17081,8 @@ * * Gets the #GDBusObjectProxy at @object_path, if any. * - * Returns: (transfer full): A #GDBusObject or %NULL. Free with g_object_unref(). + * Returns: (transfer full): A #GDBusObject or %NULL. Free with + * g_object_unref(). * Since: 2.30 */ @@ -16815,7 +17104,10 @@ * * Gets all #GDBusObject objects known to @manager. * - * 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(). + * 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 */ @@ -16861,7 +17153,9 @@ * * Gets the #GDBusConnection used by @manager. * - * 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(). + * 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 */ @@ -16927,7 +17221,8 @@ * * Gets the connection that @proxy is for. * - * Returns: (transfer none): A #GDBusConnection. Do not free, the object is owned by @proxy. + * Returns: (transfer none): A #GDBusConnection. Do not free, the + * object is owned by @proxy. * Since: 2.30 */ @@ -17051,9 +17346,11 @@ * @method_name: Name of method to invoke. * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + * care about the result of the method invocation. * @user_data: The data to pass to @callback. * * Asynchronously invokes the @method_name method on @proxy. @@ -17111,7 +17408,8 @@ * * Finishes an operation started with g_dbus_proxy_call(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -17120,9 +17418,11 @@ * g_dbus_proxy_call_sync: * @proxy: A #GDBusProxy. * @method_name: Name of method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @cancellable: (allow-none): A #GCancellable or %NULL. * @error: Return location for error or %NULL. * @@ -17161,7 +17461,8 @@ * #GDBusProxy:g-interface-info) and @method_name is referenced by it, * then the return value is checked against the return type. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -17172,10 +17473,12 @@ * @method_name: Name of method to invoke. * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. - * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't care about the result of the method invocation. + * @callback: (allow-none): A #GAsyncReadyCallback to call when the request is satisfied or %NULL if you don't + * care about the result of the method invocation. * @user_data: The data to pass to @callback. * * Like g_dbus_proxy_call() but also takes a #GUnixFDList object. @@ -17195,7 +17498,8 @@ * * Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -17204,9 +17508,11 @@ * g_dbus_proxy_call_with_unix_fd_list_sync: * @proxy: A #GDBusProxy. * @method_name: Name of method to invoke. - * @parameters: (allow-none): A #GVariant tuple with parameters for the signal or %NULL if not passing parameters. + * @parameters: (allow-none): A #GVariant tuple with parameters for the signal + * or %NULL if not passing parameters. * @flags: Flags from the #GDBusCallFlags enumeration. - * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning "infinite") or -1 to use the proxy default timeout. + * @timeout_msec: The timeout in milliseconds (with %G_MAXINT meaning + * "infinite") or -1 to use the proxy default timeout. * @fd_list: (allow-none): A #GUnixFDList or %NULL. * @out_fd_list: (out) (allow-none): Return location for a #GUnixFDList or %NULL. * @cancellable: (allow-none): A #GCancellable or %NULL. @@ -17216,7 +17522,8 @@ * * This method is only available on UNIX. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with return values. Free with g_variant_unref(). + * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with + * return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -17233,7 +17540,9 @@ * #GDBusProxy:g-interface-info) and @property_name is referenced by * it, then @value is checked against the type of the property. * - * 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(). + * 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 */ @@ -17244,7 +17553,9 @@ * * Gets the names of all cached properties on @proxy. * - * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if @proxy has no cached properties. Free the returned array with g_strfreev(). + * 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 */ @@ -17294,7 +17605,8 @@ * that @proxy conforms to. See the #GDBusProxy:g-interface-info * property for more details. * - * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned object, it is owned by @proxy. + * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned + * object, it is owned by @proxy. * Since: 2.26 */ @@ -17434,7 +17746,8 @@ * g_dbus_proxy_new_for_bus_sync: * @bus_type: A #GBusType. * @flags: Flags used when constructing the proxy. - * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface that @proxy conforms to or %NULL. + * @info: (allow-none): A #GDBusInterfaceInfo specifying the minimal interface + * that @proxy conforms to or %NULL. * @name: A bus name (well-known or unique). * @object_path: An object path. * @interface_name: A D-Bus interface name. @@ -17565,7 +17878,8 @@ * Gets a D-Bus address string that can be used by clients to connect * to @server. * - * Returns: A D-Bus address string. Do not free, the string is owned by @server. + * Returns: A D-Bus address string. Do not free, the string is owned + * by @server. * Since: 2.26 */ @@ -17630,7 +17944,8 @@ * This is a synchronous failable constructor. See * g_dbus_server_new() for the asynchronous version. * - * Returns: A #GDBusServer or %NULL if @error is set. Free with g_object_unref(). + * Returns: A #GDBusServer or %NULL if @error is set. Free with + * g_object_unref(). * Since: 2.26 */ @@ -17682,7 +17997,8 @@ /** * g_desktop_app_info_get_action_name: * @info: a #GDesktopAppInfo - * @action_name: the name of the action as from g_desktop_app_info_list_actions() + * @action_name: the name of the action as from + * g_desktop_app_info_list_actions() * * Gets the user-visible display name of the "additional application * action" specified by @action_name. @@ -17704,7 +18020,8 @@ * * The @key is looked up in the "Desktop Entry" group. * - * Returns: the boolean value, or %FALSE if the key is not found + * Returns: the boolean value, or %FALSE if the key + * is not found * Since: 2.36 */ @@ -17715,7 +18032,8 @@ * * Gets the categories 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. + * Returns: The unparsed Categories key from the desktop file; + * i.e. no attempt is made to split it by ';' or validate it. */ @@ -17792,7 +18110,9 @@ * Note that g_app_info_should_show() for @info will include this check (with * %NULL for @desktop_env) as well as additional checks. * - * Returns: %TRUE if the @info should be shown in @desktop_env according to the <literal>OnlyShowIn</literal> and <literal>NotShowIn</literal> keys, %FALSE otherwise. + * 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 */ @@ -17805,7 +18125,8 @@ * WM_CLASS property of the main window of the application, if launched * through @info. * - * Returns: (transfer none): the startup WM class, or %NULL if none is set in the desktop file. + * Returns: (transfer none): the startup WM class, or %NULL if none is set + * in the desktop file. * Since: 2.34 */ @@ -17819,7 +18140,8 @@ * * The @key is looked up in the "Desktop Entry" group. * - * Returns: a newly allocated string, or %NULL if the key is not found + * Returns: a newly allocated string, or %NULL if the key + * is not found * Since: 2.36 */ @@ -17840,7 +18162,8 @@ /** * g_desktop_app_info_launch_action: * @info: a #GDesktopAppInfo - * @action_name: the name of the action as from g_desktop_app_info_list_actions() + * @action_name: the name of the action as from + * g_desktop_app_info_list_actions() * @launch_context: (allow-none): a #GAppLaunchContext * * Activates the named application action. @@ -17869,7 +18192,8 @@ * @uris: (element-type utf8): List of URIs * @launch_context: a #GAppLaunchContext * @spawn_flags: #GSpawnFlags, used for each process - * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for each process. + * @user_setup: (scope call): a #GSpawnChildSetupFunc, used once for + * each process. * @user_setup_data: (closure user_setup): User data for @user_setup * @pid_callback: (scope call): Callback for child processes * @pid_callback_data: (closure pid_callback): User data for @callback @@ -18011,7 +18335,8 @@ * * Checks if a drive can be polled for media changes. * - * Returns: %TRUE if the @drive can be polled for media changes, %FALSE otherwise. + * Returns: %TRUE if the @drive can be polled for media changes, + * %FALSE otherwise. */ @@ -18074,7 +18399,8 @@ * * Finishes ejecting a drive. * - * Returns: %TRUE if the drive has been ejected successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been ejected successfully, + * %FALSE otherwise. * Deprecated: 2.22: Use g_drive_eject_with_operation_finish() instead. */ @@ -18083,7 +18409,8 @@ * g_drive_eject_with_operation: * @drive: a #GDrive. * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -18100,7 +18427,8 @@ * g_drive_eject_with_operation_finish: * @drive: a #GDrive. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a drive. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -18118,7 +18446,9 @@ * Use g_drive_get_identifier() to obtain the identifiers * themselves. * - * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. + * Returns: (transfer full) (array zero-terminated=1): a %NULL-terminated + * array of strings containing kinds of identifiers. Use g_strfreev() + * to free. */ @@ -18128,7 +18458,8 @@ * * Gets the icon for @drive. * - * Returns: (transfer full): #GIcon for the @drive. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GIcon for the @drive. + * Free the returned object with g_object_unref(). */ @@ -18139,7 +18470,9 @@ * * Gets the identifier of the given kind for @drive. * - * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GDrive doesn't have this kind of identifier. + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GDrive + * doesn't have this kind of identifier. */ @@ -18149,7 +18482,8 @@ * * Gets the name of @drive. * - * Returns: a string containing @drive's name. The returned string should be freed when no longer needed. + * Returns: a string containing @drive's name. The returned + * string should be freed when no longer needed. */ @@ -18181,7 +18515,8 @@ * * Gets the icon for @drive. * - * Returns: (transfer full): symbolic #GIcon for the @drive. Free the returned object with g_object_unref(). + * Returns: (transfer full): symbolic #GIcon for the @drive. + * Free the returned object with g_object_unref(). * Since: 2.34 */ @@ -18227,7 +18562,8 @@ * * Checks if @drive is capabable of automatically detecting media changes. * - * Returns: %TRUE if the @drive is capabable of automatically detecting media changes, %FALSE otherwise. + * Returns: %TRUE if the @drive is capabable of automatically detecting + * media changes, %FALSE otherwise. */ @@ -18264,7 +18600,8 @@ * * Finishes an operation started with g_drive_poll_for_media() on a drive. * - * Returns: %TRUE if the drive has been poll_for_mediaed successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been poll_for_mediaed successfully, + * %FALSE otherwise. */ @@ -18272,7 +18609,8 @@ * g_drive_start: * @drive: a #GDrive. * @flags: flags affecting the start operation. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data to pass to @callback @@ -18295,7 +18633,8 @@ * * Finishes starting a drive. * - * Returns: %TRUE if the drive has been started successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been started successfully, + * %FALSE otherwise. * Since: 2.22 */ @@ -18304,7 +18643,8 @@ * g_drive_stop: * @drive: a #GDrive. * @flags: flags affecting the unmount if required for stopping. - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data to pass to @callback @@ -18327,7 +18667,8 @@ * * Finishes stopping a drive. * - * Returns: %TRUE if the drive has been stopped successfully, %FALSE otherwise. + * Returns: %TRUE if the drive has been stopped successfully, + * %FALSE otherwise. * Since: 2.22 */ @@ -18338,7 +18679,8 @@ * * Gives back the icon from @emblem. * - * Returns: (transfer none): a #GIcon. The returned object belongs to the emblem and should not be modified or freed. + * Returns: (transfer none): a #GIcon. The returned object belongs to + * the emblem and should not be modified or freed. * Since: 2.18 */ @@ -18404,7 +18746,8 @@ * * Gets the list of emblems for the @icon. * - * Returns: (element-type Gio.Emblem) (transfer none): a #GList of #GEmblem <!-- -->s that is owned by @emblemed + * Returns: (element-type Gio.Emblem) (transfer none): a #GList of + * #GEmblem <!-- -->s that is owned by @emblemed * Since: 2.18 */ @@ -18436,7 +18779,8 @@ * g_file_append_to: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Gets an output stream for appending data to the file. @@ -18457,7 +18801,8 @@ * %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. * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -18465,9 +18810,12 @@ * g_file_append_to_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for appending. @@ -18490,7 +18838,9 @@ * Finishes an asynchronous file append operation started with * g_file_append_to_async(). * - * Returns: (transfer full): a valid #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a valid #GFileOutputStream + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -18523,7 +18873,8 @@ * * Gets the file attribute with the name @name from @list. * - * Returns: a #GFileAttributeInfo for the @name, or %NULL if an attribute isn't found. + * Returns: a #GFileAttributeInfo for the @name, or %NULL if an + * attribute isn't found. */ @@ -18567,7 +18918,8 @@ * * TODO: this is awkwardly worded. * - * Returns: %TRUE if the matcher matches all of the entries in the given @ns, %FALSE otherwise. + * Returns: %TRUE if the matcher matches all of the entries + * in the given @ns, %FALSE otherwise. */ @@ -18577,7 +18929,8 @@ * * Gets the next matched attribute from a #GFileAttributeMatcher. * - * Returns: a string containing the next attribute or %NULL if no more attribute exist. + * Returns: a string containing the next attribute or %NULL if + * no more attribute exist. */ @@ -18663,7 +19016,8 @@ * is a limitation of the current implementation, but may be fixed * in the future. * - * Returns: A file attribute matcher matching all attributes of @matcher that are not matched by @subtract + * Returns: A file attribute matcher matching all attributes of + * @matcher that are not matched by @subtract */ @@ -18676,7 +19030,8 @@ * The output however, might not be identical, as the matcher may * decide to use a different order or omit needless parts. * - * Returns: a string describing the attributes the matcher matches against or %NULL if @matcher was %NULL. + * Returns: a string describing the attributes the matcher matches + * against or %NULL if @matcher was %NULL. * Since: 2.32 */ @@ -18695,8 +19050,10 @@ * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none) (scope call): function to callback with progress information, or %NULL if progress information is not needed + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none) (scope call): function to callback with + * progress information, or %NULL if progress information is not needed * @progress_callback_data: (closure): user data to pass to @progress_callback * @error: #GError to set on error, or %NULL * @@ -18746,9 +19103,12 @@ * @source: input #GFile * @destination: destination #GFile * @flags: set of #GFileCopyFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none): function to callback with progress information, or %NULL if progress information is not needed + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none): function to callback with progress + * information, or %NULL if progress information is not needed * @progress_callback_data: (closure): user data to pass to @progress_callback * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -18770,7 +19130,8 @@ * @source: a #GFile with attributes * @destination: a #GFile to copy attributes to * @flags: a set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, %NULL to ignore * * Copies the file attributes from @source to @destination. @@ -18782,7 +19143,8 @@ * all the metadata that is possible to copy is copied. This * is useful when implementing move by copy + delete source. * - * Returns: %TRUE if the attributes were copied successfully, %FALSE otherwise. + * Returns: %TRUE if the attributes were copied successfully, + * %FALSE otherwise. */ @@ -18802,7 +19164,8 @@ * g_file_create: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a new file and returns an output stream for writing to it. @@ -18825,7 +19188,9 @@ * be returned. Other errors are possible too, and depend on what kind * of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream for the newly created + * file, or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -18833,9 +19198,12 @@ * g_file_create_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously creates a new file and returns an output stream @@ -18859,7 +19227,8 @@ * Finishes an asynchronous file create operation started with * g_file_create_async(). * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -18867,7 +19236,8 @@ * g_file_create_readwrite: * @file: a #GFile * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: return location for a #GError, or %NULL * * Creates a new file and returns a stream for reading and @@ -18894,7 +19264,9 @@ * not supported, so make sure you really need to do read and write * streaming, rather than just opening for reading or writing. * - * Returns: (transfer full): a #GFileIOStream for the newly created file, or %NULL on error. Free the returned object with g_object_unref(). + * 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 */ @@ -18903,9 +19275,12 @@ * g_file_create_readwrite_async: * @file: input #GFile * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously creates a new file and returns a stream @@ -18931,7 +19306,8 @@ * Finishes an asynchronous file create operation started with * g_file_create_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -18939,7 +19315,8 @@ /** * g_file_delete: (virtual delete_file) * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Deletes a file. If the @file is a directory, it will only be @@ -18956,9 +19333,12 @@ /** * g_file_delete_async: (virtual delete_file_async) * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: the data to pass to callback function * * Asynchronously delete a file. If the @file is a directory, it will @@ -19003,7 +19383,8 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a new #GFile that is a duplicate of the given #GFile. + * Returns: (transfer full): a new #GFile that is a duplicate + * of the given #GFile. */ @@ -19011,8 +19392,10 @@ * g_file_eject_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Starts an asynchronous eject on a mountable. @@ -19037,8 +19420,10 @@ * Finishes an asynchronous eject operation started by * g_file_eject_mountable(). * - * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise. - * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() instead. + * Returns: %TRUE if the @file was ejected successfully. + * %FALSE otherwise. + * Deprecated: 2.22: Use g_file_eject_mountable_with_operation_finish() + * instead. */ @@ -19046,9 +19431,12 @@ * g_file_eject_mountable_with_operation: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Starts an asynchronous eject on a mountable. @@ -19073,7 +19461,8 @@ * Finishes an asynchronous eject operation started by * g_file_eject_mountable_with_operation(). * - * Returns: %TRUE if the @file was ejected successfully. %FALSE otherwise. + * Returns: %TRUE if the @file was ejected successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -19083,7 +19472,8 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: #GError for error reporting * * Gets the requested information about the files in a directory. @@ -19110,7 +19500,8 @@ * be returned. If the file is not a directory, the %G_IO_ERROR_NOT_DIRECTORY * error will be returned. Other errors are possible too. * - * Returns: (transfer full): A #GFileEnumerator if successful, %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): A #GFileEnumerator if successful, + * %NULL on error. Free the returned object with g_object_unref(). */ @@ -19119,9 +19510,12 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about the files @@ -19146,7 +19540,9 @@ * Finishes an async enumerate children operation. * See g_file_enumerate_children_async(). * - * Returns: (transfer full): a #GFileEnumerator or %NULL if an error occurred. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileEnumerator or %NULL + * if an error occurred. + * Free the returned object with g_object_unref(). */ @@ -19170,7 +19566,8 @@ /** * g_file_enumerator_close_async: * @enumerator: a #GFileEnumerator. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -19188,7 +19585,8 @@ * g_file_enumerator_close_finish: * @enumerator: a #GFileEnumerator. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes closing a file enumerator, started from g_file_enumerator_close_async(). * @@ -19208,7 +19606,8 @@ /** * g_file_enumerator_get_child: * @enumerator: a #GFileEnumerator - * @info: a #GFileInfo gotten from g_file_enumerator_next_file() or the async equivalents. + * @info: a #GFileInfo gotten from g_file_enumerator_next_file() + * or the async equivalents. * * Return a new #GFile which refers to the file named by @info in the source * directory of @enumerator. This function is primarily intended to be used @@ -19275,7 +19674,8 @@ * enumerator is at the end, %NULL will be returned and @error will * be unset. * - * 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. + * 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. */ @@ -19283,7 +19683,8 @@ * g_file_enumerator_next_files_async: * @enumerator: a #GFileEnumerator. * @num_files: the number of file info objects to request - * @io_priority: the <link linkend="io-priority">io priority</link> of the request. + * @io_priority: the <link linkend="io-priority">io priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -19314,11 +19715,14 @@ * g_file_enumerator_next_files_finish: * @enumerator: a #GFileEnumerator. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes the asynchronous operation started with g_file_enumerator_next_files_async(). * - * 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. + * 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. */ @@ -19344,14 +19748,16 @@ * * This call does no blocking I/O. * - * Returns: %TRUE if @file1 and @file2 are equal. %FALSE if either is not a #GFile. + * Returns: %TRUE if @file1 and @file2 are equal. + * %FALSE if either is not a #GFile. */ /** * g_file_find_enclosing_mount: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Gets a #GMount for the #GFile. @@ -19364,16 +19770,21 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GMount where the @file is located or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GMount where the @file is located + * or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_find_enclosing_mount_async: * @file: a #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the mount for the file. @@ -19396,7 +19807,8 @@ * Finishes an asynchronous find mount request. * See g_file_find_enclosing_mount_async(). * - * Returns: (transfer full): #GMount for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GMount for given @file or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -19418,7 +19830,9 @@ * * This call does no blocking I/O. * - * 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. + * 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. */ @@ -19435,7 +19849,8 @@ * * This call does no blocking I/O. * - * Returns: (transfer full): a #GFile to a child specified by @name. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile to a child specified by @name. + * Free the returned object with g_object_unref(). */ @@ -19454,7 +19869,9 @@ * * This call does no blocking I/O. * - * 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(). + * 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(). */ @@ -19468,7 +19885,9 @@ * * This call does no blocking I/O. * - * 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(). + * 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(). */ @@ -19491,7 +19910,9 @@ * * This call does no blocking I/O. * - * Returns: a string containing the #GFile's parse name. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the #GFile's parse name. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -19503,7 +19924,9 @@ * * This call does no blocking I/O. * - * 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. + * 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. */ @@ -19516,7 +19939,10 @@ * * This call does no blocking I/O. * - * 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. + * 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. */ @@ -19528,7 +19954,9 @@ * * This call does no blocking I/O. * - * Returns: a string containing the #GFile's URI. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the #GFile's URI. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -19545,7 +19973,9 @@ * * This call does no blocking I/O. * - * Returns: a string containing the URI scheme for the given #GFile. The returned string should be freed with g_free() when no longer needed. + * Returns: a string containing the URI scheme for the given + * #GFile. The returned string should be freed with g_free() + * when no longer needed. */ @@ -19560,7 +19990,8 @@ * parent at all. If @parent is non-%NULL then %TRUE is only returned * if @file is a child of @parent. * - * Returns: %TRUE if @file is a child of @parent (or any parent in the case that @parent is %NULL). + * Returns: %TRUE if @file is a child of @parent (or any parent in the + * case that @parent is %NULL). * Since: 2.24 */ @@ -19582,7 +20013,8 @@ * filesystem point of view), because the prefix of @file is an alias * of @prefix. * - * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, %FALSE otherwise. + * Returns: %TRUE if the @files's parent, grandparent, etc is @prefix, + * %FALSE otherwise. */ @@ -19595,7 +20027,9 @@ * * This call does no blocking I/O. * - * Returns: %TRUE if #GFile's backend supports the given URI scheme, %FALSE if URI scheme is %NULL, not supported, or #GFile is invalid. + * Returns: %TRUE if #GFile's backend supports the + * given URI scheme, %FALSE if URI scheme is %NULL, + * not supported, or #GFile is invalid. */ @@ -19607,7 +20041,10 @@ * * This call does no blocking I/O. * - * 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. + * 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. */ @@ -19627,7 +20064,8 @@ * * Creates a new icon for a file. * - * Returns: (transfer full) (type GFileIcon): a #GIcon for the given @file, or %NULL on error. + * Returns: (transfer full) (type GFileIcon): a #GIcon for the given + * @file, or %NULL on error. */ @@ -19668,7 +20106,8 @@ * This escapes things as needed to make the string valid * utf8. * - * Returns: a UTF-8 string associated with the given @attribute. When you're done with the string it must be freed with g_free(). + * Returns: a UTF-8 string associated with the given @attribute. + * When you're done with the string it must be freed with g_free(). */ @@ -19692,7 +20131,8 @@ * Gets the value of a byte string attribute. If the attribute does * not contain a byte string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a byte string, or %NULL otherwise. + * Returns: the contents of the @attribute value as a byte string, or + * %NULL otherwise. */ @@ -19706,7 +20146,8 @@ * * Gets the attribute type, value and status for an attribute key. * - * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, %FALSE otherwise. + * Returns: (transfer none): %TRUE if @info has an attribute named @attribute, + * %FALSE otherwise. */ @@ -19744,7 +20185,8 @@ * Gets the value of a #GObject attribute. If the attribute does * not contain a #GObject, %NULL will be returned. * - * Returns: (transfer none): a #GObject associated with the given @attribute, or %NULL otherwise. + * Returns: (transfer none): a #GObject associated with the given @attribute, or + * %NULL otherwise. */ @@ -19755,7 +20197,8 @@ * * Gets the attribute status for an attribute key. * - * Returns: a #GFileAttributeStatus for the given @attribute, or %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. + * Returns: a #GFileAttributeStatus for the given @attribute, or + * %G_FILE_ATTRIBUTE_STATUS_UNSET if the key is invalid. */ @@ -19767,7 +20210,8 @@ * Gets the value of a string attribute. If the attribute does * not contain a string, %NULL will be returned. * - * Returns: the contents of the @attribute value as a UTF-8 string, or %NULL otherwise. + * Returns: the contents of the @attribute value as a UTF-8 string, or + * %NULL otherwise. */ @@ -19779,7 +20223,8 @@ * Gets the value of a stringv attribute. If the attribute does * not contain a stringv, %NULL will be returned. * - * Returns: (transfer none): the contents of the @attribute value as a stringv, or %NULL otherwise. Do not free. These returned strings are UTF-8. + * 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 */ @@ -19791,7 +20236,8 @@ * * Gets the attribute type for an attribute key. * - * Returns: a #GFileAttributeType for the given @attribute, or %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. + * Returns: a #GFileAttributeType for the given @attribute, or + * %G_FILE_ATTRIBUTE_TYPE_INVALID if the key is not set. */ @@ -19995,7 +20441,8 @@ * * Checks if a file info structure has an attribute named @attribute. * - * Returns: %TRUE if @Ginfo has an attribute named @attribute, %FALSE otherwise. + * Returns: %TRUE if @Ginfo has an attribute named @attribute, + * %FALSE otherwise. */ @@ -20007,7 +20454,8 @@ * Checks if a file info structure has an attribute in the * specified @name_space. * - * Returns: %TRUE if @Ginfo has an attribute in @name_space, %FALSE otherwise. + * Returns: %TRUE if @Ginfo has an attribute in @name_space, + * %FALSE otherwise. * Since: 2.22 */ @@ -20019,7 +20467,9 @@ * * Lists the file info structure's attributes. * - * 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. + * 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. */ @@ -20327,7 +20777,8 @@ * @stream: a #GFileInputStream. * @attributes: a file attribute query string. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Queries a file input stream the given @attributes. This function blocks * while querying the stream. For the asynchronous (non-blocking) version @@ -20343,7 +20794,8 @@ * g_file_input_stream_query_info_async: * @stream: a #GFileInputStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -20366,7 +20818,8 @@ * g_file_input_stream_query_info_finish: * @stream: a #GFileInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, + * or %NULL to ignore. * * Finishes an asynchronous info query operation. * @@ -20421,7 +20874,8 @@ * g_file_io_stream_query_info_async: * @stream: a #GFileIOStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. + * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -20476,8 +20930,10 @@ * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Loads the content of the file into memory. The data is always @@ -20489,7 +20945,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @file's contents were successfully loaded. %FALSE if there were errors. + * Returns: %TRUE if the @file's contents were successfully loaded. + * %FALSE if there were errors. */ @@ -20521,8 +20978,10 @@ * @file: input #GFile * @res: a #GAsyncResult * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous load of the @file's contents. @@ -20531,7 +20990,8 @@ * g_free() when no longer needed. If @etag_out is present, it will be * set to the new entity tag for the @file. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ @@ -20539,7 +20999,8 @@ * g_file_load_partial_contents_async: (skip) * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore - * @read_more_callback: a #GFileReadMoreCallback to receive partial data and to specify whether further data should be read + * @read_more_callback: a #GFileReadMoreCallback to receive partial data + * and to specify whether further data should be read * @callback: a #GAsyncReadyCallback to call when the request is satisfied * @user_data: the data to pass to the callback functions * @@ -20562,8 +21023,10 @@ * @file: input #GFile * @res: a #GAsyncResult * @contents: (out) (transfer full) (element-type guint8) (array length=length): a location to place the contents of the file - * @length: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, or %NULL if the entity tag is not needed + * @length: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @etag_out: (out) (allow-none): a location to place the current entity tag for the file, + * or %NULL if the entity tag is not needed * @error: a #GError, or %NULL * * Finishes an asynchronous partial load operation that was started @@ -20572,14 +21035,16 @@ * The returned @content should be freed with g_free() when no longer * needed. * - * Returns: %TRUE if the load was successful. If %FALSE and @error is present, it will be set appropriately. + * Returns: %TRUE if the load was successful. If %FALSE and @error is + * present, it will be set appropriately. */ /** * g_file_make_directory: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a directory. Note that this will only create a child directory @@ -20604,9 +21069,12 @@ /** * g_file_make_directory_async: (virtual make_directory_async) * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: the data to pass to callback function * * Asynchronously creates a directory. @@ -20632,7 +21100,8 @@ /** * g_file_make_directory_with_parents: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Creates a directory and any parent directories that may not @@ -20649,7 +21118,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if all directories have been successfully created, %FALSE otherwise. + * Returns: %TRUE if all directories have been successfully created, %FALSE + * otherwise. * Since: 2.18 */ @@ -20658,7 +21128,8 @@ * g_file_make_symbolic_link: * @file: a #GFile with the name of the symlink to create * @symlink_value: a string with the path for the target of the new symlink - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Creates a symbolic link named @file which contains the string @@ -20703,7 +21174,8 @@ * #GFileMeasureProgressCallback for information about when and how the * callback will be invoked. * - * Returns: %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. * Since: 2.38 */ @@ -20712,7 +21184,8 @@ * g_file_measure_disk_usage_async: * @file: a #GFile * @flags: #GFileMeasureFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request * @cancellable: (allow-none): optional #GCancellable * @progress_callback: (allow-none): a #GFileMeasureProgressCallback * @progress_data: user_data for @progress_callback @@ -20741,7 +21214,8 @@ * g_file_measure_disk_usage_async(). See g_file_measure_disk_usage() for * more information. * - * Returns: %TRUE if successful, with the out parameters set. %FALSE otherwise, with @error set. + * Returns: %TRUE if successful, with the out parameters set. + * %FALSE otherwise, with @error set. * Since: 2.38 */ @@ -20750,7 +21224,8 @@ * g_file_monitor: * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a file or directory monitor for the given file, @@ -20760,7 +21235,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.18 */ @@ -20779,7 +21256,8 @@ * g_file_monitor_directory: (virtual monitor_dir) * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a directory monitor for the given file. @@ -20795,7 +21273,9 @@ * directory for changes made via hard links; if you want to do this then * you must register individual watches with g_file_monitor(). * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -20820,7 +21300,8 @@ * g_file_monitor_file: * @file: input #GFile * @flags: a set of #GFileMonitorFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtains a file monitor for the given file. If no file notification @@ -20838,7 +21319,9 @@ * usage, and may not have any effect depending on the #GFileMonitor * backend and/or filesystem type. * - * Returns: (transfer full): a #GFileMonitor for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileMonitor for the given @file, + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -20855,7 +21338,8 @@ /** * g_file_monitor_set_rate_limit: * @monitor: a #GFileMonitor. - * @limit_msecs: a non-negative integer with the limit in milliseconds to poll for changes + * @limit_msecs: a non-negative integer with the limit in milliseconds + * to poll for changes * * Sets the rate limit to which the @monitor will report * consecutive change events to the same file. @@ -20866,9 +21350,12 @@ * g_file_mount_enclosing_volume: * @location: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Starts a @mount_operation, mounting the volume that contains @@ -20892,7 +21379,9 @@ * * Finishes a mount operation started by g_file_mount_enclosing_volume(). * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, + * this function will return %FALSE and set @error + * appropriately if present. */ @@ -20900,9 +21389,12 @@ * g_file_mount_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Mounts a file of type G_FILE_TYPE_MOUNTABLE. @@ -20930,7 +21422,8 @@ * Finish an asynchronous mount operation that was started * with g_file_mount_mountable(). * - * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -20939,9 +21432,12 @@ * @source: #GFile pointing to the source location * @destination: #GFile pointing to the destination location * @flags: set of #GFileCopyFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @progress_callback: (allow-none) (scope call): #GFileProgressCallback function for updates - * @progress_callback_data: (closure): gpointer to user data for the callback function + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @progress_callback: (allow-none) (scope call): #GFileProgressCallback + * function for updates + * @progress_callback_data: (closure): gpointer to user data for + * the callback function * @error: #GError for returning error conditions, or %NULL * * Tries to move the file or directory @source to the location specified @@ -20996,7 +21492,8 @@ * This operation never fails, but the returned object might not * support any I/O operation if @arg points to a malformed path. * - * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). */ @@ -21024,13 +21521,15 @@ /** * g_file_new_for_path: - * @path: a string containing a relative or absolute path. The string must be encoded in the glib filename encoding. + * @path: a string containing a relative or absolute path. + * The string must be encoded in the glib filename encoding. * * Constructs a #GFile for a given path. This operation never * fails, but the returned object might not support any I/O * operation if @path is malformed. * - * Returns: (transfer full): a new #GFile for the given @path. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile for the given @path. + * Free the returned object with g_object_unref(). */ @@ -21043,13 +21542,15 @@ * operation if @uri is malformed or if the uri type is * not supported. * - * Returns: (transfer full): a new #GFile for the given @uri. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile for the given @uri. + * Free the returned object with g_object_unref(). */ /** * g_file_new_tmp: - * @tmpl: (type filename) (allow-none): Template for the file name, as in g_file_open_tmp(), or %NULL for a default template + * @tmpl: (type filename) (allow-none): Template for the file + * name, as in g_file_open_tmp(), or %NULL for a default template * @iostream: (out): on return, a #GFileIOStream for the created file * @error: a #GError, or %NULL * @@ -21064,7 +21565,8 @@ * Unlike the other #GFile constructors, this will return %NULL if * a temporary file could not be created. * - * Returns: (transfer full): a new #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GFile. + * Free the returned object with g_object_unref(). * Since: 2.32 */ @@ -21092,7 +21594,8 @@ * really need to do read and write streaming, rather than just opening * for reading or writing. * - * Returns: (transfer full): #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -21100,9 +21603,12 @@ /** * g_file_open_readwrite_async: * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for reading and writing. @@ -21127,7 +21633,8 @@ * Finishes an asynchronous file read operation started with * g_file_open_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -21177,7 +21684,8 @@ * g_file_output_stream_query_info_async: * @stream: a #GFileOutputStream. * @attributes: a file attribute query string. - * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> of the request. + * @io_priority: the <link linkend="gio-GIOScheduler">I/O priority</link> + * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * @callback: callback to call when the request is satisfied * @user_data: the data to pass to callback function @@ -21221,7 +21729,8 @@ * g_file_poll_mountable: * @file: input #GFile * @cancellable: optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Polls a file of type #G_FILE_TYPE_MOUNTABLE. @@ -21249,7 +21758,8 @@ * Finish an asynchronous poll operation that was polled * with g_file_poll_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. %FALSE + * otherwise. * Since: 2.22 */ @@ -21267,14 +21777,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * 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() + * 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() */ /** * g_file_query_exists: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * * Utility function to check if a particular file exists. This is * implemented using g_file_query_info() and as such does blocking I/O. @@ -21299,7 +21812,8 @@ * dialog. If you do this, you should make sure to also handle the errors * that can happen due to races when you execute the operation. * - * Returns: %TRUE if the file exists (and can be detected without error), %FALSE otherwise (or if cancelled). + * Returns: %TRUE if the file exists (and can be detected without error), + * %FALSE otherwise (or if cancelled). */ @@ -21307,7 +21821,8 @@ * g_file_query_file_type: * @file: input #GFile * @flags: a set of #GFileQueryInfoFlags passed to g_file_query_info() - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * * Utility function to inspect the #GFileType of a file. This is * implemented using g_file_query_info() and as such does blocking I/O. @@ -21315,7 +21830,8 @@ * The primary use case of this method is to check if a file is * a regular file, directory, or symlink. * - * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN if the file does not exist + * Returns: The #GFileType of the file and #G_FILE_TYPE_UNKNOWN + * if the file does not exist * Since: 2.18 */ @@ -21324,7 +21840,8 @@ * g_file_query_filesystem_info: * @file: input #GFile * @attributes: an attribute query string - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Similar to g_file_query_info(), but obtains information @@ -21353,7 +21870,8 @@ * be returned. Other errors are possible too, and depend on what * kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo or %NULL if there was an error. + * Free the returned object with g_object_unref(). */ @@ -21361,9 +21879,12 @@ * g_file_query_filesystem_info_async: * @file: input #GFile * @attributes: an attribute query string - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about the filesystem @@ -21389,7 +21910,9 @@ * Finishes an asynchronous filesystem info query. * See g_file_query_filesystem_info_async(). * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInfo for given @file + * or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -21398,7 +21921,8 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError * * Gets the requested information about specified @file. @@ -21432,7 +21956,8 @@ * returned. Other errors are possible too, and depend on what kind of * filesystem the file is on. * - * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInfo for the given @file, or %NULL + * on error. Free the returned object with g_object_unref(). */ @@ -21441,9 +21966,12 @@ * @file: input #GFile * @attributes: an attribute query string * @flags: a set of #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously gets the requested information about specified @file. @@ -21467,14 +21995,17 @@ * Finishes an asynchronous file info query. * See g_file_query_info_async(). * - * Returns: (transfer full): #GFileInfo for given @file or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInfo for given @file + * or %NULL on error. Free the returned object with + * g_object_unref(). */ /** * g_file_query_settable_attributes: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtain the list of settable attributes for the file. @@ -21488,14 +22019,17 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileAttributeInfoList describing the settable attributes. When you are done with it, release it with g_file_attribute_info_list_unref() + * Returns: a #GFileAttributeInfoList describing the settable attributes. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ /** * g_file_query_writable_namespaces: * @file: input #GFile - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Obtain the list of attribute namespaces where new attributes @@ -21506,7 +22040,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: a #GFileAttributeInfoList describing the writable namespaces. When you are done with it, release it with g_file_attribute_info_list_unref() + * Returns: a #GFileAttributeInfoList describing the writable namespaces. + * When you are done with it, release it with + * g_file_attribute_info_list_unref() */ @@ -21528,16 +22064,20 @@ * error will be returned. Other errors are possible too, and depend * on what kind of filesystem the file is on. * - * Returns: (transfer full): #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_read_async: * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously opens @file for reading. @@ -21560,17 +22100,20 @@ * Finishes an asynchronous file read operation started with * g_file_read_async(). * - * Returns: (transfer full): a #GFileInputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileInputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace: * @file: input #GFile - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore + * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> + * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Returns an output stream for overwriting the file, possibly @@ -21615,19 +22158,24 @@ * %G_IO_ERROR_FILENAME_TOO_LONG will be returned. Other errors are * possible too, and depend on what kind of filesystem the file is on. * - * Returns: (transfer full): a #GFileOutputStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace_async: * @file: input #GFile - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore + * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> + * for the current #GFile, or NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously overwrites the file, replacing the contents, @@ -21647,10 +22195,13 @@ * @file: input #GFile * @contents: (element-type guint8) (array length=length): a string containing the new contents for @file * @length: the length of @contents in bytes - * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> for the document, or %NULL + * @etag: (allow-none): the old <link linkend="gfile-etag">entity tag</link> + * for the document, or %NULL * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when no longer needed, or %NULL + * @new_etag: (allow-none) (out): a location to a new <link linkend="gfile-etag">entity tag</link> + * for the document. This should be freed with g_free() when no longer + * needed, or %NULL * @cancellable: optional #GCancellable object, %NULL to ignore * @error: a #GError, or %NULL * @@ -21669,7 +22220,8 @@ * The returned @new_etag can be used to verify that the file hasn't * changed the next time it is saved over. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function + * will return %FALSE and set @error appropriately if present. */ @@ -21706,7 +22258,9 @@ * g_file_replace_contents_finish: * @file: input #GFile * @res: a #GAsyncResult - * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link> for the document. This should be freed with g_free() when it is no longer needed, or %NULL + * @new_etag: (out) (allow-none): a location of a new <link linkend="gfile-etag">entity tag</link> + * for the document. This should be freed with g_free() when it is no + * longer needed, or %NULL * @error: a #GError, or %NULL * * Finishes an asynchronous replace of the given @file. See @@ -21726,17 +22280,20 @@ * Finishes an asynchronous file replace operation started with * g_file_replace_async(). * - * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileOutputStream, or %NULL on error. + * Free the returned object with g_object_unref(). */ /** * g_file_replace_readwrite: * @file: a #GFile - * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> for the current #GFile, or #NULL to ignore + * @etag: (allow-none): an optional <link linkend="gfile-etag">entity tag</link> + * for the current #GFile, or #NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: return location for a #GError, or %NULL * * Returns an output stream for overwriting the file in readwrite mode, @@ -21750,7 +22307,8 @@ * supported, so make sure you really need to do read and write streaming, * rather than just opening for reading or writing. * - * Returns: (transfer full): a #GFileIOStream or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -21758,12 +22316,16 @@ /** * g_file_replace_readwrite_async: * @file: input #GFile - * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> for the current #GFile, or NULL to ignore + * @etag: (allow-none): an <link linkend="gfile-etag">entity tag</link> + * for the current #GFile, or NULL to ignore * @make_backup: %TRUE if a backup should be created * @flags: a set of #GFileCreateFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously overwrites the file in read-write mode, @@ -21790,7 +22352,8 @@ * Finishes an asynchronous file replace operation started with * g_file_replace_readwrite_async(). * - * Returns: (transfer full): a #GFileIOStream, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFileIOStream, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -21804,7 +22367,9 @@ * * This call does no blocking I/O. * - * 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(). + * 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(). */ @@ -21813,9 +22378,11 @@ * @file: input #GFile * @attribute: a string containing the attribute's name * @type: The type of the attribute - * @value_p: (allow-none): a pointer to the value (or the pointer itself if the type is a pointer type) + * @value_p: (allow-none): a pointer to the value (or the pointer + * itself if the type is a pointer type) * @flags: a set of #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets an attribute in the file with attribute name @attribute to @value. @@ -21837,7 +22404,8 @@ * @attribute: a string containing the attribute's name * @value: a string containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING to @value. @@ -21848,7 +22416,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -21858,7 +22427,8 @@ * @attribute: a string containing the attribute's name * @value: a #gint32 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT32 to @value. @@ -21868,7 +22438,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -21878,7 +22449,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint64 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_INT64 to @value. @@ -21898,7 +22470,8 @@ * @attribute: a string containing the attribute's name * @value: a string containing the attribute's value * @flags: #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_STRING to @value. @@ -21918,7 +22491,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint32 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT32 to @value. @@ -21928,7 +22502,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -21938,7 +22513,8 @@ * @attribute: a string containing the attribute's name * @value: a #guint64 containing the attribute's new value * @flags: a #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sets @attribute of type %G_FILE_ATTRIBUTE_TYPE_UINT64 to @value. @@ -21948,7 +22524,8 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if the @attribute was successfully set to @value in the @file, %FALSE otherwise. + * Returns: %TRUE if the @attribute was successfully set to @value + * in the @file, %FALSE otherwise. */ @@ -21957,8 +22534,10 @@ * @file: input #GFile * @info: a #GFileInfo * @flags: a #GFileQueryInfoFlags - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @callback: (scope async): a #GAsyncReadyCallback * @user_data: (closure): a #gpointer * @@ -21991,7 +22570,8 @@ * @file: input #GFile * @info: a #GFileInfo * @flags: #GFileQueryInfoFlags - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Tries to set all attributes in the #GFileInfo on the target @@ -22015,7 +22595,8 @@ * g_file_set_display_name: * @file: input #GFile * @display_name: a string - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Renames @file to the specified display name. @@ -22034,7 +22615,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * 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(). + * 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(). */ @@ -22042,9 +22625,12 @@ * g_file_set_display_name_async: * @file: input #GFile * @display_name: a string - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async): a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously sets the display name for a given #GFile. @@ -22067,7 +22653,8 @@ * Finishes setting a display name started with * g_file_set_display_name_async(). * - * Returns: (transfer full): a #GFile or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile or %NULL on error. + * Free the returned object with g_object_unref(). */ @@ -22107,7 +22694,8 @@ * Finish an asynchronous start operation that was started * with g_file_start_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. %FALSE + * otherwise. * Since: 2.22 */ @@ -22116,9 +22704,12 @@ * g_file_stop_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction. - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction. + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: the data to pass to callback function * * Stops a file of type #G_FILE_TYPE_MOUNTABLE. @@ -22146,7 +22737,8 @@ * Finish an asynchronous stop operation that was started * with g_file_stop_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -22169,7 +22761,8 @@ /** * g_file_trash: (virtual trash) * @file: #GFile to send to trash - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore * @error: a #GError, or %NULL * * Sends @file to the "Trashcan", if possible. This is similar to @@ -22188,9 +22781,12 @@ /** * g_file_trash_async: (virtual trash_async) * @file: input #GFile - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: a #GAsyncReadyCallback to call when the request is satisfied + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: a #GAsyncReadyCallback to call + * when the request is satisfied * @user_data: the data to pass to callback function * * Asynchronously sends @file to the Trash location, if possible. @@ -22217,8 +22813,10 @@ * g_file_unmount_mountable: * @file: input #GFile * @flags: flags affecting the operation - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Unmounts a file of type G_FILE_TYPE_MOUNTABLE. @@ -22246,8 +22844,10 @@ * Finish an asynchronous unmount operation that was started * with g_file_unmount_mountable(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. - * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() instead. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. + * Deprecated: 2.22: Use g_file_unmount_mountable_with_operation_finish() + * instead. */ @@ -22255,9 +22855,12 @@ * g_file_unmount_mountable_with_operation: * @file: input #GFile * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation, or %NULL to avoid user interaction - * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call when the request is satisfied, or %NULL + * @mount_operation: (allow-none): a #GMountOperation, + * or %NULL to avoid user interaction + * @cancellable: (allow-none): optional #GCancellable object, + * %NULL to ignore + * @callback: (scope async) (allow-none): a #GAsyncReadyCallback to call + * when the request is satisfied, or %NULL * @user_data: (closure): the data to pass to callback function * * Unmounts a file of type #G_FILE_TYPE_MOUNTABLE. @@ -22286,7 +22889,8 @@ * Finish an asynchronous unmount operation that was started * with g_file_unmount_mountable_with_operation(). * - * Returns: %TRUE if the operation finished successfully. %FALSE otherwise. + * Returns: %TRUE if the operation finished successfully. + * %FALSE otherwise. * Since: 2.22 */ @@ -22298,7 +22902,9 @@ * * Obtains a completion for @initial_text from @completer. * - * 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. + * 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. */ @@ -22309,7 +22915,8 @@ * * Gets an array of completion strings for a given 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. + * 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. */ @@ -22420,7 +23027,8 @@ * * Gets a hash for an icon. * - * Returns: a #guint containing a hash for the @icon, suitable for use in a #GHashTable or similar data structure. + * Returns: a #guint containing a hash for the @icon, suitable for + * use in a #GHashTable or similar data structure. */ @@ -22436,7 +23044,8 @@ * implementations you need to ensure that each #GType is registered * with the type system prior to calling g_icon_new_for_string(). * - * Returns: (transfer full): An object implementing the #GIcon interface or %NULL if @error is set. + * Returns: (transfer full): An object implementing the #GIcon + * interface or %NULL if @error is set. * Since: 2.20 */ @@ -22482,7 +23091,8 @@ * </para></listitem> * </itemizedlist> * - * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't be serialized. Use g_free() to free. + * Returns: An allocated NUL-terminated UTF8 string or %NULL if @icon can't + * be serialized. Use g_free() to free. * Since: 2.20 */ @@ -22689,7 +23299,8 @@ * * Tests if @address falls within the range described by @mask. * - * Returns: whether @address falls within the range described by @mask. + * Returns: whether @address falls within the range described by + * @mask. * Since: 2.32 */ @@ -22718,7 +23329,8 @@ * delimited by a "/". If it is not present, then the length is * assumed to be the full length of the address. * - * Returns: a new #GInetAddressMask corresponding to @string, or %NULL on error. + * Returns: a new #GInetAddressMask corresponding to @string, or %NULL + * on error. * Since: 2.32 */ @@ -22741,7 +23353,8 @@ * Creates a #GInetAddress for the "any" address (unassigned/"don't * care") for @family. * - * Returns: a new #GInetAddress corresponding to the "any" address for @family. + * Returns: a new #GInetAddress corresponding to the "any" address + * for @family. * Since: 2.22 */ @@ -22766,7 +23379,8 @@ * * Parses @string as an IP address and creates a new #GInetAddress. * - * Returns: a new #GInetAddress corresponding to @string, or %NULL if @string could not be parsed. + * Returns: a new #GInetAddress corresponding to @string, or %NULL if + * @string could not be parsed. * Since: 2.22 */ @@ -22777,7 +23391,8 @@ * * Creates a #GInetAddress for the loopback address for @family. * - * Returns: a new #GInetAddress corresponding to the loopback address for @family. + * Returns: a new #GInetAddress corresponding to the loopback address + * for @family. * Since: 2.22 */ @@ -22788,7 +23403,9 @@ * * Gets the raw binary address data from @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(). + * 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 */ @@ -22799,7 +23416,8 @@ * * Converts @address to string form. * - * Returns: a representation of @address as a string, which should be freed after use. + * Returns: a representation of @address as a string, which should be + * freed after use. * Since: 2.22 */ @@ -22810,7 +23428,8 @@ * * Gets @address's #GInetAddress. * - * Returns: (transfer none): the #GInetAddress for @address, which must be g_object_ref()'d if it will be stored + * Returns: (transfer none): the #GInetAddress for @address, which must be + * g_object_ref()'d if it will be stored * Since: 2.22 */ @@ -22866,7 +23485,8 @@ * g_initable_init: * @initable: a #GInitable. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Initializes the object implementing the interface. * @@ -22892,7 +23512,8 @@ * of the first call. This is so that it's safe to implement the singleton * pattern in the GObject constructor function. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error has occurred, this function will + * return %FALSE and set @error appropriately if present. * Since: 2.22 */ @@ -22901,15 +23522,19 @@ * g_initable_new: * @object_type: a #GType supporting #GInitable. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. - * @first_property_name: (allow-none): the name of the first property, or %NULL if no properties - * @...: the value if the first property, followed by and other property value pairs, and ended by %NULL. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. + * @first_property_name: (allow-none): the name of the first property, or %NULL if no + * properties + * @...: the value if the first property, followed by and other property + * value pairs, and ended by %NULL. * * Helper function for constructing #GInitable object. This is * similar to g_object_new() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (type GObject.Object) (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ @@ -22917,16 +23542,19 @@ /** * g_initable_new_valist: * @object_type: a #GType supporting #GInitable. - * @first_property_name: the name of the first property, followed by the value, and other property value pairs, and ended by %NULL. + * @first_property_name: the name of the first property, followed by + * the value, and other property value pairs, and ended by %NULL. * @var_args: The var args list generated from @first_property_name. * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Helper function for constructing #GInitable object. This is * similar to g_object_new_valist() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (type GObject.Object) (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ @@ -22937,13 +23565,15 @@ * @n_parameters: the number of parameters in @parameters * @parameters: (array length=n_parameters): the parameters to use to construct the object * @cancellable: optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Helper function for constructing #GInitable object. This is * similar to g_object_newv() but also initializes the object * and returns %NULL, setting an error on failure. * - * Returns: (type GObject.Object) (transfer full): a newly allocated #GObject, or %NULL on error + * Returns: (type GObject.Object) (transfer full): a newly allocated + * #GObject, or %NULL on error * Since: 2.22 */ @@ -23003,7 +23633,8 @@ /** * g_input_stream_close_async: * @stream: A #GInputStream. - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional cancellable object * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -23025,7 +23656,8 @@ * g_input_stream_close_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes closing a stream asynchronously, started from g_input_stream_close_async(). * @@ -23056,7 +23688,8 @@ /** * g_input_stream_read: * @stream: a #GInputStream. - * @buffer: (array length=count) (element-type guint8): a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore @@ -23087,7 +23720,8 @@ /** * g_input_stream_read_all: * @stream: a #GInputStream. - * @buffer: (array length=count) (element-type guint8): a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream * @bytes_read: (out): location to store the number of bytes that was read from the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -23114,9 +23748,11 @@ /** * g_input_stream_read_async: * @stream: A #GInputStream. - * @buffer: (array length=count) (element-type guint8): a buffer to read data into (which should be at least count bytes long). + * @buffer: (array length=count) (element-type guint8): a buffer to + * read data into (which should be at least count bytes long). * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -23150,7 +23786,8 @@ /** * g_input_stream_read_bytes: * @stream: a #GInputStream. - * @count: maximum number of bytes that will be read from the stream. Common values include 4096 and 8192. + * @count: maximum number of bytes that will be read from the stream. Common + * values include 4096 and 8192. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -23186,7 +23823,8 @@ * g_input_stream_read_bytes_async: * @stream: A #GInputStream. * @count: the number of bytes that will be read from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -23218,7 +23856,8 @@ * g_input_stream_read_bytes_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream read-into-#GBytes operation. * @@ -23230,7 +23869,8 @@ * g_input_stream_read_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream read operation. * @@ -23241,7 +23881,8 @@ /** * g_input_stream_set_pending: * @stream: input stream - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -23281,7 +23922,8 @@ * g_input_stream_skip_async: * @stream: A #GInputStream. * @count: the number of bytes that will be skipped from the stream - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): callback to call when the request is satisfied * @user_data: (closure): the data to pass to callback function @@ -23316,7 +23958,8 @@ * g_input_stream_skip_finish: * @stream: a #GInputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream skip operation. * @@ -23396,7 +24039,8 @@ * * Finds a #GIOExtension for an extension point by name. * - * Returns: (transfer none): the #GIOExtension for @extension_point that has the given name, or %NULL if there is no extension with that name + * Returns: (transfer none): the #GIOExtension for @extension_point that has the + * given name, or %NULL if there is no extension with that name */ @@ -23407,7 +24051,9 @@ * Gets a list of all extensions that implement this extension point. * The list is sorted by priority, beginning with the highest priority. * - * Returns: (element-type GIOExtension) (transfer none): a #GList of #GIOExtension<!-- -->s. The list is owned by GIO and should not be modified. + * Returns: (element-type GIOExtension) (transfer none): a #GList of + * #GIOExtension<!-- -->s. The list is owned by GIO and should not be + * modified. */ @@ -23417,7 +24063,8 @@ * * Gets the required type for @extension_point. * - * Returns: the #GType that all implementations must have, or #G_TYPE_INVALID if the extension point has no required type + * Returns: the #GType that all implementations must have, + * or #G_TYPE_INVALID if the extension point has no required type */ @@ -23444,7 +24091,8 @@ * * Looks up an existing extension point. * - * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there is no registered extension point with the given name. + * Returns: (transfer none): the #GIOExtensionPoint, or %NULL if there + * is no registered extension point with the given name. */ @@ -23454,7 +24102,8 @@ * * Registers an extension point. * - * Returns: (transfer none): the new #GIOExtensionPoint. This object is owned by GIO and should not be freed. + * Returns: (transfer none): the new #GIOExtensionPoint. This object is + * owned by GIO and should not be freed. */ @@ -23486,7 +24135,8 @@ * Creates a new GIOModule that will load the specific * shared library when in use. * - * Returns: a #GIOModule from given @filename, or %NULL on error. + * Returns: a #GIOModule from given @filename, + * or %NULL on error. */ @@ -23539,7 +24189,12 @@ * all gtypes) then you can use g_io_modules_scan_all_in_directory() * which allows delayed/lazy loading of modules. * - * 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(). + * 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(). */ @@ -23554,7 +24209,12 @@ * all gtypes) then you can use g_io_modules_scan_all_in_directory() * which allows delayed/lazy loading of modules. * - * 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(). + * 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 */ @@ -23608,7 +24268,9 @@ * A job is cancellable if a #GCancellable was passed into * g_io_scheduler_push_job(). * - * Deprecated: You should never call this function, since you don't know how other libraries in your program might be making use of gioscheduler. + * Deprecated: You should never call this function, since you don't + * know how other libraries in your program might be making use of + * gioscheduler. */ @@ -23654,7 +24316,8 @@ * @job_func: a #GIOSchedulerJobFunc. * @user_data: data to pass to @job_func * @notify: (allow-none): a #GDestroyNotify for @user_data, or %NULL - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: optional #GCancellable object, %NULL to ignore. * * Schedules the I/O job to run in another thread. @@ -23752,7 +24415,8 @@ * g_io_stream_close_finish: * @stream: a #GIOStream * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Closes a stream. * @@ -23768,7 +24432,8 @@ * Gets the input stream for this object. This is used * for reading. * - * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. Do not free. + * Returns: (transfer none): a #GInputStream, owned by the #GIOStream. + * Do not free. * Since: 2.22 */ @@ -23780,7 +24445,8 @@ * Gets the output stream for this object. This is used for * writing. * - * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. Do not free. + * Returns: (transfer none): a #GOutputStream, owned by the #GIOStream. + * Do not free. * Since: 2.22 */ @@ -23810,7 +24476,8 @@ /** * g_io_stream_set_pending: * @stream: a #GIOStream - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -23846,7 +24513,8 @@ /** * g_io_stream_splice_finish: * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous io stream splice operation. * @@ -23859,7 +24527,8 @@ * g_keyfile_settings_backend_new: * @filename: the filename of the keyfile * @root_path: the path under which all settings keys appear - * @root_group: (allow-none): the group name corresponding to @root_path, or %NULL + * @root_group: (allow-none): the group name corresponding to + * @root_path, or %NULL * * Creates a keyfile-backed #GSettingsBackend. * @@ -23914,9 +24583,11 @@ * g_loadable_icon_load: * @icon: a #GLoadableIcon. * @size: an integer. - * @type: (out) (allow-none): a location to store the type of the loaded icon, %NULL to ignore. + * @type: (out) (allow-none): a location to store the type of the + * loaded icon, %NULL to ignore. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Loads a loadable icon. For the asynchronous version of this function, * see g_loadable_icon_load_async(). @@ -23930,7 +24601,8 @@ * @icon: a #GLoadableIcon. * @size: an integer. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Loads an icon asynchronously. To finish this function, see @@ -23943,8 +24615,10 @@ * g_loadable_icon_load_finish: * @icon: a #GLoadableIcon. * @res: a #GAsyncResult. - * @type: (out) (allow-none): a location to store the type of the loaded icon, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @type: (out) (allow-none): a location to store the type of the + * loaded icon, %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous icon load started in g_loadable_icon_load_async(). * @@ -24065,8 +24739,10 @@ * g_memory_output_stream_new: (skip) * @data: (allow-none): pointer to a chunk of memory to use, or %NULL * @size: the size of @data - * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc()) to be called when @data needs to be grown, or %NULL - * @destroy_function: (allow-none): a function to be called on @data when the stream is finalized, or %NULL + * @realloc_function: (allow-none): a function with realloc() semantics (like g_realloc()) + * to be called when @data needs to be grown, or %NULL + * @destroy_function: (allow-none): a function to be called on @data when the stream is + * finalized, or %NULL * * Creates a new #GMemoryOutputStream. * @@ -24234,7 +24910,8 @@ * remains at the current position. The value returned in @value must * be unreffed using g_variant_unref() when it is no longer in use. * - * Returns: %TRUE on success, or %FALSE if there is no additional attribute + * Returns: %TRUE on success, or %FALSE if there is no additional + * attribute * Since: 2.32 */ @@ -24378,7 +25055,8 @@ * type, then the positional parameters are ignored and %FALSE is * returned. * - * Returns: %TRUE if the named attribute was found with the expected type + * Returns: %TRUE if the named attribute was found with the expected + * type * Since: 2.34 */ @@ -24879,7 +25557,8 @@ * #GVariant may go away after the call to g_variant_unref()). In * particular, no '&' characters are allowed in @format_string. * - * Returns: %TRUE if the named attribute was found with the expected type + * Returns: %TRUE if the named attribute was found with the expected + * type * Since: 2.32 */ @@ -24889,7 +25568,8 @@ * @model: a #GMenuModel * @item_index: the index of the item * @attribute: the attribute to query - * @expected_type: (allow-none): the expected type of the attribute, or %NULL + * @expected_type: (allow-none): the expected type of the attribute, or + * %NULL * * Queries the item at position @item_index in @model for the attribute * specified by @attribute. @@ -24945,7 +25625,8 @@ * An immutable #GMenuModel will never emit the #GMenuModel::items-changed * signal. Consumers of the model may make optimisations accordingly. * - * Returns: %TRUE if the model is mutable (ie: "items-changed" may be emitted). + * Returns: %TRUE if the model is mutable (ie: "items-changed" may be + * emitted). * Since: 2.32 */ @@ -25144,7 +25825,8 @@ * g_mount_eject_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -25158,7 +25840,8 @@ * g_mount_eject_with_operation: * @mount: a #GMount. * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -25175,7 +25858,8 @@ * g_mount_eject_with_operation_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -25193,7 +25877,9 @@ * @mount is a path that reflects the main entry point for the user (e.g. * the home directory, or the root of the volume). * - * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -25206,7 +25892,9 @@ * This is a convenience method for getting the #GVolume and then * using that object to get the #GDrive. * - * 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. + * 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. */ @@ -25216,7 +25904,9 @@ * * Gets the icon for @mount. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -25226,7 +25916,9 @@ * * Gets the name of @mount. * - * Returns: the name for the given @mount. The returned string should be freed with g_free() when no longer needed. + * Returns: the name for the given @mount. + * The returned string should be freed with g_free() + * when no longer needed. */ @@ -25236,7 +25928,9 @@ * * Gets the root directory on @mount. * - * Returns: (transfer full): a #GFile. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GFile. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. */ @@ -25257,7 +25951,9 @@ * * Gets the symbolic icon for @mount. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with + * g_object_unref() when no longer needed. * Since: 2.34 */ @@ -25271,7 +25967,9 @@ * considered an opaque string. Returns %NULL if there is no UUID * available. * - * 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. + * 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. */ @@ -25281,14 +25979,17 @@ * * Gets the volume for the @mount. * - * 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. + * 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. */ /** * g_mount_guess_content_type: * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @force_rescan: Whether to force a rescan of the content. + * Otherwise a cached result will be used if available * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore * @callback: a #GAsyncReadyCallback * @user_data: user data passed to @callback @@ -25312,7 +26013,8 @@ * g_mount_guess_content_type_finish: * @mount: a #GMount * @result: a #GAsyncResult - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Finishes guessing content types of @mount. If any errors occurred * during the operation, @error will be set to contain the errors and @@ -25320,7 +26022,8 @@ * %G_IO_ERROR_NOT_SUPPORTED if the mount does not support content * guessing. * - * 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. + * 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 */ @@ -25328,9 +26031,11 @@ /** * g_mount_guess_content_type_sync: * @mount: a #GMount - * @force_rescan: Whether to force a rescan of the content. Otherwise a cached result will be used if available + * @force_rescan: Whether to force a rescan of the content. + * Otherwise a cached result will be used if available * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore - * @error: a #GError location to store the error occurring, or %NULL to ignore + * @error: a #GError location to store the error occurring, or %NULL to + * ignore * * Tries to guess the type of content stored on @mount. Returns one or * more textual identifiers of well-known content types (typically @@ -25341,7 +26046,8 @@ * This is an synchronous operation and as such may block doing IO; * see g_mount_guess_content_type() for the asynchronous version. * - * 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. + * 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 */ @@ -25396,7 +26102,8 @@ * * Gets a choice from the mount operation. * - * Returns: an integer containing an index of the user's choice from the choice's list, or %0. + * Returns: an integer containing an index of the user's choice from + * the choice's list, or %0. */ @@ -25516,7 +26223,8 @@ * g_mount_remount: * @mount: a #GMount. * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -25537,7 +26245,8 @@ * g_mount_remount_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes remounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -25579,7 +26288,8 @@ * g_mount_unmount_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes unmounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -25593,7 +26303,8 @@ * g_mount_unmount_with_operation: * @mount: a #GMount. * @flags: flags affecting the operation - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid + * user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -25610,7 +26321,8 @@ * g_mount_unmount_with_operation_finish: * @mount: a #GMount. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes unmounting a mount. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -25799,7 +26511,8 @@ * @monitor: a #GNetworkMonitor * @connectable: a #GSocketConnectable * @cancellable: (allow-none): a #GCancellable, or %NULL - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the + * request is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously attempts to determine whether or not the host @@ -26032,7 +26745,8 @@ * g_output_stream_close_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Closes an output stream. * @@ -26082,7 +26796,8 @@ * g_output_stream_flush_finish: * @stream: a #GOutputStream. * @result: a GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes flushing an output stream. * @@ -26127,7 +26842,8 @@ /** * g_output_stream_set_pending: * @stream: a #GOutputStream. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Sets @stream to have actions pending. If the pending flag is * already set or @stream is closed, it will return %FALSE and set @@ -26143,11 +26859,16 @@ * @source: a #GInputStream. * @flags: a set of #GOutputStreamSpliceFlags. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Splices an input stream into an output stream. * - * 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. + * 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. */ @@ -26175,11 +26896,15 @@ * g_output_stream_splice_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an asynchronous stream splice operation. * - * 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. + * 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. */ @@ -26221,7 +26946,8 @@ * @stream: a #GOutputStream. * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. * @count: the number of bytes to write - * @bytes_written: (out): location to store the number of bytes that was written to the stream + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -26339,7 +27065,8 @@ * g_output_stream_write_bytes_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream write-from-#GBytes operation. * @@ -26351,7 +27078,8 @@ * g_output_stream_write_finish: * @stream: a #GOutputStream. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes a stream write operation. * @@ -26594,7 +27322,10 @@ * g_pollable_input_stream_read_nonblocking(), which will return a * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. * - * 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. + * 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 */ @@ -26602,7 +27333,8 @@ /** * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking) * @stream: a #GPollableInputStream - * @buffer: a buffer to read data into (which should be at least @count bytes long). + * @buffer: a buffer to read data into (which should be at least @count + * bytes long). * @count: the number of bytes you want to read * @cancellable: (allow-none): a #GCancellable, or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -26619,7 +27351,8 @@ * may happen if you call this method after a source triggers due * to having been cancelled. * - * Returns: the number of bytes read, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). + * Returns: the number of bytes read, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ @@ -26672,7 +27405,10 @@ * g_pollable_output_stream_write_nonblocking(), which will return a * %G_IO_ERROR_WOULD_BLOCK error rather than blocking. * - * 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. + * 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 */ @@ -26680,7 +27416,8 @@ /** * g_pollable_output_stream_write_nonblocking: (virtual write_nonblocking) * @stream: a #GPollableOutputStream - * @buffer: (array length=count) (element-type guint8): a buffer to write data from + * @buffer: (array length=count) (element-type guint8): a buffer to write + * data from * @count: the number of bytes you want to write * @cancellable: (allow-none): a #GCancellable, or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -26697,7 +27434,8 @@ * may happen if you call this method after a source triggers due * to having been cancelled. * - * Returns: the number of bytes written, or -1 on error (including %G_IO_ERROR_WOULD_BLOCK). + * Returns: the number of bytes written, or -1 on error (including + * %G_IO_ERROR_WOULD_BLOCK). */ @@ -26718,7 +27456,8 @@ /** * g_pollable_source_new_full: - * @pollable_stream: (type GObject): the stream associated with the new source + * @pollable_stream: (type GObject): the stream associated with the + * new source * @child_source: (allow-none): optional child source to attach * @cancellable: (allow-none): optional #GCancellable to attach * @@ -26759,7 +27498,8 @@ /** * g_pollable_stream_write: * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @buffer: (array length=count) (element-type guint8): the buffer + * containing the data to write. * @count: the number of bytes to write * @blocking: whether to do blocking I/O * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. @@ -26784,10 +27524,12 @@ /** * g_pollable_stream_write_all: * @stream: a #GOutputStream. - * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write. + * @buffer: (array length=count) (element-type guint8): the buffer + * containing the data to write. * @count: the number of bytes to write * @blocking: whether to do blocking I/O - * @bytes_written: (out): location to store the number of bytes that was written to the stream + * @bytes_written: (out): location to store the number of bytes that was + * written to the stream * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @error: location to store the error occurring, or %NULL to ignore * @@ -26924,8 +27666,10 @@ * @protocol: The proxy protocol to support, in lower case (e.g. socks, http). * @dest_hostname: The destination hostname the proxy should tunnel to. * @dest_port: The destination port to tunnel to. - * @username: (allow-none): The username to authenticate to the proxy server (or %NULL). - * @password: (allow-none): The password to authenticate to the proxy server (or %NULL). + * @username: (allow-none): The username to authenticate to the proxy server + * (or %NULL). + * @password: (allow-none): The password to authenticate to the proxy server + * (or %NULL). * * Creates a new #GProxyAddress for @inetaddr with @protocol that should * tunnel through @dest_hostname and @dest_port. @@ -26952,7 +27696,9 @@ * does the necessary handshake to connect to @proxy_address, and if * required, wraps the #GIOStream to handle proxy payload. * - * Returns: (transfer full): a #GIOStream that will replace @connection. This might be the same as @connection, in which case a reference will be added. + * 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 */ @@ -26992,7 +27738,8 @@ * Lookup "gio-proxy" extension point for a proxy implementation that supports * specified protocol. * - * Returns: (transfer full): return a #GProxy or NULL if protocol is not supported. + * Returns: (transfer full): return a #GProxy or NULL if protocol + * is not supported. * Since: 2.26 */ @@ -27043,7 +27790,9 @@ * Direct connection should not be attempted unless it is part of the * returned array of proxies. * - * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). + * Returns: (transfer full) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). * Since: 2.26 */ @@ -27073,7 +27822,9 @@ * g_proxy_resolver_lookup_async() is complete. See * g_proxy_resolver_lookup() for more details. * - * Returns: (transfer full) (array zero-terminated=1): A NULL-terminated array of proxy URIs. Must be freed with g_strfreev(). + * Returns: (transfer full) (array zero-terminated=1): A + * NULL-terminated array of proxy URIs. Must be freed + * with g_strfreev(). * Since: 2.26 */ @@ -27202,7 +27953,8 @@ * operation, in which case @error (if non-%NULL) will be set to * %G_IO_ERROR_CANCELLED. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. * Since: 2.22 */ @@ -27236,7 +27988,8 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: a hostname (either ASCII-only, or in ASCII-encoded form), or %NULL on error. + * Returns: a hostname (either ASCII-only, or in ASCII-encoded + * form), or %NULL on error. * Since: 2.22 */ @@ -27272,7 +28025,10 @@ * address, it may be easier to create a #GNetworkAddress and use its * #GSocketConnectable interface. * - * 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.) + * 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 */ @@ -27307,7 +28063,9 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GInetAddress) (transfer full): a #GList of #GInetAddress, or %NULL on error. See g_resolver_lookup_by_name() for more details. + * 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 */ @@ -27331,7 +28089,9 @@ * operation, in which case @error (if non-%NULL) will be set to * %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) + * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, + * or %NULL on error. You must free each of the records and the list when you are + * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) * Since: 2.34 */ @@ -27368,7 +28128,9 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, or %NULL on error. You must free each of the records and the list when you are done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) + * Returns: (element-type GVariant) (transfer full): a #GList of #GVariant, + * or %NULL on error. You must free each of the records and the list when you are + * done with it. (You can use g_list_free_full() with g_variant_unref() to do this.) * Since: 2.34 */ @@ -27405,7 +28167,9 @@ * to create a #GNetworkService and use its #GSocketConnectable * interface. * - * 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.) + * 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 */ @@ -27443,7 +28207,8 @@ * a value from #GResolverError. If the operation was cancelled, * @error will be set to %G_IO_ERROR_CANCELLED. * - * Returns: (element-type GSrvTarget) (transfer full): a #GList of #GSrvTarget, or %NULL on error. See g_resolver_lookup_service() for more details. + * 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 */ @@ -27499,8 +28264,10 @@ * @resource: A #GResource * @path: A pathname inside the resource * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed + * @size: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (allow-none): a location to place the flags about the file, + * or %NULL if the length is not needed * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the resource and @@ -27551,7 +28318,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref() + * Returns: (transfer full): #GBytes or %NULL on error. + * Free the returned object with g_bytes_unref() * Since: 2.32 */ @@ -27585,7 +28353,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref() + * Returns: (transfer full): #GInputStream or %NULL on error. + * Free the returned object with g_object_unref() * Since: 2.32 */ @@ -27637,8 +28406,10 @@ * g_resources_get_info: * @path: A pathname inside the resource * @lookup_flags: A #GResourceLookupFlags - * @size: (out) (allow-none): a location to place the length of the contents of the file, or %NULL if the length is not needed - * @flags: (out) (allow-none): a location to place the flags about the file, or %NULL if the length is not needed + * @size: (out) (allow-none): a location to place the length of the contents of the file, + * or %NULL if the length is not needed + * @flags: (out) (allow-none): a location to place the flags about the file, + * or %NULL if the length is not needed * @error: return location for a #GError, or %NULL * * Looks for a file at the specified @path in the set of @@ -27672,7 +28443,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GBytes or %NULL on error. Free the returned object with g_bytes_unref() + * Returns: (transfer full): #GBytes or %NULL on error. + * Free the returned object with g_bytes_unref() * Since: 2.32 */ @@ -27689,7 +28461,8 @@ * * @lookup_flags controls the behaviour of the lookup. * - * Returns: (transfer full): #GInputStream or %NULL on error. Free the returned object with g_object_unref() + * Returns: (transfer full): #GInputStream or %NULL on error. + * Free the returned object with g_object_unref() * Since: 2.32 */ @@ -27742,7 +28515,8 @@ * @offset: a #goffset. * @type: a #GSeekType. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Seeks in the stream by the given @offset, modified by @type. * @@ -27750,7 +28524,9 @@ * triggering the cancellable object from another thread. If the operation * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. */ @@ -27769,7 +28545,8 @@ * @seekable: a #GSeekable. * @offset: a #goffset. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Truncates a stream with a given #offset. * @@ -27779,7 +28556,9 @@ * operation was partially finished when the operation was cancelled the * partial result will be returned, without an error. * - * Returns: %TRUE if successful. If an error has occurred, this function will return %FALSE and set @error appropriately if present. + * Returns: %TRUE if successful. If an error + * has occurred, this function will return %FALSE and set @error + * appropriately if present. */ @@ -27845,8 +28624,10 @@ * g_settings_backend_flatten_tree: * @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 + * @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 * * 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, @@ -28008,8 +28789,10 @@ * @object: (type GObject.Object): a #GObject * @property: the name of the property to bind * @flags: flags for the binding - * @get_mapping: a function that gets called to convert values from @settings to @object, or %NULL to use the default GIO mapping - * @set_mapping: a function that gets called to convert values from @object to @settings, or %NULL to use the default GIO mapping + * @get_mapping: a function that gets called to convert values + * from @settings to @object, or %NULL to use the default GIO mapping + * @set_mapping: a function that gets called to convert values + * from @object to @settings, or %NULL to use the default GIO mapping * @user_data: data that gets passed to @get_mapping and @set_mapping * @destroy: #GDestroyNotify function for @user_data * @@ -28246,7 +29029,8 @@ * g_settings_get_mapped: * @settings: a #GSettings object * @key: the key to get the value for - * @mapping: (scope call): the function to map the value in the settings database to the value used by the application + * @mapping: (scope call): the function to map the value in the + * settings database to the value used by the application * @user_data: user data for @mapping * * Gets the value that is stored at @key in @settings, subject to @@ -28361,7 +29145,9 @@ * 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. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated, %NULL-terminated array of strings, the value that is stored at @key in @settings. + * 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 */ @@ -28468,7 +29254,9 @@ * g_settings_list_schemas() represents the complete list of all * installed schemas. * - * Returns: (element-type utf8) (transfer none): a list of relocatable #GSettings schemas that are available. The list must not be modified or freed. + * 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 */ @@ -28485,7 +29273,9 @@ * g_settings_new_with_path()). See * g_settings_list_relocatable_schemas() for that. * - * Returns: (element-type utf8) (transfer none): a list of #GSettings schemas that are available. The list must not be modified or freed. + * 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 */ @@ -28819,7 +29609,8 @@ * schema for @settings or for the #GVariantType of @format to mismatch * the type given in the schema. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -28837,7 +29628,8 @@ * It is a programmer error to give a @key that isn't specified as * having a boolean type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -28855,7 +29647,8 @@ * It is a programmer error to give a @key that isn't specified as * having a 'double' type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -28916,7 +29709,8 @@ * It is a programmer error to give a @key that isn't specified as * having a int32 type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -28934,7 +29728,8 @@ * It is a programmer error to give a @key that isn't specified as * having a string type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -28953,7 +29748,8 @@ * 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. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -28972,7 +29768,8 @@ * It is a programmer error to give a @key that isn't specified as * having a uint32 type in the schema for @settings. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.30 */ @@ -28991,7 +29788,8 @@ * * If @value is floating then this function consumes the reference. * - * Returns: %TRUE if setting the key succeeded, %FALSE if the key was not writable + * Returns: %TRUE if setting the key succeeded, + * %FALSE if the key was not writable * Since: 2.26 */ @@ -29031,7 +29829,8 @@ /** * g_simple_action_group_add_entries: * @simple: a #GSimpleActionGroup - * @entries: (array length=n_entries): a pointer to the first item in an array of #GActionEntry structs + * @entries: (array length=n_entries): a pointer to the first item in + * an array of #GActionEntry structs * @n_entries: the length of @entries, or -1 * @user_data: the user data for signal connections * @@ -29246,7 +30045,8 @@ * * Gets the operation result boolean from within the asynchronous result. * - * Returns: %TRUE if the operation's result was %TRUE, %FALSE if the operation's result was %FALSE. + * Returns: %TRUE if the operation's result was %TRUE, %FALSE + * if the operation's result was %FALSE. */ @@ -29529,8 +30329,10 @@ /** * g_simple_proxy_resolver_new: - * @default_proxy: (allow-none): the default proxy to use, eg "socks://192.168.1.1" - * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses to not use a proxy for. + * @default_proxy: (allow-none): the default proxy to use, eg + * "socks://192.168.1.1" + * @ignore_hosts: (allow-none): an optional list of hosts/IP addresses + * to not use a proxy for. * * Creates a new #GSimpleProxyResolver. See * #GSimpleProxyResolver:default-proxy and @@ -29563,7 +30365,8 @@ /** * g_simple_proxy_resolver_set_ignore_hosts: * @resolver: a #GSimpleProxyResolver - * @ignore_hosts: %NULL-terminated list of hosts/IP addresses to not use a proxy for + * @ignore_hosts: %NULL-terminated list of hosts/IP addresses + * to not use a proxy for * * Sets the list of ignored hosts. * @@ -29611,7 +30414,8 @@ * 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. * - * Returns: (transfer full): a new #GSocket, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a new #GSocket, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -29636,7 +30440,9 @@ * internal errors (other than @cancellable being triggered) will be * ignored. * - * 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. + * 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. */ @@ -29644,7 +30450,8 @@ * g_socket_address_enumerator_next_async: * @enumerator: a #GSocketAddressEnumerator * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. - * @callback: (scope async): a #GAsyncReadyCallback to call when the request is satisfied + * @callback: (scope async): a #GAsyncReadyCallback to call when the request + * is satisfied * @user_data: (closure): the data to pass to callback function * * Asynchronously retrieves the next #GSocketAddress from @enumerator @@ -29664,7 +30471,9 @@ * g_socket_address_enumerator_next() for more information about * error handling. * - * 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. + * 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. */ @@ -29687,7 +30496,8 @@ * You can use this to allocate memory to pass to * g_socket_address_to_native(). * - * Returns: the size of the native <type>struct sockaddr</type> that @address represents + * Returns: the size of the native <type>struct sockaddr</type> that + * @address represents * Since: 2.22 */ @@ -29700,7 +30510,8 @@ * Creates a #GSocketAddress subclass corresponding to the native * <type>struct sockaddr</type> @native. * - * Returns: a new #GSocketAddress if @native could successfully be converted, otherwise %NULL. + * Returns: a new #GSocketAddress if @native could successfully be converted, + * otherwise %NULL. * Since: 2.22 */ @@ -29708,8 +30519,10 @@ /** * g_socket_address_to_native: * @address: a #GSocketAddress - * @dest: a pointer to a memory location that will contain the native <type>struct sockaddr</type>. - * @destlen: the size of @dest. Must be at least as large as g_socket_address_get_native_size(). + * @dest: a pointer to a memory location that will contain the native + * <type>struct sockaddr</type>. + * @destlen: the size of @dest. Must be at least as large as + * g_socket_address_get_native_size(). * @error: #GError for error reporting, or %NULL to ignore. * * Converts a #GSocketAddress to a native <type>struct @@ -29855,7 +30668,8 @@ * g_socket_client_connect_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_async() * @@ -29931,7 +30745,8 @@ * g_socket_client_connect_to_host_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_host_async() * @@ -29987,7 +30802,8 @@ * g_socket_client_connect_to_service_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_service_async() * @@ -30054,7 +30870,8 @@ * g_socket_client_connect_to_uri_finish: * @client: a #GSocketClient. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async connect operation. See g_socket_client_connect_to_uri_async() * @@ -30121,7 +30938,8 @@ * be the resolver returned by g_proxy_resolver_get_default(), but you * can override it with g_socket_client_set_proxy_resolver(). * - * Returns: (transfer none): The #GProxyResolver being used by @client. + * Returns: (transfer none): The #GProxyResolver being used by + * @client. * Since: 2.36 */ @@ -30181,7 +30999,8 @@ * * Creates a new #GSocketClient with the default options. * - * Returns: a #GSocketClient. Free the returned object with g_object_unref(). + * Returns: a #GSocketClient. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -30256,7 +31075,8 @@ /** * g_socket_client_set_proxy_resolver: * @client: a #GSocketClient. - * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the default. + * @proxy_resolver: (allow-none): a #GProxyResolver, or %NULL for the + * default. * * Overrides the #GProxyResolver used by @client. You can call this if * you want to use specific proxies, rather than using the system @@ -30617,7 +31437,8 @@ * * Try to get the local address of a socket connection. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -30629,7 +31450,8 @@ * * Try to get the remote address of a socket connection. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -30779,7 +31601,8 @@ * g_socket_get_available_bytes() first and then doing a receive of * exactly the right size. * - * Returns: the number of bytes that can be read from the socket without blocking or truncating, or -1 on error. + * Returns: the number of bytes that can be read from the socket + * without blocking or truncating, or -1 on error. * Since: 2.32 */ @@ -30827,7 +31650,8 @@ * g_unix_connection_send_credentials() / * g_unix_connection_receive_credentials() functions. * - * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object that must be freed with g_object_unref(). + * Returns: (transfer full): %NULL if @error is set, otherwise a #GCredentials object + * that must be freed with g_object_unref(). * Since: 2.26 */ @@ -30891,7 +31715,8 @@ * useful if the socket has been bound to a local address, * either explicitly or implicitly when connecting. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -30944,7 +31769,10 @@ * @value is still a pointer to a #gint variable, not a #guchar; * g_socket_get_option() will handle the conversion internally. * - * Returns: success or failure. On failure, @error will be set, and the system error value (<literal>errno</literal> or <literal>WSAGetLastError ()</literal>) will still be set to the result of the <literal>getsockopt ()</literal> call. + * Returns: success or failure. On failure, @error will be set, and + * the system error value (<literal>errno</literal> or + * <literal>WSAGetLastError ()</literal>) will still be set to the + * result of the <literal>getsockopt ()</literal> call. * Since: 2.36 */ @@ -30969,7 +31797,8 @@ * Try to get the remove address of a connected socket. This is only * useful for connection oriented sockets that have been connected. * - * Returns: (transfer full): a #GSocketAddress or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GSocketAddress or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -31142,7 +31971,8 @@ * @listener: a #GSocketListener * @result: a #GAsyncResult. * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async accept operation. See g_socket_listener_accept_async() * @@ -31200,7 +32030,8 @@ * @listener: a #GSocketListener * @result: a #GAsyncResult. * @source_object: (out) (transfer none) (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes an async accept operation. See g_socket_listener_accept_socket_async() * @@ -31248,7 +32079,8 @@ * g_socket_listener_add_any_inet_port: * @listener: a #GSocketListener * @source_object: (allow-none): Optional #GObject identifying this source - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Listens for TCP connections on any available port number for both * IPv6 and IPv4 (if each is available). @@ -31364,7 +32196,8 @@ * system, so you can use protocols not listed in #GSocketProtocol if you * know the protocol number used for it. * - * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref(). + * Returns: a #GSocket or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -31382,7 +32215,8 @@ * will be set to non-blocking mode, independent on the blocking * mode of the #GSocket. * - * Returns: a #GSocket or %NULL on error. Free the returned object with g_object_unref(). + * Returns: a #GSocket or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.22 */ @@ -31390,7 +32224,8 @@ /** * g_socket_receive: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -31419,7 +32254,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -31427,8 +32263,10 @@ /** * g_socket_receive_from: * @socket: a #GSocket - * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL - * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long). + * @address: (out) (allow-none): a pointer to a #GSocketAddress + * pointer, or %NULL + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -31441,7 +32279,8 @@ * * See g_socket_receive() for additional information. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -31449,11 +32288,14 @@ /** * g_socket_receive_message: * @socket: a #GSocket - * @address: (out) (allow-none): a pointer to a #GSocketAddress pointer, or %NULL + * @address: (out) (allow-none): a pointer to a #GSocketAddress + * pointer, or %NULL * @vectors: (array length=num_vectors): an array of #GInputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer which may be filled with an array of #GSocketControlMessages, or %NULL - * @num_messages: a pointer which will be filled with the number of elements in @messages, or %NULL + * @messages: (array length=num_messages) (allow-none): a pointer which + * may be filled with an array of #GSocketControlMessages, or %NULL + * @num_messages: a pointer which will be filled with the number of + * elements in @messages, or %NULL * @flags: a pointer to an int containing #GSocketMsgFlags flags * @cancellable: (allow-none): a %GCancellable or %NULL * @error: a #GError pointer, or %NULL @@ -31516,7 +32358,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.22 */ @@ -31524,7 +32367,8 @@ /** * g_socket_receive_with_blocking: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): a buffer to read data into (which should be at least @size bytes long). + * @buffer: (array length=size) (element-type guint8): a buffer to + * read data into (which should be at least @size bytes long). * @size: the number of bytes you want to read from the socket * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (allow-none): a %GCancellable or %NULL @@ -31534,7 +32378,8 @@ * the choice of blocking or non-blocking behavior is determined by * the @blocking argument rather than by @socket's properties. * - * Returns: Number of bytes read, or 0 if the connection was closed by the peer, or -1 on error + * Returns: Number of bytes read, or 0 if the connection was closed by + * the peer, or -1 on error * Since: 2.26 */ @@ -31542,7 +32387,8 @@ /** * g_socket_send: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -31562,7 +32408,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -31573,7 +32420,8 @@ * @address: (allow-none): a #GSocketAddress, or %NULL * @vectors: (array length=num_vectors): an array of #GOutputVector structs * @num_vectors: the number of elements in @vectors, or -1 - * @messages: (array length=num_messages) (allow-none): a pointer to an array of #GSocketControlMessages, or %NULL. + * @messages: (array length=num_messages) (allow-none): a pointer to an + * array of #GSocketControlMessages, or %NULL. * @num_messages: number of elements in @messages, or -1. * @flags: an int containing #GSocketMsgFlags flags * @cancellable: (allow-none): a %GCancellable or %NULL @@ -31617,7 +32465,8 @@ * * On error -1 is returned and @error is set accordingly. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -31626,7 +32475,8 @@ * g_socket_send_to: * @socket: a #GSocket * @address: (allow-none): a #GSocketAddress, or %NULL - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @cancellable: (allow-none): a %GCancellable or %NULL * @error: #GError for error reporting, or %NULL to ignore. @@ -31637,7 +32487,8 @@ * * See g_socket_send() for additional information. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.22 */ @@ -31645,7 +32496,8 @@ /** * g_socket_send_with_blocking: * @socket: a #GSocket - * @buffer: (array length=size) (element-type guint8): the buffer containing the data to send. + * @buffer: (array length=size) (element-type guint8): the buffer + * containing the data to send. * @size: the number of bytes to send * @blocking: whether to do blocking or non-blocking I/O * @cancellable: (allow-none): a %GCancellable or %NULL @@ -31655,7 +32507,8 @@ * the choice of blocking or non-blocking behavior is determined by * the @blocking argument rather than by @socket's properties. * - * Returns: Number of bytes written (which may be less than @size), or -1 on error + * Returns: Number of bytes written (which may be less than @size), or -1 + * on error * Since: 2.26 */ @@ -31735,7 +32588,8 @@ /** * g_socket_set_broadcast: * @socket: a #GSocket. - * @broadcast: whether @socket should allow sending to broadcast addresses + * @broadcast: whether @socket should allow sending to broadcast + * addresses * * Sets whether @socket should allow sending to broadcast addresses. * This is %FALSE by default. @@ -31789,7 +32643,8 @@ /** * g_socket_set_multicast_loopback: * @socket: a #GSocket. - * @loopback: whether @socket should receive messages sent to its multicast groups from the local host + * @loopback: whether @socket should receive messages sent to its + * multicast groups from the local host * * Sets whether outgoing multicast packets will be received by sockets * listening on that multicast address on the same host. This is %TRUE @@ -31831,7 +32686,10 @@ * platform-dependent options, you may need to include additional * headers. * - * Returns: success or failure. On failure, @error will be set, and the system error value (<literal>errno</literal> or <literal>WSAGetLastError ()</literal>) will still be set to the result of the <literal>setsockopt ()</literal> call. + * Returns: success or failure. On failure, @error will be set, and + * the system error value (<literal>errno</literal> or + * <literal>WSAGetLastError ()</literal>) will still be set to the + * result of the <literal>setsockopt ()</literal> call. * Since: 2.36 */ @@ -32195,20 +33053,23 @@ /** * g_task_is_valid: * @result: (type Gio.AsyncResult): A #GAsyncResult - * @source_object: (allow-none) (type GObject): the source object expected to be associated with the task + * @source_object: (allow-none) (type GObject): the source object + * expected to be associated with the task * * Checks that @result is a #GTask, and that @source_object is its * source object (or that @source_object is %NULL and @result has no * source object). This can be used in g_return_if_fail() checks. * - * Returns: %TRUE if @result and @source_object are valid, %FALSE if not + * Returns: %TRUE if @result and @source_object are valid, %FALSE + * if not * Since: 2.36 */ /** * g_task_new: - * @source_object: (allow-none) (type GObject): the #GObject that owns this task, or %NULL. + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (scope async): a #GAsyncReadyCallback. * @callback_data: (closure): user data passed to @callback. @@ -32293,7 +33154,8 @@ /** * g_task_report_error: - * @source_object: (allow-none) (type GObject): the #GObject that owns this task, or %NULL. + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. * @callback: (scope async): a #GAsyncReadyCallback. * @callback_data: (closure): user data passed to @callback. * @source_tag: an opaque pointer indicating the source of this task @@ -32314,7 +33176,8 @@ /** * g_task_report_new_error: - * @source_object: (allow-none) (type GObject): the #GObject that owns this task, or %NULL. + * @source_object: (allow-none) (type GObject): the #GObject that owns + * this task, or %NULL. * @callback: (scope async): a #GAsyncReadyCallback. * @callback_data: (closure): user data passed to @callback. * @source_tag: an opaque pointer indicating the source of this task @@ -32420,7 +33283,8 @@ /** * g_task_return_pointer: * @task: a #GTask - * @result: (allow-none) (transfer full): the pointer result of a task function + * @result: (allow-none) (transfer full): the pointer result of a task + * function * @result_destroy: (allow-none): a #GDestroyNotify function. * * Sets @task's result to @result and completes the task. If @result @@ -32484,7 +33348,8 @@ /** * g_task_set_check_cancellable: * @task: the #GTask - * @check_cancellable: whether #GTask will check the state of its #GCancellable for you. + * @check_cancellable: whether #GTask will check the state of + * its #GCancellable for you. * * Sets or clears @task's check-cancellable flag. If this is %TRUE * (the default), then g_task_propagate_pointer(), etc, and @@ -32508,7 +33373,8 @@ /** * g_task_set_priority: * @task: the #GTask - * @priority: the <link linkend="io-priority">priority</link> of the request. + * @priority: the <link linkend="io-priority">priority</link> + * of the request. * * Sets @task's priority. If you do not call this, it will default to * %G_PRIORITY_DEFAULT. @@ -32525,7 +33391,8 @@ /** * g_task_set_return_on_cancel: * @task: the #GTask - * @return_on_cancel: whether the task returns automatically when it is cancelled. + * @return_on_cancel: whether the task returns automatically when + * it is cancelled. * * Sets or clears @task's return-on-cancel flag. This is only * meaningful for tasks run via g_task_run_in_thread() or @@ -32556,7 +33423,9 @@ * #GTaskThreadFunc will still be run (for consistency), but the task * will also be completed right away. * - * Returns: %TRUE if @task's return-on-cancel flag was changed to match @return_on_cancel. %FALSE if @task has already been cancelled. + * Returns: %TRUE if @task's return-on-cancel flag was changed to + * match @return_on_cancel. %FALSE if @task has already been + * cancelled. * Since: 2.36 */ @@ -32773,7 +33642,8 @@ /** * g_themed_icon_new_from_names: * @iconnames: (array length=len): an array of strings containing icon names. - * @len: the length of the @iconnames array, or -1 if @iconnames is %NULL-terminated + * @len: the length of the @iconnames array, or -1 if @iconnames is + * %NULL-terminated * * Creates a new themed icon for @iconnames. * @@ -32823,7 +33693,8 @@ /** * g_threaded_socket_service_new: - * @max_threads: the maximal number of threads to execute concurrently handling incoming clients, -1 means no limit + * @max_threads: the maximal number of threads to execute concurrently + * handling incoming clients, -1 means no limit * * Creates a new #GThreadedSocketService with no listeners. Listeners * must be added with one of the #GSocketListener "add" methods. @@ -32839,7 +33710,8 @@ * * Gets the #GType of @backend's #GTlsCertificate implementation. * - * Returns: the #GType of @backend's #GTlsCertificate implementation. + * Returns: the #GType of @backend's #GTlsCertificate + * implementation. * Since: 2.28 */ @@ -32850,7 +33722,8 @@ * * Gets the #GType of @backend's #GTlsClientConnection implementation. * - * Returns: the #GType of @backend's #GTlsClientConnection implementation. + * Returns: the #GType of @backend's #GTlsClientConnection + * implementation. * Since: 2.28 */ @@ -32871,7 +33744,8 @@ * * Gets the default #GTlsDatabase used to verify TLS connections. * - * Returns: (transfer full): the default database, which should be unreffed when done. + * Returns: (transfer full): the default database, which should be + * unreffed when done. * Since: 2.30 */ @@ -32893,7 +33767,8 @@ * * Gets the #GType of @backend's #GTlsServerConnection implementation. * - * Returns: the #GType of @backend's #GTlsServerConnection implementation. + * Returns: the #GType of @backend's #GTlsServerConnection + * implementation. * Since: 2.28 */ @@ -32916,7 +33791,9 @@ * * Gets the #GTlsCertificate representing @cert's issuer, if known * - * Returns: (transfer none): The certificate of @cert's issuer, or %NULL if @cert is self-signed or signed with an unknown certificate. + * 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 */ @@ -32948,7 +33825,9 @@ * PEM-encoded certificates, this will return an empty list and not * set @error. * - * 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. + * 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 */ @@ -33047,7 +33926,9 @@ * Each item in the list is a #GByteArray which contains the complete * subject DN of the certificate authority. * - * 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(). + * 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 */ @@ -33058,7 +33939,9 @@ * * Gets @conn's expected server identity * - * Returns: (transfer none): a #GSocketConnectable describing the expected server identity, or %NULL if the expected identity is not known. + * Returns: (transfer none): a #GSocketConnectable describing the + * expected server identity, or %NULL if the expected identity is not + * known. * Since: 2.28 */ @@ -33097,7 +33980,8 @@ * must have pollable input and output streams) which is assumed to * communicate with the server identified by @server_identity. * - * Returns: (transfer full) (type GTlsClientConnection): the new #GTlsClientConnection, or %NULL on error + * Returns: (transfer full) (type GTlsClientConnection): the new + * #GTlsClientConnection, or %NULL on error * Since: 2.28 */ @@ -33153,7 +34037,8 @@ * Used by #GTlsConnection implementations to emit the * #GTlsConnection::accept-certificate signal. * - * Returns: %TRUE if one of the signal handlers has returned %TRUE to accept @peer_cert + * Returns: %TRUE if one of the signal handlers has returned + * %TRUE to accept @peer_cert * Since: 2.28 */ @@ -33241,7 +34126,8 @@ * when the connection is closed. See * g_tls_connection_set_require_close_notify() for details. * - * Returns: %TRUE if @conn requires a proper TLS close notification. + * Returns: %TRUE if @conn requires a proper TLS close + * notification. * Since: 2.28 */ @@ -33295,7 +34181,8 @@ /** * g_tls_connection_handshake_async: * @conn: a #GTlsConnection - * @io_priority: the <link linkend="io-priority">I/O priority</link> of the request. + * @io_priority: the <link linkend="io-priority">I/O priority</link> + * of the request. * @cancellable: (allow-none): a #GCancellable, or %NULL * @callback: callback to call when the handshake is complete * @user_data: the data to pass to the callback function @@ -33316,7 +34203,8 @@ * Finish an asynchronous TLS handshake operation. See * g_tls_connection_handshake() for more information. * - * Returns: %TRUE on success, %FALSE on failure, in which case @error will be set. + * Returns: %TRUE on success, %FALSE on failure, in which + * case @error will be set. * Since: 2.28 */ @@ -33507,7 +34395,8 @@ * This function can block, use g_tls_database_lookup_certificate_for_handle_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full) (allow-none): a newly allocated #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full) (allow-none): a newly allocated + * #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -33541,7 +34430,8 @@ * If the handle is no longer valid, or does not point to a certificate in * this database, then %NULL will be returned. * - * Returns: (transfer full): a newly allocated #GTlsCertificate object. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated #GTlsCertificate object. + * Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -33564,7 +34454,8 @@ * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform * the lookup operation asynchronously. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -33595,7 +34486,8 @@ * Finish an asynchronous lookup issuer operation. See * g_tls_database_lookup_certificate_issuer() for more information. * - * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. + * Returns: (transfer full): a newly allocated issuer #GTlsCertificate, + * or %NULL. Use g_object_unref() to release the certificate. * Since: 2.30 */ @@ -33614,7 +34506,8 @@ * This function can block, use g_tls_database_lookup_certificates_issued_by_async() to perform * the lookup operation asynchronously. * - * 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. + * 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 */ @@ -33649,7 +34542,8 @@ * Finish an asynchronous lookup of certificates. See * g_tls_database_lookup_certificates_issued_by() for more information. * - * 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. + * 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 */ @@ -33690,7 +34584,8 @@ * This function can block, use g_tls_database_verify_chain_async() to perform * the verification operation asynchronously. * - * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification. + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. * Since: 2.30 */ @@ -33724,7 +34619,8 @@ * Finish an asynchronous verify chain operation. See * g_tls_database_verify_chain() for more information. * * - * Returns: the appropriate #GTlsCertificateFlags which represents the result of verification. + * Returns: the appropriate #GTlsCertificateFlags which represents the + * result of verification. * Since: 2.30 */ @@ -33749,7 +34645,8 @@ * * The certificates in @anchors must be PEM encoded. * - * Returns: (transfer full) (type GTlsFileDatabase): the new #GTlsFileDatabase, or %NULL on error + * Returns: (transfer full) (type GTlsFileDatabase): the new + * #GTlsFileDatabase, or %NULL on error * Since: 2.30 */ @@ -34006,7 +34903,8 @@ * Creates a new #GTlsServerConnection wrapping @base_io_stream (which * must have pollable input and output streams). * - * Returns: (transfer full) (type GTlsServerConnection): the new #GTlsServerConnection, or %NULL on error + * Returns: (transfer full) (type GTlsServerConnection): the new + * #GTlsServerConnection, or %NULL on error * Since: 2.28 */ @@ -34028,7 +34926,8 @@ * Other ways to exchange credentials with a foreign peer includes the * #GUnixCredentialsMessage type and g_socket_get_credentials() function. * - * Returns: (transfer full): Received credentials on success (free with g_object_unref()), %NULL if @error is set. + * Returns: (transfer full): Received credentials on success (free with + * g_object_unref()), %NULL if @error is set. * Since: 2.26 */ @@ -34061,7 +34960,8 @@ * Finishes an asynchronous receive credentials operation started with * g_unix_connection_receive_credentials_async(). * - * Returns: (transfer full): a #GCredentials, or %NULL on error. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GCredentials, or %NULL on error. + * Free the returned object with g_object_unref(). * Since: 2.32 */ @@ -34222,7 +35122,8 @@ * this index with g_unix_fd_list_get() then you will receive back a * duplicated copy of the same file descriptor. * - * Returns: the index of the appended fd in case of success, else -1 (and @error is set) + * Returns: the index of the appended fd in case of success, else -1 + * (and @error is set) * Since: 2.24 */ @@ -34295,7 +35196,8 @@ /** * g_unix_fd_list_peek_fds: * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -34311,7 +35213,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: (array length=length) (transfer none): an array of file descriptors + * Returns: (array length=length) (transfer none): an array of file + * descriptors * Since: 2.24 */ @@ -34319,7 +35222,8 @@ /** * g_unix_fd_list_steal_fds: * @list: a #GUnixFDList - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -34340,7 +35244,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @list, an empty array is returned. * - * Returns: (array length=length) (transfer full): an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * Since: 2.24 */ @@ -34403,7 +35308,8 @@ /** * g_unix_fd_message_steal_fds: * @message: a #GUnixFDMessage - * @length: (out) (allow-none): pointer to the length of the returned array, or %NULL + * @length: (out) (allow-none): pointer to the length of the returned + * array, or %NULL * * Returns the array of file descriptors that is contained in this * object. @@ -34423,7 +35329,8 @@ * This function never returns %NULL. In case there are no file * descriptors contained in @message, an empty array is returned. * - * Returns: (array length=length) (transfer full): an array of file descriptors + * Returns: (array length=length) (transfer full): an array of file + * descriptors * Since: 2.22 */ @@ -34479,14 +35386,16 @@ /** * g_unix_is_mount_path_system_internal: - * @mount_path: a mount path, e.g. <filename>/media/disk</filename> or <filename>/usr</filename> + * @mount_path: a mount path, e.g. <filename>/media/disk</filename> + * or <filename>/usr</filename> * * Determines if @mount_path is considered an implementation of the * OS. This is primarily used for hiding mountable and mounted volumes * that only are used in the OS and has little to no relevance to the * casual user. * - * Returns: %TRUE if @mount_path is considered an implementation detail of the OS. + * Returns: %TRUE if @mount_path is considered an implementation detail + * of the OS. */ @@ -34510,7 +35419,8 @@ * * Compares two unix mounts. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ @@ -34579,7 +35489,8 @@ * Guesses the name of a Unix mount. * The result is a translated string. * - * Returns: A newly allocated string that must be freed with g_free() + * Returns: A newly allocated string that must + * be freed with g_free() */ @@ -34639,7 +35550,8 @@ /** * g_unix_mount_monitor_set_rate_limit: * @mount_monitor: a #GUnixMountMonitor - * @limit_msec: a integer with the limit in milliseconds to poll for changes. + * @limit_msec: a integer with the limit in milliseconds to + * poll for changes. * * Sets the rate limit to which the @mount_monitor will report * consecutive change events to the mount and mount point entry files. @@ -34655,7 +35567,8 @@ * * Compares two unix mount points. * - * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, or less than @mount2, respectively. + * Returns: 1, 0 or -1 if @mount1 is greater than, equal to, + * or less than @mount2, respectively. */ @@ -34735,7 +35648,8 @@ * Guesses the name of a Unix mount point. * The result is a translated string. * - * Returns: A newly allocated string that must be freed with g_free() + * Returns: A newly allocated string that must + * be freed with g_free() */ @@ -34799,7 +35713,8 @@ * allowing for checking if the mounts have changed with * g_unix_mount_points_changed_since(). * - * Returns: (element-type GUnixMountPoint) (transfer full): a #GList of the UNIX mountpoints. + * Returns: (element-type GUnixMountPoint) (transfer full): + * a #GList of the UNIX mountpoints. */ @@ -34822,7 +35737,8 @@ * timestamp, allowing for checking if the mounts have changed * with g_unix_mounts_changed_since(). * - * Returns: (element-type GUnixMountEntry) (transfer full): a #GList of the UNIX mounts. + * Returns: (element-type GUnixMountEntry) (transfer full): + * a #GList of the UNIX mounts. */ @@ -35020,7 +35936,8 @@ * * Gets a #GFile for @path. * - * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ @@ -35035,7 +35952,8 @@ * might not support any I/O operation if the URI * is malformed or if the URI scheme is not supported. * - * Returns: (transfer full): a #GFile. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile. + * Free the returned object with g_object_unref(). */ @@ -35054,7 +35972,9 @@ * * Gets a list of URI schemes supported by @vfs. * - * Returns: (transfer none): a %NULL-terminated array of strings. The returned array belongs to GIO and must not be freed or modified. + * Returns: (transfer none): a %NULL-terminated array of strings. + * The returned array belongs to GIO and must + * not be freed or modified. */ @@ -35064,7 +35984,8 @@ * * Checks if the VFS is active. * - * Returns: %TRUE if construction of the @vfs was successful and it is now active. + * Returns: %TRUE if construction of the @vfs was successful + * and it is now active. */ @@ -35077,7 +35998,8 @@ * not support any I/O operations if the @parse_name cannot * be parsed by the #GVfs module. * - * Returns: (transfer full): a #GFile for the given @parse_name. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GFile for the given @parse_name. + * Free the returned object with g_object_unref(). */ @@ -35135,7 +36057,8 @@ * g_volume_eject_with_operation: * @volume: a #GVolume. * @flags: flags affecting the unmount if required for eject - * @mount_operation: (allow-none): a #GMountOperation or %NULL to avoid user interaction. + * @mount_operation: (allow-none): a #GMountOperation or %NULL to + * avoid user interaction. * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore. * @callback: (allow-none): a #GAsyncReadyCallback, or %NULL. * @user_data: user data passed to @callback. @@ -35152,7 +36075,8 @@ * g_volume_eject_with_operation_finish: * @volume: a #GVolume. * @result: a #GAsyncResult. - * @error: a #GError location to store the error occurring, or %NULL to ignore. + * @error: a #GError location to store the error occurring, or %NULL to + * ignore. * * Finishes ejecting a volume. If any errors occurred during the operation, * @error will be set to contain the errors and %FALSE will be returned. @@ -35170,7 +36094,8 @@ * that @volume has. Use g_volume_get_identifier() to obtain * the identifiers themselves. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array of strings containing kinds of identifiers. Use g_strfreev() to free. + * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated array + * of strings containing kinds of identifiers. Use g_strfreev() to free. */ @@ -35208,7 +36133,8 @@ * implementations to find the underlying mount to shadow, see * g_mount_is_shadowed() for more details. * - * Returns: (transfer full): the activation root of @volume or %NULL. Use g_object_unref() to free. + * Returns: (transfer full): the activation root of @volume or %NULL. Use + * g_object_unref() to free. * Since: 2.18 */ @@ -35219,7 +36145,9 @@ * * Gets the drive for the @volume. * - * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GDrive or %NULL if @volume is not associated with a drive. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. */ @@ -35229,7 +36157,9 @@ * * Gets the icon for @volume. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. */ @@ -35242,7 +36172,9 @@ * See the <link linkend="volume-identifier">introduction</link> * for more information about volume identifiers. * - * Returns: a newly allocated string containing the requested identfier, or %NULL if the #GVolume doesn't have this kind of identifier + * Returns: a newly allocated string containing the + * requested identfier, or %NULL if the #GVolume + * doesn't have this kind of identifier */ @@ -35252,7 +36184,9 @@ * * Gets the mount for the @volume. * - * 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. + * 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. */ @@ -35262,7 +36196,8 @@ * * Gets the name of @volume. * - * Returns: the name for the given @volume. The returned string should be freed with g_free() when no longer needed. + * Returns: the name for the given @volume. The returned string should + * be freed with g_free() when no longer needed. */ @@ -35283,7 +36218,9 @@ * * Gets the symbolic icon for @volume. * - * Returns: (transfer full): a #GIcon. The returned object should be unreffed with g_object_unref() when no longer needed. + * Returns: (transfer full): a #GIcon. + * The returned object should be unreffed with g_object_unref() + * when no longer needed. * Since: 2.34 */ @@ -35297,7 +36234,9 @@ * considered an opaque string. Returns %NULL if there is no UUID * available. * - * 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. + * 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. */ @@ -35334,8 +36273,13 @@ * is to return #GVolume objects representing entries in the users * "favorite servers" list or similar. * - * 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. + * 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. */ @@ -35344,7 +36288,8 @@ * * Gets the volume monitor used by gio. * - * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call g_object_unref() when done with it. + * Returns: (transfer full): a reference to the #GVolumeMonitor used by gio. Call + * g_object_unref() when done with it. */ @@ -35368,7 +36313,8 @@ * * Finds a #GMount object by its UUID (see g_mount_get_uuid()) * - * Returns: (transfer full): a #GMount or %NULL if no such mount is available. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GMount or %NULL if no such mount is available. + * Free the returned object with g_object_unref(). */ @@ -35392,7 +36338,8 @@ * * Finds a #GVolume object by its UUID (see g_volume_get_uuid()) * - * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. Free the returned object with g_object_unref(). + * Returns: (transfer full): a #GVolume or %NULL if no such volume is available. + * Free the returned object with g_object_unref(). */ @@ -35633,7 +36580,8 @@ * * Optionally doesn't list the desktop ids given in the @except * - * Returns: a #GList containing the desktop ids which claim to handle @mime_type. + * 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 c18fda50..d539fb3d 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -68,8 +68,10 @@ /** * GArray: - * @data: a pointer to the element data. The data may be moved as elements are added to the #GArray. - * @len: the number of elements in the #GArray not including the possible terminating zero element. + * @data: a pointer to the element data. The data may be moved as + * elements are added to the #GArray. + * @len: the number of elements in the #GArray not including the + * possible terminating zero element. * * Contains the public fields of an <link linkend="glib-Arrays">Array</link>. */ @@ -86,7 +88,8 @@ /** * GByteArray: - * @data: a pointer to the element data. The data may be moved as elements are added to the #GByteArray. + * @data: a pointer to the element data. The data may be moved as + * elements are added to the #GByteArray. * @len: the number of elements in the #GByteArray. * * The <structname>GByteArray</structname> struct allows access to the @@ -137,7 +140,8 @@ * 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. + * Returns: negative value if @a < @b; zero if @a = @b; positive + * value if @a > @b. */ @@ -151,7 +155,8 @@ * 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. + * Returns: negative value if @a < @b; zero if @a = @b; positive + * value if @a > @b. */ @@ -257,8 +262,10 @@ * @julian_days: the Julian representation of the date * @julian: this bit is set if @julian_days is valid * @dmy: this is set if @day, @month and @year are valid - * @day: the day of the day-month-year representation of the date, as a number between 1 and 31 - * @month: the day of the day-month-year representation of the date, as a number between 1 and 12 + * @day: the day of the day-month-year representation of the date, + * as a number between 1 and 31 + * @month: the day of the day-month-year representation of the date, + * as a number between 1 and 12 * @year: the day of the day-month-year representation of the date * * Represents a day between January 1, Year 1 and a few thousand years in @@ -411,31 +418,73 @@ /** * GFileError: - * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. - * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory for writing, or create or remove hard links to it. - * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not allow the attempted operation. + * @G_FILE_ERROR_EXIST: Operation not permitted; only the owner of + * the file (or other resource) or processes with special privileges + * can perform the operation. + * @G_FILE_ERROR_ISDIR: File is a directory; you cannot open a directory + * for writing, or create or remove hard links to it. + * @G_FILE_ERROR_ACCES: Permission denied; the file permissions do not + * allow the attempted operation. * @G_FILE_ERROR_NAMETOOLONG: Filename too long. - * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file doesn't exist" error for ordinary files that are referenced in contexts where they are expected to already exist. - * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when a directory is required. - * @G_FILE_ERROR_NXIO: No such device or address. The system tried to use the device represented by a file you specified, and it couldn't find the device. This can mean that the device file was installed incorrectly, or that the physical device is missing or not correctly attached to the computer. - * @G_FILE_ERROR_NODEV: The underlying file system of the specified file does not support memory mapping. - * @G_FILE_ERROR_ROFS: The directory containing the new link can't be modified because it's on a read-only file system. + * @G_FILE_ERROR_NOENT: No such file or directory. This is a "file + * doesn't exist" error for ordinary files that are referenced in + * contexts where they are expected to already exist. + * @G_FILE_ERROR_NOTDIR: A file that isn't a directory was specified when + * a directory is required. + * @G_FILE_ERROR_NXIO: No such device or address. The system tried to + * use the device represented by a file you specified, and it + * couldn't find the device. This can mean that the device file was + * installed incorrectly, or that the physical device is missing or + * not correctly attached to the computer. + * @G_FILE_ERROR_NODEV: The underlying file system of the specified file + * does not support memory mapping. + * @G_FILE_ERROR_ROFS: The directory containing the new link can't be + * modified because it's on a read-only file system. * @G_FILE_ERROR_TXTBSY: Text file busy. - * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory. (GLib won't reliably return this, don't pass in pointers to bad memory.) - * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered in looking up a file name. This often indicates a cycle of symbolic links. - * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a file failed because the disk is full. - * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate more virtual memory because its capacity is full. - * @G_FILE_ERROR_MFILE: The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. - * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the entire system. - * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a descriptor that has been closed or reading from a descriptor open only for writing (or vice versa). - * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate various kinds of problems with passing the wrong argument to a library function. - * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the other end of a pipe. Every library function that returns this error code also generates a 'SIGPIPE' signal; this signal terminates the program if not handled or blocked. Thus, your program will never actually see this code unless it has handled or blocked 'SIGPIPE'. - * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might work if you try again later. - * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal occurred and prevented completion of the call. When this happens, you should try the call again. - * @G_FILE_ERROR_IO: Input/output error; usually used for physical read or write errors. i.e. the disk or other physical device hardware is returning errors. - * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the file (or other resource) or processes with special privileges can perform the operation. - * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that the system is missing some functionality. - * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this is the standard "failed for unspecified reason" error code present in all #GError error code enumerations. Returned if no specific code applies. + * @G_FILE_ERROR_FAULT: You passed in a pointer to bad memory. + * (GLib won't reliably return this, don't pass in pointers to bad + * memory.) + * @G_FILE_ERROR_LOOP: Too many levels of symbolic links were encountered + * in looking up a file name. This often indicates a cycle of symbolic + * links. + * @G_FILE_ERROR_NOSPC: No space left on device; write operation on a + * file failed because the disk is full. + * @G_FILE_ERROR_NOMEM: No memory available. The system cannot allocate + * more virtual memory because its capacity is full. + * @G_FILE_ERROR_MFILE: The current process has too many files open and + * can't open any more. Duplicate descriptors do count toward this + * limit. + * @G_FILE_ERROR_NFILE: There are too many distinct file openings in the + * entire system. + * @G_FILE_ERROR_BADF: Bad file descriptor; for example, I/O on a + * descriptor that has been closed or reading from a descriptor open + * only for writing (or vice versa). + * @G_FILE_ERROR_INVAL: Invalid argument. This is used to indicate + * various kinds of problems with passing the wrong argument to a + * library function. + * @G_FILE_ERROR_PIPE: Broken pipe; there is no process reading from the + * other end of a pipe. Every library function that returns this + * error code also generates a 'SIGPIPE' signal; this signal + * terminates the program if not handled or blocked. Thus, your + * program will never actually see this code unless it has handled + * or blocked 'SIGPIPE'. + * @G_FILE_ERROR_AGAIN: Resource temporarily unavailable; the call might + * work if you try again later. + * @G_FILE_ERROR_INTR: Interrupted function call; an asynchronous signal + * occurred and prevented completion of the call. When this + * happens, you should try the call again. + * @G_FILE_ERROR_IO: Input/output error; usually used for physical read + * or write errors. i.e. the disk or other physical device hardware + * is returning errors. + * @G_FILE_ERROR_PERM: Operation not permitted; only the owner of the + * file (or other resource) or processes with special privileges can + * perform the operation. + * @G_FILE_ERROR_NOSYS: Function not implemented; this indicates that + * the system is missing some functionality. + * @G_FILE_ERROR_FAILED: Does not correspond to a UNIX error code; this + * is the standard "failed for unspecified reason" error code present + * in all #GError error code enumerations. Returned if no specific + * code applies. * * Values corresponding to @errno codes returned from file operations * on UNIX. Unlike @errno codes, GFileError values are available on @@ -454,11 +503,14 @@ /** * GFileTest: - * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file (not a directory). Note that this test will also return %TRUE if the tested file is a symlink to a regular file. + * @G_FILE_TEST_IS_REGULAR: %TRUE if the file is a regular file + * (not a directory). Note that this test will also return %TRUE + * if the tested file is a symlink to a regular file. * @G_FILE_TEST_IS_SYMLINK: %TRUE if the file is a symlink. * @G_FILE_TEST_IS_DIR: %TRUE if the file is a directory. * @G_FILE_TEST_IS_EXECUTABLE: %TRUE if the file is executable. - * @G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not be a regular file. + * @G_FILE_TEST_EXISTS: %TRUE if the file exists. It may or may not + * be a regular file. * * A test to perform on a file using g_file_test(). */ @@ -478,8 +530,12 @@ /** * GFormatSizeFlags: * @G_FORMAT_SIZE_DEFAULT: behave the same as g_format_size() - * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part of the returned string. For example, "45.6 kB (45,612 bytes)". - * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style suffixes. IEC units should only be used for reporting things with a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. Network and storage sizes should be reported in the normal SI units. + * @G_FORMAT_SIZE_LONG_FORMAT: include the exact number of bytes as part + * of the returned string. For example, "45.6 kB (45,612 bytes)". + * @G_FORMAT_SIZE_IEC_UNITS: use IEC (base 1024) units with "KiB"-style + * suffixes. IEC units should only be used for reporting things with + * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. + * Network and storage sizes should be reported in the normal SI units. * * Flags to modify the format of the string returned by g_format_size_full(). */ @@ -488,7 +544,8 @@ /** * GFunc: * @data: the element's data. - * @user_data: user data passed to g_list_foreach() or g_slist_foreach(). + * @user_data: user data passed to g_list_foreach() or + * g_slist_foreach(). * * Specifies the type of functions passed to g_list_foreach() and * g_slist_foreach(). @@ -519,7 +576,8 @@ * g_hash_table_foreach_remove(). It should return %TRUE if the * key/value pair should be removed from the #GHashTable. * - * Returns: %TRUE if the key/value pair should be removed from the #GHashTable + * Returns: %TRUE if the key/value pair should be removed from the + * #GHashTable */ @@ -587,9 +645,12 @@ * @prev: pointer to the previous hook in the list * @ref_count: the reference count of this hook * @hook_id: the id of this hook, which is unique within its list - * @flags: flags which are set for this hook. See #GHookFlagMask for predefined flags - * @func: the function to call when this hook is invoked. The possible signatures for this function are #GHookFunc and #GHookCheckFunc - * @destroy: the default @finalize_hook function of a #GHookList calls this member of the hook that is being finalized + * @flags: flags which are set for this hook. See #GHookFlagMask for + * predefined flags + * @func: the function to call when this hook is invoked. The possible + * signatures for this function are #GHookFunc and #GHookCheckFunc + * @destroy: the default @finalize_hook function of a #GHookList calls + * this member of the hook that is being finalized * * The <structname>GHook</structname> struct represents a single hook * function in a #GHookList. @@ -655,7 +716,8 @@ * GHookFlagMask: * @G_HOOK_FLAG_ACTIVE: set if the hook has not been destroyed * @G_HOOK_FLAG_IN_CALL: set if the hook is currently being run - * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for hook flags; see %G_HOOK_FLAG_USER_SHIFT + * @G_HOOK_FLAG_MASK: A mask covering all bits reserved for + * hook flags; see %G_HOOK_FLAG_USER_SHIFT * * Flags used internally in the #GHook implementation. */ @@ -677,7 +739,8 @@ * @is_setup: 1 if the #GHookList has been initialized * @hooks: the first #GHook element in the list * @dummy3: unused - * @finalize_hook: the function to call to finalize a #GHook element. The default behaviour is to call the hooks @destroy function + * @finalize_hook: the function to call to finalize a #GHook element. + * The default behaviour is to call the hooks @destroy function * @dummy: unused * * The <structname>GHookList</structname> struct represents a @@ -898,7 +961,8 @@ * @G_IO_OUT: Data can be written (without blocking). * @G_IO_PRI: There is urgent data to read. * @G_IO_ERR: Error condition. - * @G_IO_HUP: Hung up (the connection has been broken, usually for pipes and sockets). + * @G_IO_HUP: Hung up (the connection has been broken, usually for + * pipes and sockets). * @G_IO_NVAL: Invalid request. The file descriptor is not open. * * A bitwise combination representing a condition to watch for on an @@ -920,14 +984,24 @@ /** * GIOFlags: - * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal> (see the documentation of the UNIX open() syscall). - * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal> (see the documentation of the UNIX open() syscall). - * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. This flag cannot be changed. - * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. This flag cannot be changed. - * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, i.e. that g_io_channel_seek_position() can be used on it. This flag cannot be changed. + * @G_IO_FLAG_APPEND: turns on append mode, corresponds to <literal>O_APPEND</literal> + * (see the documentation of the UNIX open() + * syscall). + * @G_IO_FLAG_NONBLOCK: turns on nonblocking mode, corresponds to + * <literal>O_NONBLOCK</literal>/<literal>O_NDELAY</literal> + * (see the documentation of the UNIX open() syscall). + * @G_IO_FLAG_IS_READABLE: indicates that the io channel is readable. + * This flag cannot be changed. + * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable. + * This flag cannot be changed. + * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable, + * i.e. that g_io_channel_seek_position() can + * be used on it. This flag cannot be changed. * @G_IO_FLAG_MASK: the mask that specifies all the valid flags. - * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from g_io_channel_get_flags(). - * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify with g_io_channel_set_flags(). + * @G_IO_FLAG_GET_MASK: the mask of the flags that are returned from + * g_io_channel_get_flags(). + * @G_IO_FLAG_SET_MASK: the mask of the flags that the user can modify + * with g_io_channel_set_flags(). * * Specifies properties of a #GIOChannel. Some of the flags can only be * read with g_io_channel_get_flags(), but not changed with @@ -945,20 +1019,41 @@ * 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 + * Returns: the function should return %FALSE if the event source + * should be removed */ /** * 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_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. - * @io_set_flags: sets the #GIOFlags on the channel. This is called from g_io_channel_set_flags() with all flags except for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked out. - * @io_get_flags: gets the #GIOFlags for the channel. This function need only return the %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() automatically adds the others as appropriate. + * @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_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. + * @io_set_flags: sets the #GIOFlags on the channel. This is called + * from g_io_channel_set_flags() with all flags except + * for %G_IO_FLAG_APPEND and %G_IO_FLAG_NONBLOCK masked + * out. + * @io_get_flags: gets the #GIOFlags for the channel. This function + * need only return the %G_IO_FLAG_APPEND and + * %G_IO_FLAG_NONBLOCK flags; g_io_channel_get_flags() + * automatically adds the others as appropriate. * * A table of functions used to handle different types of #GIOChannel * in a generic way. @@ -986,7 +1081,8 @@ /** * GKeyFileError: - * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding + * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in + * an unknown encoding * @G_KEY_FILE_ERROR_PARSE: document was ill-formed * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found @@ -1000,8 +1096,14 @@ /** * GKeyFileFlags: * @G_KEY_FILE_NONE: No flags, default behaviour - * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise all comments will be lost when the key file is written back. - * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the (possibly modified) contents of the key file back to a file; otherwise only the translations for the current language will be written back. + * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the + * (possibly modified) contents of the key file back to a file; + * otherwise all comments will be lost when the key file is + * written back. + * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the + * (possibly modified) contents of the key file back to a file; + * otherwise only the translations for the current language will be + * written back. * * Flags which influence the parsing. */ @@ -1026,7 +1128,8 @@ * * See glib_check_version() for a runtime check. * - * Returns: %TRUE if the version of the GLib header files is the same as or newer than the passed-in version. + * Returns: %TRUE if the version of the GLib header files + * is the same as or newer than the passed-in version. */ @@ -1114,7 +1217,10 @@ /** * GList: - * @data: holds the element's data, which can be a pointer to any kind of data, or any integer value using the <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>. + * @data: holds the element's data, which can be a pointer to any kind + * of data, or any integer value using the <link + * linkend="glib-Type-Conversion-Macros">Type Conversion + * Macros</link>. * @next: contains the link to the next element in the list. * @prev: contains the link to the previous element in the list. * @@ -1125,7 +1231,8 @@ /** * GLogFunc: * @log_domain: the log domain of the message - * @log_level: the log level of the message (including the fatal and recursion flags) + * @log_level: the log level of the message (including the + * fatal and recursion flags) * @message: the message to process * @user_data: user data, set in g_log_set_handler() * @@ -1137,8 +1244,11 @@ * GLogLevelFlags: * @G_LOG_FLAG_RECURSION: internal flag * @G_LOG_FLAG_FATAL: internal flag - * @G_LOG_LEVEL_ERROR: log level for errors, see g_error(). This level is also used for messages produced by g_assert(). - * @G_LOG_LEVEL_CRITICAL: log level for critical messages, see g_critical(). This level is also used for messages produced by g_return_if_fail() and g_return_val_if_fail(). + * @G_LOG_LEVEL_ERROR: log level for errors, see g_error(). + * This level is also used for messages produced by g_assert(). + * @G_LOG_LEVEL_CRITICAL: log level for critical messages, see g_critical(). + * This level is also used for messages produced by g_return_if_fail() + * and g_return_val_if_fail(). * @G_LOG_LEVEL_WARNING: log level for warnings, see g_warning() * @G_LOG_LEVEL_MESSAGE: log level for messages, see g_message() * @G_LOG_LEVEL_INFO: log level for informational messages @@ -1163,12 +1273,27 @@ /** * GMarkupCollectType: - * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes to collect - * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from the attribute_values[] array. Expects a parameter of type (const char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the attribute isn't present then the pointer will be set to %NULL - * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but expects a parameter of type (char **) and g_strdup()s the returned pointer. The pointer must be freed with g_free() - * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *) and parses the attribute value as a boolean. Sets %FALSE if the attribute isn't present. Valid boolean values consist of (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", "yes", "y", "1" - * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but in the case of a missing attribute a value is set that compares equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is implied - * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields. If present, allows the attribute not to appear. A default value is set depending on what value type is used + * @G_MARKUP_COLLECT_INVALID: used to terminate the list of attributes + * to collect + * @G_MARKUP_COLLECT_STRING: collect the string pointer directly from + * the attribute_values[] array. Expects a parameter of type (const + * char **). If %G_MARKUP_COLLECT_OPTIONAL is specified and the + * attribute isn't present then the pointer will be set to %NULL + * @G_MARKUP_COLLECT_STRDUP: as with %G_MARKUP_COLLECT_STRING, but + * expects a parameter of type (char **) and g_strdup()s the + * returned pointer. The pointer must be freed with g_free() + * @G_MARKUP_COLLECT_BOOLEAN: expects a parameter of type (gboolean *) + * and parses the attribute value as a boolean. Sets %FALSE if the + * attribute isn't present. Valid boolean values consist of + * (case-insensitive) "false", "f", "no", "n", "0" and "true", "t", + * "yes", "y", "1" + * @G_MARKUP_COLLECT_TRISTATE: as with %G_MARKUP_COLLECT_BOOLEAN, but + * in the case of a missing attribute a value is set that compares + * equal to neither %FALSE nor %TRUE G_MARKUP_COLLECT_OPTIONAL is + * implied + * @G_MARKUP_COLLECT_OPTIONAL: can be bitwise ORed with the other fields. + * If present, allows the attribute not to appear. A default value + * is set depending on what value type is used * * A mixed enumerated type and flags field. You must specify one type * (string, strdup, boolean, tristate). Additionally, you may optionally @@ -1242,10 +1367,14 @@ /** * GNode: * @data: contains the actual data of the node. - * @next: points to the node's next sibling (a sibling is another #GNode with the same parent). + * @next: points to the node's next sibling (a sibling is another + * #GNode with the same parent). * @prev: points to the node's previous sibling. - * @parent: points to the parent of the #GNode, or is %NULL if the #GNode is the root of the tree. - * @children: points to the first child of the #GNode. The other children are accessed by using the @next pointer of each child. + * @parent: points to the parent of the #GNode, or is %NULL if the + * #GNode is the root of the tree. + * @children: points to the first child of the #GNode. The other + * children are accessed by using the @next pointer of each + * child. * * The #GNode struct represents one node in a * <link linkend="glib-N-ary-Trees">N-ary Tree</link>. fields @@ -1280,7 +1409,8 @@ /** * GOnce: * @status: the status of the #GOnce - * @retval: the value returned by the call to the function, if @status is %G_ONCE_STATUS_READY + * @retval: the value returned by the call to the function, if @status + * is %G_ONCE_STATUS_READY * * A #GOnce struct controls a one-time initialization function. Any * one-time initialization function must have its own unique #GOnce @@ -1369,7 +1499,8 @@ /** * GPtrArray: - * @pdata: points to the array of pointers, which may be moved when the array grows. + * @pdata: points to the array of pointers, which may be moved when the + * array grows. * @len: number of pointers in the array. * * Contains the public fields of a pointer array. @@ -1535,7 +1666,10 @@ /** * GSList: - * @data: holds the element's data, which can be a pointer to any kind of data, or any integer value using the <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>. + * @data: holds the element's data, which can be a pointer to any kind + * of data, or any integer value using the <link + * linkend="glib-Type-Conversion-Macros">Type Conversion + * Macros</link>. * @next: contains the link to the next element in the list. * * The #GSList struct is used for each element in the singly-linked @@ -1620,31 +1754,63 @@ /** * GScannerConfig: - * @cset_skip_characters: specifies which characters should be skipped by the scanner (the default is the whitespace characters: space, tab, carriage-return and line-feed). - * @cset_identifier_first: specifies the characters which can start identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). - * @cset_identifier_nth: specifies the characters which can be used in identifiers, after the first character (the default is #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, #G_CSET_LATINC). - * @cpair_comment_single: specifies the characters at the start and end of single-line comments. The default is "#\n" which means that single-line comments start with a '#' and continue until a '\n' (end of line). - * @case_sensitive: specifies if symbols are case sensitive (the default is %FALSE). - * @skip_comment_multi: specifies if multi-line comments are skipped and not returned as tokens (the default is %TRUE). - * @skip_comment_single: specifies if single-line comments are skipped and not returned as tokens (the default is %TRUE). - * @scan_comment_multi: specifies if multi-line comments are recognized (the default is %TRUE). - * @scan_identifier: specifies if identifiers are recognized (the default is %TRUE). - * @scan_identifier_1char: specifies if single-character identifiers are recognized (the default is %FALSE). - * @scan_identifier_NULL: specifies if %NULL is reported as %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). - * @scan_symbols: specifies if symbols are recognized (the default is %TRUE). - * @scan_binary: specifies if binary numbers are recognized (the default is %FALSE). - * @scan_octal: specifies if octal numbers are recognized (the default is %TRUE). - * @scan_float: specifies if floating point numbers are recognized (the default is %TRUE). - * @scan_hex: specifies if hexadecimal numbers are recognized (the default is %TRUE). - * @scan_hex_dollar: specifies if '$' is recognized as a prefix for hexadecimal numbers (the default is %FALSE). - * @scan_string_sq: specifies if strings can be enclosed in single quotes (the default is %TRUE). - * @scan_string_dq: specifies if strings can be enclosed in double quotes (the default is %TRUE). - * @numbers_2_int: specifies if binary, octal and hexadecimal numbers are reported as #G_TOKEN_INT (the default is %TRUE). - * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT (the default is %FALSE). - * @identifier_2_string: specifies if identifiers are reported as strings (the default is %FALSE). - * @char_2_token: specifies if characters are reported by setting <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default is %TRUE). - * @symbol_2_token: specifies if symbols are reported by setting <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the default is %FALSE). - * @scope_0_fallback: specifies if a symbol is searched for in the default scope in addition to the current scope (the default is %FALSE). + * @cset_skip_characters: specifies which characters should be skipped + * by the scanner (the default is the whitespace characters: space, + * tab, carriage-return and line-feed). + * @cset_identifier_first: specifies the characters which can start + * identifiers (the default is #G_CSET_a_2_z, "_", and #G_CSET_A_2_Z). + * @cset_identifier_nth: specifies the characters which can be used + * in identifiers, after the first character (the default is + * #G_CSET_a_2_z, "_0123456789", #G_CSET_A_2_Z, #G_CSET_LATINS, + * #G_CSET_LATINC). + * @cpair_comment_single: specifies the characters at the start and + * end of single-line comments. The default is "#\n" which means + * that single-line comments start with a '#' and continue until + * a '\n' (end of line). + * @case_sensitive: specifies if symbols are case sensitive (the + * default is %FALSE). + * @skip_comment_multi: specifies if multi-line comments are skipped + * and not returned as tokens (the default is %TRUE). + * @skip_comment_single: specifies if single-line comments are skipped + * and not returned as tokens (the default is %TRUE). + * @scan_comment_multi: specifies if multi-line comments are recognized + * (the default is %TRUE). + * @scan_identifier: specifies if identifiers are recognized (the + * default is %TRUE). + * @scan_identifier_1char: specifies if single-character + * identifiers are recognized (the default is %FALSE). + * @scan_identifier_NULL: specifies if %NULL is reported as + * %G_TOKEN_IDENTIFIER_NULL (the default is %FALSE). + * @scan_symbols: specifies if symbols are recognized (the default + * is %TRUE). + * @scan_binary: specifies if binary numbers are recognized (the + * default is %FALSE). + * @scan_octal: specifies if octal numbers are recognized (the + * default is %TRUE). + * @scan_float: specifies if floating point numbers are recognized + * (the default is %TRUE). + * @scan_hex: specifies if hexadecimal numbers are recognized (the + * default is %TRUE). + * @scan_hex_dollar: specifies if '$' is recognized as a prefix for + * hexadecimal numbers (the default is %FALSE). + * @scan_string_sq: specifies if strings can be enclosed in single + * quotes (the default is %TRUE). + * @scan_string_dq: specifies if strings can be enclosed in double + * quotes (the default is %TRUE). + * @numbers_2_int: specifies if binary, octal and hexadecimal numbers + * are reported as #G_TOKEN_INT (the default is %TRUE). + * @int_2_float: specifies if all numbers are reported as %G_TOKEN_FLOAT + * (the default is %FALSE). + * @identifier_2_string: specifies if identifiers are reported as strings + * (the default is %FALSE). + * @char_2_token: specifies if characters are reported by setting + * <literal>token = ch</literal> or as %G_TOKEN_CHAR (the default + * is %TRUE). + * @symbol_2_token: specifies if symbols are reported by setting + * <literal>token = v_symbol</literal> or as %G_TOKEN_SYMBOL (the + * default is %FALSE). + * @scope_0_fallback: specifies if a symbol is searched for in the + * default scope in addition to the current scope (the default is %FALSE). * @store_int64: use value.v_int64 rather than v_int * * Specifies the #GScanner parser configuration. Most settings can @@ -1657,7 +1823,8 @@ * GScannerMsgFunc: * @scanner: a #GScanner * @message: the message - * @error: %TRUE if the message signals an error, %FALSE if it signals a warning. + * @error: %TRUE if the message signals an error, + * %FALSE if it signals a warning. * * Specifies the type of the message handler function. */ @@ -1700,7 +1867,9 @@ * 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. + * Returns: zero if the iterators are equal, a negative value if @a + * comes before @b, and a positive value if @b comes before + * @a. */ @@ -1726,9 +1895,13 @@ /** * GString: - * @str: points to the character data. It may move as text is added. The @str field is null-terminated and so can be used as an ordinary C string. - * @len: contains the length of the string, not including the terminating nul byte. - * @allocated_len: the number of bytes that can be stored in the string before it needs to be reallocated. May be larger than @len. + * @str: points to the character data. It may move as text is added. + * The @str field is null-terminated and so + * can be used as an ordinary C string. + * @len: contains the length of the string, not including the + * terminating nul byte. + * @allocated_len: the number of bytes that can be stored in the + * string before it needs to be reallocated. May be larger than @len. * * The GString struct contains the public fields of a GString. */ @@ -1817,9 +1990,17 @@ /** * GTestSubprocessFlags: - * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child process will inherit the parent's stdin. Otherwise, the child's stdin is redirected to <filename>/dev/null</filename>. - * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child process will inherit the parent's stdout. Otherwise, the child's stdout will not be visible, but it will be captured to allow later tests with g_test_trap_assert_stdout(). - * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child process will inherit the parent's stderr. Otherwise, the child's stderr will not be visible, but it will be captured to allow later tests with g_test_trap_assert_stderr(). + * @G_TEST_SUBPROCESS_INHERIT_STDIN: If this flag is given, the child + * process will inherit the parent's stdin. Otherwise, the child's + * stdin is redirected to <filename>/dev/null</filename>. + * @G_TEST_SUBPROCESS_INHERIT_STDOUT: If this flag is given, the child + * process will inherit the parent's stdout. Otherwise, the child's + * stdout will not be visible, but it will be captured to allow + * later tests with g_test_trap_assert_stdout(). + * @G_TEST_SUBPROCESS_INHERIT_STDERR: If this flag is given, the child + * process will inherit the parent's stderr. Otherwise, the child's + * stderr will not be visible, but it will be captured to allow + * later tests with g_test_trap_assert_stderr(). * * Flags to pass to g_test_trap_subprocess() to control input and output. * @@ -1837,14 +2018,24 @@ /** * GTestTrapFlags: - * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to <filename>/dev/null</filename> so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stdout(). - * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to <filename>/dev/null</filename> so it cannot be observed on the console during test runs. The actual output is still captured though to allow later tests with g_test_trap_assert_stderr(). - * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the child process is shared with stdin of its parent process. It is redirected to <filename>/dev/null</filename> otherwise. + * @G_TEST_TRAP_SILENCE_STDOUT: Redirect stdout of the test child to + * <filename>/dev/null</filename> so it cannot be observed on the + * console during test runs. The actual output is still captured + * though to allow later tests with g_test_trap_assert_stdout(). + * @G_TEST_TRAP_SILENCE_STDERR: Redirect stderr of the test child to + * <filename>/dev/null</filename> so it cannot be observed on the + * console during test runs. The actual output is still captured + * though to allow later tests with g_test_trap_assert_stderr(). + * @G_TEST_TRAP_INHERIT_STDIN: If this flag is given, stdin of the + * child process is shared with stdin of its parent process. + * It is redirected to <filename>/dev/null</filename> otherwise. * * Test traps are guards around forked tests. * These flags determine what traps to set. * - * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), which is deprecated. g_test_trap_subprocess() uses #GTestTrapSubprocessFlags. + * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), + * which is deprecated. g_test_trap_subprocess() uses + * #GTestTrapSubprocessFlags. */ @@ -1869,7 +2060,8 @@ /** * GThreadError: - * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource shortage. Try again later. + * @G_THREAD_ERROR_AGAIN: a thread couldn't be created due to resource + * shortage. Try again later. * * Possible errors of thread related functions. */ @@ -2005,7 +2197,9 @@ /** * GTrashStack: - * @next: pointer to the previous element of the stack, gets stored in the first <literal>sizeof (gpointer)</literal> bytes of the element + * @next: pointer to the previous element of the stack, + * gets stored in the first <literal>sizeof (gpointer)</literal> + * bytes of the element * * Each piece of memory that is pushed onto the stack * is cast to a <structname>GTrashStack*</structname>. @@ -2014,8 +2208,12 @@ /** * GTraverseFlags: - * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_LEAFS. - * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This name has been introduced in 2.6, for older version use %G_TRAVERSE_NON_LEAFS. + * @G_TRAVERSE_LEAVES: only leaf nodes should be visited. This name has + * been introduced in 2.6, for older version use + * %G_TRAVERSE_LEAFS. + * @G_TRAVERSE_NON_LEAVES: only non-leaf nodes should be visited. This + * name has been introduced in 2.6, for older + * version use %G_TRAVERSE_NON_LEAFS. * @G_TRAVERSE_ALL: all nodes should be visited. * @G_TRAVERSE_MASK: a mask of all traverse flags. * @G_TRAVERSE_LEAFS: identical to %G_TRAVERSE_LEAVES. @@ -2043,10 +2241,19 @@ /** * GTraverseType: - * @G_IN_ORDER: vists a node's left child first, then the node itself, then its right child. This is the one to use if you want the output sorted according to the compare function. + * @G_IN_ORDER: vists a node's left child first, then the node itself, + * then its right child. This is the one to use if you + * want the output sorted according to the compare + * function. * @G_PRE_ORDER: visits a node, then its children. * @G_POST_ORDER: visits the node's children, then the node itself. - * @G_LEVEL_ORDER: is not implemented for <link linkend="glib-Balanced-Binary-Trees">Balanced Binary Trees</link>. For <link linkend="glib-N-ary-Trees">N-ary Trees</link>, it vists the root node first, then its children, then its grandchildren, and so on. Note that this is less efficient than the other orders. + * @G_LEVEL_ORDER: is not implemented for <link + * linkend="glib-Balanced-Binary-Trees">Balanced Binary + * Trees</link>. For <link + * linkend="glib-N-ary-Trees">N-ary Trees</link>, it + * vists the root node first, then its children, then + * its grandchildren, and so on. Note that this is less + * efficient than the other orders. * * Specifies the type of traveral performed by g_tree_traverse(), * g_node_traverse() and g_node_find(). @@ -2382,9 +2589,11 @@ * @G_VARIANT_CLASS_INT64: The #GVariant is a signed 64 bit integer. * @G_VARIANT_CLASS_UINT64: The #GVariant is an unsigned 64 bit integer. * @G_VARIANT_CLASS_HANDLE: The #GVariant is a file handle index. - * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating point value. + * @G_VARIANT_CLASS_DOUBLE: The #GVariant is a double precision floating + * point value. * @G_VARIANT_CLASS_STRING: The #GVariant is a normal string. - * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path string. + * @G_VARIANT_CLASS_OBJECT_PATH: The #GVariant is a D-Bus object path + * string. * @G_VARIANT_CLASS_SIGNATURE: The #GVariant is a D-Bus signature string. * @G_VARIANT_CLASS_VARIANT: The #GVariant is a variant. * @G_VARIANT_CLASS_MAYBE: The #GVariant is a maybe-typed value. @@ -2500,7 +2709,9 @@ * for return values and for <emphasis>out</emphasis> parameters, it doesn't * make sense for <emphasis>in</emphasis> parameters. * - * Deprecated: 2.30: API providers should replace all existing uses with <literal>const</literal> and API consumers should adjust their code accordingly + * Deprecated: 2.30: API providers should replace all existing uses with + * <literal>const</literal> and API consumers should adjust their code + * accordingly */ @@ -2863,7 +3074,8 @@ /** * G_GNUC_DEPRECATED_FOR: - * @f: the intended replacement for the deprecated symbol, such as the name of a function + * @f: the intended replacement for the deprecated symbol, + * such as the name of a function * * Like %G_GNUC_DEPRECATED, but names the intended replacement for the * deprecated symbol if the version of <command>gcc</command> in use is @@ -3058,7 +3270,8 @@ /** * G_GNUC_PRINTF: - * @format_idx: the index of the argument corresponding to the format string (The arguments are numbered from 1) + * @format_idx: the index of the argument corresponding to the + * format string (The arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments * * Expands to the GNU C <literal>format</literal> function attribute @@ -3098,7 +3311,8 @@ /** * G_GNUC_SCANF: - * @format_idx: the index of the argument corresponding to the format string (The arguments are numbered from 1) + * @format_idx: the index of the argument corresponding to + * the format string (The arguments are numbered from 1) * @arg_idx: the index of the first of the format arguments * * Expands to the GNU C <literal>format</literal> function attribute @@ -4322,7 +4536,8 @@ * G_STRUCT_MEMBER: * @member_type: the type of the struct field * @struct_p: a pointer to a struct - * @struct_offset: the offset of the field from the start of the struct, in bytes + * @struct_offset: the offset of the field from the start of the struct, + * in bytes * * Returns a member of a structure at a given offset, using the given type. * @@ -4450,7 +4665,10 @@ /** * G_WIN32_DLLMAIN_FOR_DLL_NAME: * @static: empty or "static" - * @dll_name: the name of the (pointer to the) char array where the DLL name will be stored. If this is used, you must also include <filename>windows.h</filename>. If you need a more complex DLL entry point function, you cannot use this + * @dll_name: the name of the (pointer to the) char array where + * the DLL name will be stored. If this is used, you must also + * include <filename>windows.h</filename>. If you need a more + * complex DLL entry point function, you cannot use this * * On Windows, this macro defines a DllMain() function that stores * the actual DLL name that the code being compiled will be included in. @@ -4591,7 +4809,8 @@ /** * Q_: - * @String: the string to be translated, with a '|'-separated prefix which must not be translated + * @String: the string to be translated, with a '|'-separated prefix + * which must not be translated * * Like _(), but handles context in message ids. This has the advantage * that the string can be adorned with a prefix to guarantee uniqueness @@ -4621,7 +4840,8 @@ /** * SECTION:arrays * @title: Arrays - * @short_description: arrays of arbitrary elements which grow automatically as elements are added + * @short_description: arrays of arbitrary elements which grow + * automatically as elements are added * * Arrays are similar to standard C arrays, except that they grow * automatically as elements are added. @@ -4707,7 +4927,8 @@ /** * SECTION:arrays_pointer * @title: Pointer Arrays - * @short_description: arrays of pointers to any type of data, which grow automatically as new elements are added + * @short_description: arrays of pointers to any type of data, which + * grow automatically as new elements are added * * Pointer Arrays are similar to Arrays but are used only for storing * pointers. @@ -5097,7 +5318,8 @@ /** * SECTION:datalist * @title: Keyed Data Lists - * @short_description: lists of data elements which are accessible by a string or GQuark identifier + * @short_description: lists of data elements which are accessible by a + * string or GQuark identifier * * Keyed data lists provide lists of arbitrary data elements which can * be accessed either with a string or with a #GQuark corresponding to @@ -5131,7 +5353,8 @@ /** * SECTION:datasets * @title: Datasets - * @short_description: associate groups of data elements with particular memory locations + * @short_description: associate groups of data elements with + * particular memory locations * * Datasets associate groups of data elements with particular memory * locations. These are useful if you need to associate data with a @@ -6437,7 +6660,8 @@ /** * SECTION:hash_tables * @title: Hash Tables - * @short_description: associations between keys and values so that given a key the value can be found quickly + * @short_description: associations between keys and values so that + * given a key the value can be found quickly * * A #GHashTable provides associations between keys and values which is * optimized so that given a key, the associated value can be found @@ -6551,8 +6775,15 @@ /** * SECTION:iochannels * @title: IO Channels - * @short_description: portable support for using files, pipes and sockets - * @see_also: <para> <variablelist> <varlistentry> <term>g_io_add_watch(), g_io_add_watch_full(), g_source_remove()</term> <listitem><para> Convenience functions for creating #GIOChannel instances and adding them to the <link linkend="glib-The-Main-Event-Loop">main event loop</link>. </para></listitem> </varlistentry> </variablelist> </para> + * @short_description: portable support for using files, pipes and + * sockets + * @see_also: <para> <variablelist> <varlistentry> + * <term>g_io_add_watch(), g_io_add_watch_full(), + * g_source_remove()</term> <listitem><para> Convenience + * functions for creating #GIOChannel instances and adding + * them to the <link linkend="glib-The-Main-Event-Loop">main + * event loop</link>. </para></listitem> </varlistentry> + * </variablelist> </para> * * The #GIOChannel data type aims to provide a portable method for * using file descriptors, pipes, and sockets, and integrating them @@ -6883,7 +7114,8 @@ * SECTION:markup * @Title: Simple XML Subset Parser * @Short_description: parses a subset of XML - * @See_also: <ulink url="http://www.w3.org/TR/REC-xml/">XML Specification</ulink> + * @See_also: <ulink url="http://www.w3.org/TR/REC-xml/">XML + * Specification</ulink> * * The "GMarkup" parser is intended to parse a simple markup format * that's a subset of XML. This is a small, efficient, easy-to-use @@ -6950,7 +7182,8 @@ /** * SECTION:memory_slices * @title: Memory Slices - * @short_description: efficient way to allocate groups of equal-sized chunks of memory + * @short_description: efficient way to allocate groups of equal-sized + * chunks of memory * * Memory slices provide a space-efficient and multi-processing scalable * way to allocate equal-sized pieces of memory, just like the original @@ -7031,7 +7264,8 @@ /** * SECTION:messages * @title: Message Logging - * @short_description: versatile support for logging messages with different levels of importance + * @short_description: versatile support for logging messages + * with different levels of importance * * These functions provide support for logging error messages * or messages used for debugging. @@ -7113,12 +7347,12 @@ * <informalexample><screen> * Usage: * testtreemodel [OPTION...] - test tree model performance - * + * * Help 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 @@ -7185,7 +7419,8 @@ /** * SECTION:patterns * @title: Glob-style pattern matching - * @short_description: matches strings against patterns containing '*' (wildcard) and '?' (joker) + * @short_description: matches strings against patterns containing '*' + * (wildcard) and '?' (joker) * * The <function>g_pattern_match*</function> functions match a string * against a pattern containing '*' and '?' wildcards with similar @@ -7209,7 +7444,8 @@ /** * SECTION:quarks * @title: Quarks - * @short_description: a 2-way association between a string and a unique integer identifier + * @short_description: a 2-way association between a string and a + * unique integer identifier * * Quarks are associations between strings and integer identifiers. * Given either the string or the #GQuark identifier it is possible to @@ -7442,7 +7678,8 @@ /** * SECTION:strings * @title: Strings - * @short_description: text buffers which grow automatically as text is added + * @short_description: text buffers which grow automatically + * as text is added * * A #GString is an object that handles the memory management of a C * string for you. The emphasis of #GString is on text, typically @@ -7462,7 +7699,8 @@ * SECTION:testing * @title: Testing * @short_description: a test framework - * @see_also: <link linkend="gtester">gtester</link>, <link linkend="gtester-report">gtester-report</link> + * @see_also: <link linkend="gtester">gtester</link>, + * <link linkend="gtester-report">gtester-report</link> * * GLib provides a framework for writing and maintaining unit tests * in parallel to the code they are testing. The API is designed according @@ -7551,7 +7789,8 @@ /** * SECTION:threads * @title: Threads - * @short_description: portable support for threads, mutexes, locks, conditions and thread private data + * @short_description: portable support for threads, mutexes, locks, + * conditions and thread private data * @see_also: #GThreadPool, #GAsyncQueue * * Threads act almost like processes, but unlike processes all threads @@ -7699,7 +7938,8 @@ /** * SECTION:trees-binary * @title: Balanced Binary Trees - * @short_description: a sorted collection of key/value pairs optimized for searching and traversing in order + * @short_description: a sorted collection of key/value pairs optimized + * for searching and traversing in order * * The #GTree structure and its associated functions provide a sorted * collection of key/value pairs optimized for searching and traversing @@ -7809,7 +8049,8 @@ /** * SECTION:types * @title: Basic Types - * @short_description: standard GLib types, defined for ease-of-use and portability + * @short_description: standard GLib types, defined for ease-of-use + * and portability * * GLib defines a number of commonly used types, which can be divided * into 4 groups: @@ -7834,7 +8075,8 @@ /** * SECTION:unicode * @Title: Unicode Manipulation - * @Short_description: functions operating on Unicode characters and UTF-8 strings + * @Short_description: functions operating on Unicode characters and + * UTF-8 strings * @See_also: g_locale_to_utf8(), g_locale_from_utf8() * * This section describes a number of functions for dealing with @@ -7953,7 +8195,9 @@ * * See your C library manual for more details about access(). * - * Returns: zero if the pathname refers to an existing file system object that has all the tested permissions, or -1 otherwise or on error. + * 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 */ @@ -8002,7 +8246,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(). + * Returns: the element data if @free_segment is %FALSE, otherwise + * %NULL. The element data should be freed using g_free(). */ @@ -8071,8 +8316,10 @@ /** * g_array_new: - * @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. + * @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. * * Creates a new #GArray with a reference count of 1. @@ -8104,7 +8351,8 @@ /** * g_array_prepend_vals: * @array: a #GArray. - * @data: a pointer to the elements to prepend to the start of the array. + * @data: a pointer to the elements to prepend to the start of the + * array. * @len: the number of elements to prepend. * * Adds @len elements onto the start of the array. @@ -8202,8 +8450,10 @@ /** * g_array_sized_new: - * @zero_terminated: %TRUE if the array should have an extra element at the end with all bits cleared. - * @clear_: %TRUE if all bits in the array should be cleared to 0 on allocation. + * @zero_terminated: %TRUE if the array should have an extra element at + * the end with all bits cleared. + * @clear_: %TRUE if all bits in the array should be cleared to 0 on + * allocation. * @element_size: size of each element in the array. * @reserved_size: number of elements preallocated. * @@ -8269,7 +8519,8 @@ * a char, so there's no worry about sign extension if characters * are signed. * - * Returns: If @c is a decimal digit (according to g_ascii_isdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a decimal digit (according to + * g_ascii_isdigit()), its numeric value. Otherwise, -1. */ @@ -8296,7 +8547,8 @@ * g_ascii_formatd: * @buffer: A buffer to place the resulting string in * @buf_len: The length of the buffer. - * @format: The printf()-style format to use for the code to use for converting. + * @format: The printf()-style format to use for the + * code to use for converting. * @d: The #gdouble to convert * * Converts a #gdouble to a string, using the '.' as @@ -8515,7 +8767,8 @@ * characters include all ASCII letters. If you compare two CP932 * strings using this function, you will get false matches. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. */ @@ -8526,7 +8779,11 @@ * * Converts all upper case ASCII letters to lower case ASCII letters. * - * Returns: a newly-allocated string, with all the upper case characters in @str converted to lower case, with semantics that exactly match g_ascii_tolower(). (Note that this is unlike the old g_strdown(), which modified the string in place.) + * 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.) */ @@ -8547,14 +8804,16 @@ * function only on strings known to be in encodings where bytes * corresponding to ASCII letters always represent themselves. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. + * Returns: 0 if the strings match, a negative value if @s1 < @s2, + * or a positive value if @s1 > @s2. */ /** * g_ascii_strtod: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * * Converts a string to a #gdouble value. * @@ -8587,7 +8846,8 @@ /** * g_ascii_strtoll: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * @base: to be used for the conversion, 2..36 or 0 * * Converts a string to a #gint64 value. @@ -8616,7 +8876,8 @@ /** * g_ascii_strtoull: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * @base: to be used for the conversion, 2..36 or 0 * * Converts a string to a #guint64 value. @@ -8649,7 +8910,11 @@ * * Converts all lower case ASCII letters to upper case ASCII letters. * - * Returns: a newly allocated string, with all the lower case characters in @str converted to upper case, with semantics that exactly match g_ascii_toupper(). (Note that this is unlike the old g_strup(), which modified the string in place.) + * 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.) */ @@ -8667,7 +8932,9 @@ * 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. * - * Returns: the result of converting @c to lower case. If @c is not an ASCII upper case letter, @c is returned unchanged. + * Returns: the result of converting @c to lower case. + * If @c is not an ASCII upper case letter, + * @c is returned unchanged. */ @@ -8685,7 +8952,9 @@ * 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. * - * Returns: the result of converting @c to upper case. If @c is not an ASCII lower case letter, @c is returned unchanged. + * Returns: the result of converting @c to upper case. + * If @c is not an ASCII lower case letter, + * @c is returned unchanged. */ @@ -8698,7 +8967,8 @@ * a char, so there's no worry about sign extension if characters * are signed. * - * Returns: If @c is a hex digit (according to g_ascii_isxdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a hex digit (according to + * g_ascii_isxdigit()), its numeric value. Otherwise, -1. */ @@ -8718,7 +8988,8 @@ /** * g_assert_cmpfloat: * @n1: an floating point number - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another floating point number * * Debugging macro to compare two floating point numbers. @@ -8735,7 +9006,8 @@ /** * g_assert_cmphex: * @n1: an unsigned integer - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * * Debugging macro to compare to unsigned integers. @@ -8750,7 +9022,8 @@ /** * g_assert_cmpint: * @n1: an integer - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another integer * * Debugging macro to compare two integers. @@ -8767,7 +9040,8 @@ /** * g_assert_cmpstr: * @s1: a string (may be %NULL) - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @s2: another string (may be %NULL) * * Debugging macro to compare two strings. If the comparison fails, @@ -8791,7 +9065,8 @@ /** * g_assert_cmpuint: * @n1: an unsigned integer - * @cmp: The comparison operator to use. One of ==, !=, <, >, <=, >=. + * @cmp: The comparison operator to use. + * One of ==, !=, <, >, <=, >=. * @n2: another unsigned integer * * Debugging macro to compare two unsigned integers. @@ -9087,7 +9362,9 @@ * * Increases the reference count of the asynchronous @queue by 1. * - * Deprecated: 2.8: Reference counting is done atomically. 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. */ @@ -9157,7 +9434,8 @@ * To easily calculate @end_time, a combination of g_get_current_time() * and g_time_val_add() can be used. * - * Returns: data from the queue or %NULL, when no data is received before @end_time. + * Returns: data from the queue or %NULL, when no data is + * received before @end_time. * Deprecated: use g_async_queue_timeout_pop(). */ @@ -9177,7 +9455,8 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is received before @end_time. + * Returns: data from the queue or %NULL, when no data is + * received before @end_time. * Deprecated: use g_async_queue_timeout_pop_unlocked(). */ @@ -9192,7 +9471,8 @@ * * If no data is received before the timeout, %NULL is returned. * - * Returns: data from the queue or %NULL, when no data is received before the timeout. + * Returns: data from the queue or %NULL, when no data is + * received before the timeout. */ @@ -9208,7 +9488,8 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is received before the timeout. + * Returns: data from the queue or %NULL, when no data is + * received before the timeout. */ @@ -9219,7 +9500,8 @@ * Tries to pop data from the @queue. If no data is available, * %NULL is returned. * - * Returns: data from the queue or %NULL, when no data is available immediately. + * Returns: data from the queue or %NULL, when no data is + * available immediately. */ @@ -9232,7 +9514,8 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is available immediately. + * Returns: data from the queue or %NULL, when no data is + * available immediately. */ @@ -9270,7 +9553,9 @@ * the @queue's lock. If the reference count went to 0, the @queue * will be destroyed and the memory allocated will be freed. * - * Deprecated: 2.8: Reference counting is done atomically. 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. */ @@ -9611,20 +9896,25 @@ * that the returned binary data is not necessarily zero-terminated, * so it should not be used as a character string. * - * 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(). + * 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 */ /** * g_base64_decode_inplace: - * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated string with base64 text to decode + * @text: (inout) (array length=out_len) (element-type guint8): zero-terminated + * string with base64 text to decode * @out_len: (inout): The length of the decoded data is written here * * Decode a sequence of Base-64 encoded text into binary data * by overwriting the input data. * - * Returns: (transfer none): The binary data that @text responds. This pointer is the same as the input @text. + * Returns: (transfer none): The binary data that @text responds. This pointer + * is the same as the input @text. * Since: 2.20 */ @@ -9659,7 +9949,9 @@ * Encode a sequence of binary data into its Base-64 stringified * representation. * - * Returns: (transfer full): a newly allocated, zero-terminated Base-64 encoded string representing @data. The returned string must be freed with g_free(). + * 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 */ @@ -9724,8 +10016,12 @@ * components. It returns a pointer into the given file name * string. * - * 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. + * 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. */ @@ -9836,7 +10132,8 @@ * g_bookmark_file_add_application: * @bookmark: a #GBookmarkFile * @uri: a valid URI - * @name: (allow-none): the name of the application registering the bookmark or %NULL + * @name: (allow-none): the name of the application registering the bookmark + * or %NULL * @exec: (allow-none): command line to be used to launch the bookmark or %NULL * * Adds the application with @name and @exec to the list of @@ -9949,7 +10246,8 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.12 */ @@ -9965,7 +10263,8 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified URI cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * URI cannot be found. * Since: 2.12 */ @@ -9985,7 +10284,8 @@ * The returned array is %NULL terminated, so @length may optionally * be %NULL. * - * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of group names. + * Use g_strfreev() to free it. * Since: 2.12 */ @@ -10003,7 +10303,8 @@ * In the event the URI cannot be found, %FALSE is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: %TRUE if the icon for the bookmark for the URI was found. You should free the returned strings. + * Returns: %TRUE if the icon for the bookmark for the URI was found. + * You should free the returned strings. * Since: 2.12 */ @@ -10039,7 +10340,8 @@ * event that the MIME type cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. * - * Returns: a newly allocated string or %NULL if the specified URI cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * URI cannot be found. * Since: 2.12 */ @@ -10084,7 +10386,8 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified URI cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * URI cannot be found. * Since: 2.12 */ @@ -10098,7 +10401,8 @@ * The array of returned URIs will be %NULL-terminated, so @length may * optionally be %NULL. * - * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array length=length) (transfer full): a newly allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.12 */ @@ -10187,7 +10491,8 @@ * g_bookmark_file_load_from_data_dirs: * @bookmark: a #GBookmarkFile * @file: a relative path to a filename to open and parse - * @full_path: (allow-none): return location for a string containing the full path of the file, or %NULL + * @full_path: (allow-none): return location for a string containing the full path + * of the file, or %NULL * @error: return location for a #GError, or %NULL * * This function looks for a desktop bookmark file named @file in the @@ -10356,7 +10661,8 @@ * #G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED. Otherwise, if no bookmark * for @uri is found, one is created. * - * Returns: %TRUE if the application's meta-data was successfully changed. + * Returns: %TRUE if the application's meta-data was successfully + * changed. * Since: 2.12 */ @@ -10502,7 +10808,8 @@ * * This function outputs @bookmark as a string. * - * Returns: a newly allocated string holding the contents of the #GBookmarkFile + * Returns: a newly allocated string holding + * the contents of the #GBookmarkFile * Since: 2.12 */ @@ -10635,7 +10942,8 @@ * @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(). + * Returns: the element data if @free_segment is %FALSE, otherwise + * %NULL. The element data should be freed using g_free(). */ @@ -10653,7 +10961,8 @@ * together. * * Since: 2.32 - * Returns: (transfer full): a new immutable #GBytes representing same byte data that was in the array + * Returns: (transfer full): a new immutable #GBytes representing same byte + * data that was in the array */ @@ -10819,7 +11128,8 @@ * * This function can be used to sort GBytes instances in lexographical order. * - * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is greater, and zero if bytes2 is equal to bytes1 + * 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 */ @@ -10849,7 +11159,8 @@ * * This function will always return the same pointer for a given #GBytes. * - * Returns: (transfer none) (array length=size) (type guint8): a pointer to the byte data + * Returns: (transfer none) (array length=size) (type guint8): a pointer to the + * byte data * Since: 2.32 */ @@ -10883,7 +11194,8 @@ /** * g_bytes_new: - * @data: (transfer none) (array length=size) (element-type guint8): the data to be used for the bytes + * @data: (transfer none) (array length=size) (element-type guint8): + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. @@ -10914,7 +11226,8 @@ /** * g_bytes_new_static: (skip) - * @data: (transfer full) (array length=size) (element-type guint8): the data to be used for the bytes + * @data: (transfer full) (array length=size) (element-type guint8): + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from static data. @@ -10928,7 +11241,8 @@ /** * g_bytes_new_take: - * @data: (transfer full) (array length=size) (element-type guint8): the data to be used for the bytes + * @data: (transfer full) (array length=size) (element-type guint8): + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. @@ -11019,7 +11333,8 @@ * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the * data is copied. * - * Returns: (transfer full): a pointer to the same byte data, which should be freed with g_free() + * Returns: (transfer full): a pointer to the same byte data, which should + * be freed with g_free() * Since: 2.32 */ @@ -11046,7 +11361,8 @@ * g_checksum_get_string() or g_checksum_get_digest(), the copied * checksum will be closed as well. * - * Returns: the copy of the passed #GChecksum. Use g_checksum_free() when finished using it. + * Returns: the copy of the passed #GChecksum. Use g_checksum_free() + * when finished using it. * Since: 2.16 */ @@ -11065,7 +11381,8 @@ * g_checksum_get_digest: (skip) * @checksum: a #GChecksum * @buffer: output buffer - * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest. + * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. + * After the call it contains the length of the digest. * * Gets the digest from @checksum as a raw binary vector and places it * into @buffer. The size of the digest depends on the type of checksum. @@ -11088,7 +11405,9 @@ * * The hexadecimal characters will be lower case. * - * Returns: the hexadecimal representation of the checksum. The returned string is owned by the checksum and should not be modified or freed. + * 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 */ @@ -11111,7 +11430,8 @@ * will be closed and it won't be possible to call g_checksum_update() * on it anymore. * - * Returns: (transfer full): the newly created #GChecksum, or %NULL. Use g_checksum_free() to free the memory allocated by it. + * Returns: (transfer full): the newly created #GChecksum, or %NULL. + * Use g_checksum_free() to free the memory allocated by it. * Since: 2.16 */ @@ -11132,7 +11452,8 @@ * * Gets the length in bytes of digests of type @checksum_type * - * Returns: the checksum length, or -1 if @checksum_type is not supported. + * Returns: the checksum length, or -1 if @checksum_type is + * not supported. * Since: 2.16 */ @@ -11153,7 +11474,8 @@ /** * g_child_watch_add: - * @pid: process id to watch. On POSIX the pid of a child process. On Windows a handle for a process (which doesn't have to be a child). + * @pid: process id to watch. On POSIX the pid of a child process. On + * Windows a handle for a process (which doesn't have to be a child). * @function: function to call * @data: data to pass to @function * @@ -11183,8 +11505,10 @@ /** * g_child_watch_add_full: (rename-to g_child_watch_add) - * @priority: the priority of the idle source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. - * @pid: process to watch. On POSIX the pid of a child process. On Windows a handle for a process (which doesn't have to be a child). + * @priority: the priority of the idle source. Typically this will be in the + * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + * @pid: process to watch. On POSIX the pid of a child process. On + * Windows a handle for a process (which doesn't have to be a child). * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the idle is removed, or %NULL @@ -11219,7 +11543,8 @@ /** * g_child_watch_source_new: - * @pid: process to watch. On POSIX the pid of a child process. On Windows a handle for a process (which doesn't have to be a child). + * @pid: process to watch. On POSIX the pid of a child process. On + * Windows a handle for a process (which doesn't have to be a child). * * Creates a new child_watch source. * @@ -11327,7 +11652,8 @@ * * The hexadecimal string returned will be in lower case. * - * 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. + * 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.34 */ @@ -11344,7 +11670,8 @@ * * The hexadecimal string returned will be in lower case. * - * 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. + * 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 */ @@ -11359,7 +11686,8 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the checksum as a hexadecimal string. The returned string should be freed with g_free() when done using it. + * Returns: the checksum as a hexadecimal string. The returned string + * should be freed with g_free() when done using it. * Since: 2.16 */ @@ -11378,7 +11706,8 @@ * * The hexadecimal string returned will be in lower case. * - * 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. + * 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 */ @@ -11395,7 +11724,9 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the HMAC as a hexadecimal string. The returned string should be freed with g_free() when done using it. + * Returns: the HMAC as a hexadecimal string. + * The returned string should be freed with g_free() + * when done using it. * Since: 2.30 */ @@ -11543,32 +11874,61 @@ /** * g_convert: * @str: the string to convert - * @len: the length of the string, or -1 if the string is nul-terminated<footnote id="nul-unsafe"> <para> Note that some encodings may allow nul bytes to occur inside strings. In that case, using -1 for the @len parameter is unsafe. </para> </footnote>. + * @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. - * @bytes_written: (out): 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. + * @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. + * @bytes_written: (out): 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. * * Converts a string from one character set to another. * * Note that you should use g_iconv() for streaming * conversions<footnoteref linkend="streaming-state"/>. * - * 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. + * 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. */ /** * g_convert_with_fallback: * @str: the string to convert - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. + * @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). 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. + * @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. * * Converts a string from one character set to another, possibly * including fallback sequences for characters not representable @@ -11581,18 +11941,30 @@ * Note that you should use g_iconv() for streaming * conversions<footnoteref linkend="streaming-state"/>. * - * 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. + * 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. */ /** * g_convert_with_iconv: * @str: the string to convert - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. + * @len: the length of the string, or -1 if the string is + * nul-terminated<footnoteref linkend="nul-unsafe"/>. * @converter: conversion descriptor from g_iconv_open() - * @bytes_read: location to store the number of bytes in the input string that were successfully converted, or %NULL. 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. - * @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. + * @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. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @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. * * Converts a string from one character set to another. * @@ -11611,7 +11983,9 @@ * </para> * </footnote>. * - * 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. + * 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. */ @@ -11640,14 +12014,16 @@ * * See your C library manual for more details about creat(). * - * Returns: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from creat(). + * Returns: a new file descriptor, or -1 if an error occurred. The + * return value can be used exactly like the return value from creat(). * Since: 2.8 */ /** * g_critical: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). * It's more or less application-defined what constitutes @@ -11732,7 +12108,9 @@ * This function can be useful to avoid races when multiple * threads are using the same datalist and the same key. * - * Returns: the result of calling @dup_func on the value associated with @key_id in @datalist, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. + * Returns: the result of calling @dup_func on the value + * associated with @key_id in @datalist, or %NULL if not set. + * If @dup_func is %NULL, the value is returned unmodified. * Since: 2.34 */ @@ -11792,7 +12170,8 @@ * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * - * Returns: %TRUE if the existing value for @key_id was replaced by @newval, %FALSE otherwise. + * Returns: %TRUE if the existing value for @key_id was replaced + * by @newval, %FALSE otherwise. * Since: 2.34 */ @@ -11801,7 +12180,8 @@ * g_datalist_id_set_data: * @dl: a datalist. * @q: the #GQuark to identify the data element. - * @d: (allow-none): the data element, or %NULL to remove any previous element corresponding to @q. + * @d: (allow-none): the data element, or %NULL to remove any previous element + * corresponding to @q. * * Sets the data corresponding to the given #GQuark id. Any previous * data with the same key is removed, and its destroy function is @@ -11813,8 +12193,13 @@ * g_datalist_id_set_data_full: * @datalist: a datalist. * @key_id: the #GQuark to identify the data element. - * @data: (allow-none): the data element or %NULL to remove any previous element corresponding to @key_id. - * @destroy_func: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @data is %NULL, then @destroy_func must also be %NULL. + * @data: (allow-none): the data element or %NULL to remove any previous element + * corresponding to @key_id. + * @destroy_func: the function to call when the data element is + * removed. This function will be called with the data + * element and can be used to free any memory allocated + * for it. If @data is %NULL, then @destroy_func must + * also be %NULL. * * Sets the data corresponding to the given #GQuark id, and the * function to be called when the element is removed from the datalist. @@ -11855,7 +12240,8 @@ * g_datalist_set_data: * @dl: a datalist. * @k: the string to identify the data element. - * @d: (allow-none): the data element, or %NULL to remove any previous element corresponding to @k. + * @d: (allow-none): the data element, or %NULL to remove any previous element + * corresponding to @k. * * Sets the data element corresponding to the given string identifier. */ @@ -11865,8 +12251,12 @@ * g_datalist_set_data_full: * @dl: a datalist. * @k: the string to identify the data element. - * @d: (allow-none): the data element, or %NULL to remove any previous element corresponding to @k. - * @f: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. If @d is %NULL, then @f must also be %NULL. + * @d: (allow-none): the data element, or %NULL to remove any previous element + * corresponding to @k. + * @f: the function to call when the data element is removed. This + * function will be called with the data element and can be used to + * free any memory allocated for it. If @d is %NULL, then @f must + * also be %NULL. * * Sets the data element corresponding to the given string identifier, * and the function to be called when the data element is removed. @@ -11876,7 +12266,11 @@ /** * g_datalist_set_flags: * @datalist: pointer to the location that holds a list - * @flags: the flags to turn on. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3; giving two possible boolean flags). A value for @flags that doesn't fit within the mask is an error. + * @flags: the flags to turn on. The values of the flags are + * restricted by %G_DATALIST_FLAGS_MASK (currently + * 3; giving two possible boolean flags). + * A value for @flags that doesn't fit within the mask is + * an error. * * Turns on flag values for a data list. This function is used * to keep a small number of boolean flags in an object with @@ -11892,7 +12286,11 @@ /** * g_datalist_unset_flags: * @datalist: pointer to the location that holds a list - * @flags: the flags to turn off. The values of the flags are restricted by %G_DATALIST_FLAGS_MASK (currently 3: giving two possible boolean flags). A value for @flags that doesn't fit within the mask is an error. + * @flags: the flags to turn off. The values of the flags are + * restricted by %G_DATALIST_FLAGS_MASK (currently + * 3: giving two possible boolean flags). + * A value for @flags that doesn't fit within the mask is + * an error. * * Turns off flag values for a data list. See g_datalist_unset_flags() * @@ -11929,7 +12327,8 @@ * * Gets the data element corresponding to a string. * - * Returns: the data element corresponding to the string, or %NULL if it is not found. + * Returns: the data element corresponding to the string, or %NULL if + * it is not found. */ @@ -11940,7 +12339,8 @@ * * Gets the data element corresponding to a #GQuark. * - * Returns: the data element corresponding to the #GQuark, or %NULL if it is not found. + * Returns: the data element corresponding to the #GQuark, or %NULL if + * it is not found. */ @@ -11983,7 +12383,10 @@ * @dataset_location: the location identifying the dataset. * @key_id: the #GQuark id to identify the data element. * @data: the data element. - * @destroy_func: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. + * @destroy_func: the function to call when the data element is + * removed. This function will be called with the data + * element and can be used to free any memory allocated + * for it. * * Sets the data element associated with the given #GQuark id, and also * the function to call when the data element is destroyed. Any @@ -12026,7 +12429,9 @@ * @l: the location identifying the dataset. * @k: the string to identify the data element. * @d: the data element. - * @f: the function to call when the data element is removed. This function will be called with the data element and can be used to free any memory allocated for it. + * @f: the function to call when the data element is removed. This + * function will be called with the data element and can be used to + * free any memory allocated for it. * * Sets the data corresponding to the given string identifier, and the * function to call when the data element is destroyed. @@ -12103,7 +12508,8 @@ * qsort()-style comparison function for dates. * Both dates must be valid. * - * Returns: 0 for equal, less than zero if @lhs is less than @rhs, greater than zero if @lhs is greater than @rhs + * Returns: 0 for equal, less than zero if @lhs is less than @rhs, + * greater than zero if @lhs is greater than @rhs */ @@ -12542,7 +12948,8 @@ * * Creates a copy of @datetime and adds the specified timespan to the copy. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12555,7 +12962,8 @@ * Creates a copy of @datetime and adds the specified number of days to the * copy. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12573,7 +12981,8 @@ * Creates a new #GDateTime adding the specified values to the current date and * time in @datetime. * - * Returns: the newly created #GDateTime that should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime that should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12585,7 +12994,8 @@ * * Creates a copy of @datetime and adds the specified number of hours * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12597,7 +13007,8 @@ * * Creates a copy of @datetime adding the specified number of minutes. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12610,7 +13021,8 @@ * Creates a copy of @datetime and adds the specified number of months to the * copy. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12622,7 +13034,8 @@ * * Creates a copy of @datetime and adds the specified number of seconds. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12635,7 +13048,8 @@ * Creates a copy of @datetime and adds the specified number of weeks to the * copy. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12648,7 +13062,8 @@ * Creates a copy of @datetime and adds the specified number of years to the * copy. * - * Returns: the newly created #GDateTime which should be freed with g_date_time_unref(). + * Returns: the newly created #GDateTime which should be freed with + * g_date_time_unref(). * Since: 2.26 */ @@ -12661,7 +13076,8 @@ * A comparison function for #GDateTimes that is suitable * as a #GCompareFunc. Both #GDateTimes must be non-%NULL. * - * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater than @dt2. + * Returns: -1, 0 or 1 if @dt1 is less than, equal to or greater + * than @dt2. * Since: 2.26 */ @@ -12675,7 +13091,8 @@ * #GTimeSpan that is returned is effectively @end - @begin (ie: * positive if the first parameter is larger). * - * Returns: the difference between the two #GDateTime, as a time span expressed in microseconds. + * Returns: the difference between the two #GDateTime, as a time + * span expressed in microseconds. * Since: 2.26 */ @@ -12698,7 +13115,8 @@ /** * g_date_time_format: * @datetime: A #GDateTime - * @format: a valid UTF-8 string, containing the format for the #GDateTime + * @format: a valid UTF-8 string, containing the format for the + * #GDateTime * * Creates a newly allocated string representing the requested @format. * @@ -12972,7 +13390,9 @@ * </varlistentry> * </variablelist> * - * 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(). + * 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 */ @@ -13092,7 +13512,9 @@ * months and "EDT" during the summer months when daylight savings * time is in effect. * - * Returns: (transfer none): the time zone abbreviation. The returned string is owned by the #GDateTime and it should not be modified or freed + * 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 */ @@ -13110,7 +13532,8 @@ * * If @datetime represents UTC time, then the offset is always zero. * - * Returns: the number of microseconds that should be added to UTC to get the local time + * Returns: the number of microseconds that should be added to UTC to + * get the local time * Since: 2.26 */ @@ -13649,7 +14072,8 @@ /** * g_dcgettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @msgid: message to translate * @category: a locale category * @@ -13665,7 +14089,8 @@ /** * g_debug: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * A convenience function/macro to log a debug message. * @@ -13675,7 +14100,8 @@ /** * g_dgettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @msgid: message to translate * * This function is a wrapper of dgettext() which does not translate @@ -13724,7 +14150,8 @@ /** * g_dir_make_tmp: - * @tmpl: (type filename) (allow-none): Template for directory name, as in g_mkdtemp(), basename only, or %NULL for a default template + * @tmpl: (type filename) (allow-none): Template for directory name, + * as in g_mkdtemp(), basename only, or %NULL for a default template * @error: return location for a #GError * * Creates a subdirectory in the preferred directory for temporary @@ -13739,22 +14166,30 @@ * Note that in contrast to g_mkdtemp() (and mkdtemp()) @tmpl is not * modified, and might thus be a read-only literal 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. + * 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 */ /** * g_dir_open: - * @path: the path to the directory you are interested in. On Unix in the on-disk encoding. On Windows in UTF-8 + * @path: the path to the directory you are interested in. On Unix + * in the on-disk encoding. On Windows in UTF-8 * @flags: Currently must be set to 0. Reserved for future use. - * @error: return location for a #GError, or %NULL. If non-%NULL, an error will be set if and only if g_dir_open() fails. + * @error: return location for a #GError, or %NULL. + * If non-%NULL, an error will be set if and only if + * g_dir_open() fails. * * Opens a directory for reading. The names of the files in the * directory can then be retrieved using g_dir_read_name(). Note * that the ordering is not defined. * - * 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. + * 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. */ @@ -13777,7 +14212,9 @@ * On Windows, as is true of all GLib functions which operate on * filenames, the returned name is in UTF-8. * - * 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. + * 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. */ @@ -13839,7 +14276,8 @@ /** * g_dngettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @msgid: message to translate * @msgid_plural: plural form of the message * @n: the quantity for which translation is needed @@ -13888,8 +14326,10 @@ /** * g_dpgettext: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() - * @msgctxtid: a combined message context and message id, separated by a \004 character + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() + * @msgctxtid: a combined message context and message id, separated + * by a \004 character * @msgidoffset: the offset of the message id in @msgctxid * * This function is a variant of g_dgettext() which supports @@ -13913,7 +14353,8 @@ /** * g_dpgettext2: - * @domain: (allow-none): the translation domain to use, or %NULL to use the domain set with textdomain() + * @domain: (allow-none): the translation domain to use, or %NULL to use + * the domain set with textdomain() * @context: the message context * @msgid: the message * @@ -13935,8 +14376,11 @@ /** * g_environ_getenv: - * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment list (eg, as returned from g_get_environ()), or %NULL for an empty environment list - * @variable: the environment variable to get, in the GLib file name encoding + * @envp: (allow-none) (array zero-terminated=1) (transfer none): an environment + * list (eg, as returned from g_get_environ()), or %NULL + * for an empty environment list + * @variable: the environment variable to get, in the GLib file name + * encoding * * Returns the value of the environment variable @variable in the * provided list @envp. @@ -13948,14 +14392,19 @@ * value contains references to other environment variables, they * are expanded. * - * 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. + * 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 */ /** * g_environ_setenv: - * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list + * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment + * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL + * for an empty environment list * @variable: the environment variable to set, must not contain '=' * @value: the value for to set the variable to * @overwrite: whether to change the variable if it already exists @@ -13967,27 +14416,32 @@ * file name encoding. On UNIX, this means that they can be * arbitrary byte strings. On Windows, they should be in UTF-8. * - * Returns: (array zero-terminated=1) (transfer full): the updated environment list. Free it using g_strfreev(). + * Returns: (array zero-terminated=1) (transfer full): the + * updated environment list. Free it using g_strfreev(). * Since: 2.32 */ /** * g_environ_unsetenv: - * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), or %NULL for an empty environment list + * @envp: (allow-none) (array zero-terminated=1) (transfer full): an environment + * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), + * or %NULL for an empty environment list * @variable: the environment variable to remove, must not contain '=' * * Removes the environment variable @variable from the provided * environment @envp. * - * Returns: (array zero-terminated=1) (transfer full): the updated environment list. Free it using g_strfreev(). + * Returns: (array zero-terminated=1) (transfer full): the + * updated environment list. Free it using g_strfreev(). * Since: 2.32 */ /** * g_error: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * A convenience function/macro to log an error message. * @@ -14095,7 +14549,8 @@ /** * g_file_get_contents: * @filename: (type filename): name of a file to read contents from, in the GLib file name encoding - * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free the returned string + * @contents: (out) (array length=length) (element-type guint8): location to store an allocated string, use g_free() to free + * the returned string * @length: (allow-none): location to store length in bytes of the contents, or %NULL * @error: return location for a #GError, or %NULL * @@ -14116,8 +14571,10 @@ /** * g_file_open_tmp: - * @tmpl: (type filename) (allow-none): Template for file name, as in g_mkstemp(), basename only, or %NULL for a default template - * @name_used: (out) (type filename): location to store actual name used, or %NULL + * @tmpl: (type filename) (allow-none): Template for file name, as in + * g_mkstemp(), basename only, or %NULL for a default template + * @name_used: (out) (type filename): location to store actual name used, + * or %NULL * @error: return location for a #GError * * Opens a file for writing in the preferred directory for temporary @@ -14137,7 +14594,10 @@ * when not needed any longer. The returned name is in the GLib file * name encoding. * - * 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. + * 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. */ @@ -14150,14 +14610,16 @@ * readlink() function. The returned string is in the encoding used * for filenames. Use g_filename_to_utf8() to convert it to UTF-8. * - * Returns: A newly-allocated string with the contents of the symbolic link, or %NULL if an error occurred. + * Returns: A newly-allocated string with the contents of the symbolic link, + * or %NULL if an error occurred. * Since: 2.4 */ /** * g_file_set_contents: - * @filename: (type filename): name of a file to write @contents to, in the GLib file name encoding + * @filename: (type filename): name of a file to write @contents to, in the GLib file name + * encoding * @contents: (array length=length) (element-type guint8): string to write to the file * @length: length of @contents, or -1 if @contents is a nul-terminated string * @error: return location for a #GError, or %NULL @@ -14270,7 +14732,8 @@ * This function is preferred over g_filename_display_name() if you know the * whole path, as it allows translation. * - * Returns: a newly allocated string containing a rendition of the basename of the filename in valid UTF-8 + * Returns: a newly allocated string containing + * a rendition of the basename of the filename in valid UTF-8 * Since: 2.6 */ @@ -14295,7 +14758,8 @@ * g_filename_display_basename(), since that allows location-based * translation of filenames. * - * Returns: a newly allocated string containing a rendition of the filename in valid UTF-8 + * Returns: a newly allocated string containing + * a rendition of the filename in valid UTF-8 * Since: 2.6 */ @@ -14303,53 +14767,82 @@ /** * g_filename_from_uri: * @uri: a uri describing a filename (escaped, encoded in ASCII). - * @hostname: (out) (allow-none): Location to store hostname for the URI, or %NULL. If there is no hostname in the URI, %NULL will be stored in this location. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @hostname: (out) (allow-none): Location to store hostname for the URI, or %NULL. + * If there is no hostname in the URI, %NULL will be + * stored in this location. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * Converts an escaped ASCII-encoded URI to a local filename in the * encoding used for filenames. * - * Returns: (type filename): a newly-allocated string holding the resulting filename, or %NULL on an error. + * Returns: (type filename): a newly-allocated string holding + * the resulting filename, or %NULL on an error. */ /** * g_filename_from_utf8: * @utf8string: a UTF-8 encoded string. - * @len: the length of the string, or -1 if the string is nul-terminated. - * @bytes_read: (out) (allow-none): 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. - * @bytes_written: (out): 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. + * @len: the length of the string, or -1 if the string is + * nul-terminated. + * @bytes_read: (out) (allow-none): 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. + * @bytes_written: (out): 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. * * Converts a string from UTF-8 to the encoding GLib uses for * filenames. Note that on Windows GLib uses UTF-8 for filenames; * on other platforms, this function indirectly depends on the * <link linkend="setlocale">current locale</link>. * - * Returns: (array length=bytes_written) (element-type guint8) (transfer full): The converted string, or %NULL on an error. + * Returns: (array length=bytes_written) (element-type guint8) (transfer full): + * The converted string, or %NULL on an error. */ /** * g_filename_to_uri: - * @filename: an absolute filename specified in the GLib file name encoding, which is the on-disk file name bytes on Unix, and UTF-8 on Windows + * @filename: an absolute filename specified in the GLib file name encoding, + * which is the on-disk file name bytes on Unix, and UTF-8 on + * Windows * @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError may occur. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError may occur. * * Converts an absolute filename to an escaped ASCII-encoded URI, with the path * component following Section 3.3. of RFC 2396. * - * Returns: a newly-allocated string holding the resulting URI, or %NULL on an error. + * Returns: a newly-allocated string holding the resulting + * URI, or %NULL on an error. */ /** * g_filename_to_utf8: * @opsysstring: a string in the encoding for filenames - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. - * @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. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @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. + * @len: the length of the string, or -1 if the string is + * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * @bytes_read: location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * 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. + * @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. * * Converts a string which is in the encoding used by GLib for * filenames into a UTF-8 string. Note that on Windows GLib uses UTF-8 @@ -14369,7 +14862,7 @@ * with the absolute path name, or %NULL if the program is not found in * the path. If @program is already an absolute path, returns a copy of * @program if @program exists and is executable, and %NULL otherwise. - * + * * On Windows, if @program does not have a file type suffix, tries * with the suffixes .exe, .cmd, .bat and .com, and the suffixes in * the <envar>PATHEXT</envar> environment variable. @@ -14389,7 +14882,8 @@ /** * g_fopen: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @mode: a string describing the mode in which the file should be opened + * @mode: a string describing the mode in which the file should be + * opened * * A wrapper for the stdio fopen() function. The fopen() function * opens a file and associates a new stream with it. @@ -14404,7 +14898,8 @@ * * See your C library manual for more details about fopen(). * - * Returns: A <type>FILE</type> pointer if the file was successfully opened, or %NULL if an error occurred + * Returns: A <type>FILE</type> pointer if the file was successfully + * opened, or %NULL if an error occurred * Since: 2.6 */ @@ -14425,7 +14920,8 @@ * See g_format_size_full() for more options about how the size might be * formatted. * - * Returns: a newly-allocated formatted string containing a human readable file size + * Returns: a newly-allocated formatted string containing a human readable + * file size * Since: 2.30 */ @@ -14444,9 +14940,11 @@ * * This string should be freed with g_free() when not needed any longer. * - * Returns: a newly-allocated formatted string containing a human readable file size + * 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. + * Deprecated: 2.30: This function is broken due to its use of SI + * suffixes to denote IEC units. Use g_format_size() instead. */ @@ -14460,7 +14958,8 @@ * This function is similar to g_format_size() but allows for flags * that modify the output. See #GFormatSizeFlags. * - * Returns: a newly-allocated formatted string containing a human readable file size + * Returns: a newly-allocated formatted string containing a human + * readable file size * Since: 2.30 */ @@ -14468,7 +14967,8 @@ /** * g_fprintf: * @file: the stream to write to. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @...: the arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -14491,7 +14991,8 @@ /** * g_freopen: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @mode: a string describing the mode in which the file should be opened + * @mode: a string describing the mode in which the file should be + * opened * @stream: (allow-none): an existing stream which will be reused, or %NULL * * A wrapper for the POSIX freopen() function. The freopen() function @@ -14499,7 +15000,8 @@ * * See your C library manual for more details about freopen(). * - * Returns: A <literal>FILE</literal> pointer if the file was successfully opened, or %NULL if an error occurred. + * Returns: A <literal>FILE</literal> pointer if the file was successfully + * opened, or %NULL if an error occurred. * Since: 2.6 */ @@ -14551,7 +15053,8 @@ * * Gets the character set for the current locale. * - * Returns: a newly allocated string containing the name of the character set. This string must be freed with g_free(). + * Returns: a newly allocated string containing the name + * of the character set. This string must be freed with g_free(). */ @@ -14592,7 +15095,8 @@ * The return value is freshly allocated and it should be freed with * g_strfreev() when it is no longer needed. * - * Returns: (array zero-terminated=1) (transfer full): the list of environment variables + * Returns: (array zero-terminated=1) (transfer full): the list of + * environment variables * Since: 2.28 */ @@ -14701,7 +15205,8 @@ * <envar>LC_ALL</envar>, <envar>LC_MESSAGES</envar> and <envar>LANG</envar> * to find the list of locales specified by the user. * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed. + * 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 */ @@ -14721,7 +15226,9 @@ * If you need the list of variants for the <emphasis>current locale</emphasis>, * use g_get_language_names(). * - * 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(). + * 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 */ @@ -14773,7 +15280,8 @@ * which is called by gtk_init(). The program name is found by taking * the last component of <literal>argv[0]</literal>.) * - * Returns: the name of the program. The returned string belongs to GLib and must not be modified or freed. + * Returns: the name of the program. The returned string belongs + * to GLib and must not be modified or freed. */ @@ -14826,7 +15334,8 @@ * 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. * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed. + * 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 */ @@ -14864,7 +15373,8 @@ * Note that on Windows the returned list can vary depending on where * this function is called. * - * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must not be modified or freed. + * 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 */ @@ -14906,7 +15416,8 @@ * C:\Documents and Settings\username\Local Settings\Temporary Internet Files. * See documentation for CSIDL_INTERNET_CACHE. * - * Returns: a string owned by GLib that must not be modified or freed. + * Returns: a string owned by GLib that must not be modified + * or freed. * Since: 2.6 */ @@ -14927,7 +15438,8 @@ * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as * what g_get_user_data_dir() returns. * - * Returns: a string owned by GLib that must not be modified or freed. + * Returns: a string owned by GLib that must not be modified + * or freed. * Since: 2.6 */ @@ -14948,7 +15460,8 @@ * CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as * what g_get_user_config_dir() returns. * - * Returns: a string owned by GLib that must not be modified or freed. + * Returns: a string owned by GLib that must not be modified + * or freed. * Since: 2.6 */ @@ -15003,14 +15516,17 @@ * of the special directory without requiring the session to restart; GLib * will not reflect any change once the special directories are loaded. * - * 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. + * 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 */ /** * g_getenv: - * @variable: the environment variable to get, in the GLib file name encoding + * @variable: the environment variable to get, in the GLib file name + * encoding * * Returns the value of an environment variable. * @@ -15020,7 +15536,10 @@ * On Windows, in case the environment variable's value contains * references to other environment variables, they are expanded. * - * 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(). + * 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(). */ @@ -15085,7 +15604,9 @@ * (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). * - * 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. + * 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 */ @@ -15161,7 +15682,10 @@ * Retrieves every key inside @hash_table. The returned data is valid * until changes to the hash release those keys. * - * 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. + * 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 */ @@ -15173,7 +15697,10 @@ * Retrieves every value inside @hash_table. The returned data * is valid until @hash_table is modified. * - * 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. + * 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 */ @@ -15354,8 +15881,12 @@ * g_hash_table_new_full: * @hash_func: a function to create a hash value from a key * @key_equal_func: a function to check two keys for equality - * @key_destroy_func: (allow-none): a function to free the memory allocated for the key used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. - * @value_destroy_func: (allow-none): a function to free the memory allocated for the value used when removing the entry from the #GHashTable, or %NULL if you don't want to supply such a function. + * @key_destroy_func: (allow-none): a function to free the memory allocated for the key + * used when removing the entry from the #GHashTable, or %NULL + * if you don't want to supply such a function. + * @value_destroy_func: (allow-none): a function to free the memory allocated for the + * value used when removing the entry from the #GHashTable, or %NULL + * if you don't want to supply such a function. * * Creates a new #GHashTable like g_hash_table_new() with a reference * count of 1 and allows to specify functions to free the memory @@ -15488,7 +16019,8 @@ * g_hmac_get_string() or g_hmac_get_digest(), the copied * HMAC will be closed as well. * - * Returns: the copy of the passed #GHmac. Use g_hmac_unref() when finished using it. + * Returns: the copy of the passed #GHmac. Use g_hmac_unref() + * when finished using it. * Since: 2.30 */ @@ -15497,7 +16029,8 @@ * g_hmac_get_digest: * @hmac: a #GHmac * @buffer: output buffer - * @digest_len: an inout parameter. The caller initializes it to the size of @buffer. After the call it contains the length of the digest + * @digest_len: an inout parameter. The caller initializes it to the + * size of @buffer. After the call it contains the length of the digest * * Gets the digest from @checksum as a raw binary array and places it * into @buffer. The size of the digest depends on the type of checksum. @@ -15520,7 +16053,9 @@ * * The hexadecimal characters will be lower case. * - * Returns: the hexadecimal representation of the HMAC. The returned string is owned by the HMAC and should not be modified or freed. + * 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 */ @@ -15545,7 +16080,8 @@ * will be closed and it won't be possible to call g_hmac_update() * on it anymore. * - * Returns: the newly created #GHmac, or %NULL. Use g_hmac_unref() to free the memory allocated by it. + * Returns: the newly created #GHmac, or %NULL. + * Use g_hmac_unref() to free the memory allocated by it. * Since: 2.30 */ @@ -15648,8 +16184,10 @@ /** * g_hook_find: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped - * @func: the function to call for each #GHook, which should return %TRUE when the #GHook has been found + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped + * @func: the function to call for each #GHook, which should return + * %TRUE when the #GHook has been found * @data: the data to pass to @func * * Finds a #GHook in a #GHookList using the given function to @@ -15662,44 +16200,52 @@ /** * g_hook_find_data: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped * @data: the data to find * * Finds a #GHook in a #GHookList with the given data. * - * Returns: the #GHook with the given @data or %NULL if no matching #GHook is found + * Returns: the #GHook with the given @data or %NULL if no matching + * #GHook is found */ /** * g_hook_find_func: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped * @func: the function to find * * Finds a #GHook in a #GHookList with the given function. * - * Returns: the #GHook with the given @func or %NULL if no matching #GHook is found + * Returns: the #GHook with the given @func or %NULL if no matching + * #GHook is found */ /** * g_hook_find_func_data: * @hook_list: a #GHookList - * @need_valids: %TRUE if #GHook elements which have been destroyed should be skipped + * @need_valids: %TRUE if #GHook elements which have been destroyed + * should be skipped * @func: the function to find * @data: the data to find * * Finds a #GHook in a #GHookList with the given function and data. * - * Returns: the #GHook with the given @func and @data or %NULL if no matching #GHook is found + * Returns: the #GHook with the given @func and @data or %NULL if + * no matching #GHook is found */ /** * g_hook_first_valid: * @hook_list: a #GHookList - * @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_be_in_call: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * * Returns the first #GHook in a #GHookList which has not been destroyed. * The reference count for the #GHook is incremented, so you must call @@ -15762,7 +16308,8 @@ /** * g_hook_list_init: * @hook_list: a #GHookList - * @hook_size: the size of each element in the #GHookList, typically <literal>sizeof (GHook)</literal> + * @hook_size: the size of each element in the #GHookList, + * typically <literal>sizeof (GHook)</literal> * * Initializes a #GHookList. * This must be called before the #GHookList is used. @@ -15772,7 +16319,9 @@ /** * g_hook_list_invoke: * @hook_list: a #GHookList - * @may_recurse: %TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if functions which are already running + * (e.g. in another thread) can be called. If set to %FALSE, + * these are skipped * * Calls all of the #GHook functions in a #GHookList. */ @@ -15781,7 +16330,9 @@ /** * g_hook_list_invoke_check: * @hook_list: a #GHookList - * @may_recurse: %TRUE if functions which are already running (e.g. in another thread) can be called. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if functions which are already running + * (e.g. in another thread) can be called. If set to %FALSE, + * these are skipped * * Calls all of the #GHook functions in a #GHookList. * Any function which returns %FALSE is removed from the #GHookList. @@ -15791,7 +16342,9 @@ /** * g_hook_list_marshal: * @hook_list: a #GHookList - * @may_recurse: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * @marshaller: the function to call for each #GHook * @marshal_data: data to pass to @marshaller * @@ -15802,7 +16355,9 @@ /** * g_hook_list_marshal_check: * @hook_list: a #GHookList - * @may_recurse: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_recurse: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * @marshaller: the function to call for each #GHook * @marshal_data: data to pass to @marshaller * @@ -15815,7 +16370,9 @@ * g_hook_next_valid: * @hook_list: a #GHookList * @hook: the current #GHook - * @may_be_in_call: %TRUE if hooks which are currently running (e.g. in another thread) are considered valid. If set to %FALSE, these are skipped + * @may_be_in_call: %TRUE if hooks which are currently running + * (e.g. in another thread) are considered valid. If set to %FALSE, + * these are skipped * * Returns the next #GHook in a #GHookList which has not been destroyed. * The reference count for the #GHook is incremented, so you must call @@ -15870,7 +16427,8 @@ * 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. * - * Returns: %TRUE if @hostname contains any ASCII-encoded segments. + * Returns: %TRUE if @hostname contains any ASCII-encoded + * segments. * Since: 2.22 */ @@ -15912,7 +16470,8 @@ * string containing no uppercase letters and not ending with a * trailing dot. * - * Returns: an ASCII hostname, which must be freed, or %NULL if @hostname is in some way invalid. + * Returns: an ASCII hostname, which must be freed, or %NULL if + * @hostname is in some way invalid. * Since: 2.22 */ @@ -15929,7 +16488,8 @@ * Of course if @hostname is not an internationalized hostname, then * the canonical presentation form will be entirely ASCII. * - * Returns: a UTF-8 hostname, which must be freed, or %NULL if @hostname is in some way invalid. + * Returns: a UTF-8 hostname, which must be freed, or %NULL if + * @hostname is in some way invalid. * Since: 2.22 */ @@ -16002,7 +16562,8 @@ * GLib provides g_convert() and g_locale_to_utf8() which are likely * more convenient than the raw iconv wrappers. * - * Returns: a "conversion descriptor", or (GIConv)-1 if opening the converter failed. + * Returns: a "conversion descriptor", or (GIConv)-1 if + * opening the converter failed. */ @@ -16027,7 +16588,8 @@ /** * g_idle_add_full: (rename-to g_idle_add) - * @priority: the priority of the idle source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + * @priority: the priority of the idle source. Typically this will be in the + * range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the idle is removed, or %NULL @@ -16214,7 +16776,8 @@ * * Converts an <literal>errno</literal> error number to a #GIOChannelError. * - * Returns: a #GIOChannelError error number, e.g. %G_IO_CHANNEL_ERROR_INVAL. + * Returns: a #GIOChannelError error number, e.g. + * %G_IO_CHANNEL_ERROR_INVAL. */ @@ -16232,7 +16795,9 @@ * * Flushes the write buffer for the GIOChannel. * - * Returns: the status of the operation: One of #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or #G_IO_STATUS_ERROR. + * Returns: the status of the operation: One of + * #G_IO_STATUS_NORMAL, #G_IO_STATUS_AGAIN, or + * #G_IO_STATUS_ERROR. */ @@ -16277,7 +16842,8 @@ * destroyed. The default value of this is %TRUE for channels created * by g_io_channel_new_file (), and %FALSE for all other channels. * - * Returns: Whether the channel will be closed on the final unref of the GIOChannel data structure. + * Returns: Whether the channel will be closed on the final unref of + * the GIOChannel data structure. */ @@ -16289,7 +16855,8 @@ * The internal encoding is always UTF-8. The encoding %NULL * makes the channel safe for binary data. * - * Returns: A string containing the encoding, this string is owned by GLib and must not be freed. + * Returns: A string containing the encoding, this string is + * owned by GLib and must not be freed. */ @@ -16320,7 +16887,8 @@ * where in the file a line break occurs. A value of %NULL * indicates autodetection. * - * Returns: The line termination string. This value is owned by GLib and must not be freed. + * Returns: The line termination string. This value + * is owned by GLib and must not be freed. */ @@ -16339,7 +16907,8 @@ /** * g_io_channel_new_file: * @filename: A string containing the name of a file - * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have the same meaning as in fopen() + * @mode: One of "r", "w", "a", "r+", "w+", "a+". These have + * the same meaning as in fopen() * @error: A location to return an error of type %G_FILE_ERROR * * Open a file @filename as a #GIOChannel using mode @mode. This @@ -16355,7 +16924,8 @@ /** * g_io_channel_read: * @channel: a #GIOChannel - * @buf: a buffer to read the data into (which should be at least count bytes long) + * @buf: a buffer to read the data into (which should be at least + * count bytes long) * @count: the number of bytes to read from the #GIOChannel * @bytes_read: returns the number of bytes actually read * @@ -16369,10 +16939,17 @@ /** * g_io_channel_read_chars: * @channel: a #GIOChannel - * @buf: (out caller-allocates) (array length=count) (element-type guint8): a buffer to read data into - * @count: (in): the size of the buffer. Note that the buffer may not be complelely filled even if there is data in the buffer if the remaining data is not a complete character. - * @bytes_read: (allow-none) (out): The number of bytes read. This may be zero even on success if count < 6 and the channel's encoding is non-%NULL. This indicates that the next UTF-8 character is too wide for the buffer. - * @error: a location to return an error of type #GConvertError or #GIOChannelError. + * @buf: (out caller-allocates) (array length=count) (element-type guint8): + * a buffer to read data into + * @count: (in): the size of the buffer. Note that the buffer may not be + * complelely filled even if there is data in the buffer if the + * remaining data is not a complete character. + * @bytes_read: (allow-none) (out): The number of bytes read. This may be + * zero even on success if count < 6 and the channel's encoding + * is non-%NULL. This indicates that the next UTF-8 character is + * too wide for the buffer. + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError. * * Replacement for g_io_channel_read() with the new API. * @@ -16383,10 +16960,14 @@ /** * g_io_channel_read_line: * @channel: a #GIOChannel - * @str_return: (out): The line read from the #GIOChannel, including the line terminator. This data should be freed with g_free() when no longer needed. This is a nul-terminated string. If a @length of zero is returned, this will be %NULL instead. + * @str_return: (out): The line read from the #GIOChannel, including the + * line terminator. This data should be freed with g_free() + * when no longer needed. This is a nul-terminated string. + * If a @length of zero is returned, this will be %NULL instead. * @length: (allow-none) (out): location to store length of the read data, or %NULL * @terminator_pos: (allow-none) (out): location to store position of line terminator, or %NULL - * @error: A location to return an error of type #GConvertError or #GIOChannelError + * @error: A location to return an error of type #GConvertError + * or #GIOChannelError * * Reads a line, including the terminating character(s), * from a #GIOChannel into a newly-allocated string. @@ -16400,9 +16981,12 @@ /** * g_io_channel_read_line_string: * @channel: a #GIOChannel - * @buffer: a #GString into which the line will be written. If @buffer already contains data, the old data will be overwritten. + * @buffer: a #GString into which the line will be written. + * If @buffer already contains data, the old data will + * be overwritten. * @terminator_pos: (allow-none): location to store position of line terminator, or %NULL - * @error: a location to store an error of type #GConvertError or #GIOChannelError + * @error: a location to store an error of type #GConvertError + * or #GIOChannelError * * Reads a line from a #GIOChannel, using a #GString as a buffer. * @@ -16413,13 +16997,19 @@ /** * g_io_channel_read_to_end: * @channel: a #GIOChannel - * @str_return: (out) (array length=length) (element-type guint8): Location to store a pointer to a string holding the remaining data in the #GIOChannel. This data should be freed with g_free() when no longer needed. This data is terminated by an extra nul character, but there may be other nuls in the intervening data. + * @str_return: (out) (array length=length) (element-type guint8): Location to + * store a pointer to a string holding the remaining data in the + * #GIOChannel. This data should be freed with g_free() when no + * longer needed. This data is terminated by an extra nul + * character, but there may be other nuls in the intervening data. * @length: (out): location to store length of the data - * @error: location to return an error of type #GConvertError or #GIOChannelError + * @error: location to return an error of type #GConvertError + * or #GIOChannelError * * Reads all the remaining data from the file. * - * Returns: %G_IO_STATUS_NORMAL on success. This function never returns %G_IO_STATUS_EOF. + * Returns: %G_IO_STATUS_NORMAL on success. + * This function never returns %G_IO_STATUS_EOF. */ @@ -16427,7 +17017,8 @@ * g_io_channel_read_unichar: * @channel: a #GIOChannel * @thechar: (out): a location to return a character - * @error: a location to return an error of type #GConvertError or #GIOChannelError + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError * * Reads a Unicode character from @channel. * This function cannot be called on a channel with %NULL encoding. @@ -16449,8 +17040,11 @@ /** * g_io_channel_seek: * @channel: a #GIOChannel - * @offset: an offset, in bytes, which is added to the position specified by @type - * @type: the position in the file, which can be %G_SEEK_CUR (the current position), %G_SEEK_SET (the start of the file), or %G_SEEK_END (the end of the file) + * @offset: an offset, in bytes, which is added to the position specified + * by @type + * @type: the position in the file, which can be %G_SEEK_CUR (the current + * position), %G_SEEK_SET (the start of the file), or %G_SEEK_END + * (the end of the file) * * Sets the current position in the #GIOChannel, similar to the standard * library function fseek(). @@ -16464,7 +17058,10 @@ * g_io_channel_seek_position: * @channel: a #GIOChannel * @offset: The offset in bytes from the position specified by @type - * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those cases where a call to g_io_channel_set_encoding () is allowed. See the documentation for g_io_channel_set_encoding () for details. + * @type: a #GSeekType. The type %G_SEEK_CUR is only allowed in those + * cases where a call to g_io_channel_set_encoding () + * is allowed. See the documentation for + * g_io_channel_set_encoding () for details. * @error: A location to return an error of type #GIOChannelError * * Replacement for g_io_channel_seek() with the new API. @@ -16512,7 +17109,10 @@ /** * g_io_channel_set_close_on_unref: * @channel: a #GIOChannel - * @do_close: Whether to close the channel on the final unref of the GIOChannel data structure. The default value of this is %TRUE for channels created by g_io_channel_new_file (), and %FALSE for all other channels. + * @do_close: Whether to close the channel on the final unref of + * the GIOChannel data structure. The default value of + * this is %TRUE for channels created by g_io_channel_new_file (), + * and %FALSE for all other channels. * * Setting this flag to %TRUE for a channel you have already closed * can cause problems. @@ -16588,8 +17188,13 @@ /** * g_io_channel_set_line_term: * @channel: a #GIOChannel - * @line_term: (allow-none): The line termination string. Use %NULL for autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", and the Unicode paragraph separator. Autodetection should not be used for anything other than file-based channels. - * @length: The length of the termination string. If -1 is passed, the string is assumed to be nul-terminated. This option allows termination strings with embedded nuls. + * @line_term: (allow-none): The line termination string. Use %NULL for + * autodetect. Autodetection breaks on "\n", "\r\n", "\r", "\0", + * and the Unicode paragraph separator. Autodetection should not be + * used for anything other than file-based channels. + * @length: The length of the termination string. If -1 is passed, the + * string is assumed to be nul-terminated. This option allows + * termination strings with embedded nuls. * * This sets the string that #GIOChannel uses to determine * where in the file a line break occurs. @@ -16739,9 +17344,15 @@ * g_io_channel_write_chars: * @channel: a #GIOChannel * @buf: (array) (element-type guint8): a buffer to write data from - * @count: the size of the buffer. If -1, the buffer is taken to be a nul-terminated string. - * @bytes_written: (out): The number of bytes written. This can be nonzero even if the return value is not %G_IO_STATUS_NORMAL. If the return value is %G_IO_STATUS_NORMAL and the channel is blocking, this will always be equal to @count if @count >= 0. - * @error: a location to return an error of type #GConvertError or #GIOChannelError + * @count: the size of the buffer. If -1, the buffer + * is taken to be a nul-terminated string. + * @bytes_written: (out): The number of bytes written. This can be nonzero + * even if the return value is not %G_IO_STATUS_NORMAL. + * If the return value is %G_IO_STATUS_NORMAL and the + * channel is blocking, this will always be equal + * to @count if @count >= 0. + * @error: a location to return an error of type #GConvertError + * or #GIOChannelError * * Replacement for g_io_channel_write() with the new API. * @@ -16758,7 +17369,8 @@ * g_io_channel_write_unichar: * @channel: a #GIOChannel * @thechar: a character - * @error: location to return an error of type #GConvertError or #GIOChannelError + * @error: location to return an error of type #GConvertError + * or #GIOChannelError * * Writes a Unicode character to @channel. * This function cannot be called on a channel with %NULL encoding. @@ -16815,7 +17427,8 @@ * associated with @key cannot be interpreted as a boolean then %FALSE * is returned and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: the value associated with the key as a boolean, or %FALSE if the key was not found or could not be parsed. + * 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 */ @@ -16836,7 +17449,10 @@ * with @key cannot be interpreted as booleans then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * 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. + * 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 */ @@ -16873,7 +17489,8 @@ * with @key cannot be interpreted as a double then 0.0 is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: the value associated with the key as a double, or 0.0 if the key was not found or could not be parsed. + * 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 */ @@ -16894,7 +17511,10 @@ * with @key cannot be interpreted as doubles then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * 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. + * 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 */ @@ -16908,7 +17528,8 @@ * The array of returned groups will be %NULL-terminated, so * @length may optionally be %NULL. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.6 */ @@ -16924,7 +17545,8 @@ * 64-bit integer. This is similar to g_key_file_get_integer() but can return * 64-bit results without truncation. * - * 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. + * 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 */ @@ -16944,7 +17566,8 @@ * with @key cannot be interpreted as an integer then 0 is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * Returns: the value associated with the key as an integer, or 0 if the key was not found or could not be parsed. + * 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 */ @@ -16965,7 +17588,10 @@ * with @key cannot be interpreted as integers then %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE. * - * 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. + * 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 */ @@ -16983,7 +17609,8 @@ * be found, %NULL is returned and @error is set to * #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: (array zero-terminated=1) (transfer full): a newly-allocated %NULL-terminated array of strings. + * Use g_strfreev() to free it. * Since: 2.6 */ @@ -17005,7 +17632,8 @@ * with @key cannot be interpreted or no suitable translation can * be found then the untranslated value is returned. * - * Returns: a newly allocated string or %NULL if the specified key cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * key cannot be found. * Since: 2.6 */ @@ -17030,7 +17658,9 @@ * returned array is %NULL-terminated, so @length may optionally * be %NULL. * - * Returns: (array zero-terminated=1 length=length) (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(). + * Returns: (array zero-terminated=1 length=length) (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 */ @@ -17062,7 +17692,8 @@ * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified key cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * key cannot be found. * Since: 2.6 */ @@ -17082,7 +17713,9 @@ * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: (array zero-terminated=1 length=length) (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(). + * Returns: (array zero-terminated=1 length=length) (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 */ @@ -17098,7 +17731,8 @@ * 64-bit integer. This is similar to g_key_file_get_integer() but can return * large positive results without truncation. * - * 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. + * 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 */ @@ -17118,7 +17752,8 @@ * event that the @group_name cannot be found, %NULL is returned * and @error is set to #G_KEY_FILE_ERROR_GROUP_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified key cannot be found. + * Returns: a newly allocated string or %NULL if the specified + * key cannot be found. * Since: 2.6 */ @@ -17130,7 +17765,8 @@ * * Looks whether the key file has the group @group_name. * - * Returns: %TRUE if @group_name is a part of @key_file, %FALSE otherwise. + * Returns: %TRUE if @group_name is a part of @key_file, %FALSE + * otherwise. * Since: 2.6 */ @@ -17153,7 +17789,8 @@ * Language bindings should use g_key_file_get_value() to test whether * or not a key exists. * - * Returns: %TRUE if @key is a part of @group_name, %FALSE otherwise. + * Returns: %TRUE if @key is a part of @group_name, %FALSE + * otherwise. * Since: 2.6 */ @@ -17178,7 +17815,8 @@ * g_key_file_load_from_data_dirs: * @key_file: an empty #GKeyFile struct * @file: (type filename): a relative path to a filename to open and parse - * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path of the file, or %NULL + * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path + * of the file, or %NULL * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * @@ -17198,7 +17836,8 @@ * @key_file: an empty #GKeyFile struct * @file: (type filename): a relative path to a filename to open and parse * @search_dirs: (array zero-terminated=1) (element-type filename): %NULL-terminated array of directories to search - * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path of the file, or %NULL + * @full_path: (out) (type filename) (allow-none): return location for a string containing the full path + * of the file, or %NULL * @flags: flags from #GKeyFileFlags * @error: return location for a #GError, or %NULL * @@ -17548,7 +18187,8 @@ /** * g_key_file_to_data: * @key_file: a #GKeyFile - * @length: (out) (allow-none): return location for the length of the returned string, or %NULL + * @length: (out) (allow-none): return location for the length of the + * returned string, or %NULL * @error: return location for a #GError, or %NULL * * This function outputs @key_file as a string. @@ -17556,7 +18196,8 @@ * Note that this function never reports an error, * so it is safe to pass %NULL as @error. * - * Returns: a newly allocated string holding the contents of the #GKeyFile + * Returns: a newly allocated string holding + * the contents of the #GKeyFile * Since: 2.6 */ @@ -17700,7 +18341,8 @@ * Finds the element in a #GList which * contains the given data. * - * Returns: the found #GList element, or %NULL if it is not found + * Returns: the found #GList element, + * or %NULL if it is not found */ @@ -17708,7 +18350,8 @@ * g_list_find_custom: * @list: a #GList * @data: user data passed to the function - * @func: the function to call for each element. It should return 0 when the desired element is found + * @func: the function to call for each element. + * It should return 0 when the desired element is found * * Finds an element in a #GList, using a supplied function to * find the desired element. It iterates over the list, calling @@ -17727,7 +18370,8 @@ * * Gets the first element in a #GList. * - * Returns: the first element in the #GList, or %NULL if the #GList has no elements + * Returns: the first element in the #GList, + * or %NULL if the #GList has no elements */ @@ -17792,7 +18436,8 @@ * Gets the position of the element containing * the given data (starting from 0). * - * Returns: the index of the element containing the data, or -1 if the data is not found + * Returns: the index of the element containing the data, + * or -1 if the data is not found */ @@ -17800,7 +18445,9 @@ * g_list_insert: * @list: a pointer to a #GList * @data: the data for the new element - * @position: the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. + * @position: the position to insert the element. If this is + * negative, or is larger than the number of elements in the + * list, the new element is added on to the end of the list. * * Inserts a new element into the list at the given position. * @@ -17811,7 +18458,8 @@ /** * g_list_insert_before: * @list: a pointer to a #GList - * @sibling: the list element before which the new element is inserted or %NULL to insert at the end of the list + * @sibling: the list element before which the new element + * is inserted or %NULL to insert at the end of the list * @data: the data for the new element * * Inserts a new element into the list before the given position. @@ -17824,7 +18472,9 @@ * g_list_insert_sorted: * @list: a pointer to a #GList * @data: the data for the new element - * @func: the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. + * @func: the function to compare elements in the list. It should + * return a number > 0 if the first parameter comes after the + * second parameter in the sort order. * * Inserts a new element into the list, using the given comparison * function to determine its position. @@ -17837,7 +18487,9 @@ * g_list_insert_sorted_with_data: * @list: a pointer to a #GList * @data: the data for the new element - * @func: the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. + * @func: the function to compare elements in the list. + * It should return a number > 0 if the first parameter + * comes after the second parameter in the sort order. * @user_data: user data to pass to comparison function. * * Inserts a new element into the list, using the given comparison @@ -17854,7 +18506,8 @@ * * Gets the last element in a #GList. * - * Returns: the last element in the #GList, or %NULL if the #GList has no elements + * Returns: the last element in the #GList, + * or %NULL if the #GList has no elements */ @@ -17890,7 +18543,8 @@ * * Gets the element at the given position in a #GList. * - * Returns: the element, or %NULL if the position is off the end of the #GList + * Returns: the element, or %NULL if the position is off + * the end of the #GList */ @@ -17901,7 +18555,8 @@ * * Gets the data of the element at the given position. * - * Returns: the element's data, or %NULL if the position is off the end of the #GList + * Returns: the element's data, or %NULL if the position + * is off the end of the #GList */ @@ -17912,7 +18567,8 @@ * * Gets the element @n places before @list. * - * Returns: the element, or %NULL if the position is off the end of the #GList + * Returns: the element, or %NULL if the position is + * off the end of the #GList */ @@ -17924,7 +18580,8 @@ * Gets the position of the given element * in the #GList (starting from 0). * - * Returns: the position of the element in the #GList, or -1 if the element is not found + * Returns: the position of the element in the #GList, + * or -1 if the element is not found */ @@ -17957,7 +18614,8 @@ * * A convenience macro to get the previous element in a #GList. * - * Returns: the previous element, or %NULL if there are no previous elements. + * Returns: the previous element, or %NULL if there are no previous + * elements. */ @@ -18015,7 +18673,11 @@ /** * g_list_sort: * @list: a #GList - * @compare_func: the comparison function used to sort the #GList. This function is passed the data from 2 elements of the #GList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second. + * @compare_func: the comparison function used to sort the #GList. + * This function is passed the data from 2 elements of the #GList + * and should return 0 if they are equal, a negative value if the + * first element comes before the second, or a positive value if + * the first element comes after the second. * * Sorts a #GList using the given comparison function. The algorithm * used is a stable sort. @@ -18049,7 +18711,8 @@ * use cases for environment variables in GLib-using programs you want * the UTF-8 encoding that this function and g_getenv() provide. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated list of strings which must be freed with g_strfreev(). + * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated + * list of strings which must be freed with g_strfreev(). * Since: 2.8 */ @@ -18057,10 +18720,20 @@ /** * g_locale_from_utf8: * @utf8string: a UTF-8 encoded string - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. - * @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. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @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. + * @len: the length of the string, or -1 if the string is + * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * @bytes_read: location to store the number of bytes in the + * input string that were successfully converted, or %NULL. + * Even if the conversion was successful, this may be + * 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. + * @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. * * Converts a string from UTF-8 to the encoding used for strings by * the C runtime (usually the same as that used by the operating @@ -18073,11 +18746,22 @@ /** * g_locale_to_utf8: - * @opsysstring: a string in the encoding of the current locale. On Windows this means the system codepage. - * @len: the length of the string, or -1 if the string is nul-terminated<footnoteref linkend="nul-unsafe"/>. - * @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. If the error #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value stored will the byte offset after the last valid input sequence. - * @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. + * @opsysstring: a string in the encoding of the current locale. On Windows + * this means the system codepage. + * @len: the length of the string, or -1 if the string is + * nul-terminated<footnoteref linkend="nul-unsafe"/>. + * @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. If the error + * #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value + * stored will the byte offset after the last valid + * input sequence. + * @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. * * Converts a string which is in the encoding used for strings by * the C runtime (usually the same as that used by the operating @@ -18091,7 +18775,8 @@ /** * g_log: * @log_domain: the log domain, usually #G_LOG_DOMAIN - * @log_level: the log level, either from #GLogLevelFlags or a user-defined level + * @log_level: the log level, either from #GLogLevelFlags + * or a user-defined level * @format: the message format. See the printf() documentation * @...: the parameters to insert into the format string * @@ -18144,7 +18829,8 @@ /** * g_log_remove_handler: * @log_domain: the log domain - * @handler_id: the id of the handler, which was returned in g_log_set_handler() + * @handler_id: the id of the handler, which was returned + * in g_log_set_handler() * * Removes the log handler. */ @@ -18152,7 +18838,8 @@ /** * g_log_set_always_fatal: - * @fatal_mask: the mask containing bits set for each level of error which is to be fatal + * @fatal_mask: the mask containing bits set for each level + * of error which is to be fatal * * Sets the message levels which are always fatal, in any log domain. * When a message with any of these levels is logged the program terminates. @@ -18196,8 +18883,12 @@ /** * g_log_set_handler: - * @log_domain: (allow-none): the log domain, or %NULL for the default "" application domain - * @log_levels: the log levels to apply the log handler for. To handle fatal and recursive messages as well, combine the log levels with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION bit flags. + * @log_domain: (allow-none): the log domain, or %NULL for the default "" + * application domain + * @log_levels: the log levels to apply the log handler for. + * To handle fatal and recursive messages as well, combine + * the log levels with the #G_LOG_FLAG_FATAL and + * #G_LOG_FLAG_RECURSION bit flags. * @log_func: the log handler function * @user_data: data passed to the log handler * @@ -18257,7 +18948,8 @@ /** * g_lstat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @buf: a pointer to a <structname>stat</structname> struct, which will be filled with the file information + * @buf: a pointer to a <structname>stat</structname> struct, which + * will be filled with the file information * * A wrapper for the POSIX lstat() function. The lstat() function is * like stat() except that in the case of symbolic links, it returns @@ -18267,7 +18959,8 @@ * * See your C library manual for more details about lstat(). * - * Returns: 0 if the information was successfully retrieved, -1 if an error occurred + * Returns: 0 if the information was successfully retrieved, -1 if an error + * occurred * Since: 2.6 */ @@ -18287,15 +18980,19 @@ * can call g_main_context_prepare(), g_main_context_query(), * g_main_context_check(), g_main_context_dispatch(). * - * Returns: %TRUE if the operation succeeded, and this thread is now the owner of @context. + * Returns: %TRUE if the operation succeeded, and + * this thread is now the owner of @context. */ /** * g_main_context_add_poll: * @context: (allow-none): a #GMainContext (or %NULL for the default context) - * @fd: a #GPollFD structure holding information about a file descriptor to watch. - * @priority: the priority for this file descriptor which should be the same as the priority used for g_source_attach() to ensure that the file descriptor is polled whenever the results may be needed. + * @fd: a #GPollFD structure holding information about a file + * descriptor to watch. + * @priority: the priority for this file descriptor which should be + * the same as the priority used for g_source_attach() to ensure that the + * file descriptor is polled whenever the results may be needed. * * Adds a file descriptor to the set of file descriptors polled for * this context. This will very seldom be used directly. Instead @@ -18307,7 +19004,8 @@ * g_main_context_check: * @context: a #GMainContext * @max_priority: the maximum numerical priority of sources to check - * @fds: (array length=n_fds): array of #GPollFD's that was passed to the last call to g_main_context_query() + * @fds: (array length=n_fds): array of #GPollFD's that was passed to + * the last call to g_main_context_query() * @n_fds: return value of g_main_context_query() * * Passes the results of polling back to the main loop. @@ -18399,7 +19097,8 @@ * If you need to hold a reference on the context, use * g_main_context_ref_thread_default() instead. * - * Returns: (transfer none): the thread-default #GMainContext, or %NULL if the thread-default context is the global default context. + * Returns: (transfer none): the thread-default #GMainContext, or + * %NULL if the thread-default context is the global default context. * Since: 2.22 */ @@ -18527,12 +19226,14 @@ /** * g_main_context_prepare: * @context: a #GMainContext - * @priority: location to store priority of highest priority source already ready. + * @priority: location to store priority of highest priority + * source already ready. * * Prepares to poll sources within a main loop. The resulting information * for polling is determined by calling g_main_context_query (). * - * Returns: %TRUE if some source is ready to be dispatched prior to polling. + * Returns: %TRUE if some source is ready to be dispatched + * prior to polling. */ @@ -18578,12 +19279,15 @@ * @context: a #GMainContext * @max_priority: maximum priority source to check * @timeout_: (out): location to store timeout to be used in polling - * @fds: (out caller-allocates) (array length=n_fds): location to store #GPollFD records that need to be polled. + * @fds: (out caller-allocates) (array length=n_fds): location to + * store #GPollFD records that need to be polled. * @n_fds: length of @fds. * * Determines information necessary to poll this main loop. * - * 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. + * 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. */ @@ -18607,7 +19311,8 @@ * is the global default context, this will return that #GMainContext * (with a ref added to it) rather than returning %NULL. * - * Returns: (transfer full): the thread-default #GMainContext. Unref with g_main_context_unref() when you are done with it. + * Returns: (transfer full): the thread-default #GMainContext. Unref + * with g_main_context_unref() when you are done with it. * Since: 2.32 */ @@ -18669,7 +19374,8 @@ * that owner releases ownership or until @cond is signaled, then * try again (once) to become the owner. * - * Returns: %TRUE if the operation succeeded, and this thread is now the owner of @context. + * Returns: %TRUE if the operation succeeded, and + * this thread is now the owner of @context. */ @@ -18693,11 +19399,11 @@ * #define NUM_TASKS 10 * static volatile gint tasks_remaining = NUM_TASKS; * ... - * + * * while (g_atomic_int_get (&tasks_remaining) != 0) * g_main_context_iteration (NULL, TRUE); * ]| - * + * * Then in a thread: * |[ * perform_work(); @@ -18784,7 +19490,7 @@ * free_allocated_memory (void) * { * GList *l; - * + * * int depth = g_main_depth (); * for (l = free_list; l; ); * { @@ -18796,7 +19502,7 @@ * g_free (block); * free_list = g_list_delete_link (free_list, l); * } - * + * * l = next; * } * } @@ -18859,7 +19565,9 @@ /** * g_main_loop_new: * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used). - * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_loop_run() will set this to %TRUE anyway. + * @is_running: set to %TRUE to indicate that the loop is running. This + * is not very important since calling g_main_loop_run() will set this to + * %TRUE anyway. * * Creates a new #GMainLoop structure. * @@ -18977,7 +19685,8 @@ * The mapped contents of the file must not be modified after creating this * bytes object, because a #GBytes should be immutable. * - * Returns: (transfer full): A newly allocated #GBytes referencing data from @file + * Returns: (transfer full): A newly allocated #GBytes referencing data + * from @file * Since: 2.34 */ @@ -19032,7 +19741,8 @@ * size 0 (e.g. device files such as /dev/null), @error will be set * to the #GFileError value #G_FILE_ERROR_INVAL. * - * Returns: a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. + * Returns: a newly allocated #GMappedFile which must be unref'd + * with g_mapped_file_unref(), or %NULL if the mapping failed. * Since: 2.8 */ @@ -19055,7 +19765,8 @@ * will not be modified, or if all modifications of the file are done * atomically (e.g. using g_file_set_contents()). * - * Returns: a newly allocated #GMappedFile which must be unref'd with g_mapped_file_unref(), or %NULL if the mapping failed. + * Returns: a newly allocated #GMappedFile which must be unref'd + * with g_mapped_file_unref(), or %NULL if the mapping failed. * Since: 2.32 */ @@ -19093,7 +19804,9 @@ * @error: a pointer to a #GError or %NULL * @first_type: the #GMarkupCollectType of the first attribute * @first_attr: the name of the first attribute - * @...: a pointer to the storage location of the first attribute (or %NULL), followed by more types names and pointers, ending with %G_MARKUP_COLLECT_INVALID + * @...: a pointer to the storage location of the first attribute + * (or %NULL), followed by more types names and pointers, ending + * with %G_MARKUP_COLLECT_INVALID * * Collects the attributes of the element from the data passed to the * #GMarkupParser start_element function, dealing with common error @@ -19242,7 +19955,9 @@ * g_markup_parse_context_new() or to the most recent call * of g_markup_parse_context_push(). * - * 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. + * 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 */ @@ -19252,7 +19967,8 @@ * @parser: a #GMarkupParser * @flags: one or more #GMarkupParseFlags * @user_data: user data to pass to #GMarkupParser functions - * @user_data_dnotify: user data destroy notifier called when the parse context is freed + * @user_data_dnotify: user data destroy notifier called when + * the parse context is freed * * Creates a new parse context. A parse context is used to parse * marked-up documents. You can feed any number of documents into @@ -19480,7 +20196,8 @@ * store, item); * ]| * - * Returns: newly allocated result from formatting operation. Free with g_free(). + * Returns: newly allocated result from formatting + * operation. Free with g_free(). * Since: 2.4 */ @@ -19494,7 +20211,8 @@ * all string and character arguments in the fashion * of g_markup_escape_text(). See g_markup_printf_escaped(). * - * Returns: newly allocated result from formatting operation. Free with g_free(). + * Returns: newly allocated result from formatting + * operation. Free with g_free(). * Since: 2.4 */ @@ -19550,7 +20268,8 @@ * The string is fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * - * Returns: (allow-none): The matched substring, or %NULL if an error occurred. You have to free the string yourself + * Returns: (allow-none): The matched substring, or %NULL if an error + * occurred. You have to free the string yourself * Since: 2.14 */ @@ -19576,7 +20295,9 @@ * The strings are fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * - * Returns: (transfer full): a %NULL-terminated array of gchar * pointers. It must be freed using g_strfreev(). If the previous match failed %NULL is returned + * Returns: (transfer full): 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 */ @@ -19595,7 +20316,8 @@ * The string is fetched from the string passed to the match function, * so you cannot call this function after freeing the string. * - * Returns: (allow-none): The matched substring, or %NULL if an error occurred. You have to free the string yourself + * Returns: (allow-none): The matched substring, or %NULL if an error + * occurred. You have to free the string yourself * Since: 2.14 */ @@ -19604,8 +20326,10 @@ * g_match_info_fetch_named_pos: * @match_info: #GMatchInfo structure * @name: name of the subexpression - * @start_pos: (out) (allow-none): pointer to location where to store the start position, or %NULL - * @end_pos: (out) (allow-none): pointer to location where to store the end position, or %NULL + * @start_pos: (out) (allow-none): pointer to location where to store + * the start position, or %NULL + * @end_pos: (out) (allow-none): pointer to location where to store + * the end position, or %NULL * * Retrieves the position in bytes of the capturing parentheses named @name. * @@ -19613,7 +20337,9 @@ * (e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") * then @start_pos and @end_pos are set to -1 and %TRUE is returned. * - * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged. + * 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 */ @@ -19622,8 +20348,10 @@ * g_match_info_fetch_pos: * @match_info: #GMatchInfo structure * @match_num: number of the sub expression - * @start_pos: (out) (allow-none): pointer to location where to store the start position, or %NULL - * @end_pos: (out) (allow-none): pointer to location where to store the end position, or %NULL + * @start_pos: (out) (allow-none): pointer to location where to store + * the start position, or %NULL + * @end_pos: (out) (allow-none): pointer to location where to store + * the end position, or %NULL * * Retrieves the position in bytes of the @match_num<!-- -->'th capturing * parentheses. 0 is the full text of the match, 1 is the first @@ -19639,7 +20367,9 @@ * substring. Substrings are matched in reverse order of length, so * 0 is the longest match. * - * Returns: %TRUE if the position was fetched, %FALSE otherwise. If the position cannot be fetched, @start_pos and @end_pos are left unchanged + * 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 */ @@ -19748,7 +20478,8 @@ * * Returns whether the previous match operation succeeded. * - * Returns: %TRUE if the previous match operation succeeded, %FALSE otherwise + * Returns: %TRUE if the previous match operation succeeded, + * %FALSE otherwise * Since: 2.14 */ @@ -19853,7 +20584,8 @@ * Allocates @byte_size bytes of memory, and copies @byte_size bytes into it * from @mem. If @mem is %NULL it returns %NULL. * - * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem is %NULL. + * Returns: a pointer to the newly-allocated copy of the memory, or %NULL if @mem + * is %NULL. */ @@ -19875,7 +20607,8 @@ /** * g_message: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * A convenience function/macro to log a normal message. */ @@ -19892,7 +20625,8 @@ * * See your C library manual for more details about mkdir(). * - * Returns: 0 if the directory was successfully created, -1 if an error occurred + * Returns: 0 if the directory was successfully created, -1 if an error + * occurred * Since: 2.6 */ @@ -19905,7 +20639,8 @@ * Create a directory if it doesn't already exist. Create intermediate * parent directories as needed, too. * - * Returns: 0 if the directory already exists, or was successfully created. Returns -1 if an error occurred, with errno set. + * Returns: 0 if the directory already exists, or was successfully + * created. Returns -1 if an error occurred, with errno set. * Since: 2.8 */ @@ -19926,7 +20661,9 @@ * The string should be in the GLib file name encoding. Most importantly, * on Windows it should be in UTF-8. * - * 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. + * 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 */ @@ -19948,7 +20685,9 @@ * in the GLib file name encoding. Most importantly, on Windows it * should be in UTF-8. * - * 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. + * 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 */ @@ -19968,14 +20707,19 @@ * didn't exist. The string should be in the GLib file name encoding. * Most importantly, on Windows it should be in UTF-8. * - * 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. + * 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. */ /** * g_mkstemp_full: * @tmpl: (type filename): template filename - * @flags: flags to pass to an open() call in addition to O_EXCL and O_CREAT, which are passed automatically + * @flags: flags to pass to an open() call in addition to O_EXCL + * and O_CREAT, which are passed automatically * @mode: permissions to create the temporary file with * * Opens a temporary file. See the mkstemp() documentation @@ -19990,7 +20734,10 @@ * The string should be in the GLib file name encoding. Most importantly, * on Windows it should be in UTF-8. * - * 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. + * 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 */ @@ -20097,7 +20844,8 @@ * Gets the position of the first child of a #GNode * which contains the given data. * - * Returns: the index of the child of @node which contains @data, or -1 if the data is not found + * Returns: the index of the child of @node which contains + * @data, or -1 if the data is not found */ @@ -20117,7 +20865,8 @@ /** * g_node_children_foreach: * @node: a #GNode - * @flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @flags: which types of children are to be visited, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @func: the function to call for each visited node * @data: user data to pass to the function * @@ -20140,7 +20889,8 @@ /** * g_node_copy_deep: * @node: a #GNode - * @copy_func: the function which is called to copy the data inside each node, or %NULL to use the original data. + * @copy_func: the function which is called to copy the data inside each node, + * or %NULL to use the original data. * @data: data to pass to @copy_func * * Recursively copies a #GNode and its data. @@ -20175,8 +20925,10 @@ /** * g_node_find: * @root: the root #GNode of the tree to search - * @order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER - * @flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @order: the order in which nodes are visited - %G_IN_ORDER, + * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER + * @flags: which types of children are to be searched, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @data: the data to find * * Finds a #GNode in a tree. @@ -20188,7 +20940,8 @@ /** * g_node_find_child: * @node: a #GNode - * @flags: which types of children are to be searched, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @flags: which types of children are to be searched, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * @data: the data to find * * Finds the first child of a #GNode with the given data. @@ -20221,7 +20974,8 @@ /** * g_node_insert: * @parent: the #GNode to place @node under - * @position: the position to place @node at, with respect to its siblings If position is -1, @node is inserted as the last child of @parent + * @position: the position to place @node at, with respect to its siblings + * If position is -1, @node is inserted as the last child of @parent * @node: the #GNode to insert * * Inserts a #GNode beneath the parent at the given position. @@ -20233,7 +20987,8 @@ /** * g_node_insert_after: * @parent: the #GNode to place @node under - * @sibling: the sibling #GNode to place @node after. If sibling is %NULL, the node is inserted as the first child of @parent. + * @sibling: the sibling #GNode to place @node after. + * If sibling is %NULL, the node is inserted as the first child of @parent. * @node: the #GNode to insert * * Inserts a #GNode beneath the parent after the given sibling. @@ -20245,7 +21000,8 @@ /** * g_node_insert_before: * @parent: the #GNode to place @node under - * @sibling: the sibling #GNode to place @node before. If sibling is %NULL, the node is inserted as the last child of @parent. + * @sibling: the sibling #GNode to place @node before. + * If sibling is %NULL, the node is inserted as the last child of @parent. * @node: the #GNode to insert * * Inserts a #GNode beneath the parent before the given sibling. @@ -20315,7 +21071,8 @@ /** * g_node_n_nodes: * @root: a #GNode - * @flags: which types of children are to be counted, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @flags: which types of children are to be counted, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES * * Gets the number of nodes in a tree. * @@ -20370,9 +21127,14 @@ /** * g_node_traverse: * @root: the root #GNode of the tree to traverse - * @order: the order in which nodes are visited - %G_IN_ORDER, %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. - * @flags: which types of children are to be visited, one of %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES - * @max_depth: the maximum depth of the traversal. Nodes below this depth will not be visited. If max_depth is -1 all nodes in the tree are visited. If depth is 1, only the root is visited. If depth is 2, the root and its children are visited. And so on. + * @order: the order in which nodes are visited - %G_IN_ORDER, + * %G_PRE_ORDER, %G_POST_ORDER, or %G_LEVEL_ORDER. + * @flags: which types of children are to be visited, one of + * %G_TRAVERSE_ALL, %G_TRAVERSE_LEAVES and %G_TRAVERSE_NON_LEAVES + * @max_depth: the maximum depth of the traversal. Nodes below this + * depth will not be visited. If max_depth is -1 all nodes in + * the tree are visited. If depth is 1, only the root is visited. + * If depth is 2, the root and its children are visited. And so on. * @func: the function to call for each visited #GNode * @data: user data to pass to the function * @@ -20420,7 +21182,10 @@ /** * g_on_error_query: - * @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname() is called to get the program name (which will work correctly if gdk_init() or gtk_init() has been called) + * @prg_name: the program name, needed by <command>gdb</command> + * for the [S]tack trace option. If @prg_name is %NULL, g_get_prgname() + * is called to get the program name (which will work correctly if + * gdk_init() or gtk_init() has been called) * * Prompts the user with * <computeroutput>[E]xit, [H]alt, show [S]tack trace or [P]roceed</computeroutput>. @@ -20469,7 +21234,8 @@ /** * g_on_error_stack_trace: - * @prg_name: the program name, needed by <command>gdb</command> for the [S]tack trace option. + * @prg_name: the program name, needed by <command>gdb</command> + * for the [S]tack trace option. * * Invokes <command>gdb</command>, which attaches to the current * process and shows a stack trace. Called by g_on_error_query() @@ -20484,7 +21250,9 @@ /** * g_once: * @once: a #GOnce structure - * @func: the #GThreadFunc function associated to @once. This function is called only once, regardless of the number of times it and its associated #GOnce struct are passed to g_once(). + * @func: the #GThreadFunc function associated to @once. This function + * is called only once, regardless of the number of times it and + * its associated #GOnce struct are passed to g_once(). * @arg: data to be passed to @func * * The first call to this routine by a process with a given #GOnce @@ -20543,7 +21311,8 @@ * /** use initialization_value here **/ * ]| * - * Returns: %TRUE if the initialization section should be entered, %FALSE and blocks otherwise + * Returns: %TRUE if the initialization section should be entered, + * %FALSE and blocks otherwise * Since: 2.14 */ @@ -20588,7 +21357,8 @@ * * See your C library manual for more details about open(). * - * Returns: a new file descriptor, or -1 if an error occurred. The return value can be used exactly like the return value from open(). + * Returns: a new file descriptor, or -1 if an error occurred. The + * return value can be used exactly like the return value from open(). * Since: 2.6 */ @@ -20612,7 +21382,9 @@ * g_option_context_add_main_entries: * @context: a #GOptionContext * @entries: a %NULL-terminated array of #GOptionEntry<!-- -->s - * @translation_domain: (allow-none): a translation domain to use for translating the <option>--help</option> output for the options in @entries with gettext(), or %NULL + * @translation_domain: (allow-none): a translation domain to use for translating + * the <option>--help</option> output for the options in @entries + * with gettext(), or %NULL * * A convenience function which creates a main group if it doesn't * exist, adds the @entries to it and sets the translation domain. @@ -20695,7 +21467,9 @@ * * Returns a pointer to the main group of @context. * - * 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. + * 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 */ @@ -20713,7 +21487,10 @@ /** * g_option_context_new: - * @parameter_string: (allow-none): a string which is displayed in the first line of <option>--help</option> output, after the usage summary <literal><replaceable>programname</replaceable> [OPTION...]</literal> + * @parameter_string: (allow-none): a string which is displayed in + * the first line of <option>--help</option> output, after the + * usage summary + * <literal><replaceable>programname</replaceable> [OPTION...]</literal> * * Creates a new option context. * @@ -20735,7 +21512,8 @@ * function set with g_option_context_set_translate_func(), so * it should normally be passed untranslated. * - * Returns: a newly created #GOptionContext, which must be freed with g_option_context_free() after use. + * Returns: a newly created #GOptionContext, which must be + * freed with g_option_context_free() after use. * Since: 2.6 */ @@ -20770,7 +21548,8 @@ * automatic character set conversion of string and filename * arguments. * - * Returns: %TRUE if the parsing was successful, %FALSE if an error occurred + * Returns: %TRUE if the parsing was successful, + * %FALSE if an error occurred * Since: 2.6 */ @@ -20778,7 +21557,8 @@ /** * g_option_context_set_description: * @context: a #GOptionContext - * @description: (allow-none): a string to be shown in <option>--help</option> output after the list of options, or %NULL + * @description: (allow-none): a string to be shown in <option>--help</option> output + * after the list of options, or %NULL * * Adds a string to be displayed in <option>--help</option> output * after the list of options. This text often includes a bug reporting @@ -20810,7 +21590,8 @@ /** * g_option_context_set_ignore_unknown_options: * @context: a #GOptionContext - * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce an error when unknown options are met + * @ignore_unknown: %TRUE to ignore unknown options, %FALSE to produce + * an error when unknown options are met * * Sets whether to ignore unknown options or not. If an argument is * ignored, it is left in the @argv array after parsing. By default, @@ -20841,7 +21622,8 @@ /** * g_option_context_set_summary: * @context: a #GOptionContext - * @summary: (allow-none): a string to be shown in <option>--help</option> output before the list of options, or %NULL + * @summary: (allow-none): a string to be shown in <option>--help</option> output + * before the list of options, or %NULL * * Adds a string to be displayed in <option>--help</option> output * before the list of options. This is typically a summary of the @@ -20914,15 +21696,22 @@ /** * g_option_group_new: - * @name: the name for the option group, this is used to provide help for the options in this group with <option>--help-</option>@name - * @description: a description for this group to be shown in <option>--help</option>. This string is translated using the translation domain or translation function of the group - * @help_description: a description for the <option>--help-</option>@name option. This string is translated using the translation domain or translation function of the group - * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks, the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL + * @name: the name for the option group, this is used to provide + * help for the options in this group with <option>--help-</option>@name + * @description: a description for this group to be shown in + * <option>--help</option>. This string is translated using the translation + * domain or translation function of the group + * @help_description: a description for the <option>--help-</option>@name option. + * This string is translated using the translation domain or translation function + * of the group + * @user_data: (allow-none): user data that will be passed to the pre- and post-parse hooks, + * the error hook and to callbacks of %G_OPTION_ARG_CALLBACK options, or %NULL * @destroy: (allow-none): a function that will be called to free @user_data, or %NULL * * Creates a new #GOptionGroup. * - * Returns: a newly created option group. It should be added to a #GOptionContext or freed with g_option_group_free(). + * Returns: a newly created option group. It should be added + * to a #GOptionContext or freed with g_option_group_free(). * Since: 2.6 */ @@ -20993,8 +21782,10 @@ /** * g_parse_debug_string: - * @string: (allow-none): a list of debug options separated by colons, spaces, or commas, or %NULL. - * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate strings with bit flags. + * @string: (allow-none): a list of debug options separated by colons, spaces, or + * commas, or %NULL. + * @keys: (array length=nkeys): pointer to an array of #GDebugKey which associate + * strings with bit flags. * @nkeys: the number of #GDebugKey<!-- -->s in the array. * * Parses a string containing debugging options @@ -21025,7 +21816,8 @@ * separators (and on Windows, possibly a drive letter), a single * separator is returned. If @file_name is empty, it gets ".". * - * Returns: a newly allocated string containing the last component of the filename + * Returns: a newly allocated string containing the last + * component of the filename */ @@ -21090,7 +21882,8 @@ /** * g_pattern_match: * @pspec: a #GPatternSpec - * @string_length: the length of @string (in bytes, i.e. strlen(), <emphasis>not</emphasis> g_utf8_strlen()) + * @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 * @@ -21244,7 +22037,9 @@ * Windows, the easiest solution is to construct all of your * #GPollFD<!-- -->s with g_io_channel_win32_make_pollfd(). * - * Returns: the number of entries in @fds whose %revents fields were filled in, or 0 if the operation timed out, or -1 on error or if the call was interrupted. + * 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 */ @@ -21302,7 +22097,8 @@ /** * g_printf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @...: the arguments to insert in the output. * * An implementation of the standard printf() function which supports @@ -21432,7 +22228,8 @@ * 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(). + * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. + * The pointer array should be freed using g_free(). */ @@ -21513,7 +22310,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. + * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is + * not found in the array. */ @@ -21697,7 +22495,8 @@ * expect to ever unload the module again (e.g. do not use this * function in GTK+ theme engines). * - * Returns: the #GQuark identifying the string, or 0 if @string is %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is + * %NULL. */ @@ -21709,7 +22508,8 @@ * not currently have an associated #GQuark, a new #GQuark is created, * using a copy of the string. * - * Returns: the #GQuark identifying the string, or 0 if @string is %NULL. + * Returns: the #GQuark identifying the string, or 0 if @string is + * %NULL. */ @@ -21733,7 +22533,8 @@ * 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. + * Returns: the #GQuark associated with the string, or 0 if @string is + * %NULL or there is no #GQuark associated with it. */ @@ -21790,7 +22591,8 @@ * g_queue_find_custom: * @queue: a #GQueue * @data: user data passed to @func - * @func: a #GCompareFunc to call for each element. It should return 0 when the desired element is found + * @func: a #GCompareFunc to call for each element. It should return 0 + * when the desired element is found * * Finds an element in a #GQueue, using a supplied function to find the * desired element. It iterates over the queue, calling the given function @@ -21912,7 +22714,11 @@ * g_queue_insert_sorted: * @queue: a #GQueue * @data: the data to insert - * @func: the #GCompareDataFunc used to compare elements in the queue. It is called with two elements of the @queue and @user_data. It should return 0 if the elements are equal, a negative value if the first element comes before the second, and a positive value if the second element comes before the first. + * @func: the #GCompareDataFunc used to compare elements in the queue. It is + * called with two elements of the @queue and @user_data. It should + * return 0 if the elements are equal, a negative value if the first + * element comes before the second, and a positive value if the second + * element comes before the first. * @user_data: user data passed to @func. * * Inserts @data into @queue using @func to determine the new position. @@ -21938,7 +22744,8 @@ * * Returns the position of @link_ in @queue. * - * Returns: The position of @link_, or -1 if the link is not part of @queue + * Returns: The position of @link_, or -1 if the link is + * not part of @queue * Since: 2.4 */ @@ -21958,7 +22765,8 @@ * * Returns the first element of the queue. * - * Returns: the data of the first element in the queue, or %NULL if the queue is empty. + * Returns: the data of the first element in the queue, or %NULL if the queue + * is empty. */ @@ -21980,7 +22788,8 @@ * * Returns the @n'th element of @queue. * - * Returns: The data for the @n'th element of @queue, or %NULL if @n is off the end of @queue. + * Returns: The data for the @n'th element of @queue, or %NULL if @n is + * off the end of @queue. * Since: 2.4 */ @@ -21992,7 +22801,8 @@ * * Returns the link at the given position * - * Returns: The link at the @n'th position, or %NULL if @n is off the end of the list + * Returns: The link at the @n'th position, or %NULL if @n is off the + * end of the list * Since: 2.4 */ @@ -22003,7 +22813,8 @@ * * Returns the last element of the queue. * - * Returns: the data of the last element in the queue, or %NULL if the queue is empty. + * Returns: the data of the last element in the queue, or %NULL if the queue + * is empty. */ @@ -22024,7 +22835,8 @@ * * Removes the first element of the queue. * - * Returns: the data of the first element in the queue, or %NULL if the queue is empty. + * Returns: the data of the first element in the queue, or %NULL if the queue + * is empty. */ @@ -22034,7 +22846,8 @@ * * Removes the first element of the queue. * - * Returns: the #GList element at the head of the queue, or %NULL if the queue is empty. + * Returns: the #GList element at the head of the queue, or %NULL if the queue + * is empty. */ @@ -22068,7 +22881,8 @@ * * Removes the last element of the queue. * - * Returns: the data of the last element in the queue, or %NULL if the queue is empty. + * Returns: the data of the last element in the queue, or %NULL if the queue + * is empty. */ @@ -22078,7 +22892,8 @@ * * Removes the last element of the queue. * - * Returns: the #GList element at the tail of the queue, or %NULL if the queue is empty. + * Returns: the #GList element at the tail of the queue, or %NULL if the queue + * is empty. */ @@ -22094,7 +22909,8 @@ /** * g_queue_push_head_link: * @queue: a #GQueue. - * @link_: a single #GList element, <emphasis>not</emphasis> a list with more than one element. + * @link_: a single #GList element, <emphasis>not</emphasis> a list with + * more than one element. * * Adds a new element at the head of the queue. */ @@ -22104,7 +22920,9 @@ * g_queue_push_nth: * @queue: a #GQueue * @data: the data for the new element - * @n: the position to insert the new element. If @n is negative or larger than the number of elements in the @queue, the element is added to the end of the queue. + * @n: the position to insert the new element. If @n is negative or + * larger than the number of elements in the @queue, the element is + * added to the end of the queue. * * Inserts a new element into @queue at the given position * @@ -22115,7 +22933,9 @@ /** * g_queue_push_nth_link: * @queue: a #GQueue - * @n: the position to insert the link. If this is negative or larger than the number of elements in @queue, the link is added to the end of @queue. + * @n: the position to insert the link. If this is negative or larger than + * the number of elements in @queue, the link is added to the end of + * @queue. * @link_: the link to add to @queue * * Inserts @link into @queue at the given position. @@ -22136,7 +22956,8 @@ /** * g_queue_push_tail_link: * @queue: a #GQueue. - * @link_: a single #GList element, <emphasis>not</emphasis> a list with more than one element. + * @link_: a single #GList element, <emphasis>not</emphasis> a list with + * more than one element. * * Adds a new element at the tail of the queue. */ @@ -22179,7 +23000,10 @@ /** * g_queue_sort: * @queue: a #GQueue - * @compare_func: the #GCompareDataFunc used to sort @queue. This function is passed two elements of the queue and should return 0 if they are equal, a negative value if the first comes before the second, and a positive value if the second comes before the first. + * @compare_func: the #GCompareDataFunc used to sort @queue. This function + * is passed two elements of the queue and should return 0 if they are + * equal, a negative value if the first comes before the second, and + * a positive value if the second comes before the first. * @user_data: user data passed to @compare_func * * Sorts @queue using @compare_func. @@ -22527,7 +23351,8 @@ /** * g_regex_check_replacement: * @replacement: the replacement string - * @has_references: (out) (allow-none): location to store information about references in @replacement or %NULL + * @has_references: (out) (allow-none): location to store information about + * references in @replacement or %NULL * @error: location to store error * * Checks whether @replacement is a valid replacement string @@ -22668,7 +23493,8 @@ * * Retrieves the number of the subexpression named @name. * - * Returns: The number of the subexpression or -1 if @name does not exists + * Returns: The number of the subexpression or -1 if @name + * does not exists * Since: 2.14 */ @@ -22678,7 +23504,8 @@ * @regex: a #GRegex structure from g_regex_new() * @string: the string to scan for matches * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * * Scans for a match in string for the pattern in @regex. * The @match_options are combined with the match options specified @@ -22729,7 +23556,8 @@ * @regex: a #GRegex structure from g_regex_new() * @string: the string to scan for matches * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * * Using the standard algorithm for regular expression matching only * the longest match in the string is retrieved. This function uses @@ -22758,7 +23586,8 @@ * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * @error: location to store the error occurring, or %NULL to ignore errors * * Using the standard algorithm for regular expression matching only @@ -22810,7 +23639,8 @@ * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match options - * @match_info: (out) (allow-none): pointer to location where to store the #GMatchInfo, or %NULL if you do not need it + * @match_info: (out) (allow-none): pointer to location where to store + * the #GMatchInfo, or %NULL if you do not need it * @error: location to store the error occurring, or %NULL to ignore errors * * Scans for a match in string for the pattern in @regex. @@ -22901,7 +23731,8 @@ * Compiles the regular expression to an internal form, and does * the initial setup of the #GRegex structure. * - * Returns: a #GRegex structure. Call g_regex_unref() when you are done with it + * Returns: a #GRegex structure. Call g_regex_unref() when you + * are done with it * Since: 2.14 */ @@ -23089,7 +23920,8 @@ * For example splitting "ab c" using as a separator "\s*", you will get * "a", "b" and "c". * - * Returns: (transfer full): a %NULL-terminated gchar ** array. Free it using g_strfreev() + * Returns: (transfer full): a %NULL-terminated gchar ** array. Free + * it using g_strfreev() * Since: 2.14 */ @@ -23101,7 +23933,8 @@ * @string_len: the length of @string, or -1 if @string is nul-terminated * @start_position: starting index of the string to match * @match_options: match time option flags - * @max_tokens: the maximum number of tokens to split @string into. If this is less than 1, the string is split completely + * @max_tokens: the maximum number of tokens to split @string into. + * If this is less than 1, the string is split completely * @error: return location for a #GError * * Breaks the string on the pattern, and returns an array of the tokens. @@ -23126,7 +23959,8 @@ * string and setting #G_REGEX_MATCH_NOTBOL in the case of a pattern * that begins with any kind of lookbehind assertion, such as "\b". * - * Returns: (transfer full): a %NULL-terminated gchar ** array. Free it using g_strfreev() + * Returns: (transfer full): a %NULL-terminated gchar ** array. Free + * it using g_strfreev() * Since: 2.14 */ @@ -23166,7 +24000,8 @@ * characters. For example splitting "ab c" using as a separator * "\s*", you will get "a", "b" and "c". * - * Returns: (transfer full): a %NULL-terminated array of strings. Free it using g_strfreev() + * Returns: (transfer full): a %NULL-terminated array of strings. Free + * it using g_strfreev() * Since: 2.14 */ @@ -23219,7 +24054,8 @@ * fail. Any errno value set by remove() will be overwritten by that * set by rmdir(). * - * Returns: 0 if the file was successfully removed, -1 if an error occurred + * Returns: 0 if the file was successfully removed, -1 if an error + * occurred * Since: 2.6 */ @@ -23251,7 +24087,8 @@ * See your C library manual for more details about how rmdir() works * on your system. * - * Returns: 0 if the directory was successfully removed, -1 if an error occurred + * Returns: 0 if the directory was successfully removed, -1 if an error + * occurred * Since: 2.6 */ @@ -23457,7 +24294,8 @@ * Returns %TRUE if the scanner has reached the end of * the file or text buffer. * - * Returns: %TRUE if the scanner has reached the end of the file or text buffer + * Returns: %TRUE if the scanner has reached the end of + * the file or text buffer */ @@ -23534,7 +24372,8 @@ * If the symbol is not bound in the current scope, %NULL is * returned. * - * Returns: the value of @symbol in the current scope, or %NULL if @symbol is not bound in the current scope + * Returns: the value of @symbol in the current scope, or %NULL + * if @symbol is not bound in the current scope */ @@ -23618,7 +24457,8 @@ * Looks up a symbol in a scope and return its value. If the * symbol is not bound in the scope, %NULL is returned. * - * Returns: the value of @symbol in the given scope, or %NULL if @symbol is not bound in the given scope. + * Returns: the value of @symbol in the given scope, or %NULL + * if @symbol is not bound in the given scope. */ @@ -23668,11 +24508,20 @@ * g_scanner_unexp_token: * @scanner: a #GScanner * @expected_token: the expected token - * @identifier_spec: a string describing how the scanner's user refers to identifiers (%NULL defaults to "identifier"). This is used if @expected_token is %G_TOKEN_IDENTIFIER or %G_TOKEN_IDENTIFIER_NULL. - * @symbol_spec: a string describing how the scanner's user refers to symbols (%NULL defaults to "symbol"). This is used if @expected_token is %G_TOKEN_SYMBOL or any token value greater than %G_TOKEN_LAST. - * @symbol_name: the name of the symbol, if the scanner's current token is a symbol. - * @message: a message string to output at the end of the warning/error, or %NULL. - * @is_error: if %TRUE it is output as an error. If %FALSE it is output as a warning. + * @identifier_spec: a string describing how the scanner's user + * refers to identifiers (%NULL defaults to "identifier"). + * This is used if @expected_token is %G_TOKEN_IDENTIFIER or + * %G_TOKEN_IDENTIFIER_NULL. + * @symbol_spec: a string describing how the scanner's user refers + * to symbols (%NULL defaults to "symbol"). This is used if + * @expected_token is %G_TOKEN_SYMBOL or any token value greater + * than %G_TOKEN_LAST. + * @symbol_name: the name of the symbol, if the scanner's current + * token is a symbol. + * @message: a message string to output at the end of the + * warning/error, or %NULL. + * @is_error: if %TRUE it is output as an error. If %FALSE it is + * output as a warning. * * Outputs a message through the scanner's msg_handler, * resulting from an unexpected token in the input stream. @@ -23871,7 +24720,8 @@ * * The @a and @b iterators must point into the same sequence. * - * Returns: A negative number if @a comes before @b, 0 if they are equal, and a positive number if @a comes after @b. + * Returns: A negative number if @a comes before @b, 0 if they are + * equal, and a positive number if @a comes after @b. * Since: 2.14 */ @@ -23923,7 +24773,8 @@ /** * g_sequence_iter_move: * @iter: a #GSequenceIter - * @delta: A positive or negative number indicating how many positions away from @iter the returned #GSequenceIter will be. + * @delta: A positive or negative number indicating how many positions away + * from @iter the returned #GSequenceIter will be. * * Returns the #GSequenceIter which is @delta positions away from @iter. * If @iter is closer than -@delta positions to the beginning of the sequence, @@ -23954,7 +24805,8 @@ * Returns an iterator pointing to the previous position before @iter. If * @iter is the begin iterator, the begin iterator is returned. * - * Returns: a #GSequenceIter pointing to the previous position before @iter. + * Returns: a #GSequenceIter pointing to the previous position before + * @iter. * Since: 2.14 */ @@ -23985,7 +24837,9 @@ * doing unsorted insertions. * </para></note> * - * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data, or %NULL if no such item exists. + * Returns: an #GSequenceIter pointing to the position of the + * first item found equal to @data according to @cmp_func and + * @cmp_data, or %NULL if no such item exists. * Since: 2.28 */ @@ -24013,7 +24867,9 @@ * doing unsorted insertions. * </para></note> * - * Returns: an #GSequenceIter pointing to the position of the first item found equal to @data according to @cmp_func and @cmp_data, or %NULL if no such item exists. + * Returns: an #GSequenceIter pointing to the position of + * the first item found equal to @data according to @cmp_func + * and @cmp_data, or %NULL if no such item exists. * Since: 2.28 */ @@ -24021,7 +24877,8 @@ /** * g_sequence_move: * @src: a #GSequenceIter pointing to the item to move - * @dest: a #GSequenceIter pointing to the position to which the item is moved. + * @dest: a #GSequenceIter pointing to the position to which + * the item is moved. * * Moves the item pointed to by @src to the position indicated by @dest. * After calling this function @dest will point to the position immediately @@ -24088,7 +24945,8 @@ * The @begin and @end iterators must both point to the same sequence and * @begin must come before or be equal to @end in the sequence. * - * Returns: A #GSequenceIter pointing somewhere in the (@begin, @end) range. + * Returns: A #GSequenceIter pointing somewhere in the + * (@begin, @end) range. * Since: 2.14 */ @@ -24147,7 +25005,8 @@ * doing unsorted insertions. * </para></note> * - * Returns: an #GSequenceIter pointing to the position where @data would have been inserted according to @cmp_func and @cmp_data. + * Returns: an #GSequenceIter pointing to the position where @data + * would have been inserted according to @cmp_func and @cmp_data. * Since: 2.14 */ @@ -24178,7 +25037,9 @@ * doing unsorted insertions. * </para></note> * - * Returns: a #GSequenceIter pointing to the position in @seq where @data would have been inserted according to @iter_cmp and @cmp_data. + * 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 */ @@ -24792,7 +25653,8 @@ * Finds the element in a #GSList which * contains the given data. * - * Returns: the found #GSList element, or %NULL if it is not found + * Returns: the found #GSList element, + * or %NULL if it is not found */ @@ -24800,7 +25662,8 @@ * g_slist_find_custom: * @list: a #GSList * @data: user data passed to the function - * @func: the function to call for each element. It should return 0 when the desired element is found + * @func: the function to call for each element. + * It should return 0 when the desired element is found * * Finds an element in a #GSList, using a supplied function to * find the desired element. It iterates over the list, calling @@ -24876,7 +25739,8 @@ * Gets the position of the element containing * the given data (starting from 0). * - * Returns: the index of the element containing the data, or -1 if the data is not found + * Returns: the index of the element containing the data, + * or -1 if the data is not found */ @@ -24884,7 +25748,10 @@ * g_slist_insert: * @list: a #GSList * @data: the data for the new element - * @position: the position to insert the element. If this is negative, or is larger than the number of elements in the list, the new element is added on to the end of the list. + * @position: the position to insert the element. + * If this is negative, or is larger than the number + * of elements in the list, the new element is added on + * to the end of the list. * * Inserts a new element into the list at the given position. * @@ -24908,7 +25775,9 @@ * g_slist_insert_sorted: * @list: a #GSList * @data: the data for the new element - * @func: the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. + * @func: the function to compare elements in the list. + * It should return a number > 0 if the first parameter + * comes after the second parameter in the sort order. * * Inserts a new element into the list, using the given * comparison function to determine its position. @@ -24921,7 +25790,9 @@ * g_slist_insert_sorted_with_data: * @list: a #GSList * @data: the data for the new element - * @func: the function to compare elements in the list. It should return a number > 0 if the first parameter comes after the second parameter in the sort order. + * @func: the function to compare elements in the list. + * It should return a number > 0 if the first parameter + * comes after the second parameter in the sort order. * @user_data: data to pass to comparison function * * Inserts a new element into the list, using the given @@ -24942,7 +25813,8 @@ * This function iterates over the whole list. * </para></note> * - * Returns: the last element in the #GSList, or %NULL if the #GSList has no elements + * Returns: the last element in the #GSList, + * or %NULL if the #GSList has no elements */ @@ -24978,7 +25850,8 @@ * * Gets the element at the given position in a #GSList. * - * Returns: the element, or %NULL if the position is off the end of the #GSList + * Returns: the element, or %NULL if the position is off + * the end of the #GSList */ @@ -24989,7 +25862,8 @@ * * Gets the data of the element at the given position. * - * Returns: the element's data, or %NULL if the position is off the end of the #GSList + * Returns: the element's data, or %NULL if the position + * is off the end of the #GSList */ @@ -25001,7 +25875,8 @@ * Gets the position of the given element * in the #GSList (starting from 0). * - * Returns: the position of the element in the #GSList, or -1 if the element is not found + * Returns: the position of the element in the #GSList, + * or -1 if the element is not found */ @@ -25088,7 +25963,11 @@ /** * g_slist_sort: * @list: a #GSList - * @compare_func: the comparison function used to sort the #GSList. This function is passed the data from 2 elements of the #GSList and should return 0 if they are equal, a negative value if the first element comes before the second, or a positive value if the first element comes after the second. + * @compare_func: the comparison function used to sort the #GSList. + * This function is passed the data from 2 elements of the #GSList + * and should return 0 if they are equal, a negative value if the + * first element comes before the second, or a positive value if + * the first element comes after the second. * * Sorts a #GSList using the given comparison function. * @@ -25111,8 +25990,10 @@ /** * g_snprintf: * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the terminating nul character). - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @n: the maximum number of bytes to produce (including the + * terminating nul character). + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @...: the arguments to insert in the output. * * A safer form of the standard sprintf() function. The output is guaranteed @@ -25133,7 +26014,8 @@ * The format string may contain positional parameters, as specified in * the Single Unix Specification. * - * Returns: the number of bytes which would be produced if the buffer was large enough. + * Returns: the number of bytes which would be produced if the buffer + * was large enough. */ @@ -25164,7 +26046,8 @@ /** * g_source_add_poll: * @source: a #GSource - * @fd: a #GPollFD structure holding information about a file descriptor to watch. + * @fd: a #GPollFD structure holding information about a file + * descriptor to watch. * * Adds a file descriptor to the set of file descriptors polled for * this source. This is usually combined with g_source_new() to add an @@ -25208,7 +26091,8 @@ * Adds a #GSource to a @context so that it will be executed within * that context. Remove it by calling g_source_destroy(). * - * Returns: the ID (greater than 0) for the source within the #GMainContext. + * Returns: the ID (greater than 0) for the source within the + * #GMainContext. */ @@ -25246,7 +26130,9 @@ * g_main_current_source(). But calling this function on a source * whose #GMainContext has been destroyed is an error. * - * 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. + * 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. */ @@ -25344,29 +26230,29 @@ * idle_callback (gpointer data) * { * SomeWidget *self = data; - * + * * GDK_THREADS_ENTER (<!-- -->); * /<!-- -->* do stuff with self *<!-- -->/ * self->idle_id = 0; * GDK_THREADS_LEAVE (<!-- -->); - * + * * return G_SOURCE_REMOVE; * } - * + * * static void * some_widget_do_stuff_later (SomeWidget *self) * { * self->idle_id = g_idle_add (idle_callback, self); * } - * + * * static void * some_widget_finalize (GObject *object) * { * SomeWidget *self = SOME_WIDGET (object); - * + * * if (self->idle_id) * g_source_remove (self->idle_id); - * + * * G_OBJECT_CLASS (parent_class)->finalize (object); * } * ]| @@ -25382,14 +26268,14 @@ * idle_callback (gpointer data) * { * SomeWidget *self = data; - * + * * GDK_THREADS_ENTER (); * if (!g_source_is_destroyed (g_main_current_source ())) * { * /<!-- -->* do stuff with self *<!-- -->/ * } * GDK_THREADS_LEAVE (); - * + * * return FALSE; * } * ]| @@ -25420,7 +26306,8 @@ /** * g_source_new: - * @source_funcs: structure containing functions that implement the sources behavior. + * @source_funcs: structure containing functions that implement + * the sources behavior. * @struct_size: size of the #GSource structure to create. * * Creates a new #GSource structure. The size is specified to @@ -25510,7 +26397,8 @@ /** * g_source_remove_child_source: * @source: a #GSource - * @child_source: a #GSource previously passed to g_source_add_child_source(). + * @child_source: a #GSource previously passed to + * g_source_add_child_source(). * * Detaches @child_source from @source and destroys it. * @@ -25568,7 +26456,8 @@ * g_source_set_callback_indirect: * @source: the source * @callback_data: pointer to callback data "object" - * @callback_funcs: functions for reference counting @callback_data and getting the callback and data + * @callback_funcs: functions for reference counting @callback_data + * and getting the callback and data * * Sets the callback function storing the data as a refcounted callback * "object". This is used internally. Note that calling @@ -25653,7 +26542,8 @@ /** * g_source_set_ready_time: * @source: a #GSource - * @ready_time: the monotonic time at which the source will be ready, 0 for "immediately", -1 for "never" + * @ready_time: the monotonic time at which the source will be ready, + * 0 for "immediately", -1 for "never" * * Sets a #GSource to be dispatched when the given monotonic time is * reached (or passed). If the monotonic time is in the past (as it @@ -25697,7 +26587,8 @@ * The built-in array of primes ranges from 11 to 13845163 such that * each prime is approximately 1.5-2 times the previous prime. * - * Returns: the smallest prime number from a built-in array of primes which is larger than @num + * Returns: the smallest prime number from a built-in array of primes + * which is larger than @num */ @@ -26068,8 +26959,11 @@ /** * g_sprintf: - * @string: A pointer to a memory buffer to contain the resulting string. It is up to the caller to ensure that the allocated buffer is large enough to hold the formatted result - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @string: A pointer to a memory buffer to contain the resulting string. It + * is up to the caller to ensure that the allocated buffer is large + * enough to hold the formatted result + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @...: the arguments to insert in the output. * * An implementation of the standard sprintf() function which supports @@ -26088,7 +26982,8 @@ /** * g_stat: * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows) - * @buf: a pointer to a <structname>stat</structname> struct, which will be filled with the file information + * @buf: a pointer to a <structname>stat</structname> struct, which + * will be filled with the file information * * A wrapper for the POSIX stat() function. The stat() function * returns information about a file. On Windows the stat() function in @@ -26112,7 +27007,8 @@ * * See your C library manual for more details about stat(). * - * Returns: 0 if the information was successfully retrieved, -1 if an error occurred + * Returns: 0 if the information was successfully retrieved, -1 if an error + * occurred * Since: 2.6 */ @@ -26218,8 +27114,10 @@ * A case-insensitive string comparison, corresponding to the standard * strcasecmp() function on platforms which support it. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. - * Deprecated: 2.2: See g_strncasecmp() for a discussion of why this function is deprecated and how to replace it. + * 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. */ @@ -26278,7 +27176,8 @@ * * This function does the reverse conversion of g_strescape(). * - * Returns: a newly-allocated copy of @source with all escaped character compressed + * Returns: a newly-allocated copy of @source with all escaped + * character compressed */ @@ -26305,7 +27204,8 @@ /** * g_strdelimit: * @string: the string to convert - * @delimiters: (allow-none): a string containing the current delimiters, or %NULL to use the standard delimiters defined in #G_STR_DELIMITERS + * @delimiters: (allow-none): a string containing the current delimiters, or %NULL + * to use the standard delimiters defined in #G_STR_DELIMITERS * @new_delimiter: the new delimiter character * * Converts any delimiter characters in @string to @new_delimiter. @@ -26328,7 +27228,9 @@ * Converts a string to lower case. * * 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. + * 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. */ @@ -26346,7 +27248,8 @@ /** * g_strdup_printf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link> + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link> * @...: the parameters to insert into the format string * * Similar to the standard C sprintf() function but safer, since it @@ -26360,7 +27263,8 @@ /** * g_strdup_vprintf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link> + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link> * @args: the list of parameters to insert into the format string * * Similar to the standard C vsprintf() function but safer, since it @@ -26390,14 +27294,16 @@ /** * g_strerror: - * @errnum: the system error number. See the standard C %errno documentation + * @errnum: the system error number. See the standard C %errno + * documentation * * Returns a string corresponding to the given error code, e.g. * "no such process". You should use this function in preference to * strerror(), because it returns a string in UTF-8 encoding, and since * not all platforms support the strerror() function. * - * Returns: a UTF-8 string describing the error code. If the error code is unknown, it returns "unknown error (<code>)". + * Returns: a UTF-8 string describing the error code. If the error code + * is unknown, it returns "unknown error (<code>)". */ @@ -26415,7 +27321,8 @@ * * g_strcompress() does the reverse conversion. * - * Returns: a newly-allocated copy of @source with certain characters escaped. See above. + * Returns: a newly-allocated copy of @source with certain + * characters escaped. See above. */ @@ -26498,7 +27405,8 @@ * g_string_append_uri_escaped: * @string: a #GString * @unescaped: a string - * @reserved_chars_allowed: a string of reserved characters allowed to be used, or %NULL + * @reserved_chars_allowed: a string of reserved characters allowed + * to be used, or %NULL * @allow_utf8: set %TRUE if the escaped string may include UTF8 characters * * Appends @unescaped to @string, escaped any characters that @@ -26530,7 +27438,9 @@ * * Converts all uppercase ASCII letters to lowercase ASCII letters. * - * Returns: passed-in @string pointer, with all the uppercase characters converted to lowercase in place, with semantics that exactly match g_ascii_tolower(). + * Returns: passed-in @string pointer, with all the + * uppercase characters converted to lowercase in place, + * with semantics that exactly match g_ascii_tolower(). */ @@ -26540,13 +27450,16 @@ * * Converts all lowercase ASCII letters to uppercase ASCII letters. * - * Returns: passed-in @string pointer, with all the lowercase characters converted to uppercase in place, with semantics that exactly match g_ascii_toupper(). + * Returns: passed-in @string pointer, with all the + * lowercase characters converted to uppercase in place, + * with semantics that exactly match g_ascii_toupper(). */ /** * g_string_assign: - * @string: the destination #GString. Its current contents are destroyed. + * @string: the destination #GString. Its current contents + * are destroyed. * @rval: the string to copy into @string * * Copies the bytes from a string into a #GString, @@ -26597,7 +27510,8 @@ * by g_string_chunk_insert_const() when looking for * duplicates. * - * Returns: a pointer to the copy of @string within the #GStringChunk + * Returns: a pointer to the copy of @string within + * the #GStringChunk */ @@ -26620,7 +27534,8 @@ * pointer to a string added with g_string_chunk_insert(), even * if they do match. * - * Returns: a pointer to the new or existing copy of @string within the #GStringChunk + * Returns: a pointer to the new or existing copy of @string + * within the #GStringChunk */ @@ -26628,7 +27543,8 @@ * g_string_chunk_insert_len: * @chunk: a #GStringChunk * @string: bytes to insert - * @len: number of bytes of @string to insert, or -1 to insert a nul-terminated string + * @len: number of bytes of @string to insert, or -1 to insert a + * nul-terminated string * * Adds a copy of the first @len bytes of @string to the #GStringChunk. * The copy is nul-terminated. @@ -26647,7 +27563,10 @@ /** * g_string_chunk_new: - * @size: the default size of the blocks of memory which are allocated to store the strings. If a particular string is larger than this default size, a larger block of memory will be allocated for it. + * @size: the default size of the blocks of memory which are + * allocated to store the strings. If a particular string + * is larger than this default size, a larger block of + * memory will be allocated for it. * * Creates a new #GStringChunk. * @@ -26662,7 +27581,9 @@ * Converts a #GString to lowercase. * * 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. + * 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. */ @@ -26674,7 +27595,8 @@ * Compares two strings for equality, returning %TRUE if they are equal. * For use with #GHashTable. * - * Returns: %TRUE if the strings are the same length and contain the same bytes + * Returns: %TRUE if the strings are the same length and contain the + * same bytes */ @@ -26682,7 +27604,8 @@ * g_string_erase: * @string: a #GString * @pos: the position of the content to remove - * @len: the number of bytes to remove, or -1 to remove all following bytes + * @len: the number of bytes to remove, or -1 to remove all + * following bytes * * Removes @len bytes from a #GString, starting at position @pos. * The rest of the #GString is shifted down to fill the gap. @@ -26701,7 +27624,8 @@ * it's %FALSE, the caller gains ownership of the buffer and must * free it after use with g_free(). * - * Returns: the character data of @string (i.e. %NULL if @free_segment is %TRUE) + * Returns: the character data of @string + * (i.e. %NULL if @free_segment is %TRUE) */ @@ -26761,7 +27685,8 @@ /** * g_string_insert_len: * @string: a #GString - * @pos: position in @string where insertion should happen, or -1 for at the end + * @pos: position in @string where insertion should + * happen, or -1 for at the end * @val: bytes to insert * @len: number of bytes of @val to insert * @@ -26781,7 +27706,8 @@ /** * g_string_insert_unichar: * @string: a #GString - * @pos: the position at which to insert character, or -1 to append at the end of the string + * @pos: the position at which to insert character, or -1 + * to append at the end of the string * @wc: a Unicode character * * Converts a Unicode character into UTF-8, and insert it @@ -26931,7 +27857,8 @@ /** * g_string_sized_new: - * @dfl_size: the default size of the space allocated to hold the string + * @dfl_size: the default size of the space allocated to + * hold the string * * Creates a new #GString, with enough space for @dfl_size * bytes. This is useful if you are going to add a lot of @@ -26990,7 +27917,9 @@ * Converts a #GString to uppercase. * * 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. + * 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. */ @@ -27015,7 +27944,9 @@ * * An auxiliary function for gettext() support (see Q_()). * - * 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. + * 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 */ @@ -27029,7 +27960,8 @@ * optional @separator inserted between each of them. The returned string * should be freed with g_free(). * - * Returns: a newly-allocated string containing all of the strings joined together, with @separator between them + * Returns: a newly-allocated string containing all of the strings joined + * together, with @separator between them */ @@ -27042,7 +27974,8 @@ * optional @separator inserted between each of them. The returned string * should be freed with g_free(). * - * Returns: a newly-allocated string containing all of the strings joined together, with @separator between them + * Returns: a newly-allocated string containing all of the strings joined + * together, with @separator between them */ @@ -27050,7 +27983,8 @@ * g_strlcat: * @dest: destination buffer, already containing one nul-terminated string * @src: source buffer - * @dest_size: length of @dest buffer in bytes (not length of existing string inside @dest) + * @dest_size: length of @dest buffer in bytes (not length of existing string + * inside @dest) * * Portability wrapper that calls strlcat() on systems which have it, * and emulates it otherwise. Appends nul-terminated @src string to @dest, @@ -27067,7 +28001,9 @@ * strcat() or strncat(), but for real security g_strconcat() is harder * to mess up.</para></note> * - * Returns: size of attempted result, which is MIN (dest_size, strlen (original dest)) + strlen (src), so if retval >= dest_size, truncation occurred. + * Returns: size of attempted result, which is MIN (dest_size, strlen + * (original dest)) + strlen (src), so if retval >= dest_size, + * truncation occurred. */ @@ -27107,8 +28043,22 @@ * It is similar to g_strcasecmp() except it only compares the first @n * characters of the strings. * - * Returns: 0 if the strings match, a negative value if @s1 < @s2, or a positive value if @s1 > @s2. - * Deprecated: 2.2: The problem with g_strncasecmp() is that it does the comparison by calling toupper()/tolower(). These functions are locale-specific and operate on single bytes. However, it is impossible to handle things correctly from an I18N standpoint by operating on bytes, since characters may be multibyte. Thus g_strncasecmp() is broken if your string is guaranteed to be ASCII, since it's locale-sensitive, and it's broken if your string is localized, since it doesn't work on many encodings at all, including UTF-8, EUC-JP, etc. There are therefore two replacement techniques: g_ascii_strncasecmp(), which only works on ASCII and is not locale-sensitive, and g_utf8_casefold() followed by strcmp() on the resulting strings, which is good for case-insensitive sorting of UTF-8. + * 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 techniques: g_ascii_strncasecmp(), + * which only works on ASCII and is not locale-sensitive, and + * g_utf8_casefold() followed by strcmp() on the resulting strings, which is + * good for case-insensitive sorting of UTF-8. */ @@ -27128,7 +28078,8 @@ * g_utf8_strncpy() instead. * </para></note> * - * Returns: a newly-allocated buffer containing the first @n bytes of @str, nul-terminated + * Returns: a newly-allocated buffer containing the first @n bytes + * of @str, nul-terminated */ @@ -27168,7 +28119,8 @@ * Searches the string @haystack for the last occurrence * of the string @needle. * - * Returns: a pointer to the found occurrence, or %NULL if not found. + * Returns: a pointer to the found occurrence, or + * %NULL if not found. */ @@ -27182,28 +28134,34 @@ * of the string @needle, limiting the length of the search * to @haystack_len. * - * Returns: a pointer to the found occurrence, or %NULL if not found. + * Returns: a pointer to the found occurrence, or + * %NULL if not found. */ /** * g_strsignal: - * @signum: the signal number. See the <literal>signal</literal> documentation + * @signum: the signal number. See the <literal>signal</literal> + * documentation * * Returns a string describing the given signal, e.g. "Segmentation fault". * You should use this function in preference to strsignal(), because it * returns a string in UTF-8 encoding, and since not all platforms support * the strsignal() function. * - * Returns: a UTF-8 string describing the signal. If the signal is unknown, it returns "unknown signal (<signum>)". + * Returns: a UTF-8 string describing the signal. If the signal is unknown, + * it returns "unknown signal (<signum>)". */ /** * g_strsplit: * @string: a string to split - * @delimiter: a string which specifies the places at which to split the string. The delimiter is not included in any of the resulting strings, unless @max_tokens is reached. - * @max_tokens: the maximum number of pieces to split @string into. If this is less than 1, the string is split completely. + * @delimiter: a string which specifies the places at which to split + * the string. The delimiter is not included in any of the resulting + * strings, unless @max_tokens is reached. + * @max_tokens: the maximum number of pieces to split @string into. + * If this is less than 1, the string is split completely. * * Splits a string into a maximum of @max_tokens pieces, using the given * @delimiter. If @max_tokens is reached, the remainder of @string is @@ -27216,15 +28174,18 @@ * to represent empty elements, you'll need to check for the empty string * before calling g_strsplit(). * - * Returns: a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: a newly-allocated %NULL-terminated array of strings. Use + * g_strfreev() to free it. */ /** * g_strsplit_set: * @string: The string to be tokenized - * @delimiters: A nul-terminated string containing bytes that are used to split the string. - * @max_tokens: The maximum number of tokens to split @string into. If this is less than 1, the string is split completely + * @delimiters: A nul-terminated string containing bytes that are used + * to split the string. + * @max_tokens: The maximum number of tokens to split @string into. + * If this is less than 1, the string is split completely * * Splits @string into a number of tokens not containing any of the characters * in @delimiter. A token is the (possibly empty) longest string that does not @@ -27248,7 +28209,8 @@ * 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. * - * Returns: a newly-allocated %NULL-terminated array of strings. Use g_strfreev() to free it. + * Returns: a newly-allocated %NULL-terminated array of strings. Use + * g_strfreev() to free it. * Since: 2.4 */ @@ -27256,14 +28218,17 @@ /** * g_strstr_len: * @haystack: a string - * @haystack_len: the maximum length of @haystack. Note that -1 is a valid length, if @haystack is nul-terminated, meaning it will search through the whole string. + * @haystack_len: the maximum length of @haystack. Note that -1 is + * a valid length, if @haystack is nul-terminated, meaning it will + * search through the whole string. * @needle: the string to search for * * Searches the string @haystack for the first occurrence * of the string @needle, limiting the length of the search * to @haystack_len. * - * Returns: a pointer to the found occurrence, or %NULL if not found. + * Returns: a pointer to the found occurrence, or + * %NULL if not found. */ @@ -27281,7 +28246,8 @@ /** * g_strtod: * @nptr: the string to convert to a numeric value. - * @endptr: if non-%NULL, it returns the character after the last character used in the conversion. + * @endptr: if non-%NULL, it returns the character after + * the last character used in the conversion. * * Converts a string to a #gdouble value. * It calls the standard strtod() function to handle the conversion, but @@ -27306,7 +28272,8 @@ * Converts a string to upper case. * * Returns: the string - * Deprecated: 2.2: This function is totally broken for the reasons discussed in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead. + * Deprecated: 2.2: This function is totally broken for the reasons discussed + * in the g_strncasecmp() docs - use g_ascii_strup() or g_utf8_strup() instead. */ @@ -27517,7 +28484,8 @@ * g_test_expect_message: * @log_domain: (allow-none): the log domain of the message * @log_level: the log level of the message - * @pattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @pattern: a glob-style + * <link linkend="glib-Glob-style-pattern-matching">pattern</link> * * Indicates that a message with the given @log_domain and @log_level, * with text matching @pattern, is expected to be logged. When this @@ -27662,8 +28630,10 @@ /** * g_test_init: - * @argc: Address of the @argc parameter of the main() function. Changed if any arguments were handled. - * @argv: Address of the @argv parameter of main(). Any parameters understood by g_test_init() stripped before return. + * @argc: Address of the @argc parameter of the main() function. + * Changed if any arguments were handled. + * @argv: Address of the @argv parameter of main(). + * Any parameters understood by g_test_init() stripped before return. * @...: Reserved for future extension. Currently, you must pass %NULL. * * Initialize the GLib testing framework, e.g. by seeding the @@ -28083,7 +29053,8 @@ * Returns %TRUE (after g_test_init() has been called) if the test * program is running under g_test_trap_subprocess(). * - * Returns: %TRUE if the test program is running under g_test_trap_subprocess(). + * Returns: %TRUE if the test program is running under + * g_test_trap_subprocess(). * Since: 2.38 */ @@ -28178,7 +29149,8 @@ /** * g_test_trap_assert_stderr: - * @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @serrpattern: a glob-style + * <link linkend="glib-Glob-style-pattern-matching">pattern</link> * * Assert that the stderr output of the last test subprocess * matches @serrpattern. See g_test_trap_subprocess(). @@ -28196,7 +29168,8 @@ /** * g_test_trap_assert_stderr_unmatched: - * @serrpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @serrpattern: a glob-style + * <link linkend="glib-Glob-style-pattern-matching">pattern</link> * * Assert that the stderr output of the last test subprocess * does not match @serrpattern. See g_test_trap_subprocess(). @@ -28207,7 +29180,8 @@ /** * g_test_trap_assert_stdout: - * @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @soutpattern: a glob-style + * <link linkend="glib-Glob-style-pattern-matching">pattern</link> * * Assert that the stdout output of the last test subprocess matches * @soutpattern. See g_test_trap_subprocess(). @@ -28218,7 +29192,8 @@ /** * g_test_trap_assert_stdout_unmatched: - * @soutpattern: a glob-style <link linkend="glib-Glob-style-pattern-matching">pattern</link> + * @soutpattern: a glob-style + * <link linkend="glib-Glob-style-pattern-matching">pattern</link> * * Assert that the stdout output of the last test subprocess * does not match @soutpattern. See g_test_trap_subprocess(). @@ -28263,7 +29238,9 @@ * * Returns: %TRUE for the forked child and %FALSE for the executing parent process. * Since: 2.16 - * Deprecated: This function is implemented only on Unix platforms, and is not always reliable due to problems inherent in fork-without-exec. Use g_test_trap_subprocess() instead. + * Deprecated: This function is implemented only on Unix platforms, + * and is not always reliable due to problems inherent in + * fork-without-exec. Use g_test_trap_subprocess() instead. */ @@ -28487,7 +29464,9 @@ * If this function returns 0, threads waiting in the thread * pool for new work are not stopped. * - * Returns: the maximum @interval (milliseconds) to wait for new tasks in the thread pool before stopping the thread + * Returns: the maximum @interval (milliseconds) to wait + * for new tasks in the thread pool before stopping the + * thread * Since: 2.10 */ @@ -28533,8 +29512,10 @@ /** * g_thread_pool_new: * @func: a function to execute in the threads of the new thread pool - * @user_data: user data that is handed over to @func every time it is called - * @max_threads: the maximal number of threads to execute concurrently in the new thread pool, -1 means no limit + * @user_data: user data that is handed over to @func every time it + * is called + * @max_threads: the maximal number of threads to execute concurrently + * in the new thread pool, -1 means no limit * @exclusive: should this thread pool be exclusive? * @error: return location for error, or %NULL * @@ -28592,7 +29573,8 @@ /** * g_thread_pool_set_max_idle_time: - * @interval: the maximum @interval (in milliseconds) a thread can be idle + * @interval: the maximum @interval (in milliseconds) + * a thread can be idle * * This function will set the maximum @interval that a thread * waiting in the pool for new tasks can be idle for before @@ -28611,7 +29593,8 @@ /** * g_thread_pool_set_max_threads: * @pool: a #GThreadPool - * @max_threads: a new maximal number of threads for @pool, or -1 for unlimited + * @max_threads: a new maximal number of threads for @pool, + * or -1 for unlimited * @error: return location for error, or %NULL * * Sets the maximal allowed number of threads for @pool. @@ -28654,7 +29637,12 @@ /** * g_thread_pool_set_sort_function: * @pool: a #GThreadPool - * @func: the #GCompareDataFunc used to sort the list of tasks. This function is passed two tasks. It should return 0 if the order in which they are handled does not matter, a negative value if the first task should be processed before the second or a positive value if the second task should be processed first. + * @func: the #GCompareDataFunc used to sort the list of tasks. + * This function is passed two tasks. It should return + * 0 if the order in which they are handled does not matter, + * a negative value if the first task should be processed before + * the second or a positive value if the second task should be + * processed first. * @user_data: user data passed to @func * * Sets the function used to sort the list of tasks. This allows the @@ -28919,7 +29907,8 @@ * arrive at local time for @tz (ie: negative numbers for time zones * west of GMT, positive numbers for east). * - * Returns: the number of seconds that should be added to UTC to get the local time in @tz + * Returns: the number of seconds that should be added to UTC to get the + * local time in @tz * Since: 2.26 */ @@ -29070,7 +30059,8 @@ /** * g_timeout_add: - * @interval: the time between calls to the function, in milliseconds (1/1000ths of a second) + * @interval: the time between calls to the function, in milliseconds + * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * @@ -29104,8 +30094,10 @@ /** * g_timeout_add_full: (rename-to g_timeout_add) - * @priority: the priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. - * @interval: the time between calls to the function, in milliseconds (1/1000ths of a second) + * @priority: the priority of the timeout source. Typically this will be in + * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * @interval: the time between calls to the function, in milliseconds + * (1/1000ths of a second) * @function: function to call * @data: data to pass to @function * @notify: (allow-none): function to call when the timeout is removed, or %NULL @@ -29164,7 +30156,8 @@ /** * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds) - * @priority: the priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * @priority: the priority of the timeout source. Typically this will be in + * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * @interval: the time between calls to the function, in seconds * @function: function to call * @data: data to pass to @function @@ -29270,7 +30263,9 @@ /** * 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 + * @microseconds: return location for the fractional part of seconds + * elapsed, in microseconds (that is, the total number + * of microseconds elapsed, modulo 1000000), or %NULL * * If @timer has been started but not stopped, obtains the time since * the timer was started. If @timer has been stopped, obtains the @@ -29279,7 +30274,8 @@ * including any fractional part. The @microseconds out parameter is * essentially useless. * - * Returns: seconds elapsed as a floating point value, including any fractional part. + * Returns: seconds elapsed as a floating point value, including any + * fractional part. */ @@ -29382,7 +30378,8 @@ /** * g_tree_foreach: * @tree: a #GTree. - * @func: the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. + * @func: the function to call for each node visited. + * If this function returns %TRUE, the traversal is stopped. * @user_data: user data to pass to the function. * * Calls the given function for each of the key/value pairs in the #GTree. @@ -29436,7 +30433,8 @@ * automatically balanced as key/value pairs are added, key lookup is very * fast. * - * Returns: the value corresponding to the key, or %NULL if the key was not found. + * Returns: the value corresponding to the key, or %NULL if the key was + * not found. */ @@ -29458,7 +30456,11 @@ /** * g_tree_new: - * @key_compare_func: the function used to order the nodes in the #GTree. It should return values similar to the standard strcmp() function - 0 if the two arguments are equal, a negative value if the first argument comes before the second, or a positive value if the first argument comes after the second. + * @key_compare_func: the function used to order the nodes in the #GTree. + * It should return values similar to the standard strcmp() function - + * 0 if the two arguments are equal, a negative value if the first argument + * comes before the second, or a positive value if the first argument comes + * after the second. * * Creates a new #GTree. * @@ -29470,8 +30472,12 @@ * g_tree_new_full: * @key_compare_func: qsort()-style comparison function. * @key_compare_data: data to pass to comparison function. - * @key_destroy_func: a function to free the memory allocated for the key used when removing the entry from the #GTree or %NULL if you don't want to supply such a function. - * @value_destroy_func: a function to free the memory allocated for the value used when removing the entry from the #GTree or %NULL if you don't want to supply such a function. + * @key_destroy_func: a function to free the memory allocated for the key + * used when removing the entry from the #GTree or %NULL if you don't + * want to supply such a function. + * @value_destroy_func: a function to free the memory allocated for the + * value used when removing the entry from the #GTree or %NULL if you + * don't want to supply such a function. * * Creates a new #GTree like g_tree_new() and allows to specify functions * to free the memory allocated for the key and value that get called when @@ -29527,7 +30533,8 @@ * make sure that any dynamically allocated values are freed yourself. * If the key does not exist in the #GTree, the function does nothing. * - * Returns: %TRUE if the key was found (prior to 2.8, this function returned nothing) + * Returns: %TRUE if the key was found (prior to 2.8, this function returned + * nothing) */ @@ -29565,7 +30572,8 @@ * @search_func returns 1, searching will proceed among the key/value * pairs that have a larger key. * - * Returns: the value corresponding to the found key, or %NULL if the key was not found. + * Returns: the value corresponding to the found key, or %NULL if + * the key was not found. */ @@ -29579,20 +30587,26 @@ * * If the key does not exist in the #GTree, the function does nothing. * - * Returns: %TRUE if the key was found (prior to 2.8, this function returned nothing) + * Returns: %TRUE if the key was found (prior to 2.8, this function returned + * nothing) */ /** * g_tree_traverse: * @tree: a #GTree. - * @traverse_func: the function to call for each node visited. If this function returns %TRUE, the traversal is stopped. - * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, %G_PRE_ORDER and %G_POST_ORDER. + * @traverse_func: the function to call for each node visited. If this + * function returns %TRUE, the traversal is stopped. + * @traverse_type: the order in which nodes are visited, one of %G_IN_ORDER, + * %G_PRE_ORDER and %G_POST_ORDER. * @user_data: user data to pass to the function. * * 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>. */ @@ -29690,30 +30704,50 @@ /** * g_ucs4_to_utf16: * @str: a UCS-4 encoded string - * @len: the maximum length (number of characters) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of bytes read, or %NULL. If an error occurs then the index of the invalid input is stored here. - * @items_written: (allow-none): location to store number of <type>gunichar2</type> written, or %NULL. The value stored here does not include the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of characters) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of bytes read, or %NULL. + * If an error occurs then the index of the invalid input + * is stored here. + * @items_written: (allow-none): location to store number of <type>gunichar2</type> + * written, or %NULL. The value stored here does not + * include the trailing 0. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UCS-4 to UTF-16. A 0 character will be * added to the result after the converted text. * - * Returns: a pointer to a newly allocated UTF-16 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set. + * 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. */ /** * g_ucs4_to_utf8: * @str: a UCS-4 encoded string - * @len: the maximum length (number of characters) of @str to use. If @len < 0, then the string is nul-terminated. + * @len: the maximum length (number of characters) of @str to use. + * If @len < 0, then the string is nul-terminated. * @items_read: (allow-none): location to store number of characters read, or %NULL. - * @items_written: (allow-none): location to store number of bytes written or %NULL. The value here stored does not include the trailing 0 byte. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @items_written: (allow-none): location to store number of bytes written or %NULL. + * The value here stored does not include the trailing 0 + * byte. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * 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. * - * 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. + * 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. */ @@ -29811,7 +30845,8 @@ * Determines the numeric value of a character as a decimal * digit. * - * Returns: If @c is a decimal digit (according to g_unichar_isdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a decimal digit (according to + * g_unichar_isdigit()), its numeric value. Otherwise, -1. */ @@ -30116,7 +31151,9 @@ /** * g_unichar_to_utf8: * @c: a Unicode character code - * @outbuf: output buffer, must have at least 6 bytes of space. If %NULL, the length will be computed and returned and nothing will be written to @outbuf. + * @outbuf: output buffer, must have at least 6 bytes of space. + * If %NULL, the length will be computed and returned + * and nothing will be written to @outbuf. * * Converts a single character to UTF-8. * @@ -30130,7 +31167,9 @@ * * Converts a character 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. + * 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. */ @@ -30140,7 +31179,9 @@ * * Converts a character to the titlecase. * - * Returns: the result of converting @c to titlecase. If @c is not an uppercase or lowercase character, @c is returned unchanged. + * Returns: the result of converting @c to titlecase. + * If @c is not an uppercase or lowercase character, + * @c is returned unchanged. */ @@ -30150,7 +31191,9 @@ * * Converts a character 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. + * 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. */ @@ -30183,7 +31226,8 @@ * Determines the numeric value of a character as a hexidecimal * digit. * - * Returns: If @c is a hex digit (according to g_unichar_isxdigit()), its numeric value. Otherwise, -1. + * Returns: If @c is a hex digit (according to + * g_unichar_isxdigit()), its numeric value. Otherwise, -1. */ @@ -30194,8 +31238,10 @@ * * Computes the canonical decomposition of a Unicode character. * - * 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. + * 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. */ @@ -30224,7 +31270,9 @@ * See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the * representation of names of scripts</ulink> for details. * - * 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. + * 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 */ @@ -30242,7 +31290,9 @@ * See <ulink url="http://unicode.org/iso15924/codelists.html">Codes for the * representation of names of scripts</ulink> for details. * - * 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. + * 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 */ @@ -30363,7 +31413,8 @@ /** * g_unix_signal_add_full: (rename-to g_unix_signal_add) - * @priority: the priority of the signal source. Typically this will be in the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + * @priority: the priority of the signal source. Typically this will be in + * the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * @signum: Signal number * @handler: Callback * @user_data: Data for @handler @@ -30426,7 +31477,8 @@ * that on Windows, it is in general not possible to delete files that * are open to some process, or mapped into memory. * - * Returns: 0 if the name was successfully deleted, -1 if an error occurred + * Returns: 0 if the name was successfully deleted, -1 if an error + * occurred * Since: 2.6 */ @@ -30462,7 +31514,8 @@ /** * g_uri_escape_string: * @unescaped: the unescaped input string. - * @reserved_chars_allowed: (allow-none): a string of reserved characters that are allowed to be used, or %NULL. + * @reserved_chars_allowed: (allow-none): a string of reserved characters that + * are allowed to be used, or %NULL. * @allow_utf8: %TRUE if the result can include UTF-8 characters. * * Escapes a string for use in a URI. @@ -30474,7 +31527,8 @@ * specification, since those are allowed unescaped in some portions of * a URI. * - * Returns: an escaped version of @unescaped. The returned string should be freed when no longer needed. + * Returns: an escaped version of @unescaped. The returned string should be + * freed when no longer needed. * Since: 2.16 */ @@ -30487,7 +31541,9 @@ * mime type defined in RFC 2483 into individual URIs, * discarding any comments. The URIs are not validated. * - * Returns: (transfer full): a newly allocated %NULL-terminated list of strings holding the individual URIs. The array should be freed with g_strfreev(). + * Returns: (transfer full): a newly allocated %NULL-terminated list + * of strings holding the individual URIs. The array should be freed + * with g_strfreev(). * Since: 2.6 */ @@ -30502,7 +31558,8 @@ * </programlisting> * Common schemes include "file", "http", "svn+ssh", etc. * - * Returns: The "Scheme" component of the URI, or %NULL on error. The returned string should be freed when no longer needed. + * Returns: The "Scheme" component of the URI, or %NULL on error. + * The returned string should be freed when no longer needed. * Since: 2.16 */ @@ -30521,7 +31578,10 @@ * slash being expanded in an escaped path element, which might confuse pathname * handling. * - * 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. + * 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 */ @@ -30529,7 +31589,8 @@ /** * g_uri_unescape_string: * @escaped_string: an escaped string to be unescaped. - * @illegal_characters: (allow-none): a string of illegal characters not to be allowed, or %NULL. + * @illegal_characters: (allow-none): a string of illegal characters not to be + * allowed, or %NULL. * * Unescapes a whole escaped string. * @@ -30539,7 +31600,8 @@ * slash being expanded in an escaped path element, which might confuse pathname * handling. * - * Returns: an unescaped version of @escaped_string. The returned string should be freed when no longer needed. + * Returns: an unescaped version of @escaped_string. The returned string + * should be freed when no longer needed. * Since: 2.16 */ @@ -30560,25 +31622,46 @@ /** * g_utf16_to_ucs4: * @str: a UTF-16 encoded string - * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. - * @items_written: (allow-none): location to store number of characters written, or %NULL. The value stored here does not include the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of words read, or %NULL. + * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial + * character. If an error occurs then the index of the + * invalid input is stored here. + * @items_written: (allow-none): location to store number of characters written, or %NULL. + * The value stored here does not include the trailing + * 0 character. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UCS-4. The result will be * nul-terminated. * - * Returns: a pointer to a newly allocated UCS-4 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set. + * 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. */ /** * g_utf16_to_utf8: * @str: a UTF-16 encoded string - * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. - * @items_written: (allow-none): location to store number of bytes written, or %NULL. The value stored here does not include the trailing 0 byte. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of <type>gunichar2</type>) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of words read, or %NULL. + * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial + * character. If an error occurs then the index of the + * invalid input is stored here. + * @items_written: (allow-none): location to store number of bytes written, or %NULL. + * The value stored here does not include the trailing + * 0 byte. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-16 to UTF-8. The result will be * terminated with a 0 byte. @@ -30594,7 +31677,10 @@ * be correctly interpreted as UTF-16, i.e. it doesn't contain * things unpaired surrogates. * - * Returns: a pointer to a newly allocated UTF-8 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set. + * 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. */ @@ -30615,7 +31701,8 @@ * takes case sensitivity into account. GLib does not currently * provide such a function. * - * Returns: a newly allocated string, that is a case independent form of @str. + * Returns: a newly allocated string, that is a + * case independent form of @str. */ @@ -30631,7 +31718,8 @@ * compare the keys with strcmp() when sorting instead of sorting * the original strings. * - * Returns: < 0 if @str1 compares before @str2, 0 if they compare equal, > 0 if @str1 compares after @str2. + * Returns: < 0 if @str1 compares before @str2, + * 0 if they compare equal, > 0 if @str1 compares after @str2. */ @@ -30651,7 +31739,8 @@ * Note that this function depends on the * <link linkend="setlocale">current locale</link>. * - * Returns: a newly allocated string. This string should be freed with g_free() when you are done with it. + * Returns: a newly allocated string. This string should + * be freed with g_free() when you are done with it. */ @@ -30673,7 +31762,8 @@ * Note that this function depends on the * <link linkend="setlocale">current locale</link>. * - * Returns: a newly allocated string. This string should be freed with g_free() when you are done with it. + * Returns: a newly allocated string. This string should + * be freed with g_free() when you are done with it. * Since: 2.8 */ @@ -30681,7 +31771,8 @@ /** * g_utf8_find_next_char: * @p: a pointer to a position within a UTF-8 encoded string - * @end: a pointer to the byte following the end of the string, or %NULL to indicate that the string is nul-terminated. + * @end: a pointer to the byte following the end of the string, + * or %NULL to indicate that the string is nul-terminated. * * Finds the start of the next UTF-8 character in the string after @p. * @@ -30727,14 +31818,19 @@ /** * g_utf8_get_char_validated: * @p: a pointer to Unicode character encoded as UTF-8 - * @max_len: the maximum number of bytes to read, or -1, for no maximum or if @p is nul-terminated + * @max_len: the maximum number of bytes to read, or -1, for no maximum or + * if @p is nul-terminated * * Convert a sequence of bytes encoded as UTF-8 to a Unicode character. * This function checks for incomplete characters, for invalid characters * such as characters that are out of the range of Unicode, and for * overlong encodings of valid characters. * - * Returns: the resulting character. If @p points to a partial sequence at the end of a string that could begin a valid character (or if @max_len is zero), returns (gunichar)-2; otherwise, if @p does not point to a valid UTF-8 encoded Unicode character, returns (gunichar)-1. + * 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. */ @@ -30770,7 +31866,9 @@ * a legacy encoding or pass it to a system with * less capable Unicode handling. * - * Returns: a newly allocated string, that is the normalized form of @str, or %NULL if @str is not valid UTF-8. + * Returns: a newly allocated string, that is the + * normalized form of @str, or %NULL if @str is not + * valid UTF-8. */ @@ -30840,7 +31938,9 @@ * in a UTF-8 encoded string, while limiting the search to @len bytes. * If @len is -1, allow unbounded search. * - * Returns: %NULL if the string does not contain the character, otherwise, a pointer to the start of the leftmost occurrence of the character in the string. + * 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. */ @@ -30854,14 +31954,19 @@ * on the current locale, and may result in the number of * characters in the string changing. * - * Returns: a newly allocated string, with all characters converted to lowercase. + * Returns: a newly allocated string, with all characters + * converted to lowercase. */ /** * g_utf8_strlen: * @p: pointer to the start of a UTF-8 encoded string - * @max: the maximum number of bytes to examine. If @max is less than 0, then the string is assumed to be nul-terminated. If @max is 0, @p will not be examined and may be %NULL. If @max is greater than 0, up to @max bytes are examined + * @max: the maximum number of bytes to examine. If @max + * is less than 0, then the string is assumed to be + * nul-terminated. If @max is 0, @p will not be examined and + * may be %NULL. If @max is greater than 0, up to @max + * bytes are examined * * Computes the length of the string in characters, not including * the terminating nul character. If the @max'th byte falls in the @@ -30897,14 +32002,17 @@ * in a UTF-8 encoded string, while limiting the search to @len bytes. * If @len is -1, allow unbounded search. * - * Returns: %NULL if the string does not contain the character, otherwise, a pointer to the start of the rightmost occurrence of the character in the string. + * 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. */ /** * g_utf8_strreverse: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, then the string is nul-terminated. + * @len: the maximum length of @str to use, in bytes. If @len < 0, + * then the string is nul-terminated. * * Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. * (Use g_utf8_validate() on all text before trying to use UTF-8 @@ -30936,7 +32044,8 @@ * characters in the string increasing. (For instance, the * German ess-zet will be changed to SS.) * - * Returns: a newly allocated string, with all characters converted to uppercase. + * Returns: a newly allocated string, with all characters + * converted to uppercase. */ @@ -30950,7 +32059,8 @@ * The substring will contain @end_pos - @start_pos * characters. * - * Returns: a newly allocated copy of the requested substring. Free with g_free() when no longer needed. + * Returns: a newly allocated copy of the requested + * substring. Free with g_free() when no longer needed. * Since: 2.30 */ @@ -30958,24 +32068,38 @@ /** * g_utf8_to_ucs4: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. - * @items_written: (allow-none): location to store number of characters written or %NULL. The value here stored does not include the trailing 0 character. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length of @str to use, in bytes. If @len < 0, + * then the string is nul-terminated. + * @items_read: (allow-none): location to store number of bytes read, or %NULL. + * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial + * character. If an error occurs then the index of the + * invalid input is stored here. + * @items_written: (allow-none): location to store number of characters written or %NULL. + * The value here stored does not include the trailing 0 + * character. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4. A trailing 0 character will be added to the * string after the converted text. * - * Returns: a pointer to a newly allocated UCS-4 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set. + * 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. */ /** * g_utf8_to_ucs4_fast: * @str: a UTF-8 encoded string - * @len: the maximum length of @str to use, in bytes. If @len < 0, then the string is nul-terminated. - * @items_written: (allow-none): location to store the number of characters in the result, or %NULL. + * @len: the maximum length of @str to use, in bytes. If @len < 0, + * then the string is nul-terminated. + * @items_written: (allow-none): location to store the number of characters in the + * result, or %NULL. * * Convert a string from UTF-8 to a 32-bit fixed width * representation as UCS-4, assuming valid UTF-8 input. @@ -30983,22 +32107,35 @@ * but does no error checking on the input. A trailing 0 character * will be added to the string after the converted text. * - * Returns: a pointer to a newly allocated UCS-4 string. This value must be freed with g_free(). + * Returns: a pointer to a newly allocated UCS-4 string. + * This value must be freed with g_free(). */ /** * g_utf8_to_utf16: * @str: a UTF-8 encoded string - * @len: the maximum length (number of bytes) of @str to use. If @len < 0, then the string is nul-terminated. - * @items_read: (allow-none): location to store number of bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. - * @items_written: (allow-none): location to store number of <type>gunichar2</type> written, or %NULL. The value stored here does not include the trailing 0. - * @error: location to store the error occurring, or %NULL to ignore errors. Any of the errors in #GConvertError other than %G_CONVERT_ERROR_NO_CONVERSION may occur. + * @len: the maximum length (number of bytes) of @str to use. + * If @len < 0, then the string is nul-terminated. + * @items_read: (allow-none): location to store number of bytes read, or %NULL. + * If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + * returned in case @str contains a trailing partial + * character. If an error occurs then the index of the + * invalid input is stored here. + * @items_written: (allow-none): location to store number of <type>gunichar2</type> written, + * or %NULL. + * The value stored here does not include the trailing 0. + * @error: location to store the error occurring, or %NULL to ignore + * errors. Any of the errors in #GConvertError other than + * %G_CONVERT_ERROR_NO_CONVERSION may occur. * * Convert a string from UTF-8 to UTF-16. A 0 character will be * added to the result after the converted text. * - * Returns: a pointer to a newly allocated UTF-16 string. This value must be freed with g_free(). If an error occurs, %NULL will be returned and @error set. + * 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. */ @@ -31039,7 +32176,8 @@ * See your C library manual for more details about how utime() works * on your system. * - * Returns: 0 if the operation was successful, -1 if an error occurred + * Returns: 0 if the operation was successful, -1 if an error + * occurred * Since: 2.18 */ @@ -31383,7 +32521,9 @@ * If you only require an equality comparison, g_variant_equal() is more * general. * - * Returns: negative value if a < b; zero if a = b; positive value if a > b. + * Returns: negative value if a < b; + * zero if a = b; + * positive value if a > b. * Since: 2.26 */ @@ -31391,14 +32531,16 @@ /** * g_variant_dup_bytestring: * @value: an array-of-bytes #GVariant instance - * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store the length (not including the nul terminator) + * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store + * the length (not including the nul terminator) * * Similar to g_variant_get_bytestring() except that instead of * returning a constant string, the string is duplicated. * * The return value must be freed using g_free(). * - * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): a newly allocated string + * Returns: (transfer full) (array zero-terminated=1 length=length) (element-type guint8): + * a newly allocated string * Since: 2.26 */ @@ -31573,7 +32715,8 @@ * * The return value remains valid as long as @value exists. * - * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): the constant string + * Returns: (transfer none) (array zero-terminated=1) (element-type guint8): + * the constant string * Since: 2.26 */ @@ -31750,7 +32893,8 @@ * @n_elements, which must be non-%NULL is set equal to the number of * items in the array. * - * Returns: (array length=n_elements) (transfer none): a pointer to the fixed array + * Returns: (array length=n_elements) (transfer none): a pointer to + * the fixed array * Since: 2.24 */ @@ -31898,7 +33042,8 @@ /** * g_variant_get_string: * @value: a string #GVariant instance - * @length: (allow-none) (default 0) (out): a pointer to a #gsize, to store the length + * @length: (allow-none) (default 0) (out): a pointer to a #gsize, + * to store the length * * Returns the string value of a #GVariant instance with a string * type. This includes the types %G_VARIANT_TYPE_STRING, @@ -32014,7 +33159,8 @@ * g_variant_get_va: (skip) * @value: a #GVariant * @format_string: a string that is prefixed with a format string - * @endptr: (allow-none) (default NULL): location to store the end pointer, or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * @app: a pointer to a #va_list * * This function is intended to be used by libraries based on #GVariant @@ -32295,7 +33441,8 @@ * see the section on * <link linkend='gvariant-format-strings-pointers'>GVariant Format Strings</link>. * - * Returns: %TRUE if a value was unpacked, or %FALSE if there was no value + * Returns: %TRUE if a value was unpacked, or %FALSE if there was no + * value * Since: 2.24 */ @@ -32534,7 +33681,8 @@ /** * g_variant_new_array: * @child_type: (allow-none): the element type of the new array - * @children: (allow-none) (array length=n_children): an array of #GVariant pointers, the children + * @children: (allow-none) (array length=n_children): an array of + * #GVariant pointers, the children * @n_children: the length of @children * * Creates a new #GVariant array from @children. @@ -32582,7 +33730,8 @@ /** * g_variant_new_bytestring: - * @string: (array zero-terminated=1) (element-type guint8): a normal nul-terminated string in no particular encoding + * @string: (array zero-terminated=1) (element-type guint8): a normal + * nul-terminated string in no particular encoding * * Creates an array-of-bytes #GVariant with the contents of @string. * This function is just like g_variant_new_string() except that the @@ -32895,7 +34044,8 @@ * g_variant_new_string() but it saves a temporary variable and an * unnecessary copy. * - * Returns: (transfer none): a floating reference to a new string #GVariant instance + * Returns: (transfer none): a floating reference to a new string + * #GVariant instance * Since: 2.38 */ @@ -32956,7 +34106,8 @@ * it to this function. It is even possible that @string is immediately * freed. * - * Returns: (transfer none): a floating reference to a new string #GVariant instance + * Returns: (transfer none): a floating reference to a new string + * #GVariant instance * Since: 2.38 */ @@ -33016,7 +34167,8 @@ /** * g_variant_new_va: (skip) * @format_string: a string that is prefixed with a format string - * @endptr: (allow-none) (default NULL): location to store the end pointer, or %NULL + * @endptr: (allow-none) (default NULL): location to store the end pointer, + * or %NULL * @app: a pointer to a #va_list * * This function is intended to be used by libraries based on @@ -33118,7 +34270,8 @@ /** * g_variant_print: * @value: a #GVariant - * @type_annotate: %TRUE if type information should be included in the output + * @type_annotate: %TRUE if type information should be included in + * the output * * Pretty-prints @value in the format understood by g_variant_parse(). * @@ -33136,7 +34289,8 @@ * g_variant_print_string: (skip) * @value: a #GVariant * @string: (allow-none) (default NULL): a #GString, or %NULL - * @type_annotate: %TRUE if type information should be included in the output + * @type_annotate: %TRUE if type information should be included in + * the output * * Behaves as g_variant_print(), but operates on a #GString. * @@ -33261,7 +34415,9 @@ * Makes a copy of a #GVariantType. It is appropriate to call * g_variant_type_free() on the return value. @type may not be %NULL. * - * Returns: (transfer full): a new #GVariantType Since 2.24 + * Returns: (transfer full): a new #GVariantType + * + * Since 2.24 */ @@ -33273,7 +34429,9 @@ * @type. The returned string is nul-terminated. It is appropriate to * call g_free() on the return value. * - * Returns: (transfer full): the corresponding type string Since 2.24 + * Returns: (transfer full): the corresponding type string + * + * Since 2.24 */ @@ -33285,7 +34443,9 @@ * * This function may only be used with array or maybe types. * - * Returns: (transfer none): the element type of @type Since 2.24 + * Returns: (transfer none): the element type of @type + * + * Since 2.24 */ @@ -33305,7 +34465,9 @@ * allow use with #GHashTable without function pointer casting. For * both arguments, a valid #GVariantType must be provided. * - * Returns: %TRUE if @type1 and @type2 are exactly equal Since 2.24 + * Returns: %TRUE if @type1 and @type2 are exactly equal + * + * Since 2.24 */ @@ -33328,7 +34490,9 @@ * This call, together with g_variant_type_next() provides an iterator * interface over tuple and dictionary entry types. * - * Returns: (transfer none): the first item type of @type, or %NULL Since 2.24 + * Returns: (transfer none): the first item type of @type, or %NULL + * + * Since 2.24 */ @@ -33354,7 +34518,9 @@ * @type. This function must be used to determine the valid extent of * the memory region returned by g_variant_type_peek_string(). * - * Returns: the length of the corresponding type string Since 2.24 + * Returns: the length of the corresponding type string + * + * Since 2.24 */ @@ -33368,7 +34534,9 @@ * #GHashTable without function pointer casting. A valid * #GVariantType must be provided. * - * Returns: the hash value Since 2.24 + * Returns: the hash value + * + * Since 2.24 */ @@ -33383,7 +34551,9 @@ * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for * example. * - * Returns: %TRUE if @type is an array type Since 2.24 + * Returns: %TRUE if @type is an array type + * + * Since 2.24 */ @@ -33401,7 +34571,9 @@ * This function returns %FALSE for all indefinite types except * %G_VARIANT_TYPE_BASIC. * - * Returns: %TRUE if @type is a basic type Since 2.24 + * Returns: %TRUE if @type is a basic type + * + * Since 2.24 */ @@ -33418,7 +34590,9 @@ * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for * example. * - * Returns: %TRUE if @type is a container type Since 2.24 + * Returns: %TRUE if @type is a container type + * + * Since 2.24 */ @@ -33437,7 +34611,9 @@ * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in * %FALSE being returned. * - * Returns: %TRUE if @type is definite Since 2.24 + * Returns: %TRUE if @type is definite + * + * Since 2.24 */ @@ -33452,7 +34628,9 @@ * definite subtype is a dictionary entry type -- * %G_VARIANT_TYPE_DICT_ENTRY, for example. * - * Returns: %TRUE if @type is a dictionary entry type Since 2.24 + * Returns: %TRUE if @type is a dictionary entry type + * + * Since 2.24 */ @@ -33467,7 +34645,9 @@ * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for * example. * - * Returns: %TRUE if @type is a maybe type Since 2.24 + * Returns: %TRUE if @type is a maybe type + * + * Since 2.24 */ @@ -33482,7 +34662,9 @@ * types are considered to be subtypes of themselves. Aside from that, * only indefinite types can have subtypes. * - * Returns: %TRUE if @type is a subtype of @supertype Since 2.24 + * Returns: %TRUE if @type is a subtype of @supertype + * + * Since 2.24 */ @@ -33498,7 +34680,9 @@ * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for * example. * - * Returns: %TRUE if @type is a tuple type Since 2.24 + * Returns: %TRUE if @type is a tuple type + * + * Since 2.24 */ @@ -33508,7 +34692,9 @@ * * Determines if the given @type is the variant type. * - * Returns: %TRUE if @type is the variant type Since 2.24 + * Returns: %TRUE if @type is the variant type + * + * Since 2.24 */ @@ -33522,7 +34708,9 @@ * than the additional restriction, this call is equivalent to * g_variant_type_first(). * - * Returns: (transfer none): the key type of the dictionary entry Since 2.24 + * Returns: (transfer none): the key type of the dictionary entry + * + * Since 2.24 */ @@ -33540,7 +34728,9 @@ * In the case of a dictionary entry type, this function will always * return 2. * - * Returns: the number of items in @type Since 2.24 + * Returns: the number of items in @type + * + * Since 2.24 */ @@ -33569,7 +34759,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new array #GVariantType Since 2.24 + * Returns: (transfer full): a new array #GVariantType + * + * Since 2.24 */ @@ -33583,7 +34775,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new dictionary entry #GVariantType Since 2.24 + * Returns: (transfer full): a new dictionary entry #GVariantType + * + * Since 2.24 */ @@ -33596,7 +34790,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new maybe #GVariantType Since 2.24 + * Returns: (transfer full): a new maybe #GVariantType + * + * Since 2.24 */ @@ -33612,7 +34808,9 @@ * * It is appropriate to call g_variant_type_free() on the return value. * - * Returns: (transfer full): a new tuple #GVariantType Since 2.24 + * Returns: (transfer full): a new tuple #GVariantType + * + * Since 2.24 */ @@ -33632,7 +34830,9 @@ * * For tuples, %NULL is returned when @type is the last item in a tuple. * - * Returns: (transfer none): the next #GVariantType after @type, or %NULL Since 2.24 + * Returns: (transfer none): the next #GVariantType after @type, or %NULL + * + * Since 2.24 */ @@ -33646,7 +34846,9 @@ * * To get a nul-terminated string, see g_variant_type_dup_string(). * - * Returns: the corresponding type string (not nul-terminated) Since 2.24 + * Returns: the corresponding type string (not nul-terminated) + * + * Since 2.24 */ @@ -33658,7 +34860,9 @@ * equivalent to calling g_variant_type_string_scan() and confirming * that the following character is a nul terminator. * - * Returns: %TRUE if @type_string is exactly one valid type string Since 2.24 + * Returns: %TRUE if @type_string is exactly one valid type string + * + * Since 2.24 */ @@ -33695,7 +34899,9 @@ * * This function may only be used with a dictionary entry type. * - * Returns: (transfer none): the value type of the dictionary entry Since 2.24 + * Returns: (transfer none): the value type of the dictionary entry + * + * Since 2.24 */ @@ -33713,7 +34919,8 @@ /** * g_vasprintf: * @string: the return location for the newly-allocated string. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @args: the list of arguments to insert in the output. * * An implementation of the GNU vasprintf() function which supports @@ -33730,7 +34937,8 @@ /** * g_vfprintf: * @file: the stream to write to. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @args: the list of arguments to insert in the output. * * An implementation of the standard fprintf() function which supports @@ -33743,7 +34951,8 @@ /** * g_vprintf: - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @args: the list of arguments to insert in the output. * * An implementation of the standard vprintf() function which supports @@ -33757,8 +34966,10 @@ /** * g_vsnprintf: * @string: the buffer to hold the output. - * @n: the maximum number of bytes to produce (including the terminating nul character). - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @n: the maximum number of bytes to produce (including the + * terminating nul character). + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @args: the list of arguments to insert in the output. * * A safer form of the standard vsprintf() function. The output is guaranteed @@ -33779,14 +34990,16 @@ * The format string may contain positional parameters, as specified in * the Single Unix Specification. * - * Returns: the number of bytes which would be produced if the buffer was large enough. + * Returns: the number of bytes which would be produced if the buffer + * was large enough. */ /** * g_vsprintf: * @string: the buffer to hold the output. - * @format: a standard printf() format string, but notice <link linkend="string-precision">string precision pitfalls</link>. + * @format: a standard printf() format string, but notice + * <link linkend="string-precision">string precision pitfalls</link>. * @args: the list of arguments to insert in the output. * * An implementation of the standard vsprintf() function which supports @@ -33868,7 +35081,8 @@ /** * g_warning: - * @...: format string, followed by parameters to insert into the format string (as with printf()) + * @...: format string, followed by parameters to insert + * into the format string (as with printf()) * * A convenience function/macro to log a warning message. * @@ -33940,8 +35154,12 @@ * the main executable of the process was loaded is used instead in * the same way as above. * - * 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. + * 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. */ @@ -33973,7 +35191,11 @@ * construct names of files in the installation tree it calls this * function passing the DLL handle. * - * 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. + * 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 */ @@ -33996,8 +35218,14 @@ * particular, note that it is deprecated to pass anything except NULL * as @package. * - * 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(). + * 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(). */ @@ -34058,7 +35286,8 @@ * The return value is dynamically allocated and should be freed with * g_free() when no longer needed. * - * Returns: The converted filename, or %NULL on conversion failure and lack of short names. + * Returns: The converted filename, or %NULL on conversion + * failure and lack of short names. * Since: 2.8 */ @@ -34203,7 +35432,10 @@ * version @required_major.required_minor.@required_micro * (same major version.) * - * Returns: %NULL if the GLib library is compatible with the given version, or a string describing the version mismatch. The returned string is owned by GLib and must not be modified or freed. + * 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 */ @@ -34232,7 +35464,8 @@ /** * glib_pgettext: - * @msgctxtid: a combined message context and message id, separated by a \004 character + * @msgctxtid: a combined message context and message id, separated + * by a \004 character * @msgidoffset: the offset of the message id in @msgctxid * * This function is a variant of glib_gettext() which supports diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c index 8ffed600..0b40df3e 100644 --- a/gir/gmodule-2.0.c +++ b/gir/gmodule-2.0.c @@ -28,8 +28,13 @@ /** * GModuleFlags: - * @G_MODULE_BIND_LAZY: specifies that symbols are only resolved when needed. The default action is to bind all symbols when the module is loaded. - * @G_MODULE_BIND_LOCAL: specifies that symbols in the module should not be added to the global name space. The default action on most platforms is to place symbols in the module in the global name space, which may cause conflicts with existing symbols. + * @G_MODULE_BIND_LAZY: specifies that symbols are only resolved when + * needed. The default action is to bind all symbols when the module + * is loaded. + * @G_MODULE_BIND_LOCAL: specifies that symbols in the module should + * not be added to the global name space. The default action on most + * platforms is to place symbols in the module in the global name space, + * which may cause conflicts with existing symbols. * @G_MODULE_BIND_MASK: mask for all flags. * * Flags passed to g_module_open(). @@ -159,7 +164,9 @@ /** * g_module_build_path: - * @directory: (allow-none): the directory where the module is. This can be %NULL or the empty string to indicate that the standard platform-specific directories will be used, though that is not recommended + * @directory: (allow-none): the directory where the module is. This can be %NULL + * or the empty string to indicate that the standard platform-specific + * directories will be used, though that is not recommended * @module_name: the name of the module * * A portable way to build the filename of a module. The platform-specific @@ -177,7 +184,8 @@ * using <filename>\Windows</filename> as the directory it will return * <filename>\Windows\mylibrary.dll</filename>. * - * Returns: the complete path of the module, including the standard library prefix and suffix. This should be freed when no longer needed + * Returns: the complete path of the module, including the standard library + * prefix and suffix. This should be freed when no longer needed */ @@ -223,8 +231,10 @@ /** * g_module_open: - * @file_name: (allow-none): the name of the file containing the module, or %NULL to obtain a #GModule representing the main program itself - * @flags: the flags used for opening the module. This can be the logical OR of any of the #GModuleFlags + * @file_name: (allow-none): the name of the file containing the module, or %NULL + * to obtain a #GModule representing the main program itself + * @flags: the flags used for opening the module. This can be the + * logical OR of any of the #GModuleFlags * * Opens a module. If the module has already been opened, * its reference count is incremented. diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 98879df0..2a0d2767 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -114,7 +114,8 @@ * SECTION:enumerations_flags * @short_description: Enumeration and flags types * @title: Enumeration and Flag Types - * @see_also: #GParamSpecEnum, #GParamSpecFlags, g_param_spec_enum(), g_param_spec_flags() + * @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 @@ -221,7 +222,8 @@ /** * SECTION:gboxed - * @short_description: A mechanism to wrap opaque C structures registered by the type system + * @short_description: A mechanism to wrap opaque C structures registered + * by the type system * @see_also: #GParamSpecBoxed, g_param_spec_boxed() * @title: Boxed Types * @@ -292,8 +294,13 @@ /** * SECTION:generic_values - * @short_description: A polymorphic type that can hold values of any other type - * @see_also: The fundamental types which all support #GValue operations and thus can be used as a type initializer for g_value_init() are defined by a separate interface. See the <link linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values API</link> for details. + * @short_description: A polymorphic type that can hold values of any + * other type + * @see_also: The fundamental types which all support #GValue + * operations and thus can be used as a type initializer for + * g_value_init() are defined by a separate interface. See the <link + * linkend="gobject-Standard-Parameter-and-Value-Types">Standard + * Values API</link> for details. * @title: Generic values * * The #GValue structure is basically a variable container that consists @@ -371,7 +378,9 @@ /** * SECTION:gparamspec * @short_description: Metadata for parameter specifications - * @see_also: g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func() + * @see_also: g_object_class_install_property(), g_object_set(), + * g_object_get(), g_object_set_property(), g_object_get_property(), + * g_value_register_transform_func() * @title: GParamSpec * * #GParamSpec is an object structure that encapsulates the metadata @@ -389,7 +398,8 @@ /** * SECTION:gtype - * @short_description: The GLib Runtime type identification and management system + * @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 @@ -433,7 +443,16 @@ /** * SECTION:gtypemodule * @short_description: Type loading modules - * @see_also: <variablelist> <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist> + * @see_also: <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 @@ -619,7 +638,8 @@ /** * SECTION:signals - * @short_description: A means for customization of object behaviour and a general purpose notification mechanism + * @short_description: A means for customization of object behaviour + * and a general purpose notification mechanism * @title: Signals * * The basic concept of the signal system is that of the @@ -683,7 +703,8 @@ /** * SECTION:value_arrays - * @short_description: A container structure to maintain an array of generic values + * @short_description: A container structure to maintain an array of + * generic values * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array() * @title: Value arrays * @@ -824,7 +845,8 @@ * @return_value: a #GValue which can store the returned #gboolean * @n_param_values: 2 * @param_values: a #GValue array holding instance and arg1 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -839,7 +861,8 @@ * @return_value: a #GValue, which can store the returned string * @n_param_values: 3 * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -862,7 +885,8 @@ * @return_value: a #GValue, which can store the returned string * @n_param_values: 3 * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -876,7 +900,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gboolean parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -890,7 +915,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GBoxed* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -904,7 +930,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gchar parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -918,7 +945,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gdouble parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -932,7 +960,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the enumeration parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -946,7 +975,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the flags parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -960,7 +990,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gfloat parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -974,7 +1005,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gint parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -988,7 +1020,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #glong parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1002,7 +1035,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GObject* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1016,7 +1050,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1030,7 +1065,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gpointer parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1044,7 +1080,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gchar* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1058,7 +1095,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #guchar parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1072,7 +1110,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #guint parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1086,7 +1125,8 @@ * @return_value: ignored * @n_param_values: 3 * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1100,7 +1140,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #gulong parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1114,7 +1155,8 @@ * @return_value: ignored * @n_param_values: 2 * @param_values: a #GValue array holding the instance and the #GVariant* parameter - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1130,7 +1172,8 @@ * @return_value: ignored * @n_param_values: 1 * @param_values: a #GValue array holding only the instance - * @invocation_hint: the invocation hint given as the last argument to g_closure_invoke() + * @invocation_hint: the invocation hint given as the last argument + * to g_closure_invoke() * @marshal_data: additional data specified when registering the marshaller * * A marshaller for a #GCClosure with a callback of type @@ -1141,11 +1184,16 @@ /** * g_cclosure_marshal_generic: * @closure: A #GClosure. - * @return_gvalue: A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. + * @return_gvalue: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. * @n_param_values: The length of the @param_values array. - * @param_values: An array of #GValue<!-- -->s holding the arguments on which to invoke the callback of closure. - * @invocation_hint: The invocation hint given as the last argument to g_closure_invoke(). - * @marshal_data: Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() + * @param_values: An array of #GValue<!-- -->s holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * * A generic marshaller function implemented via <ulink * url="http://sourceware.org/libffi/">libffi</ulink>. @@ -1298,9 +1346,13 @@ /** * g_closure_invoke: * @closure: a #GClosure - * @return_value: (allow-none): a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure + * doesn't return a value. * @n_param_values: the length of the @param_values array - * @param_values: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @param_values: (array length=n_param_values): an array of + * #GValue<!-- -->s holding the arguments on which to + * invoke the callback of @closure * @invocation_hint: (allow-none): a context-dependent invocation hint * * Invokes the closure, i.e. executes the callback represented by the @closure. @@ -1309,8 +1361,10 @@ /** * g_closure_new_object: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> - * @object: a #GObject pointer to store in the @data field of the newly allocated #GClosure + * @sizeof_closure: the size of the structure to allocate, must be at least + * <literal>sizeof (GClosure)</literal> + * @object: a #GObject pointer to store in the @data field of the newly + * allocated #GClosure * * A variant of g_closure_new_simple() which stores @object in the * @data field of the closure and calls g_object_watch_closure() on @@ -1323,7 +1377,8 @@ /** * g_closure_new_simple: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> + * @sizeof_closure: the size of the structure to allocate, must be at least + * <literal>sizeof (GClosure)</literal> * @data: data to store in the @data field of the newly allocated #GClosure * * Allocates a struct of the given size and initializes the initial @@ -1381,7 +1436,8 @@ /** * g_closure_remove_finalize_notifier: (skip) * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_finalize_notifier() when registering @notify_func + * @notify_data: data which was passed to g_closure_add_finalize_notifier() + * when registering @notify_func * @notify_func: the callback function to remove * * Removes a finalization notifier. @@ -1393,7 +1449,8 @@ /** * g_closure_remove_invalidate_notifier: (skip) * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func + * @notify_data: data which was passed to g_closure_add_invalidate_notifier() + * when registering @notify_func * @notify_func: the callback function to remove * * Removes an invalidation notifier. @@ -1442,7 +1499,8 @@ /** * g_closure_sink: - * @closure: #GClosure to decrement the initial reference count on, if it's still being held + * @closure: #GClosure to decrement the initial reference count on, if it's + * still being held * * Takes over the initial ownership of a closure. Each closure is * initially created in a <firstterm>floating</firstterm> state, which @@ -1501,7 +1559,9 @@ * g_enum_complete_type_info: * @g_enum_type: the type identifier of the type being completed * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * @const_values: An array of #GEnumValue structs for the possible + * enumeration values. The array is terminated by a struct with all + * members being 0. * * This function is meant to be called from the <literal>complete_type_info</literal> * function of a #GTypePlugin implementation, as in the following @@ -1533,7 +1593,8 @@ * * Returns the #GEnumValue for a value. * - * Returns: the #GEnumValue for @value, or %NULL if @value is not a member of the enumeration + * Returns: the #GEnumValue for @value, or %NULL if @value is not a + * member of the enumeration */ @@ -1544,7 +1605,8 @@ * * Looks up a #GEnumValue by name. * - * Returns: the #GEnumValue with name @name, or %NULL if the enumeration doesn't have a member with that name + * Returns: the #GEnumValue with name @name, or %NULL if the + * enumeration doesn't have a member with that name */ @@ -1555,14 +1617,18 @@ * * Looks up a #GEnumValue by nickname. * - * Returns: the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn't have a member with that nickname + * Returns: the #GEnumValue with nickname @nick, or %NULL if the + * enumeration doesn't have a member with that nickname */ /** * g_enum_register_static: * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * @const_static_values: An array of #GEnumValue structs for the possible + * enumeration values. The array is terminated by a struct with all + * members being 0. GObject keeps a reference to the data, so it cannot + * be stack-allocated. * * Registers a new static enumeration type with the name @name. * @@ -1579,7 +1645,9 @@ * g_flags_complete_type_info: * @g_flags_type: the type identifier of the type being completed * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * @const_values: An array of #GFlagsValue structs for the possible + * enumeration values. The array is terminated by a struct with all + * members being 0. * * This function is meant to be called from the complete_type_info() * function of a #GTypePlugin implementation, see the example for @@ -1594,7 +1662,8 @@ * * Returns the first #GFlagsValue which is set in @value. * - * Returns: the first #GFlagsValue which is set in @value, or %NULL if none is set + * Returns: the first #GFlagsValue which is set in @value, or %NULL if + * none is set */ @@ -1605,7 +1674,8 @@ * * Looks up a #GFlagsValue by name. * - * Returns: the #GFlagsValue with name @name, or %NULL if there is no flag with that name + * Returns: the #GFlagsValue with name @name, or %NULL if there is no + * flag with that name */ @@ -1616,14 +1686,17 @@ * * Looks up a #GFlagsValue by nickname. * - * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is no flag with that nickname + * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is + * no flag with that nickname */ /** * g_flags_register_static: * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * @const_static_values: An array of #GFlagsValue structs for the possible + * flags values. The array is terminated by a struct with all members being 0. + * GObject keeps a reference to the data, so it cannot be stack-allocated. * * Registers a new static flags type with the name @name. * @@ -1639,7 +1712,9 @@ /** * g_object_add_toggle_ref: (skip) * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @notify: a function to call when this reference is the + * last reference to the object, or is no longer + * the last reference. * @data: data to pass to @notify * * Increases the reference count of the object by one and sets a @@ -1723,7 +1798,9 @@ * * A #GObject can have multiple bindings. * - * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. + * 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 */ @@ -1735,10 +1812,14 @@ * @target: (type GObject.Object): the target #GObject * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding - * @transform_to: (scope notified) (allow-none): the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: (scope notified) (allow-none): the transformation function from the @target to the @source, or %NULL to use the default - * @user_data: custom data to be passed to the transformation functions, or %NULL - * @notify: function to be called when disposing the binding, to free the resources used by the transformation functions + * @transform_to: (scope notified) (allow-none): the transformation function + * from the @source to the @target, or %NULL to use the default + * @transform_from: (scope notified) (allow-none): the transformation function + * from the @target to the @source, or %NULL to use the default + * @user_data: custom data to be passed to the transformation functions, + * or %NULL + * @notify: function to be called when disposing the binding, to free the + * resources used by the transformation functions * * Complete version of g_object_bind_property(). * @@ -1764,7 +1845,9 @@ * for each transformation function, please use * g_object_bind_property_with_closures() instead.</note> * - * 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. + * 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 */ @@ -1776,8 +1859,10 @@ * @target: (type GObject.Object): the target #GObject * @target_property: the property on @target to bind * @flags: flags to pass to #GBinding - * @transform_to: a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default + * @transform_to: a #GClosure wrapping the transformation function + * from the @source to the @target, or %NULL to use the default + * @transform_from: a #GClosure wrapping the transformation function + * from the @target to the @source, or %NULL to use the default * * Creates a binding between @source_property on @source and @target_property * on @target, allowing you to set the transformation functions to be used by @@ -1787,7 +1872,9 @@ * g_object_bind_property_full(), using #GClosure<!-- -->s instead of * function pointers. * - * Returns: (transfer none): the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. + * 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 */ @@ -1799,7 +1886,8 @@ * * Looks up the #GParamSpec for a property of a class. * - * Returns: (transfer none): the #GParamSpec for the property, or %NULL if the class doesn't have a property of that name + * Returns: (transfer none): the #GParamSpec for the property, or + * %NULL if the class doesn't have a property of that name */ @@ -1807,7 +1895,8 @@ * g_object_class_install_properties: * @oclass: a #GObjectClass * @n_pspecs: the length of the #GParamSpec<!-- -->s array - * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array defining the new properties + * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array + * defining the new properties * * Installs new properties from an array of #GParamSpec<!-- -->s. This is * usually done in the class initializer. @@ -1892,7 +1981,8 @@ * * Get an array of #GParamSpec* for all properties of a class. * - * Returns: (array length=n_properties) (transfer container): an array of #GParamSpec* which should be freed after use + * Returns: (array length=n_properties) (transfer container): an array of + * #GParamSpec* which should be freed after use */ @@ -1900,7 +1990,8 @@ * g_object_class_override_property: * @oclass: a #GObjectClass * @property_id: the new property ID - * @name: the name of a property registered in a parent class or in an interface of this class. + * @name: the name of a property registered in a parent class or + * in an interface of this class. * * Registers @property_id as referring to a property with the * name @name in a parent class or in an interface implemented @@ -1929,7 +2020,9 @@ * g_object_connect: (skip) * @object: a #GObject * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL + * @...: #GCallback for the first signal, followed by data for the + * first signal, followed optionally by more signal + * spec/callback/data triples, followed by %NULL * * A convenience function to connect multiple signals at once. * @@ -2012,7 +2105,9 @@ * g_object_disconnect: (skip) * @object: a #GObject * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL + * @...: #GCallback for the first signal, followed by data for the first signal, + * followed optionally by more signal spec/callback/data triples, + * followed by %NULL * * A convenience function to disconnect multiple signals at once. * @@ -2045,7 +2140,10 @@ * threads are using object data on the same key on the same * object. * - * Returns: the result of calling @dup_func on the value associated with @key on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. + * Returns: the result of calling @dup_func on the value + * associated with @key on @object, or %NULL if not set. + * If @dup_func is %NULL, the value is returned + * unmodified. * Since: 2.34 */ @@ -2072,7 +2170,10 @@ * threads are using object data on the same key on the same * object. * - * Returns: the result of calling @dup_func on the value associated with @quark on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. + * Returns: the result of calling @dup_func on the value + * associated with @quark on @object, or %NULL if not set. + * If @dup_func is %NULL, the value is returned + * unmodified. * Since: 2.34 */ @@ -2111,7 +2212,8 @@ * g_object_get: (skip) * @object: a #GObject * @first_property_name: name of the first property to get - * @...: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * @...: return location for the first property, followed optionally by more + * name/return location pairs, followed by %NULL * * Gets properties of an object. * @@ -2189,7 +2291,8 @@ * g_object_get_valist: (skip) * @object: a #GObject * @first_property_name: name of the first property to get - * @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * @var_args: return location for the first property, followed optionally by more + * name/return location pairs, followed by %NULL * * Gets properties of an object. * @@ -2203,7 +2306,8 @@ /** * g_object_interface_find_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface * @property_name: name of a property to lookup. * * Find the #GParamSpec with the given name for an @@ -2213,13 +2317,16 @@ * g_type_default_interface_peek(). * * Since: 2.4 - * Returns: (transfer none): the #GParamSpec for the property of the interface with the name @property_name, or %NULL if no such property exists. + * Returns: (transfer none): the #GParamSpec for the property of the + * interface with the name @property_name, or %NULL if no + * such property exists. */ /** * g_object_interface_install_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface. + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface. * @pspec: the #GParamSpec for the new property * * Add a property to an interface; this is only useful for interfaces @@ -2243,7 +2350,8 @@ /** * g_object_interface_list_properties: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @g_iface: any interface vtable for the interface, or the default + * vtable for the interface * @n_properties_p: (out): location to store number of properties returned. * * Lists the properties of an interface.Generally, the interface @@ -2252,7 +2360,11 @@ * already been loaded, g_type_default_interface_peek(). * * Since: 2.4 - * 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. + * 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. */ @@ -2272,7 +2384,8 @@ * g_object_new: (skip) * @object_type: the type id of the #GObject subtype to instantiate * @first_property_name: the name of the first property - * @...: the value of the first property, followed optionally by more name/value pairs, followed by %NULL + * @...: the value of the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Creates a new instance of a #GObject subtype and sets its properties. * @@ -2287,7 +2400,8 @@ * g_object_new_valist: (skip) * @object_type: the type id of the #GObject subtype to instantiate * @first_property_name: the name of the first property - * @var_args: the value of the first property, followed optionally by more name/value pairs, followed by %NULL + * @var_args: the value of the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Creates a new instance of a #GObject subtype and sets its properties. * @@ -2309,7 +2423,8 @@ * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) * which are not explicitly specified are set to their default values. * - * Returns: (type GObject.Object) (transfer full): a new instance of @object_type + * Returns: (type GObject.Object) (transfer full): a new instance of + * @object_type */ @@ -2406,7 +2521,9 @@ /** * g_object_remove_toggle_ref: (skip) * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @notify: a function to call when this reference is the + * last reference to the object, or is no longer + * the last reference. * @data: data to pass to @notify * * Removes a reference added with g_object_add_toggle_ref(). The @@ -2450,7 +2567,8 @@ * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * - * Returns: %TRUE if the existing value for @key was replaced by @newval, %FALSE otherwise. + * Returns: %TRUE if the existing value for @key was replaced + * by @newval, %FALSE otherwise. * Since: 2.34 */ @@ -2478,7 +2596,8 @@ * or may not include using @old_destroy as sometimes replacement * should not destroy the object in the normal way. * - * Returns: %TRUE if the existing value for @quark was replaced by @newval, %FALSE otherwise. + * Returns: %TRUE if the existing value for @quark was replaced + * by @newval, %FALSE otherwise. * Since: 2.34 */ @@ -2498,7 +2617,8 @@ * g_object_set: (skip) * @object: a #GObject * @first_property_name: name of the first property to set - * @...: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * @...: value for the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Sets properties on an object. */ @@ -2565,7 +2685,8 @@ * @object: The GObject to set store a user data pointer * @quark: A #GQuark, naming the user data pointer * @data: An opaque user data pointer - * @destroy: Function to invoke with @data as argument, when @data needs to be freed + * @destroy: Function to invoke with @data as argument, when @data + * needs to be freed * * This function works like g_object_set_qdata(), but in addition, * a void (*destroy) (gpointer) function may be specified which is @@ -2579,7 +2700,8 @@ * g_object_set_valist: (skip) * @object: a #GObject * @first_property_name: name of the first property to set - * @var_args: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * @var_args: value for the first property, followed optionally by more + * name/value pairs, followed by %NULL * * Sets properties on an object. */ @@ -2905,7 +3027,8 @@ * for an example of the use of this capability. * * Since: 2.4 - * Returns: (transfer none): paramspec to which requests on this paramspec should be redirected, or %NULL if none. + * Returns: (transfer none): paramspec to which requests on this + * paramspec should be redirected, or %NULL if none. */ @@ -2914,7 +3037,8 @@ * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified - * @is_a_type: a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) + * @is_a_type: a #GType whose subtypes are allowed as values + * of the property (use %G_TYPE_NONE for any type) * @flags: flags for the property specified * * Creates a new #GParamSpecGType instance specifying a @@ -3093,7 +3217,9 @@ * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in * the pool. * - * Returns: (array length=n_pspecs_p) (transfer container): a newly allocated array containing pointers to all #GParamSpecs owned by @owner_type in the pool + * Returns: (array length=n_pspecs_p) (transfer container): a newly + * allocated array containing pointers to all #GParamSpecs + * owned by @owner_type in the pool */ @@ -3105,7 +3231,9 @@ * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in * the pool. * - * Returns: (transfer container) (element-type GObject.ParamSpec): a #GList of all #GParamSpec<!-- -->s owned by @owner_type in the pool#GParamSpec<!-- -->s. + * Returns: (transfer container) (element-type GObject.ParamSpec): a + * #GList of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool#GParamSpec<!-- -->s. */ @@ -3114,11 +3242,13 @@ * @pool: a #GParamSpecPool * @param_name: the name to look for * @owner_type: the owner to look for - * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. + * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name + * owned by an ancestor of @owner_type. * * Looks up a #GParamSpec in the pool. * - * Returns: (transfer none): The found #GParamSpec, or %NULL if no matching #GParamSpec was found. + * Returns: (transfer none): The found #GParamSpec, or %NULL if no + * matching #GParamSpec was found. */ @@ -3187,7 +3317,8 @@ * @pspec: the #GParamSpec to set store a user data pointer * @quark: a #GQuark, naming the user data pointer * @data: an opaque user data pointer - * @destroy: function to invoke with @data as argument, when @data needs to be freed + * @destroy: function to invoke with @data as argument, when @data needs to + * be freed * * This function works like g_param_spec_set_qdata(), but in addition, * a <literal>void (*destroy) (gpointer)</literal> function may be @@ -3344,7 +3475,8 @@ * @name: canonical name of the property specified * @nick: nick name for the property specified * @blurb: description of the property specified - * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @element_spec: a #GParamSpec describing the elements contained in + * arrays of this property, may be %NULL * @flags: flags for the property specified * * Creates a new #GParamSpecValueArray instance specifying a @@ -3364,7 +3496,8 @@ * @nick: nick name for the property specified * @blurb: description of the property specified * @type: a #GVariantType - * @default_value: (allow-none) (transfer full): a #GVariant of type @type to use as the default value, or %NULL + * @default_value: (allow-none) (transfer full): a #GVariant of type @type to + * use as the default value, or %NULL * @flags: flags for the property specified * * Creates a new #GParamSpecVariant instance specifying a #GVariant @@ -3398,7 +3531,8 @@ * @pspec: a valid #GParamSpec * @src_value: souce #GValue * @dest_value: destination #GValue of correct type for @pspec - * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications + * @strict_validation: %TRUE requires @dest_value to conform to @pspec + * without modifications * * Transforms @src_value into @dest_value if possible, and then * validates @dest_value, in order for it to conform to @pspec. If @@ -3408,7 +3542,8 @@ * See also g_value_type_transformable(), g_value_transform() and * g_param_value_validate(). * - * Returns: %TRUE if transformation and validation were successful, %FALSE otherwise and @dest_value is left untouched. + * Returns: %TRUE if transformation and validation were successful, + * %FALSE otherwise and @dest_value is left untouched. */ @@ -3534,7 +3669,9 @@ /** * 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 @@ -3547,7 +3684,9 @@ /** * g_signal_chain_from_overridden_handler: (skip) * @instance: the instance the signal is being emitted on. - * @...: parameters to be passed to the parent class closure, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @...: parameters to be passed to the parent class closure, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Calls the original class closure of a signal. This function should * only be called from an overridden class closure; see @@ -3563,7 +3702,8 @@ * @instance: (type GObject.Object): the instance to connect to. * @detailed_signal: a string of the form "signal-name::detail". * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * @after: whether the handler should be called before or after the + * default handler of the signal. * * Connects a closure to a signal for a particular object. * @@ -3577,7 +3717,8 @@ * @signal_id: the id of the signal. * @detail: the detail. * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * @after: whether the handler should be called before or after the + * default handler of the signal. * * Connects a closure to a signal for a particular object. * @@ -3630,7 +3771,9 @@ * @instance: (type GObject.Object): the instance the signal is being emitted on. * @signal_id: the signal id * @detail: the detail - * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @...: parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Emits a signal. * @@ -3643,7 +3786,9 @@ * g_signal_emit_by_name: * @instance: (type GObject.Object): the instance the signal is being emitted on. * @detailed_signal: a string of the form "signal-name::detail". - * @...: parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @...: parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Emits a signal. * @@ -3657,7 +3802,9 @@ * @instance: the instance the signal is being emitted on. * @signal_id: the signal id * @detail: the detail - * @var_args: a list of parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal is #G_TYPE_NONE, the return value location can be omitted. + * @var_args: a list of parameters to be passed to the signal, followed by a + * location for the return value. If the return type of the signal + * is #G_TYPE_NONE, the return value location can be omitted. * * Emits a signal. * @@ -3668,7 +3815,9 @@ /** * g_signal_emitv: - * @instance_and_params: (array): argument list for 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): argument list for 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. * @signal_id: the signal id * @detail: the detail * @return_value: Location to store the return value of the signal emission. @@ -3723,7 +3872,8 @@ /** * g_signal_handler_find: * @instance: (type GObject.Object): The instance owning the signal handler to be found. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handler has to match. * @signal_id: Signal the handler has to be connected to. * @detail: Signal detail the handler has to be connected to. * @closure: (allow-none): The closure the handler will invoke. @@ -3775,7 +3925,8 @@ /** * g_signal_handlers_block_matched: * @instance: (type GObject.Object): The instance to block handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: (allow-none): The closure the handlers will invoke. @@ -3803,7 +3954,8 @@ /** * g_signal_handlers_disconnect_matched: * @instance: (type GObject.Object): The instance to remove handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: (allow-none): The closure the handlers will invoke. @@ -3826,7 +3978,8 @@ /** * g_signal_handlers_unblock_matched: * @instance: (type GObject.Object): The instance to unblock handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func + * and/or @data the handlers have to match. * @signal_id: Signal the handlers have to be connected to. * @detail: Signal detail the handlers have to be connected to. * @closure: (allow-none): The closure the handlers will invoke. @@ -3861,7 +4014,8 @@ * emit the signal if no one is attached anyway, thus saving the cost * of building the arguments. * - * Returns: %TRUE if a handler is connected to the signal, %FALSE otherwise. + * Returns: %TRUE if a handler is connected to the signal, %FALSE + * otherwise. */ @@ -3910,13 +4064,20 @@ /** * g_signal_new: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_offset: The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_offset: The offset of the function pointer in the class structure + * for this type. Used to invoke a class method generically. Pass 0 to + * not associate a class method slot with this signal. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @c_marshaller: (allow-none): the function to translate arrays of parameter + * values to signal emissions into C language callback invocations or %NULL. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. * @n_params: the number of parameter types to follow. * @...: a list of types, one for each parameter. * @@ -3945,13 +4106,20 @@ /** * g_signal_new_class_handler: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_handler: a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_handler: a #GCallback which acts as class implementation of + * this signal. Used to invoke a class method generically. Pass %NULL to + * not associate a class method with this signal. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @c_marshaller: (allow-none): the function to translate arrays of parameter + * values to signal emissions into C language callback invocations or %NULL. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. * @n_params: the number of parameter types to follow. * @...: a list of types, one for each parameter. * @@ -3980,13 +4148,18 @@ /** * g_signal_new_valist: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. * @class_closure: The closure to invoke on signal emission; may be %NULL. * @accumulator: the accumulator for this signal; may be %NULL. * @accu_data: user data for the @accumulator. - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @c_marshaller: (allow-none): the function to translate arrays of parameter + * values to signal emissions into C language callback invocations or %NULL. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value. * @n_params: the number of parameter types in @args. * @args: va_list of #GType, one for each parameter. * @@ -4004,15 +4177,23 @@ /** * g_signal_newv: * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST - * @class_closure: (allow-none): The closure to invoke on signal emission; may be %NULL + * @itype: the type this signal pertains to. It will also pertain to + * types which are derived from this type + * @signal_flags: a combination of #GSignalFlags specifying detail of when + * the default handler is to be invoked. You should at least specify + * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST + * @class_closure: (allow-none): The closure to invoke on signal emission; + * may be %NULL * @accumulator: (allow-none): the accumulator for this signal; may be %NULL * @accu_data: user data for the @accumulator - * @c_marshaller: (allow-none): the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value + * @c_marshaller: (allow-none): the function to translate arrays of + * parameter values to signal emissions into C language callback + * invocations or %NULL + * @return_type: the type of return value, or #G_TYPE_NONE for a signal + * without a return value * @n_params: the length of @param_types - * @param_types: (array length=n_params): an array of types, one for each parameter + * @param_types: (array length=n_params): an array of types, one for + * each parameter * * Creates a new signal. (This is usually done in the class initializer.) * @@ -4028,7 +4209,8 @@ /** * g_signal_override_class_closure: * @signal_id: the signal id - * @instance_type: the instance type on which to override the class closure for the signal. + * @instance_type: the instance type on which to override the class closure + * for the signal. * @class_closure: the closure. * * Overrides the class closure (i.e. the default handler) for the given signal @@ -4044,7 +4226,8 @@ /** * g_signal_override_class_handler: * @signal_name: the name for the signal - * @instance_type: the instance type on which to override the class handler for the signal. + * @instance_type: the instance type on which to override the class handler + * for the signal. * @class_handler: the handler. * * Overrides the class closure (i.e. the default handler) for the @@ -4078,7 +4261,8 @@ /** * g_signal_query: * @signal_id: The signal id of the signal to query information for. - * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. + * @query: (out caller-allocates): A user provided structure that is + * filled in with constant values upon success. * * Queries the signal system for in-depth information about a * specific signal. This function will fill in a user-provided @@ -4092,7 +4276,8 @@ /** * g_signal_remove_emission_hook: * @signal_id: the id of the signal - * @hook_id: the id of the emission hook, as returned by g_signal_add_emission_hook() + * @hook_id: the id of the emission hook, as returned by + * g_signal_add_emission_hook() * * Deletes an emission hook. */ @@ -4129,7 +4314,8 @@ /** * g_signal_type_cclosure_new: * @itype: the #GType identifier of an interface or classed type - * @struct_offset: the offset of the member function of @itype's class structure which is to be invoked by the new closure + * @struct_offset: the offset of the member function of @itype's class + * structure which is to be invoked by the new closure * * Creates a new closure which invokes the function found at the offset * @struct_offset in the class structure of the interface or classed type @@ -4218,7 +4404,8 @@ /** * g_type_add_interface_check: (skip) * @check_data: data to pass to @check_func - * @check_func: function to be called after each interface is initialized. + * @check_func: function to be called after each interface + * is initialized. * * Adds a function to be called after an interface vtable is * initialized for any class (i.e. after the @interface_init member of @@ -4250,7 +4437,8 @@ * g_type_add_interface_static: * @instance_type: #GType value of an instantiable type. * @interface_type: #GType value of an interface type. - * @info: The #GInterfaceInfo structure for this (@instance_type, @interface_type) combination. + * @info: The #GInterfaceInfo structure for this + * (@instance_type, @interface_type) combination. * * Adds the static @interface_type to @instantiable_type. The * information contained in the #GInterfaceInfo structure pointed to by @@ -4272,12 +4460,14 @@ /** * g_type_children: * @type: The parent type. - * @n_children: (out) (allow-none): Optional #guint pointer to contain the number of child types. + * @n_children: (out) (allow-none): Optional #guint pointer to contain + * the number of child types. * * 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. * - * Returns: (array length=n_children) (transfer full): Newly allocated and 0-terminated array of child types. + * Returns: (array length=n_children) (transfer full): Newly allocated + * and 0-terminated array of child types. */ @@ -4380,13 +4570,16 @@ * may return %NULL if the class of the type passed in does not currently * exist (hasn't been referenced before). * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID or %NULL if the class does not currently exist. + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass + * structure for the given type ID or %NULL if the class does not + * currently exist. */ /** * g_type_class_peek_parent: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to retrieve the parent class for. + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to + * retrieve the parent class for. * * This is a convenience function often needed in class initializers. * It returns the class structure of the immediate parent type of the @@ -4399,7 +4592,8 @@ * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); * </programlisting> * - * Returns: (type GObject.TypeClass) (transfer none): The parent class of @g_class. + * Returns: (type GObject.TypeClass) (transfer none): The parent class + * of @g_class. */ @@ -4411,7 +4605,9 @@ * static types. * * Since: 2.4 - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID or %NULL if the class does not currently exist or is dynamically loaded. + * 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. */ @@ -4423,13 +4619,15 @@ * @type. This function will demand-create the class if it doesn't * exist already. * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass structure for the given type ID. + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass + * structure for the given type ID. */ /** * g_type_class_unref: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to + * unreference. * * Decrements the reference count of the class structure being passed in. * Once the last reference count of a class has been released, classes @@ -4440,7 +4638,8 @@ /** * g_type_class_unref_uncached: (skip) - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to + * unreference. * * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc * implementations. It unreferences a class without consulting the chain @@ -4467,7 +4666,8 @@ * type. Also language bindings should <emphasis>not</emphasis> use * this function but g_object_new() instead. * - * Returns: An allocated and initialized instance, subject to further treatment by the fundamental type implementation. + * Returns: An allocated and initialized instance, subject to further + * treatment by the fundamental type implementation. */ @@ -4479,7 +4679,9 @@ * default interface vtable. * * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default vtable for the interface, or %NULL if the type is not currently in use. + * Returns: (type GObject.TypeInterface) (transfer none): the default + * vtable for the interface, or %NULL if the type is not currently in + * use. */ @@ -4500,13 +4702,17 @@ * have been installed. * * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default vtable for the interface; call g_type_default_interface_unref() when you are done using the interface. + * 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. */ /** * g_type_default_interface_unref: - * @g_iface: (type GObject.TypeInterface): the default vtable structure for a interface, as returned by g_type_default_interface_ref() + * @g_iface: (type GObject.TypeInterface): the default vtable + * structure for a interface, as returned by + * g_type_default_interface_ref() * * Decrements the reference count for the type corresponding to the * interface default vtable @g_iface. If the type is dynamic, then @@ -4595,7 +4801,8 @@ * The returned type ID represents the highest currently registered * fundamental type identifier. * - * Returns: The nextmost fundamental type ID to be registered, or 0 if the type system ran out of fundamental type IDs. + * Returns: The nextmost fundamental type ID to be registered, + * or 0 if the type system ran out of fundamental type IDs. */ @@ -4606,7 +4813,8 @@ * Returns the #GTypePlugin structure for @type or * %NULL if @type does not have a #GTypePlugin structure. * - * Returns: (transfer none): The corresponding plugin if @type is a dynamic type, %NULL otherwise. + * Returns: (transfer none): The corresponding plugin if @type is a + * dynamic type, %NULL otherwise. */ @@ -4653,7 +4861,8 @@ /** * g_type_init_with_debug_flags: - * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. + * @debug_flags: Bitwise combination of #GTypeDebugFlags values for + * debugging purposes. * * This function used to initialise the type system with debugging * flags. Since GLib 2.36, the type system is initialised automatically @@ -4689,7 +4898,8 @@ * @interface_type has not been added to @instance_type or does not * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). * - * Returns: (transfer none): the #GTypePlugin for the dynamic interface @interface_type of @instance_type. + * Returns: (transfer none): the #GTypePlugin for the dynamic + * interface @interface_type of @instance_type. */ @@ -4701,7 +4911,9 @@ * Returns the #GTypeInterface structure of an interface to which the * passed in class conforms. * - * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface structure of iface_type if implemented by @instance_class, %NULL otherwise + * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface + * structure of iface_type if implemented by @instance_class, %NULL + * otherwise */ @@ -4714,32 +4926,40 @@ * deriving the implementation of an interface from the parent type and * then possibly overriding some methods. * - * Returns: (transfer none) (type GObject.TypeInterface): The corresponding #GTypeInterface structure of the parent type of the instance type to which @g_iface belongs, or %NULL if the parent type doesn't conform to the interface. + * Returns: (transfer none) (type GObject.TypeInterface): The + * corresponding #GTypeInterface structure of the parent type of the + * instance type to which @g_iface belongs, or %NULL if the parent + * type doesn't conform to the interface. */ /** * g_type_interface_prerequisites: * @interface_type: an interface type - * @n_prerequisites: (out) (allow-none): location to return the number of prerequisites, or %NULL + * @n_prerequisites: (out) (allow-none): location to return the number + * of prerequisites, or %NULL * * Returns the prerequisites of an interfaces type. * * Since: 2.2 - * Returns: (array length=n_prerequisites) (transfer full): a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type + * Returns: (array length=n_prerequisites) (transfer full): a + * newly-allocated zero-terminated array of #GType containing + * the prerequisites of @interface_type */ /** * g_type_interfaces: * @type: The type to list interface types for. - * @n_interfaces: (out) (allow-none): Optional #guint pointer to contain the number of interface types. + * @n_interfaces: (out) (allow-none): Optional #guint pointer to + * contain the number of interface types. * * Return a newly allocated and 0-terminated array of type IDs, listing the * interface types that @type conforms to. The return value has to be * g_free()ed after use. * - * Returns: (array length=n_interfaces) (transfer full): Newly allocated and 0-terminated array of interface types. + * Returns: (array length=n_interfaces) (transfer full): Newly + * allocated and 0-terminated array of interface types. */ @@ -4776,7 +4996,10 @@ * g_type_module_register_enum: * @module: a #GTypeModule * @name: name for the type - * @const_static_values: an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * @const_static_values: an array of #GEnumValue structs for the + * possible enumeration values. The array is + * terminated by a struct with all members being + * 0. * * Looks up or registers an enumeration that is implemented with a particular * type plugin. If a type with name @type_name was previously registered, @@ -4795,7 +5018,10 @@ * g_type_module_register_flags: * @module: a #GTypeModule * @name: name for the type - * @const_static_values: an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. + * @const_static_values: an array of #GFlagsValue structs for the + * possible flags values. The array is + * terminated by a struct with all members being + * 0. * * Looks up or registers a flags type that is implemented with a particular * type plugin. If a type with name @type_name was previously registered, @@ -4864,7 +5090,8 @@ * If loading the plugin fails, the use count is reset to * its prior value. * - * Returns: %FALSE if the plugin needed to be loaded and loading the plugin failed. + * Returns: %FALSE if the plugin needed to be loaded and + * loading the plugin failed. */ @@ -4913,7 +5140,8 @@ /** * g_type_plugin_complete_interface_info: * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiable type to which the interface is added + * @instance_type: the #GType of an instantiable type to which the interface + * is added * @interface_type: the #GType of the interface whose info is completed * @info: the #GInterfaceInfo to fill in * @@ -4969,7 +5197,8 @@ /** * g_type_query: * @type: the #GType value of a static, classed type. - * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. + * @query: (out caller-allocates): A user provided structure that is + * filled in with constant values upon success. * * Queries the type system for information about a specific type. * This function will fill in a user-provided structure to hold @@ -5096,7 +5325,8 @@ * that implements or has internal knowledge of the implementation of * @type.</emphasis> * - * Returns: Location of the #GTypeValueTable associated with @type or %NULL if there is no #GTypeValueTable associated with @type. + * Returns: Location of the #GTypeValueTable associated with @type or + * %NULL if there is no #GTypeValueTable associated with @type. */ @@ -5190,7 +5420,9 @@ /** * g_value_array_remove: * @value_array: #GValueArray to remove an element from - * @index_: position of value to remove, which must be less than <code>value_array-><link linkend="GValueArray.n-values">n_values</link></code> + * @index_: position of value to remove, which must be less than + * <code>value_array-><link + * linkend="GValueArray.n-values">n_values</link></code> * * Remove the value at position @index_ from @value_array. * @@ -5262,7 +5494,8 @@ * its reference count. If the contents of the #GValue are %NULL, then * %NULL will be returned. * - * Returns: (type GObject.Object) (transfer full): object content of @value, should be unreferenced when no longer needed. + * Returns: (type GObject.Object) (transfer full): object content of @value, + * should be unreferenced when no longer needed. */ @@ -5273,7 +5506,8 @@ * Get the contents of a %G_TYPE_PARAM #GValue, increasing its * reference count. * - * Returns: #GParamSpec content of @value, should be unreferenced when no longer needed. + * Returns: #GParamSpec content of @value, should be unreferenced when + * no longer needed. */ @@ -5293,7 +5527,8 @@ * * Get the contents of a variant #GValue, increasing its refcount. * - * Returns: variant contents of @value, should be unrefed using g_variant_unref() when no longer needed + * Returns: variant contents of @value, should be unrefed using + * g_variant_unref() when no longer needed * Since: 2.26 */ @@ -5541,7 +5776,10 @@ * g_value_peek_pointer: * @value: An initialized #GValue structure. * - * 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. + * 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. */ @@ -5549,7 +5787,8 @@ * g_value_register_transform_func: (skip) * @src_type: Source type. * @dest_type: Target type. - * @transform_func: a function which transforms values of type @src_type into value of type @dest_type + * @transform_func: a function which transforms values of type @src_type + * into value of type @dest_type * * Registers a value transformation function for use in g_value_transform(). * A previously registered transformation function for @src_type and @dest_type @@ -5941,7 +6180,8 @@ * results and shouldn't be relied upon for production code (such * as rcfile value or object property serialization). * - * Returns: Whether a transformation rule was found and could be applied. Upon failing transformations, @dest_value is left untouched. + * Returns: Whether a transformation rule was found and could be applied. + * Upon failing transformations, @dest_value is left untouched. */ @@ -5990,7 +6230,8 @@ /** * g_weak_ref_clear: (skip) - * @weak_ref: (inout): location of a weak reference, which may be empty + * @weak_ref: (inout): location of a weak reference, which + * may be empty * * Frees resources associated with a non-statically-allocated #GWeakRef. * After this call, the #GWeakRef is left in an undefined state. @@ -6016,14 +6257,16 @@ * The caller should release the resulting reference in the usual way, * by using g_object_unref(). * - * Returns: (transfer full) (type GObject.Object): the object pointed to by @weak_ref, or %NULL if it was empty + * Returns: (transfer full) (type GObject.Object): the object pointed to + * by @weak_ref, or %NULL if it was empty * Since: 2.32 */ /** * g_weak_ref_init: (skip) - * @weak_ref: (inout): uninitialized or empty location for a weak reference + * @weak_ref: (inout): uninitialized or empty location for a weak + * reference * @object: (allow-none): a #GObject or %NULL * * Initialise a non-statically-allocated #GWeakRef. diff --git a/giscanner/annotationparser.py b/giscanner/annotationparser.py index 542734a0..45b2e66b 100644 --- a/giscanner/annotationparser.py +++ b/giscanner/annotationparser.py @@ -1039,7 +1039,8 @@ class GtkDocCommentBlock(GtkDocAnnotatable): lines[0] += ' ' + annotations for param in self.params.values(): - lines.append(param.to_gtk_doc()) + for l in param.to_gtk_doc().split('\n'): + lines.append(l) if self.description: lines.append('') for l in self.description.split('\n'): @@ -1047,12 +1048,12 @@ class GtkDocCommentBlock(GtkDocAnnotatable): if self.tags: lines.append('') for tag in self.tags.values(): - lines.append(tag.to_gtk_doc()) + for l in tag.to_gtk_doc().split('\n'): + lines.append(l) comment = '' comment += '/**\n' for line in lines: - line = line.rstrip() if line: comment += ' * %s\n' % (line, ) else: @@ -1493,10 +1494,10 @@ class GtkDocCommentBlockParser(object): in_part = PART_DESCRIPTION - if not comment_block.description: + if comment_block.description is None: comment_block.description = tag_fields else: - comment_block.description += '\n' + tag_fields + comment_block.description += '\n%s' % (tag_fields, ) continue # Now that the deprecated stuff is out of the way, continue parsing real tags @@ -1568,8 +1569,15 @@ class GtkDocCommentBlockParser(object): # If we get here, we must be in the middle of a multiline # comment block, parameter or tag description. #################################################################### + if EMPTY_LINE_RE.match(line) is None: + line = line.rstrip() + if in_part in [PART_IDENTIFIER, PART_DESCRIPTION]: if not comment_block.description: + if in_part == PART_IDENTIFIER: + self._validate_multiline_annotation_continuation(line, original_line, + column_offset, position) + if comment_block.description is None: comment_block.description = line else: comment_block.description += '\n' + line @@ -1578,8 +1586,10 @@ class GtkDocCommentBlockParser(object): if not current_part.description: self._validate_multiline_annotation_continuation(line, original_line, column_offset, position) - # Append to parameter description. - current_part.description += ' ' + line.strip() + if current_part.description is None: + current_part.description = line + else: + current_part.description += '\n' + line continue ######################################################################## @@ -1592,10 +1602,10 @@ class GtkDocCommentBlockParser(object): comment_block.description = comment_block.description.strip() for tag in comment_block.tags.values(): - self._clean_comment_block_part(tag) + self._clean_description_field(tag) for param in comment_block.params.values(): - self._clean_comment_block_part(param) + self._clean_description_field(param) comment_block.indentation = block_indent comment_block.validate() @@ -1603,11 +1613,21 @@ class GtkDocCommentBlockParser(object): else: return None - def _clean_comment_block_part(self, part): + def _clean_description_field(self, part): + ''' + Remove extraneous leading and trailing whitespace from description fields. + + :param part: a GTK-Doc comment block part having a description field + ''' + if part.description: - part.description = part.description.strip() - else: - part.description = None + if part.description.strip() == '': + part.description = None + else: + if EMPTY_LINE_RE.match(part.description.split('\n', 1)[0]): + part.description = part.description.rstrip() + else: + part.description = part.description.strip() def _validate_multiline_annotation_continuation(self, line, original_line, column_offset, position): @@ -1632,7 +1652,7 @@ class GtkDocCommentBlockParser(object): success, annotations, start_pos, end_pos = self._parse_annotations(position, column_offset, original_line, line, False) - if annotations: + if success and annotations: marker = ' ' * (start_pos + column_offset) + '^' warn('ignoring invalid multiline annotation continuation:\n%s\n%s' % (original_line, marker), diff --git a/giscanner/maintransformer.py b/giscanner/maintransformer.py index d356aacb..5ae83ace 100644 --- a/giscanner/maintransformer.py +++ b/giscanner/maintransformer.py @@ -214,8 +214,8 @@ class MainTransformer(object): name = self._get_annotation_name(node) section_name = 'SECTION:%s' % (name.lower(), ) block = self._blocks.get(section_name) - if block: - node.doc = block.description if block.description else '' + if block and block.description: + node.doc = block.description if isinstance(node, (ast.Class, ast.Interface)): for prop in node.properties: self._apply_annotations_property(node, prop) @@ -565,7 +565,7 @@ class MainTransformer(object): or node.type.target_giname == 'Gio.Cancellable'): node.allow_none = True - if tag is not None and tag.description is not None: + if tag and tag.description: node.doc = tag.description if ANN_SKIP in annotations: @@ -582,7 +582,8 @@ class MainTransformer(object): if block is None: return - node.doc = block.description if block.description else '' + if block.description: + node.doc = block.description since_tag = block.tags.get(TAG_SINCE) if since_tag is not None: @@ -794,7 +795,7 @@ class MainTransformer(object): for m in node.members: tag = block.params.get(m.symbol, None) - if tag is not None: + if tag and tag.description: m.doc = tag.description def _pass_read_annotations2(self, node, chain): diff --git a/tests/scanner/Makefile.am b/tests/scanner/Makefile.am index aa5b55af..3eef89b3 100644 --- a/tests/scanner/Makefile.am +++ b/tests/scanner/Makefile.am @@ -231,6 +231,7 @@ EXTRA_DIST += \ annotationparser/gi/syntax.xml \ annotationparser/gi/syntax_nested_tags.xml \ annotationparser/gi/syntax_paragraph_breaks.xml \ + annotationparser/gi/syntax_whitespace.xml \ annotationparser/gi/tag.xml \ annotationparser/gi/tag_deprecated.xml \ annotationparser/gi/tag_description.xml \ diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_n.page b/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_n.page index feb7a55e..91ebe4b6 100644 --- a/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_n.page +++ b/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_n.page @@ -49,7 +49,8 @@ void regress_annotation_object_compute_sum_n (RegressAnnotationObject* object, </item> <item> <title><code>nums</code></title> -<p>Sequence of numbers that are zero-terminated</p> +<p>Sequence of + numbers that are zero-terminated</p> </item> <item> <title><code>n_nums</code></title> diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_nz.page b/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_nz.page index 2af59a52..7f5b0cf2 100644 --- a/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_nz.page +++ b/tests/scanner/Regress-1.0-C-expected/Regress.AnnotationObject.compute_sum_nz.page @@ -49,7 +49,8 @@ void regress_annotation_object_compute_sum_nz (RegressAnnotationObject* object, </item> <item> <title><code>nums</code></title> -<p>Sequence of numbers that are zero-terminated</p> +<p>Sequence of numbers that +are zero-terminated</p> </item> <item> <title><code>n_nums</code></title> diff --git a/tests/scanner/Regress-1.0-C-expected/Regress.test_ghash_gvalue_in.page b/tests/scanner/Regress-1.0-C-expected/Regress.test_ghash_gvalue_in.page index b6d2da5f..7603f2aa 100644 --- a/tests/scanner/Regress-1.0-C-expected/Regress.test_ghash_gvalue_in.page +++ b/tests/scanner/Regress-1.0-C-expected/Regress.test_ghash_gvalue_in.page @@ -35,7 +35,8 @@ void regress_test_ghash_gvalue_in (GHashTable* hash); <terms> <item> <title><code>hash</code></title> -<p>the hash table returned by <link xref="Regress.test_ghash_gvalue_return"/>.</p> +<p>the hash table returned by +<link xref="Regress.test_ghash_gvalue_return"/>.</p> </item> <item> <title><code>Returns</code></title> diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_n.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_n.page index 16b62150..932b1922 100644 --- a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_n.page +++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_n.page @@ -37,7 +37,8 @@ function compute_sum_n(nums:[Number]):void { <terms> <item> <title><code>nums</code></title> -<p>Sequence of numbers that are zero-terminated</p> +<p>Sequence of + numbers that are zero-terminated</p> </item> </terms> diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_nz.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_nz.page index f4a3b7d6..3891049b 100644 --- a/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_nz.page +++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.AnnotationObject.compute_sum_nz.page @@ -37,7 +37,8 @@ function compute_sum_nz(nums:[Number]):void { <terms> <item> <title><code>nums</code></title> -<p>Sequence of numbers that are zero-terminated</p> +<p>Sequence of numbers that +are zero-terminated</p> </item> </terms> diff --git a/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_ghash_gvalue_in.page b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_ghash_gvalue_in.page index 2c801375..b12b8f8b 100644 --- a/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_ghash_gvalue_in.page +++ b/tests/scanner/Regress-1.0-Gjs-expected/Regress.test_ghash_gvalue_in.page @@ -37,7 +37,8 @@ function test_ghash_gvalue_in(hash:{String: GObject.Value}):void { <terms> <item> <title><code>hash</code></title> -<p>the hash table returned by <link xref="Regress.test_ghash_gvalue_return"/>.</p> +<p>the hash table returned by +<link xref="Regress.test_ghash_gvalue_return"/>.</p> </item> </terms> diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_n.page b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_n.page index fc993130..33463c4f 100644 --- a/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_n.page +++ b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_n.page @@ -50,7 +50,8 @@ def compute_sum_n(self, nums, n_nums): </item> <item> <title><code>nums</code></title> -<p>Sequence of numbers that are zero-terminated</p> +<p>Sequence of + numbers that are zero-terminated</p> </item> <item> <title><code>n_nums</code></title> diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_nz.page b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_nz.page index 67efe7c5..b3beb695 100644 --- a/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_nz.page +++ b/tests/scanner/Regress-1.0-Python-expected/Regress.AnnotationObject.compute_sum_nz.page @@ -50,7 +50,8 @@ def compute_sum_nz(self, nums, n_nums): </item> <item> <title><code>nums</code></title> -<p>Sequence of numbers that are zero-terminated</p> +<p>Sequence of numbers that +are zero-terminated</p> </item> <item> <title><code>n_nums</code></title> diff --git a/tests/scanner/Regress-1.0-Python-expected/Regress.test_ghash_gvalue_in.page b/tests/scanner/Regress-1.0-Python-expected/Regress.test_ghash_gvalue_in.page index 5bbde33c..8273602b 100644 --- a/tests/scanner/Regress-1.0-Python-expected/Regress.test_ghash_gvalue_in.page +++ b/tests/scanner/Regress-1.0-Python-expected/Regress.test_ghash_gvalue_in.page @@ -38,7 +38,8 @@ def test_ghash_gvalue_in(hash): <terms> <item> <title><code>hash</code></title> -<p>the hash table returned by <link xref="Regress.test_ghash_gvalue_return"/>.</p> +<p>the hash table returned by +<link xref="Regress.test_ghash_gvalue_return"/>.</p> </item> </terms> diff --git a/tests/scanner/Regress-1.0-expected.gir b/tests/scanner/Regress-1.0-expected.gir index 94962c95..070f9927 100644 --- a/tests/scanner/Regress-1.0-expected.gir +++ b/tests/scanner/Regress-1.0-expected.gir @@ -240,7 +240,8 @@ and/or use gtk-doc annotations. --> <type name="AnnotationObject" c:type="RegressAnnotationObject*"/> </instance-parameter> <parameter name="nums" transfer-ownership="none"> - <doc xml:space="preserve">Sequence of numbers that are zero-terminated</doc> + <doc xml:space="preserve">Sequence of + numbers that are zero-terminated</doc> <array length="1" zero-terminated="0" c:type="int*"> <type name="gint" c:type="int"/> </array> @@ -263,7 +264,8 @@ and/or use gtk-doc annotations. --> <type name="AnnotationObject" c:type="RegressAnnotationObject*"/> </instance-parameter> <parameter name="nums" transfer-ownership="none"> - <doc xml:space="preserve">Sequence of numbers that are zero-terminated</doc> + <doc xml:space="preserve">Sequence of numbers that +are zero-terminated</doc> <array length="1" zero-terminated="1" c:type="int*"> <type name="gint" c:type="int"/> </array> @@ -5319,7 +5321,8 @@ call and can be released on return.</doc> </return-value> <parameters> <parameter name="hash" transfer-ownership="none"> - <doc xml:space="preserve">the hash table returned by regress_test_ghash_gvalue_return().</doc> + <doc xml:space="preserve">the hash table returned by +regress_test_ghash_gvalue_return().</doc> <type name="GLib.HashTable" c:type="GHashTable*"> <type name="utf8"/> <type name="GObject.Value"/> @@ -6420,9 +6423,12 @@ https://bugzilla.gnome.org/show_bug.cgi?id=685399</doc> deprecated="1" deprecated-version="1.33.3" stability="Unstable"> - <doc-version xml:space="preserve">Actually, this function was introduced earlier than this, but it didn't do anything before this version.</doc-version> - <doc-deprecated xml:space="preserve">This function has been deprecated, because it sucks. Use foobar instead.</doc-deprecated> - <doc-stability xml:space="preserve">Maybe someday we will find the time to stabilize this function. Who knows?</doc-stability> + <doc-version xml:space="preserve">Actually, this function was introduced earlier + than this, but it didn't do anything before this version.</doc-version> + <doc-deprecated xml:space="preserve">This function has been deprecated, + because it sucks. Use foobar instead.</doc-deprecated> + <doc-stability xml:space="preserve">Maybe someday we will find the time + to stabilize this function. Who knows?</doc-stability> <return-value transfer-ownership="none"> <type name="none" c:type="void"/> </return-value> diff --git a/tests/scanner/annotationparser/gi/annotation_array.xml b/tests/scanner/annotationparser/gi/annotation_array.xml index a59c267a..b821dcfc 100644 --- a/tests/scanner/annotationparser/gi/annotation_array.xml +++ b/tests/scanner/annotationparser/gi/annotation_array.xml @@ -67,7 +67,8 @@ </options> </annotation> </annotations> - <description>Sequence of numbers that are zero-terminated</description> + <description>Sequence of + numbers that are zero-terminated</description> </parameter> <parameter> <name>n_nums</name> @@ -116,7 +117,8 @@ </options> </annotation> </annotations> - <description>Sequence of numbers that are zero-terminated</description> + <description>Sequence of numbers that +are zero-terminated</description> </parameter> <parameter> <name>n_nums</name> diff --git a/tests/scanner/annotationparser/gi/parameter.xml b/tests/scanner/annotationparser/gi/parameter.xml index d6c4ab37..809b9d89 100644 --- a/tests/scanner/annotationparser/gi/parameter.xml +++ b/tests/scanner/annotationparser/gi/parameter.xml @@ -88,7 +88,8 @@ <name>allow-none</name> </annotation> </annotations> - <description>(transfer full): first parameter</description> + <description> +(transfer full): first parameter</description> </parameter> </parameters> <description>Annotations spanning multiple lines are not valid</description> @@ -122,7 +123,8 @@ <name>allow-none</name> </annotation> </annotations> - <description>first parameter having a second line which looks (like an annotation), but isn't. This should not result in a warning.</description> + <description>first parameter having a second line which looks +(like an annotation), but isn't. This should not result in a warning.</description> </parameter> </parameters> <description>Annotations spanning multiple lines are not valid</description> diff --git a/tests/scanner/annotationparser/gi/parameter_varargs.xml b/tests/scanner/annotationparser/gi/parameter_varargs.xml index b873de28..0952ee92 100644 --- a/tests/scanner/annotationparser/gi/parameter_varargs.xml +++ b/tests/scanner/annotationparser/gi/parameter_varargs.xml @@ -28,7 +28,8 @@ <parameters> <parameter> <name>par1</name> - <description>description of parameter 1. These can extend over more than one line.</description> + <description>description of parameter 1. These can extend over more than +one line.</description> </parameter> <parameter> <name>par2</name> @@ -134,7 +135,8 @@ name it is called in.</description> <parameters> <parameter> <name>par1</name> - <description>description of parameter 1. These can extend over more than one line.</description> + <description>description of parameter 1. These can extend over more than +one line.</description> </parameter> <parameter> <name>par2</name> @@ -202,7 +204,8 @@ other declarations (which may be documented elsewhere).</description> <parameters> <parameter> <name>par1</name> - <description>description of parameter 1. These can extend over more than one line.</description> + <description>description of parameter 1. These can extend over more than +one line.</description> </parameter> <parameter> <name>par2</name> diff --git a/tests/scanner/annotationparser/gi/syntax_nested_tags.xml b/tests/scanner/annotationparser/gi/syntax_nested_tags.xml index 4ebe0ea4..d5a30423 100644 --- a/tests/scanner/annotationparser/gi/syntax_nested_tags.xml +++ b/tests/scanner/annotationparser/gi/syntax_nested_tags.xml @@ -28,7 +28,12 @@ <parameters> <parameter> <name>G_APPLICATION_NON_UNIQUE</name> - <description>Make no attempts to do any of the typical single-instance application negotiation, even if the application ID is given. The application neither attempts to become the owner of the application ID nor does it check if an existing owner already exists. Everything occurs in the local process. Since: 2.30.</description> + <description>Make no attempts to do any of the typical + single-instance application negotiation, even if the application + ID is given. The application neither attempts to become the + owner of the application ID nor does it check if an existing + owner already exists. Everything occurs in the local process. + Since: 2.30.</description> </parameter> </parameters> <description>Flags used to define the behaviour of a #GApplication.</description> diff --git a/tests/scanner/annotationparser/gi/syntax_whitespace.xml b/tests/scanner/annotationparser/gi/syntax_whitespace.xml new file mode 100644 index 00000000..e66836c2 --- /dev/null +++ b/tests/scanner/annotationparser/gi/syntax_whitespace.xml @@ -0,0 +1,62 @@ +<?xml version="1.0" encoding="UTF-8"?> + +<tests xmlns="http://schemas.gnome.org/gobject-introspection/2013/test"> + +<test> + <input>/** + * whitespace_test: + * @object: (skip): + * + * A #AnnotationObject + * + * + * @func: The callback + * + * + * Test overriding via the "Rename To" annotation. + * + * + * Returns: nothing + * + * + */</input> + <parser> + <docblock> + <identifier> + <name>whitespace_test</name> + </identifier> + <parameters> + <parameter> + <name>object</name> + <annotations> + <annotation> + <name>skip</name> + </annotation> + </annotations> + </parameter> + <parameter> + <name>func</name> + <description>The callback</description> + </parameter> + </parameters> + <description>A #AnnotationObject + + + +Test overriding via the "Rename To" annotation.</description> + <tags> + <tag> + <name>returns</name> + <description>nothing</description> + </tag> + </tags> + </docblock> + <messages> + <message>8: Warning: Test: "@func" parameter unexpected at this location: + * @func: The callback + ^</message> + </messages> + </parser> +</test> + +</tests> diff --git a/tests/scanner/annotationparser/gi/tag.xml b/tests/scanner/annotationparser/gi/tag.xml index 2dfe41aa..d7eca816 100644 --- a/tests/scanner/annotationparser/gi/tag.xml +++ b/tests/scanner/annotationparser/gi/tag.xml @@ -25,7 +25,8 @@ <name>allow-none</name> </annotation> </annotations> - <description>(transfer full): something</description> + <description> +(transfer full): something</description> </tag> </tags> </docblock> @@ -60,7 +61,8 @@ <name>allow-none</name> </annotation> </annotations> - <description>Returns tag having a second line which looks (like an annotation), but isn't. This should not result in a warning.</description> + <description>Returns tag having a second line which looks +(like an annotation), but isn't. This should not result in a warning.</description> </tag> </tags> </docblock> diff --git a/tests/scanner/annotationparser/gi/tag_returns.xml b/tests/scanner/annotationparser/gi/tag_returns.xml index ec6e2c45..2f76e025 100644 --- a/tests/scanner/annotationparser/gi/tag_returns.xml +++ b/tests/scanner/annotationparser/gi/tag_returns.xml @@ -53,7 +53,9 @@ <tags> <tag> <name>returns</name> - <description>something Tags should go after the comment block description</description> + <description>something + +Tags should go after the comment block description</description> </tag> </tags> </docblock> diff --git a/tests/scanner/annotationparser/gi/tag_since.xml b/tests/scanner/annotationparser/gi/tag_since.xml index 502d8b6e..78ce7865 100644 --- a/tests/scanner/annotationparser/gi/tag_since.xml +++ b/tests/scanner/annotationparser/gi/tag_since.xml @@ -91,7 +91,8 @@ <tag> <name>since</name> <value>2.0</value> - <description>one of these "Since:" tags is wrong...</description> + <description>one of these "Since:" +tags is wrong...</description> </tag> </tags> </docblock> diff --git a/tests/scanner/annotationparser/gtkdoc/annotations/tester.c.xml b/tests/scanner/annotationparser/gtkdoc/annotations/tester.c.xml index a39b1502..9fda10b5 100644 --- a/tests/scanner/annotationparser/gtkdoc/annotations/tester.c.xml +++ b/tests/scanner/annotationparser/gtkdoc/annotations/tester.c.xml @@ -98,7 +98,8 @@ <name>allow-none</name> </annotation> </annotations> - <description>an optional string, which is used in ways too complicated to describe in a single line, making it necessary to wrap it</description> + <description>an optional string, which is used in ways too + complicated to describe in a single line, making it necessary to wrap it</description> </parameter> </parameters> <description>Document optional parameters.</description> @@ -118,7 +119,8 @@ <name>allow-none</name> </annotation> </annotations> - <description>Returns stuff which you have to free after use, whose description is also rather long</description> + <description>Returns stuff which you have to + free after use, whose description is also rather long</description> </tag> </tags> </docblock> diff --git a/tests/scanner/annotationparser/gtkdoc/gobject/giface.c.xml b/tests/scanner/annotationparser/gtkdoc/gobject/giface.c.xml index 053b44b4..dc9ae531 100644 --- a/tests/scanner/annotationparser/gtkdoc/gobject/giface.c.xml +++ b/tests/scanner/annotationparser/gtkdoc/gobject/giface.c.xml @@ -100,7 +100,6 @@ or \# or even \@.]]></description> * Configure a new instance * * Returns: %TRUE for sucess or %FALSE in case of an error - * * Since: 0.1 */</input> <parser> diff --git a/tests/scanner/annotationparser/gtkdoc/gobject/gobject.c.xml b/tests/scanner/annotationparser/gtkdoc/gobject/gobject.c.xml index 7234ed8a..111b5d67 100644 --- a/tests/scanner/annotationparser/gtkdoc/gobject/gobject.c.xml +++ b/tests/scanner/annotationparser/gtkdoc/gobject/gobject.c.xml @@ -207,7 +207,8 @@ All the internal details go here or not: </parameter> <parameter> <name>value</name> - <description>the new otest value, whose description extends further than one line will allow</description> + <description>the new otest value, whose description extends further than one + line will allow</description> </parameter> </parameters> <description>Set the #GtkdocObject:otest property.</description> diff --git a/tests/scanner/annotationparser/gtkdoc/gobject/gtypes.h.xml b/tests/scanner/annotationparser/gtkdoc/gobject/gtypes.h.xml index 4965adbe..644d5946 100644 --- a/tests/scanner/annotationparser/gtkdoc/gobject/gtypes.h.xml +++ b/tests/scanner/annotationparser/gtkdoc/gobject/gtypes.h.xml @@ -23,7 +23,8 @@ </parameter> <parameter> <name>GTKDOC_ENUM_V2</name> - <description>second Since: 0.10</description> + <description>second + Since: 0.10</description> </parameter> </parameters> <description>Enum values for the #GtkdocEnum type.</description> diff --git a/tests/scanner/annotationparser/test_patterns.py b/tests/scanner/annotationparser/test_patterns.py index ead487d7..207fdc63 100644 --- a/tests/scanner/annotationparser/test_patterns.py +++ b/tests/scanner/annotationparser/test_patterns.py @@ -32,7 +32,7 @@ against the expected output. from giscanner.annotationparser import (COMMENT_BLOCK_START_RE, COMMENT_BLOCK_END_RE, - COMMENT_ASTERISK_RE, + COMMENT_ASTERISK_RE, INDENTATION_RE, EMPTY_LINE_RE, SECTION_RE, SYMBOL_RE, PROPERTY_RE, SIGNAL_RE, PARAMETER_RE, TAG_RE, TAG_VALUE_VERSION_RE, TAG_VALUE_STABILITY_RE) @@ -175,6 +175,28 @@ comment_asterisk_tests = [ None)] +indentaton_tests = [ + (INDENTATION_RE, '', + {'indentation': ''}), + (INDENTATION_RE, ' ', + {'indentation': ' '}), + (INDENTATION_RE, ' ', + {'indentation': ' '}), + (INDENTATION_RE, ' x', + {'indentation': ' '}), + (INDENTATION_RE, ' *', + {'indentation': ' '})] + + +empty_line_tests = [ + (EMPTY_LINE_RE, '', + {}), + (EMPTY_LINE_RE, ' ', + {}), + (EMPTY_LINE_RE, ' .', + None)] + + identifier_section_tests = [ (SECTION_RE, 'TSIEOCN', None), @@ -752,6 +774,8 @@ if __name__ == '__main__': create_tests('test_comment_start', comment_start_tests) create_tests('test_comment_end', comment_end_tests) create_tests('test_comment_asterisk', comment_asterisk_tests) + create_tests('test_indentaton', indentaton_tests) + create_tests('test_empty_line', empty_line_tests) create_tests('test_identifier_section', identifier_section_tests) create_tests('test_identifier_symbol', identifier_symbol_tests) create_tests('test_identifier_property', identifier_property_tests) |