[gobject-introspection] Update glib annotations from git master

[Rico Tzschichholz <ricotz src gnome org>]

commit a543d8563f8e9ca059afb7218c63496f577cd0fc
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Wed Oct 22 08:22:10 2014 +0200

    Update glib annotations from git master

 gir/gio-2.0.c     |  182 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 gir/glib-2.0.c    |   58 +++++++++++++++++-
 gir/gobject-2.0.c |   15 +++++
 3 files changed, 238 insertions(+), 17 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 35f04f8..9324c36 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -13274,6 +13274,13 @@
  *
  * If cancellable is currently in use by any cancellable operation
  * then the behavior of this function is undefined.
+ *
+ * Note that it is generally not a good idea to reuse an existing
+ * cancellable for more operations after it has been cancelled once,
+ * as this function might tempt you to do. The recommended practice
+ * is to drop the reference to a cancellable after cancelling it,
+ * and let it die with the outstanding async operations. You should
+ * create a fresh cancellable for further async operations.
  */
 
 
@@ -20392,7 +20399,7 @@
  * @file1: the first #GFile
  * @file2: the second #GFile
  *
- * Checks equality of two given #GFiles.
+ * Checks if the two given #GFiles refer to the same file.
  *
  * Note that two #GFiles that differ can still refer to the same
  * file on the filesystem due to various forms of filename
@@ -20658,6 +20665,9 @@
  * so a path like /foo is not considered a prefix of /foobar, only
  * of /foo/bar.
  *
+ * A #GFile is not a prefix of itself. If you want to check for
+ * equality, use g_file_equal().
+ *
  * This call does no I/O, as it works purely on names. As such it can
  * sometimes return %FALSE even if @file is inside a @prefix (from a
  * filesystem point of view), because the prefix of @file is an alias
@@ -24422,14 +24432,68 @@
  * read into @buffer.
  *
  * If there is an error during the operation %FALSE is returned and @error
- * is set to indicate the error status, @bytes_read is updated to contain
- * the number of bytes read into @buffer before the error occurred.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_read will be set to the number of bytes that were successfully
+ * read before the error was encountered.  This functionality is only
+ * available from C.  If you need it from another language then you must
+ * write your own loop around g_input_stream_read().
  *
  * Returns: %TRUE on success, %FALSE if there was an error
  */
 
 
 /**
+ * g_input_stream_read_all_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)
+ * @count: the number of bytes that will be read from the stream
+ * @io_priority: the [I/O priority][io-priority] of the request
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Request an asynchronous read of @count bytes from the stream into the
+ * buffer starting at @buffer.
+ *
+ * This is the asynchronous equivalent of g_input_stream_read_all().
+ *
+ * Call g_input_stream_read_all_finish() to collect the result.
+ *
+ * Any outstanding I/O request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. Default priority is %G_PRIORITY_DEFAULT.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_input_stream_read_all_finish:
+ * @stream: a #GInputStream
+ * @result: a #GAsyncResult
+ * @bytes_read: (out): location to store the number of bytes that was read from the stream
+ * @error: a #GError location to store the error occurring, or %NULL to ignore
+ *
+ * Finishes an asynchronous stream read operation started with
+ * g_input_stream_read_all_async().
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_read will be set to the number of bytes that were successfully
+ * read before the error was encountered.  This functionality is only
+ * available from C.  If you need it from another language then you must
+ * write your own loop around g_input_stream_read_async().
+ *
+ * Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
+ */
+
+
+/**
  * g_input_stream_read_async:
  * @stream: A #GInputStream.
  * @buffer: (array length=count) (element-type guint8): a buffer to
@@ -27929,14 +27993,74 @@
  * is set to @count.
  *
  * If there is an error during the operation %FALSE is returned and @error
- * is set to indicate the error status, @bytes_written is updated to contain
- * the number of bytes written into the stream before the error occurred.
+ * is set to indicate the error status.
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered.  This
+ * functionality is only available from C.  If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write().
  *
  * Returns: %TRUE on success, %FALSE if there was an error
  */
 
 
 /**
+ * g_output_stream_write_all_async:
+ * @stream: A #GOutputStream
+ * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write
+ * @count: the number of bytes to write
+ * @io_priority: the io priority of the request
+ * @cancellable: (allow-none): optional #GCancellable object, %NULL to ignore
+ * @callback: (scope async): callback to call when the request is satisfied
+ * @user_data: (closure): the data to pass to callback function
+ *
+ * Request an asynchronous write of @count bytes from @buffer into
+ * the stream. When the operation is finished @callback will be called.
+ * You can then call g_output_stream_write_all_finish() to get the result of the
+ * operation.
+ *
+ * This is the asynchronous version of g_output_stream_write_all().
+ *
+ * Call g_output_stream_write_all_finish() to collect the result.
+ *
+ * Any outstanding I/O request with higher priority (lower numerical
+ * value) will be executed before an outstanding request with lower
+ * priority. Default priority is %G_PRIORITY_DEFAULT.
+ *
+ * Note that no copy of @buffer will be made, so it must stay valid
+ * until @callback is called.
+ *
+ * Since: 2.44
+ */
+
+
+/**
+ * g_output_stream_write_all_finish:
+ * @stream: a #GOutputStream
+ * @result: a #GAsyncResult
+ * @bytes_written: (out): location to store the number of bytes that was written to the stream
+ * @error: a #GError location to store the error occurring, or %NULL to ignore.
+ *
+ * Finishes an asynchronous stream write operation started with
+ * g_output_stream_write_all_async().
+ *
+ * As a special exception to the normal conventions for functions that
+ * use #GError, if this function returns %FALSE (and sets @error) then
+ * @bytes_written will be set to the number of bytes that were
+ * successfully written before the error was encountered.  This
+ * functionality is only available from C.  If you need it from another
+ * language then you must write your own loop around
+ * g_output_stream_write_async().
+ *
+ * Returns: %TRUE on success, %FALSE if there was an error
+ * Since: 2.44
+ */
+
+
+/**
  * g_output_stream_write_async:
  * @stream: A #GOutputStream.
  * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
@@ -35473,7 +35597,7 @@
  * @connection: a #GTcpConnection
  * @graceful_disconnect: Whether to do graceful disconnects or not
  *
- * This enabled graceful disconnects on close. A graceful disconnect
+ * This enables graceful disconnects on close. A graceful disconnect
  * means that we signal the receiving end that the connection is terminated
  * and wait for it to close the connection before closing the connection.
  *
@@ -35831,8 +35955,17 @@
  * @file: file containing a PEM-encoded certificate to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Creates a #GTlsCertificate from the PEM-encoded data in @file. If
- * @file cannot be read or parsed, the function will return %NULL and
+ * Creates a #GTlsCertificate from the PEM-encoded data in @file. The
+ * returned certificate will be the first certificate found in @file. As
+ * of GLib 2.44, if @file contains more certificates it will try to load
+ * a certificate chain. All certificates will be verified in the order
+ * found (top-level certificate should be the last one in the file) and
+ * the #GTlsCertificate:issuer property of each certificate will be set
+ * accordingly if the verification succeeds. If any certificate in the
+ * chain cannot be verified, the first certificate in the file will
+ * still be returned.
+ *
+ * If @file cannot be read or parsed, the function will return %NULL and
  * set @error. Otherwise, this behaves like
  * g_tls_certificate_new_from_pem().
  *
@@ -35843,14 +35976,25 @@
 
 /**
  * g_tls_certificate_new_from_files:
- * @cert_file: file containing a PEM-encoded certificate to import
+ * @cert_file: file containing one or more PEM-encoded certificates to
+ * import
  * @key_file: file containing a PEM-encoded private key to import
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Creates a #GTlsCertificate from the PEM-encoded data in @cert_file
- * and @key_file. If either file cannot be read or parsed, the
- * function will return %NULL and set @error. Otherwise, this behaves
- * like g_tls_certificate_new_from_pem().
+ * and @key_file. The returned certificate will be the first certificate
+ * found in @cert_file. As of GLib 2.44, if @cert_file contains more
+ * certificates it will try to load a certificate chain. All
+ * certificates will be verified in the order found (top-level
+ * certificate should be the last one in the file) and the
+ * #GTlsCertificate:issuer property of each certificate will be set
+ * accordingly if the verification succeeds. If any certificate in the
+ * chain cannot be verified, the first certificate in the file will
+ * still be returned.
+ *
+ * If either file cannot be read or parsed, the function will return
+ * %NULL and set @error. Otherwise, this behaves like
+ * g_tls_certificate_new_from_pem().
  *
  * Returns: the new certificate, or %NULL on error
  * Since: 2.28
@@ -35863,14 +36007,20 @@
  * @length: the length of @data, or -1 if it's 0-terminated.
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Creates a new #GTlsCertificate from the PEM-encoded data in @data.
- * If @data includes both a certificate and a private key, then the
+ * Creates a #GTlsCertificate from the PEM-encoded data in @data. If
+ * @data includes both a certificate and a private key, then the
  * returned certificate will include the private key data as well. (See
  * the #GTlsCertificate:private-key-pem property for information about
  * supported formats.)
  *
- * If @data includes multiple certificates, only the first one will be
- * parsed.
+ * The returned certificate will be the first certificate found in
+ * @data. As of GLib 2.44, if @data contains more certificates it will
+ * try to load a certificate chain. All certificates will be verified in
+ * the order found (top-level certificate should be the last one in the
+ * file) and the #GTlsCertificate:issuer property of each certificate
+ * will be set accordingly if the verification succeeds. If any
+ * certificate in the chain cannot be verified, the first certificate in
+ * the file will still be returned.
  *
  * Returns: the new certificate, or %NULL if @data is invalid
  * Since: 2.28
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index d1c3b59..b8e24ec 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -15538,6 +15538,13 @@
  * allocated for the key and value that get called when removing the
  * entry from the #GHashTable.
  *
+ * Since version 2.42 it is permissible for destroy notify functions to
+ * recursively remove further items from the hash table. This is only
+ * permissible if the application still holds a reference to the hash table.
+ * This means that you may need to ensure that the hash table is empty by
+ * calling g_hash_table_remove_all before releasing the last reference using
+ * g_hash_table_unref().
+ *
  * Returns: a new #GHashTable
  */
 
@@ -21168,6 +21175,18 @@
 
 
 /**
+ * g_option_context_get_strict_posix:
+ * @context: a #GoptionContext
+ *
+ * Returns whether strict POSIX code is enabled.
+ *
+ * See g_option_context_set_strict_posix() for more information.
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * g_option_context_get_summary:
  * @context: a #GOptionContext
  *
@@ -21338,6 +21357,39 @@
 
 
 /**
+ * g_option_context_set_strict_posix:
+ * @context: a #GoptionContext
+ *
+ * Sets strict POSIX mode.
+ *
+ * By default, this mode is disabled.
+ *
+ * In strict POSIX mode, the first non-argument parameter encountered
+ * (eg: filename) terminates argument processing.  Remaining arguments
+ * are treated as non-options and are not attempted to be parsed.
+ *
+ * If strict POSIX mode is disabled then parsing is done in the GNU way
+ * where option arguments can be freely mixed with non-options.
+ *
+ * As an example, consider "ls foo -l".  With GNU style parsing, this
+ * will list "foo" in long mode.  In strict POSIX style, this will list
+ * the files named "foo" and "-l".
+ *
+ * It may be useful to force strict POSIX mode when creating "verb
+ * style" command line tools.  For example, the "gsettings" command line
+ * tool supports the global option "--schemadir" as well as many
+ * subcommands ("get", "set", etc.) which each have their own set of
+ * arguments.  Using strict POSIX mode will allow parsing the global
+ * options up to the verb name while leaving the remaining options to be
+ * parsed by the relevant subcommand (which can be determined by
+ * examining the verb name, which should be present in argv[1] after
+ * parsing).
+ *
+ * Since: 2.44
+ */
+
+
+/**
  * g_option_context_set_summary:
  * @context: a #GOptionContext
  * @summary: (allow-none): a string to be shown in `--help` output
@@ -21891,6 +21943,10 @@
  *
  * If @dest is %NULL, free @src; otherwise, moves @src into * dest 
  * The error variable @dest points to must be %NULL.
+ *
+ * Note that @src is no longer valid after this call. If you want
+ * to keep using the same GError*, you need to set it to %NULL
+ * after calling this function on it.
  */
 
 
@@ -29364,7 +29420,7 @@
  * @error can be %NULL to ignore errors, or non-%NULL to report
  * errors. An error can only occur when @exclusive is set to %TRUE
  * and not all @max_threads threads could be created.
- * See #GThreadError for possible errors that may occurr.
+ * See #GThreadError for possible errors that may occur.
  * Note, even in case of error a valid #GThreadPool is returned.
  *
  * Returns: the new #GThreadPool
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 57765db..344b4a3 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -4744,6 +4744,21 @@
 
 
 /**
+ * g_type_get_instance_count:
+ * @type: a #GType
+ *
+ * Returns the number of instances allocated of the particular type;
+ * this is only available if GLib is built with debugging support and
+ * the instance_count debug flag is set (by setting the GOBJECT_DEBUG
+ * variable to include instance-count).
+ *
+ * Returns: the number of instances allocated of the given type;
+ *   if instance counts are not available, returns 0.
+ * Since: 2.44
+ */
+
+
+/**
  * g_type_get_plugin:
  * @type: #GType to retrieve the plugin for
  *