[gobject-introspection] Update annotations for GLib 2.31.14

From: Rico Tzschichholz <ricotz src gnome org>
To: commits-list gnome org
Cc:
Subject: [gobject-introspection] Update annotations for GLib 2.31.14
Date: Tue, 31 Jan 2012 07:13:28 +0000 (UTC)
commit 8a30b9dd3981d3e0c3076232c504edf850624893
Author: Rico Tzschichholz <ricotz t-online de>
Date:   Tue Jan 31 08:09:21 2012 +0100

    Update annotations for GLib 2.31.14

 gir/gio-2.0.c     |  387 +++++++++++++++++++++++++----------------------------
 gir/glib-2.0.c    |   96 +++++++++++---
 gir/gobject-2.0.c |   59 ++++++++
 3 files changed, 324 insertions(+), 218 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index c50c393..2d93ce6 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -133,10 +133,9 @@
  * @get_action_state_hint: the virtual function pointer for g_action_group_get_action_state_hint()
  * @get_action_enabled: the virtual function pointer for g_action_group_get_action_enabled()
  * @get_action_state: the virtual function pointer for g_action_group_get_action_state()
- * @set_action_state: the virtual function pointer for g_action_group_set_action_state()
+ * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
  * @query_action: the virtual function pointer for g_action_group_query_action()
  * @activate_action: the virtual function pointer for g_action_group_activate_action()
- * @change_action_state: the virtual function pointer for g_action_group_change_action_state()
  * @action_added: the class closure for the #GActionGroup::action-added signal
  * @action_removed: the class closure for the #GActionGroup::action-removed signal
  * @action_enabled_changed: the class closure for the #GActionGroup::action-enabled-changed signal
@@ -1397,6 +1396,7 @@
  * @get_info: Returns a #GDBusInterfaceInfo. See g_dbus_interface_get_info().
  * @get_object: Gets the enclosing #GDBusObject. See g_dbus_interface_get_object().
  * @set_object: Sets the enclosing #GDBusObject. See g_dbus_interface_set_object().
+ * @dup_object: Gets a reference to the enclosing #GDBusObject. See g_dbus_interface_dup_object(). Added in 2.32.
  *
  * Base type for D-Bus interfaces.
  *
@@ -9688,6 +9688,7 @@
  * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
  *
  * Returns: %TRUE on success.
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -10097,6 +10098,8 @@
  * @pspec: a valid #GParamSpec instance
  *
  * Cast a #GParamSpec instance into a #GParamSpecValueArray.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -11282,6 +11285,8 @@
  * G_TYPE_PARAM_VALUE_ARRAY:
  *
  * The #GType of #GParamSpecValueArray.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -11470,6 +11475,8 @@
  *
  * The type ID of the "GValueArray" type which is a boxed type,
  * used to pass around pointers to GValueArrays.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -14266,48 +14273,6 @@
 
 
 /**
- * SECTION:gmenumarkup
- * @title: GMenu Markup
- * @short_description: parsing and printing GMenuModel XML
- *
- * The functions here allow to instantiate #GMenuModels by parsing
- * fragments of an XML document.
- * * The XML format for #GMenuModel consists of a toplevel
- * <tag class="starttag">menu</tag> element, which contains one or more
- * <tag class="starttag">item</tag> elements. Each <tag class="starttag">item</tag>
- * element contains <tag class="starttag">attribute</tag> and <tag class="starttag">link</tag>
- * elements with a mandatory name attribute.
- * <tag class="starttag">link</tag> elements have the same content
- * model as <tag class="starttag">menu</tag>.
- *
- * Here is the XML for <xref linkend="menu-example"/>:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/menumarkup2.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
- *
- * The parser also understands a somewhat less verbose format, in which
- * attributes are encoded as actual XML attributes of <tag class="starttag">item</tag>
- * elements, and <tag class="starttag">link</tag> elements are replaced by
- * <tag class="starttag">section</tag> and <tag class="starttag">submenu</tag> elements.
- *
- * Here is how the example looks in this format:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/menumarkup.xml"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
- *
- * The parser can obtaing translations for attribute values using gettext.
- * To make use of this, the <tag class="starttag">menu</tag> element must
- * have a domain attribute which specifies the gettext domain to use, and
- * <tag class="starttag">attribute</tag> elements can be marked for translation
- * with a <literal>translatable="yes"</literal> attribute. It is also possible
- * to specify message context and translator comments, using the context
- * and comments attributes.
- *
- * The following DTD describes the XML format approximately:
- * |[<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; parse="text" href="../../../../gio/menumarkup.dtd"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>]|
- *
- * To serialize a #GMenuModel into an XML fragment, use
- * g_menu_markup_print_string().
- */
-
-
-/**
  * SECTION:gmenumodel
  * @title: GMenuModel
  * @short_description: An abstract class representing the contents of a menu
@@ -14517,7 +14482,9 @@
  * @short_description: Network status monitor
  * @include: gio/gio.h
  *
- *
+ * #GNetworkMonitor provides an easy-to-use cross-platform API
+ * for monitoring network connectivity. On Linux, the implementation
+ * is based on the kernels netlink interface.
  */
 
 
@@ -14710,6 +14677,14 @@
  * in a compressed form, but will be automatically uncompressed when the resource is used. This
  * is very useful e.g. for larger text files that are parsed once (or rarely) and then thrown away.
  *
+ * Resource files can also be marked to be preprocessed, by setting the value of the
+ * <literal>preprocess</literal> attribute to a comma-separated list of preprocessing options.
+ * The only option currently supported is
+ * <literal>xml-stripblanks</literal> which will use <literal>xmllint</literal> to strip
+ * ignorable whitespace from the xml file. For this to work, the <envar>XMLLINT</envar>
+ * environment variable must be set to the full path to the xmllint executable;
+ * otherwise the preprocessing step is skipped.
+ *
  * Resource bundles are created by the <link linkend="glib-compile-schemas">glib-compile-resources</link> program
  * which takes an xml file that describes the bundle, and a set of files that the xml references. These
  * are combined into a binary resource bundle.
@@ -14721,7 +14696,7 @@
  * <gresource prefix="/org/gtk/Example">
  * <file>data/splashscreen.png</file>
  * <file compressed="true">dialog.ui</file>
- * <file>menumarkup.xml</file>
+ * <file preprocess="xml-stripblanks">menumarkup.xml</file>
  * </gresource>
  * </gresources>
  * ]]></programlisting></example>
@@ -17543,7 +17518,6 @@
 
 /**
  * g_application_get_default:
- * @returns: (transfer none): the default application for this process, or %NULL
  *
  * Returns the default #GApplication instance for this process.
  *
@@ -17553,6 +17527,7 @@
  *
  * If there is no default application then %NULL is returned.
  *
+ * Returns: (transfer none): the default application for this process, or %NULL
  * Since: 2.32
  */
 
@@ -21499,6 +21474,20 @@
 
 
 /**
+ * g_dbus_interface_dup_object:
+ * @interface_: An exported D-Bus interface.
+ *
+ * Gets the #GDBusObject that @interface_ belongs to, if any.
+ *
+ * reference should be freed with g_object_unref().
+ *
+ * Returns: (transfer full): A #GDBusObject or %NULL. The returned
+ * Since: 2.32
+ * Rename to: g_dbus_interface_get_object
+ */
+
+
+/**
  * g_dbus_interface_get_info:
  * @interface_: An exported D-Bus interface.
  *
@@ -21511,11 +21500,16 @@
 
 
 /**
- * g_dbus_interface_get_object:
+ * g_dbus_interface_get_object: (skip)
  * @interface_: An exported D-Bus interface.
  *
  * Gets the #GDBusObject that @interface_ belongs to, if any.
  *
+ * <warning>It is not safe to use the returned object if @interface_
+ * or the returned object is being used from other threads. See
+ * g_dbus_interface_dup_object() for a thread-safe
+ * alternative.</warning>
+ *
  * reference belongs to @interface_ and should not be freed.
  *
  * Returns: (transfer none): A #GDBusObject or %NULL. The returned
@@ -28818,18 +28812,6 @@
 
 
 /**
- * g_inet_address_get_scope_id:
- * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
- *
- * Gets the <literal>sin6_scope_id</literal> field from @address,
- * which must be an IPv6 address.
- *
- * Returns: the scope id field
- * Since: 2.32
- */
-
-
-/**
  * g_inet_address_mask_equal:
  * @mask: a #GInetAddressMask
  * @mask2: another #GInetAddressMask
@@ -29048,6 +29030,18 @@
 
 
 /**
+ * g_inet_socket_address_get_scope_id:
+ * @address: a %G_SOCKET_FAMILY_IPV6 #GInetAddress
+ *
+ * Gets the <literal>sin6_scope_id</literal> field from @address,
+ * which must be an IPv6 address.
+ *
+ * Returns: the scope id field
+ * Since: 2.32
+ */
+
+
+/**
  * g_inet_socket_address_new:
  * @address: a #GInetAddress
  * @port: a port number
@@ -31005,130 +30999,6 @@
 
 
 /**
- * g_menu_markup_parser_end:
- * @context: a #GMarkupParseContext
- *
- * Stop the parsing of a set of menus and return the #GHashTable.
- *
- * The #GHashTable maps strings to #GObject instances.  The parser only
- * adds #GMenu instances to the table, but it may contain other types if
- * a table was provided to g_menu_markup_parser_start().
- *
- * This call should be matched with g_menu_markup_parser_start().
- * See that function for more information
- *
- * Returns: (transfer full): the #GHashTable containing the objects
- * Since: 2.32
- */
-
-
-/**
- * g_menu_markup_parser_end_menu:
- * @context: a #GMarkupParseContext
- *
- * Stop the parsing of a menu and return the newly-created #GMenu.
- *
- * This call should be matched with g_menu_markup_parser_start_menu().
- * See that function for more information
- *
- * Returns: (transfer full): the newly-created #GMenu
- * Since: 2.32
- */
-
-
-/**
- * g_menu_markup_parser_start:
- * @context: a #GMarkupParseContext
- * @domain: (allow-none): translation domain for labels, or %NULL
- * @objects: (allow-none): a #GHashTable for the objects, or %NULL
- *
- * Begin parsing a group of menus in XML form.
- *
- * If @domain is not %NULL, it will be used to translate attributes
- * that are marked as translatable, using gettext().
- *
- * If @objects is specified then it must be a #GHashTable that was
- * created using g_hash_table_new_full() with g_str_hash(),
- * g_str_equal(), g_free() and g_object_unref().
- * Any named menus (ie: <tag class="starttag">menu</tag>,
- * <tag class="starttag">submenu</tag>,
- * <tag class="starttag">section</tag> or <tag class="starttag">link</tag>
- * elements with an id='' attribute) that are encountered while parsing
- * will be added to this table. Each toplevel menu must be named.
- *
- * If @objects is %NULL then an empty hash table will be created.
- *
- * This function should be called from the start_element function for
- * the element representing the group containing the menus.  In other
- * words, the content inside of this element is expected to be a list of
- * menus.
- *
- * Since: 2.32
- */
-
-
-/**
- * g_menu_markup_parser_start_menu:
- * @context: a #GMarkupParseContext
- * @domain: (allow-none): translation domain for labels, or %NULL
- * @objects: (allow-none): a #GHashTable for the objects, or %NULL
- *
- * Begin parsing the XML definition of a menu.
- *
- * This function should be called from the start_element function for
- * the element representing the menu itself.  In other words, the
- * content inside of this element is expected to be a list of items.
- *
- * If @domain is not %NULL, it will be used to translate attributes
- * that are marked as translatable, using gettext().
- *
- * If @objects is specified then it must be a #GHashTable that was
- * created using g_hash_table_new_full() with g_str_hash(),
- * g_str_equal(), g_free() and g_object_unref().
- * Any named menus (ie: <tag class="starttag">submenu</tag>,
- * <tag class="starttag">section</tag> or <tag class="starttag">link</tag>
- * elements with an id='' attribute) that are encountered while parsing
- * will be added to this table.
- * Note that toplevel <tag class="starttag">menu</tag> is not added to
- * the hash table, even if it has an id attribute.
- *
- * If @objects is %NULL then named menus will not be supported.
- *
- * You should call g_menu_markup_parser_end_menu() from the
- * corresponding end_element function in order to collect the newly
- * parsed menu.
- *
- * Since: 2.32
- */
-
-
-/**
- * g_menu_markup_print_stderr:
- * @model: a #GMenuModel
- *
- * Print @model to stderr for debugging purposes.
- *
- * This debugging function will be removed in the future.
- */
-
-
-/**
- * g_menu_markup_print_string:
- * @string: a #GString
- * @model: the #GMenuModel to print
- * @indent: the intentation level to start at
- * @tabstop: how much to indent each level
- *
- * Print the contents of @model to @string.
- * Note that you have to provide the containing
- * <tag class="starttag">menu</tag> element yourself.
- *
- * Returns: @string
- * Since: 2.32
- */
-
-
-/**
  * g_menu_model_get_item_attribute:
  * @model: a #GMenuModel
  * @item_index: the index of the item
@@ -32073,6 +31943,39 @@
 
 
 /**
+ * g_network_monitor_can_reach_async:
+ * @monitor: a #GNetworkMonitor
+ * @connectable: a #GSocketConnectable
+ * @cancellable: a #GCancellable, or %NULL
+ * @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
+ * pointed to by @connectable can be reached, without actually
+ * trying to connect to it.
+ *
+ * For more details, see g_network_monitor_can_reach().
+ *
+ * When the operation is finished, @callback will be called.
+ * You can then call g_network_monitor_can_reach_finish()
+ * to get the result of the operation.
+ */
+
+
+/**
+ * g_network_monitor_can_reach_finish:
+ * @monitor: a #GNetworkMonitor
+ * @result: a #GAsyncResult
+ * @error: return location for errors, or %NULL
+ *
+ * Finishes an async network connectivity test.
+ * See g_network_monitor_can_reach_async().
+ *
+ * Returns: %TRUE if network is reachable, %FALSE if not.
+ */
+
+
+/**
  * g_network_monitor_get_default:
  *
  * Gets the default #GNetworkMonitor for the system.
@@ -32263,6 +32166,18 @@
 
 
 /**
+ * g_node_insert_data_after:
+ * @parent: the #GNode to place the new #GNode under
+ * @sibling: the sibling #GNode to place the new #GNode after
+ * @data: the data for the new #GNode
+ *
+ * Inserts a new #GNode after the given sibling.
+ *
+ * Returns: the new #GNode
+ */
+
+
+/**
  * g_node_insert_data_before:
  * @parent: the #GNode to place the new #GNode under
  * @sibling: the sibling #GNode to place the new #GNode before
@@ -33283,6 +33198,27 @@
 
 /**
  * g_remote_action_group_activate_action_full:
+ * @remote: a #GDBusActionGroup
+ * @action_name: the name of the action to activate
+ * @parameter: (allow none): the optional parameter to the activation
+ * @platform_data: the platform data to send
+ *
+ * Activates the remote action.
+ *
+ * This is the same as g_action_group_activate_action() except that it
+ * allows for provision of "platform data" to be sent along with the
+ * activation request.  This typically contains details such as the user
+ * interaction timestamp or startup notification information.
+ *
+ * @platform_data must be non-%NULL and must have the type
+ * %G_VARIANT_TYPE_VARDICT.  If it is floating, it will be consumed.
+ *
+ * Since: 2.32
+ */
+
+
+/**
+ * g_remote_action_group_change_action_state_full:
  * @remote: a #GRemoteActionGroup
  * @action_name: the name of the action to change the state of
  * @value: the new requested value for the state
@@ -34210,6 +34146,31 @@
 
 
 /**
+ * g_settings_create_action:
+ * @settings: a #GSettings
+ * @key: the name of a key in @settings
+ *
+ * Creates a #GAction corresponding to a given #GSettings key.
+ *
+ * The action has the same name as the key.
+ *
+ * The value of the key becomes the state of the action and the action
+ * is enabled when the key is writable.  Changing the state of the
+ * action results in the key being written to.  Changes to the value or
+ * writability of the key cause appropriate change notifications to be
+ * emitted for the action.
+ *
+ * For boolean-valued keys, action activations take no parameter and
+ * result in the toggling of the value.  For all other types,
+ * activations take the new value for the key (which must have the
+ * correct type).
+ *
+ * Returns: (transfer full): a new #GAction
+ * Since: 2.32
+ */
+
+
+/**
  * g_settings_delay:
  * @settings: a #GSettings object
  *
@@ -35237,6 +35198,18 @@
 
 
 /**
+ * g_signal_handlers_disconnect_by_data:
+ * @instance: The instance to remove handlers from
+ * @data: the closure data of the handlers' closures
+ *
+ * Disconnects all handlers on an instance that match @data.
+ *
+ * Returns: The number of handlers that matched.
+ * Since: 2.32
+ */
+
+
+/**
  * g_signal_handlers_disconnect_by_func:
  * @instance: The instance to remove handlers from.
  * @func: The C closure callback of the handlers (useless for non-C closures).
@@ -37072,7 +37045,7 @@
  * g_socket_join_multicast_group:
  * @socket: a #GSocket.
  * @group: a #GInetAddress specifying the group address to join.
- * @iface: Interface to use
+ * @iface: (allow-none): Name of the interface to use, or %NULL
  * @source_specific: %TRUE if source-specific multicast should be used
  * @error: #GError for error reporting, or %NULL to ignore.
  *
@@ -37081,8 +37054,12 @@
  * been bound to an appropriate interface and port with
  * g_socket_bind().
  *
+ * If @iface is %NULL, the system will automatically pick an interface
+ * to bind to based on @group.
+ *
  * If @source_specific is %TRUE, source-specific multicast as defined
- * in RFC 4604 is used.
+ * in RFC 4604 is used. Note that on older platforms this may fail
+ * with a %G_IO_ERROR_NOT_SUPPORTED error.
  *
  * Returns: %TRUE on success, %FALSE on error.
  * Since: 2.32
@@ -37093,15 +37070,16 @@
  * g_socket_leave_multicast_group:
  * @socket: a #GSocket.
  * @group: a #GInetAddress specifying the group address to leave.
- * @iface: Interface to use
- * @source_specific: %TRUE if source-specific multicast should be used
+ * @iface: (allow-none): Interface used
+ * @source_specific: %TRUE if source-specific multicast was used
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Removes @socket from the multicast group @group (while still
- * allowing it to receive unicast messages).
+ * Removes @socket from the multicast group defined by @group, @iface,
+ * and @source_specific (which must all have the same values they had
+ * when you joined the group).
  *
- * If @source_specific is %TRUE, source-specific multicast as defined
- * in RFC 4604 is used.
+ * @socket remains bound to its address and port, and can still receive
+ * unicast messages after calling this.
  *
  * Returns: %TRUE on success, %FALSE on error.
  * Since: 2.32
@@ -37786,7 +37764,7 @@
 /**
  * g_socket_set_broadcast:
  * @socket: a #GSocket.
- * @loopback: whether @socket should allow sending to and receiving from broadcast addresses
+ * @broadcast: whether @socket should allow sending to and receiving from broadcast addresses
  *
  * Sets whether @socket should allow sending to and receiving from
  * broadcast addresses. This is %FALSE by default.
@@ -39283,10 +39261,13 @@
  * @password: a #GTlsPassword object
  * @length: (allow-none): location to place the length of the password.
  *
- * Get the password value. If @length is not %NULL then it will be filled
- * in with the length of the password value.
+ * Get the password value. If @length is not %NULL then it will be
+ * filled in with the length of the password value. (Note that the
+ * password value is not nul-terminated, so you can only pass %NULL
+ * for @length in contexts where you know the password will have a
+ * certain fixed length.)
  *
- * Returns: The password value owned by the password object.
+ * Returns: The password value (owned by the password object).
  * Since: 2.30
  */
 
@@ -39346,9 +39327,10 @@
  * Set the value for this password. The @value will be copied by the password
  * object.
  *
- * Specify the @length, for a non-null-terminated password. Pass -1 as
- * @length if using a null-terminated password, and @length will be calculated
- * automatically.
+ * Specify the @length, for a non-nul-terminated password. Pass -1 as
+ * @length if using a nul-terminated password, and @length will be
+ * calculated automatically. (Note that the terminating nul is not
+ * considered part of the password in this case.)
  *
  * Since: 2.30
  */
@@ -39366,9 +39348,10 @@
  * The @value will be owned by the password object, and later freed using
  * the @destroy function callback.
  *
- * Specify the @length, for a non-null-terminated password. Pass -1 as
- * @length if using a null-terminated password, and @length will be calculated
- * automatically.
+ * Specify the @length, for a non-nul-terminated password. Pass -1 as
+ * @length if using a nul-terminated password, and @length will be
+ * calculated automatically. (Note that the terminating nul is not
+ * considered part of the password in this case.)
  *
  * Virtual: set_value
  * Since: 2.30
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 551c084..2343c2d 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -972,11 +972,24 @@
  * g_direct_hash() is also the appropriate hash function for keys
  * of the form <literal>GINT_TO_POINTER (n)</literal> (or similar macros).
  *
- * <!-- FIXME: Need more here. --> The hash values should be evenly
- * distributed over a fairly large range? The modulus is taken with the
- * hash table size (a prime number) to find the 'bucket' to place each
- * key into. The function should also be very fast, since it is called
- * for each key lookup.
+ * <!-- FIXME: Need more here. --> A good hash functions should produce
+ * hash values that are evenly distributed over a fairly large range.
+ * The modulus is taken with the hash table size (a prime number) to
+ * find the 'bucket' to place each key into. The function should also
+ * be very fast, since it is called for each key lookup.
+ *
+ * Note that the hash functions provided by GLib have these qualities,
+ * but are not particularly robust against manufactured keys that
+ * cause hash collisions. Therefore, you should consider choosing
+ * a more secure hash function when using a GHashTable with keys
+ * that originate in untrusted data (such as HTTP requests).
+ * Using g_str_hash() in that situation might make your application
+ * vulerable to <ulink url="https://lwn.net/Articles/474912/";>Algorithmic Complexity Attacks</ulink>.
+ *
+ * The key to choosing a good hash is unpredictability.  Even
+ * cryptographic hashes are very easy to find collisions for when the
+ * remainder is taken modulo a somewhat predictable prime number.  There
+ * must be an element of randomness that an attacker is unable to guess.
  *
  * Returns: the hash value corresponding to the key
  */
@@ -6177,6 +6190,7 @@
  * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
  *
  * Returns: %TRUE on success.
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -7258,6 +7272,8 @@
  * @pspec: a valid #GParamSpec instance
  *
  * Cast a #GParamSpec instance into a #GParamSpecValueArray.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -8603,6 +8619,8 @@
  * G_TYPE_PARAM_VALUE_ARRAY:
  *
  * The #GType of #GParamSpecValueArray.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -8766,6 +8784,8 @@
  *
  * The type ID of the "GValueArray" type which is a boxed type,
  * used to pass around pointers to GValueArrays.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -12750,8 +12770,9 @@
  * g_node_insert_before(), g_node_append() and g_node_prepend().
  *
  * To create a new node and insert it into a tree use
- * g_node_insert_data(), g_node_insert_data_before(),
- * g_node_append_data() and g_node_prepend_data().
+ * g_node_insert_data(), g_node_insert_data_after(),
+ * g_node_insert_data_before(), g_node_append_data()
+ * and g_node_prepend_data().
  *
  * To reverse the children of a node use g_node_reverse_children().
  *
@@ -13201,6 +13222,25 @@
 
 
 /**
+ * g_array_set_clear_func:
+ * @array: A #GArray
+ * @clear_func: a function to clear an element of @array
+ *
+ * Sets a function to clear an element of @array.
+ *
+ * The @clear_func will be called when an element in the array
+ * data segment is removed and when the array is freed and data
+ * segment is deallocated as well.
+ *
+ * Note that in contrast with other uses of #GDestroyNotify
+ * functions, @clear_func is expected to clear the contents of
+ * the array element it is given, but not free the element itself.
+ *
+ * Since: 2.32
+ */
+
+
+/**
  * g_array_set_size:
  * @array: a #GArray.
  * @length: the new size of the #GArray.
@@ -15191,7 +15231,7 @@
  * @full_path.  If the file could not be loaded then an %error is
  * set to either a #GFileError or #GBookmarkFileError.
  *
- * Returns: %TRUE if a key file could be loaded, %FALSE othewise
+ * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
  * Since: 2.12
  */
 
@@ -16485,7 +16525,7 @@
  * Notice that the end time is calculated once, before entering the
  * loop and reused.  This is the motivation behind the use of absolute
  * time on this API -- if a relative time of 5 seconds were passed
- * directly to the call and a spurious wakeup occured, the program would
+ * directly to the call and a spurious wakeup occurred, the program would
  * have to start over waiting again (which would lead to a total wait
  * time of more than 5 seconds).
  *
@@ -16657,7 +16697,7 @@
  * @key: the string identifying a data element.
  * @Returns: the data element, or %NULL if it is not found.
  *
- * Gets a data element, using its string identifer. This is slower than
+ * Gets a data element, using its string identifier. This is slower than
  * g_datalist_id_get_data() because it compares strings.
  */
 
@@ -17004,7 +17044,7 @@
  * @lhs: first date to compare
  * @rhs: second date to compare
  *
- * qsort()-style comparsion function for dates.
+ * qsort()-style comparison function for dates.
  * Both dates must be valid.
  *
  * greater than zero if @lhs is greater than @rhs
@@ -19712,8 +19752,8 @@
  * On Windows, "limitations of the OS kernel" is a rather substantial
  * statement.  Depending on the configuration of the system, the wall
  * clock time is updated as infrequently as 64 times a second (which
- * is approximately every 16ms). Also, the on XP (not on Vista or later)
- * the monitonic clock is locally monotonic, but may differ in exact
+ * is approximately every 16ms). Also, on XP (but not on Vista or later)
+ * the monotonic clock is locally monotonic, but may differ in exact
  * value between processes due to timer wrap handling.
  *
  * Returns: the monotonic time, in microseconds
@@ -25467,6 +25507,18 @@
 
 
 /**
+ * g_node_insert_data_after:
+ * @parent: the #GNode to place the new #GNode under
+ * @sibling: the sibling #GNode to place the new #GNode after
+ * @data: the data for the new #GNode
+ *
+ * Inserts a new #GNode after the given sibling.
+ *
+ * Returns: the new #GNode
+ */
+
+
+/**
  * g_node_insert_data_before:
  * @parent: the #GNode to place the new #GNode under
  * @sibling: the sibling #GNode to place the new #GNode before
@@ -29376,7 +29428,7 @@
  * Removes the item pointed to by @iter. It is an error to pass the
  * end iterator to this function.
  *
- * If the sequnce has a data destroy function associated with it, this
+ * If the sequence has a data destroy function associated with it, this
  * function is called on the data for the removed item.
  *
  * Since: 2.14
@@ -29799,6 +29851,18 @@
 
 
 /**
+ * g_signal_handlers_disconnect_by_data:
+ * @instance: The instance to remove handlers from
+ * @data: the closure data of the handlers' closures
+ *
+ * Disconnects all handlers on an instance that match @data.
+ *
+ * Returns: The number of handlers that matched.
+ * Since: 2.32
+ */
+
+
+/**
  * g_signal_handlers_disconnect_by_func:
  * @instance: The instance to remove handlers from.
  * @func: The C closure callback of the handlers (useless for non-C closures).
@@ -30623,7 +30687,7 @@
  * self->idle_id = 0;
  * GDK_THREADS_LEAVE (<!-- -->);
  *
- * return FALSE;
+ * return G_SOURCE_REMOVE;
  * }
  *
  * static void
@@ -39219,7 +39283,7 @@
  * This is an internal function and should only be used by
  * the internals of glib (such as libgio).
  *
- * Returns: the transation of @str to the current locale
+ * Returns: the translation of @str to the current locale
  */
 
 
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 07a4d54..b7fc6b4 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -3145,6 +3145,7 @@
  * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY.
  *
  * Returns: %TRUE on success.
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -3544,6 +3545,8 @@
  * @pspec: a valid #GParamSpec instance
  *
  * Cast a #GParamSpec instance into a #GParamSpecValueArray.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -4590,6 +4593,8 @@
  * G_TYPE_PARAM_VALUE_ARRAY:
  *
  * The #GType of #GParamSpecValueArray.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -4753,6 +4758,8 @@
  *
  * The type ID of the "GValueArray" type which is a boxed type,
  * used to pass around pointers to GValueArrays.
+ *
+ * Deprecated: 2.32: Use #GArray instead of #GValueArray
  */
 
 
@@ -5984,6 +5991,23 @@
  * object property that holds an array of values. A #GValueArray wraps
  * an array of #GValue elements in order for it to be used as a boxed
  * type through %G_TYPE_VALUE_ARRAY.
+ *
+ * #GValueArray is deprecated in favour of #GArray since GLib 2.32. It
+ * is possible to create a #GArray that behaves like a #GValueArray by
+ * using the size of #GValue as the element size, and by setting
+ * g_value_unset() as the clear function using g_array_set_clear_func(),
+ * for instance, the following code:
+ *
+ * |[
+ * GValueArray *array = g_value_array_new (10);
+ * ]|
+ *
+ * can be replaced by:
+ *
+ * |[
+ * GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
+ * g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
+ * ]|
  */
 
 
@@ -7142,6 +7166,18 @@
 
 
 /**
+ * g_node_insert_data_after:
+ * @parent: the #GNode to place the new #GNode under
+ * @sibling: the sibling #GNode to place the new #GNode after
+ * @data: the data for the new #GNode
+ *
+ * Inserts a new #GNode after the given sibling.
+ *
+ * Returns: the new #GNode
+ */
+
+
+/**
  * g_node_insert_data_before:
  * @parent: the #GNode to place the new #GNode under
  * @sibling: the sibling #GNode to place the new #GNode before
@@ -9347,6 +9383,18 @@
 
 
 /**
+ * g_signal_handlers_disconnect_by_data:
+ * @instance: The instance to remove handlers from
+ * @data: the closure data of the handlers' closures
+ *
+ * Disconnects all handlers on an instance that match @data.
+ *
+ * Returns: The number of handlers that matched.
+ * Since: 2.32
+ */
+
+
+/**
  * g_signal_handlers_disconnect_by_func:
  * @instance: The instance to remove handlers from.
  * @func: The C closure callback of the handlers (useless for non-C closures).
@@ -10720,6 +10768,7 @@
  * %NULL, an uninitialized value is appended.
  *
  * Returns: (transfer none): the #GValueArray passed in as @value_array
+ * Deprecated: 2.32: Use #GArray and g_array_append_val() instead.
  */
 
 
@@ -10731,6 +10780,7 @@
  * contents.
  *
  * Returns: (transfer full): Newly allocated copy of #GValueArray
+ * Deprecated: 2.32: Use #GArray and g_array_ref() instead.
  */
 
 
@@ -10739,6 +10789,8 @@
  * @value_array: #GValueArray to free
  *
  * Free a #GValueArray including its contents.
+ *
+ * Deprecated: 2.32: Use #GArray and g_array_unref() instead.
  */
 
 
@@ -10750,6 +10802,7 @@
  * Return a pointer to the value at @index_ containd in @value_array.
  *
  * Returns: (transfer none): pointer to a value at @index_ in @value_array
+ * Deprecated: 2.32: Use g_array_index() instead.
  */
 
 
@@ -10763,6 +10816,7 @@
  * is %NULL, an uninitialized value is inserted.
  *
  * Returns: (transfer none): the #GValueArray passed in as @value_array
+ * Deprecated: 2.32: Use #GArray and g_array_insert_val() instead.
  */
 
 
@@ -10775,6 +10829,7 @@
  * regardless of the value of @n_prealloced.
  *
  * Returns: a newly allocated #GValueArray with 0 values
+ * Deprecated: 2.32: Use #GArray and g_array_sized_new() instead.
  */
 
 
@@ -10787,6 +10842,7 @@
  * %NULL, an uninitialized value is prepended.
  *
  * Returns: (transfer none): the #GValueArray passed in as @value_array
+ * Deprecated: 2.32: Use #GArray and g_array_prepend_val() instead.
  */
 
 
@@ -10798,6 +10854,7 @@
  * Remove the value at position @index_ from @value_array.
  *
  * Returns: (transfer none): the #GValueArray passed in as @value_array
+ * Deprecated: 2.32: Use #GArray and g_array_remove_index() instead.
  */
 
 
@@ -10812,6 +10869,7 @@
  * The current implementation uses Quick-Sort as sorting algorithm.
  *
  * Returns: (transfer none): the #GValueArray passed in as @value_array
+ * Deprecated: 2.32: Use #GArray and g_array_sort().
  */
 
 
@@ -10828,6 +10886,7 @@
  *
  * Rename to: g_value_array_sort
  * Returns: (transfer none): the #GValueArray passed in as @value_array
+ * Deprecated: 2.32: Use #GArray and g_array_sort_with_data().
  */
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]