[gobject-introspection] gir: Update annotations from GLib git master

[Rico Tzschichholz <ricotz src gnome org>]

commit 5c3f20e243929e8f37b23f2e8f48ecbcdbd4303f
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Sat Nov 18 16:07:44 2017 +0100

    gir: Update annotations from GLib git master

 gir/gio-2.0.c  |   81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 gir/glib-2.0.c |   54 +++++++++++++++++++++++++++++--------
 2 files changed, 121 insertions(+), 14 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 24bbb32..fa8c679 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -16503,7 +16503,8 @@
 /**
  * g_dbus_action_group_get:
  * @connection: A #GDBusConnection
- * @bus_name: the bus name which exports the action group
+ * @bus_name: (nullable): the bus name which exports the action
+ *     group or %NULL if @connection is not a message bus connection
  * @object_path: the object path at which the action group is exported
  *
  * Obtains a #GDBusActionGroup for the action group which is exported at
@@ -18598,7 +18599,8 @@
 /**
  * g_dbus_menu_model_get:
  * @connection: a #GDBusConnection
- * @bus_name: the bus name which exports the menu model
+ * @bus_name: (nullable): the bus name which exports the menu model
+ *     or %NULL if @connection is not a message bus connection
  * @object_path: the object path at which the menu model is exported
  *
  * Obtains a #GDBusMenuModel for the menu model which is exported
@@ -24375,6 +24377,77 @@
 
 
 /**
+ * g_file_load_bytes:
+ * @file: a #GFile
+ * @cancellable: (nullable): a #GCancellable or %NULL
+ * @etag_out: (out) (nullable) (optional): a location to place the current
+ *     entity tag for the file, or %NULL if the entity tag is not needed
+ * @error: a location for a #GError or %NULL
+ *
+ * Loads the contents of @file and returns it as #GBytes.
+ *
+ * If @file is a resource:// based URI, the resulting bytes will reference the
+ * embedded resource instead of a copy. Otherwise, this is equivalent to calling
+ * g_file_load_contents() and g_bytes_new_take().
+ *
+ * For resources, @etag_out will be set to %NULL.
+ *
+ * The data contained in the resulting #GBytes is always zero-terminated, but
+ * this is not included in the #GBytes length. The resulting #GBytes should be
+ * freed with g_bytes_unref() when no longer in use.
+ *
+ * Returns: (transfer full): a #GBytes or %NULL and @error is set
+ * Since: 2.56
+ */
+
+
+/**
+ * g_file_load_bytes_async:
+ * @file: a #GFile
+ * @cancellable: (nullable): 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 loads the contents of @file as #GBytes.
+ *
+ * If @file is a resource:// based URI, the resulting bytes will reference the
+ * embedded resource instead of a copy. Otherwise, this is equivalent to calling
+ * g_file_load_contents_async() and g_bytes_new_take().
+ *
+ * @callback should call g_file_load_bytes_finish() to get the result of this
+ * asynchronous operation.
+ *
+ * See g_file_load_bytes() for more information.
+ *
+ * Since: 2.56
+ */
+
+
+/**
+ * g_file_load_bytes_finish:
+ * @file: a #GFile
+ * @result: a #GAsyncResult provided to the callback
+ * @etag_out: (out) (nullable) (optional): a location to place the current
+ *     entity tag for the file, or %NULL if the entity tag is not needed
+ * @error: a location for a #GError, or %NULL
+ *
+ * Completes an asynchronous request to g_file_load_bytes_async().
+ *
+ * For resources, @etag_out will be set to %NULL.
+ *
+ * The data contained in the resulting #GBytes is always zero-terminated, but
+ * this is not included in the #GBytes length. The resulting #GBytes should be
+ * freed with g_bytes_unref() when no longer in use.
+ *
+ * See g_file_load_bytes() for more information.
+ *
+ * Returns: (transfer full): a #GBytes or %NULL and @error is set
+ * Since: 2.56
+ */
+
+
+/**
  * g_file_load_contents:
  * @file: input #GFile
  * @cancellable: optional #GCancellable object, %NULL to ignore
@@ -32563,6 +32636,10 @@
  * If you want to use this resource in the global resource namespace you need
  * to register it with g_resources_register().
  *
+ * Note: @data must be backed by memory that is at least pointer aligned.
+ * Otherwise this function will internally create a copy of the memory since
+ * GLib 2.56, or in older versions fail and exit the process.
+ *
  * Returns: (transfer full): a new #GResource, or %NULL on error
  * Since: 2.32
  */
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 23509cf..1651e31 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -12972,6 +12972,10 @@
  * function is NOT thread-safe. So unless @datalist can be protected
  * from any modifications during invocation of this function, it should
  * not be called.
+ *
+ * @func can make changes to @datalist, but the iteration will not
+ * reflect changes made during the g_datalist_foreach() call, other
+ * than skipping over elements that are removed.
  */
 
 
@@ -13230,8 +13234,12 @@
  *
  * Calls the given function for each data element which is associated
  * with the given location. Note that this function is NOT thread-safe.
- * So unless @datalist can be protected from any modifications during
- * invocation of this function, it should not be called.
+ * So unless @dataset_location can be protected from any modifications
+ * during invocation of this function, it should not be called.
+ *
+ * @func can make changes to the dataset, but the iteration will not
+ * reflect changes made during the g_dataset_foreach() call, other
+ * than skipping over elements that are removed.
  */
 
 
@@ -19329,6 +19337,9 @@
  * @user_data: user data to pass to the function
  *
  * Calls a function for each element of a #GList.
+ *
+ * It is safe for @func to remove the element from @list, but it must
+ * not modify any part of the list after that element.
  */
 
 
@@ -19371,6 +19382,9 @@
  * Convenience method, which frees all the memory used by a #GList,
  * and calls @free_func on every element's data.
  *
+ * @free_func must not modify the list (eg, by removing the freed
+ * element from it).
+ *
  * Since: 2.28
  */
 
@@ -22245,8 +22259,9 @@
  * @func: the function to call for each visited node
  * @data: user data to pass to the function
  *
- * Calls a function for each of the children of a #GNode.
- * Note that it doesn't descend beneath the child nodes.
+ * Calls a function for each of the children of a #GNode. Note that it
+ * doesn't descend beneath the child nodes. @func must not do anything
+ * that would modify the structure of the tree.
  */
 
 
@@ -22516,6 +22531,7 @@
  * Traverses a tree starting at the given root #GNode.
  * It calls the given function for each node visited.
  * The traversal can be halted at any point by returning %TRUE from @func.
+ * @func must not do anything that would modify the structure of the tree.
  */
 
 
@@ -23734,7 +23750,8 @@
  * @func: the function to call for each array element
  * @user_data: user data to pass to the function
  *
- * Calls a function for each element of a #GPtrArray.
+ * Calls a function for each element of a #GPtrArray. @func must not
+ * add elements to or remove elements from the array.
  *
  * Since: 2.4
  */
@@ -24164,6 +24181,9 @@
  * Calls @func for each element in the queue passing @user_data to the
  * function.
  *
+ * It is safe for @func to remove the element from @queue, but it must
+ * not modify any part of the queue after that element.
+ *
  * Since: 2.4
  */
 
@@ -24189,6 +24209,9 @@
  * Convenience method, which frees all the memory used by a #GQueue,
  * and calls the specified destroy function on every element's data.
  *
+ * @free_func should not modify the queue (eg, by removing the freed
+ * element from it).
+ *
  * Since: 2.32
  */
 
@@ -26113,7 +26136,7 @@
  * @user_data: user data passed to @func
  *
  * Calls @func for each item in the sequence passing @user_data
- * to the function.
+ * to the function. @func must not modify the sequence itself.
  *
  * Since: 2.14
  */
@@ -26127,7 +26150,8 @@
  * @user_data: user data passed to @func
  *
  * Calls @func for each item in the range (@begin, @end) passing
- * @user_data to the function.
+ * @user_data to the function. @func must not modify the sequence
+ * itself.
  *
  * Since: 2.14
  */
@@ -27297,6 +27321,9 @@
  * @user_data: user data to pass to the function
  *
  * Calls a function for each element of a #GSList.
+ *
+ * It is safe for @func to remove the element from @list, but it must
+ * not modify any part of the list after that element.
  */
 
 
@@ -27339,6 +27366,9 @@
  * Convenience method, which frees all the memory used by a #GSList, and
  * calls the specified destroy function on every element's data.
  *
+ * @free_func must not modify the list (eg, by removing the freed
+ * element from it).
+ *
  * Since: 2.28
  */
 
@@ -28804,11 +28834,11 @@
  * call g_str_tokenize_and_fold() on the search term and
  * perform lookups into that index.
  *
- * As some examples, searching for "fred" would match the potential hit
- * "Smith, Fred" and also "Frédéric".  Searching for "Fréd" would match
- * "Frédéric" but not "Frederic" (due to the one-directional nature of
- * accent matching).  Searching "fo" would match "Foo" and "Bar Foo
- * Baz", but not "SFO" (because no word as "fo" as a prefix).
+ * As some examples, searching for ‘fred’ would match the potential hit
+ * ‘Smith, Fred’ and also ‘Frédéric’.  Searching for ‘Fréd’ would match
+ * ‘Frédéric’ but not ‘Frederic’ (due to the one-directional nature of
+ * accent matching).  Searching ‘fo’ would match ‘Foo’ and ‘Bar Foo
+ * Baz’, but not ‘SFO’ (because no word has ‘fo’ as a prefix).
  *
  * Returns: %TRUE if @potential_hit is a hit
  * Since: 2.40