[gobject-introspection] Update glib annotations from git master

[Rico Tzschichholz <ricotz src gnome org>]

commit 9112ec1e845015a17bba49fb1dd385a2c6e9efd7
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Tue Nov 26 19:55:17 2013 +0100

    Update glib annotations from git master

 gir/gio-2.0.c     |  105 +++++++++++++++++++++++++++++++++++++++++++++------
 gir/glib-2.0.c    |  108 +++++++++++++++++++++++++++++++++++-----------------
 gir/gmodule-2.0.c |    6 +-
 gir/gobject-2.0.c |   42 +++++++++++++-------
 4 files changed, 195 insertions(+), 66 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index a8dc63b..4ca1f23 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -2540,7 +2540,8 @@
  *       @client is about to make a connection to a remote host;
  *       either a proxy server or the destination server itself.
  *       @connection is the #GSocketConnection, which is not yet
- *       connected.
+ *       connected.  Since GLib 2.40, you can access the remote
+ *       address via g_socket_connection_get_remote_address().
  *     </para></listitem>
  *   </varlistentry>
  *   <varlistentry>
@@ -3495,7 +3496,7 @@
  * organized fashion.
  *
  * An extension point is identified by a name, and it may optionally
- * require that any implementation must by of a certain type (or derived
+ * require that any implementation must be of a certain type (or derived
  * thereof). Use g_io_extension_point_register() to register an
  * extension point, and g_io_extension_point_set_required_type() to
  * set a required type.
@@ -18561,6 +18562,8 @@
  * applications that matched @search_string with an equal score.  The
  * outer list is sorted by score so that the first strv contains the
  * best-matching applications, and so on.
+ * The algorithm for determining matches is undefined and may change at
+ * any time.
  *
  * Returns: (array zero-terminated=1) (element-type GStrv) (transfer full): a
  *   list of strvs.  Free each item with g_strfreev() and free the outer
@@ -20215,8 +20218,9 @@
  * This call does no blocking I/O.
  *
  * Returns: string with the relative path from @descendant
- *     to @parent. The returned string should be freed with
- *     g_free() when no longer needed.
+ *     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.
  */
 
 
@@ -27324,6 +27328,34 @@
 
 
 /**
+ * g_output_stream_printf:
+ * @stream: a #GOutputStream.
+ * @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
+ * @format: the format string. See the printf() documentation
+ * @...: the parameters to insert into the format string
+ *
+ * This is a utility function around g_output_stream_write_all(). It
+ * uses g_strdup_vprintf() to turn @format and @... into a string that
+ * is then written to @stream.
+ *
+ * See the documentation of g_output_stream_write_all() about the
+ * behavior of the actual write operation.
+ *
+ * Note that partial writes cannot be properly checked with this
+ * function due to the variable length of the written string, if you
+ * need precise control over partial write failures, you need to
+ * create you own printf()-like wrapper around g_output_stream_write()
+ * or g_output_stream_write_all().
+ *
+ * Since: 2.40
+ * Returns: %TRUE on success, %FALSE if there was an error
+ */
+
+
+/**
  * g_output_stream_set_pending:
  * @stream: a #GOutputStream.
  * @error: a #GError location to store the error occurring, or %NULL to
@@ -27393,6 +27425,34 @@
 
 
 /**
+ * g_output_stream_vprintf:
+ * @stream: a #GOutputStream.
+ * @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
+ * @format: the format string. See the printf() documentation
+ * @args: the parameters to insert into the format string
+ *
+ * This is a utility function around g_output_stream_write_all(). It
+ * uses g_strdup_vprintf() to turn @format and @args into a string that
+ * is then written to @stream.
+ *
+ * See the documentation of g_output_stream_write_all() about the
+ * behavior of the actual write operation.
+ *
+ * Note that partial writes cannot be properly checked with this
+ * function due to the variable length of the written string, if you
+ * need precise control over partial write failures, you need to
+ * create you own printf()-like wrapper around g_output_stream_write()
+ * or g_output_stream_write_all().
+ *
+ * Since: 2.40
+ * Returns: %TRUE on success, %FALSE if there was an error
+ */
+
+
+/**
  * g_output_stream_write: (virtual write_fn)
  * @stream: a #GOutputStream.
  * @buffer: (array length=count) (element-type guint8): the buffer containing the data to write.
@@ -29429,7 +29489,7 @@
 /**
  * g_settings_get_default_value:
  * @settings: a #GSettings object
- * @key: the key to check for being set
+ * @key: the key to get the default value for
  *
  * Gets the "default value" of a key.
  *
@@ -29657,7 +29717,7 @@
 /**
  * g_settings_get_user_value:
  * @settings: a #GSettings object
- * @key: the key to check for being set
+ * @key: the key to get the user value for
  *
  * Checks the "user value" of a key, if there is one.
  *
@@ -29773,7 +29833,10 @@
  *   schemas that are available.  The list must not be modified or
  *   freed.
  * Since: 2.26
- * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead
+ * Deprecated: 2.40: Use g_settings_schema_source_list_schemas() instead.
+ * If you used g_settings_list_schemas() to check for the presence of
+ * a particular schema, use g_settings_schema_source_lookup() instead
+ * of your whole loop.
  */
 
 
@@ -32155,6 +32218,13 @@
  *
  * Try to get the remote address of a socket connection.
  *
+ * Since GLib 2.40, when used with g_socket_client_connect() or
+ * g_socket_client_connect_async(), during emission of
+ * %G_SOCKET_CLIENT_CONNECTING, this function will return the remote
+ * address that will be used for the connection.  This allows
+ * applications to print e.g. "Connecting to example.com
+ * (10.42.77.3)...".
+ *
  * Returns: (transfer full): a #GSocketAddress or %NULL on error.
  *     Free the returned object with g_object_unref().
  * Since: 2.22
@@ -33633,7 +33703,7 @@
 /**
  * g_subprocess_communicate:
  * @subprocess: a #GSubprocess
- * @stdin_buf: data to send to the stdin of the subprocess, or %NULL
+ * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
  * @cancellable: a #GCancellable
  * @stdout_buf: (out): data read from the subprocess stdout
  * @stderr_buf: (out): data read from the subprocess stderr
@@ -33642,7 +33712,7 @@
  * Communicate with the subprocess until it terminates, and all input
  * and output has been completed.
  *
- * If @stdin is given, the subprocess must have been created with
+ * If @stdin_buf is given, the subprocess must have been created with
  * %G_SUBPROCESS_FLAGS_STDIN_PIPE.  The given data is fed to the
  * stdin of the subprocess and the pipe is closed (ie: EOF).
  *
@@ -33689,8 +33759,8 @@
 /**
  * g_subprocess_communicate_async:
  * @subprocess: Self
- * @stdin_buf: Input data
- * @cancellable: Cancellable
+ * @stdin_buf: (allow-none): Input data, or %NULL
+ * @cancellable: (allow-none): Cancellable
  * @callback: Callback
  * @user_data: User data
  *
@@ -33714,7 +33784,7 @@
 /**
  * g_subprocess_communicate_utf8:
  * @subprocess: a #GSubprocess
- * @stdin_buf: data to send to the stdin of the subprocess, or %NULL
+ * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
  * @cancellable: a #GCancellable
  * @stdout_buf: (out): data read from the subprocess stdout
  * @stderr_buf: (out): data read from the subprocess stderr
@@ -33728,7 +33798,7 @@
 /**
  * g_subprocess_communicate_utf8_async:
  * @subprocess: Self
- * @stdin_buf: Input data
+ * @stdin_buf: (allow-none): Input data, or %NULL
  * @cancellable: Cancellable
  * @callback: Callback
  * @user_data: User data
@@ -33785,6 +33855,15 @@
 
 
 /**
+ * g_subprocess_get_identifier:
+ * @subprocess: a #GSubprocess
+ *
+ * On UNIX, returns the process ID as a decimal string.  On Windows,
+ * returns the result of GetProcessId() also as a string.
+ */
+
+
+/**
  * g_subprocess_get_if_exited:
  * @subprocess: a #GSubprocess
  *
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 69981bd..c0c7feb 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -1257,7 +1257,7 @@
  *     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
+ * @G_LOG_LEVEL_INFO: log level for informational messages, see g_info()
  * @G_LOG_LEVEL_DEBUG: log level for debug messages, see g_debug()
  * @G_LOG_LEVEL_MASK: a mask including all log levels
  *
@@ -4274,14 +4274,6 @@
 
 
 /**
- * G_OS_BEOS:
- *
- * This macro is defined only on BeOS. So you can bracket
- * BeOS-specific code in "&num;ifdef G_OS_BEOS".
- */
-
-
-/**
  * G_OS_UNIX:
  *
  * This macro is defined only on UNIX. So you can bracket
@@ -8551,7 +8543,7 @@
  * Converts a #gdouble to a string, using the '.' as
  * decimal point.
  *
- * This functions generates enough precision that converting
+ * This function generates enough precision that converting
  * the string back using g_ascii_strtod() gives the same machine-number
  * (on machines with IEEE compatible 64bit doubles). It is
  * guaranteed that the size of the resulting string will never
@@ -8785,6 +8777,8 @@
  * characters include all ASCII letters. If you compare two CP932
  * strings using this function, you will get false matches.
  *
+ * Both @s1 and @s2 must be non-%NULL.
+ *
  * Returns: 0 if the strings match, a negative value if @s1 &lt; @s2,
  *   or a positive value if @s1 &gt; @s2.
  */
@@ -9153,6 +9147,22 @@
 
 
 /**
+ * g_assert_nonnull:
+ * @expr: the expression to check
+ *
+ * Debugging macro to check an expression is not %NULL.
+ *
+ * If the assertion fails (i.e. the expression is %NULL),
+ * an error message is logged and the application is either
+ * terminated or the testcase marked as failed.
+ *
+ * See g_test_set_nonfatal_assertions().
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * g_assert_not_reached:
  *
  * Debugging macro to terminate the application if it is ever
@@ -14123,6 +14133,9 @@
  * character will automatically be appended to @..., and need not be entered
  * manually.
  *
+ * Such messages are suppressed by the g_log_default_handler() unless
+ * the G_MESSAGES_DEBUG environment variable is set appropriately.
+ *
  * Since: 2.6
  */
 
@@ -15579,6 +15592,7 @@
  * corresponding value it is able to be stored more efficiently.  See
  * the discussion in the section description.
  *
+ * Returns: %TRUE if the key did not exist yet
  * Since: 2.32
  */
 
@@ -15767,6 +15781,8 @@
  * value is freed using that function. If you supplied a
  * @key_destroy_func when creating the #GHashTable, the passed
  * key is freed using that function.
+ *
+ * Returns: %TRUE if the key did not exist yet
  */
 
 
@@ -16001,6 +16017,8 @@
  * the #GHashTable, the old value is freed using that function.
  * If you supplied a @key_destroy_func when creating the
  * #GHashTable, the old key is freed using that function.
+ *
+ * Returns: %TRUE of the key did not exist yet
  */
 
 
@@ -16680,6 +16698,24 @@
 
 
 /**
+ * g_info:
+ * @...: format string, followed by parameters to insert
+ *     into the format string (as with printf())
+ *
+ * A convenience function/macro to log an informational message. Seldom used.
+ *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
+ *
+ * Such messages are suppressed by the g_log_default_handler() unless
+ * the G_MESSAGES_DEBUG environment variable is set appropriately.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * g_int64_equal:
  * @v1: a pointer to a #gint64 key
  * @v2: a pointer to a #gint64 key to compare with @v1
@@ -17847,7 +17883,7 @@
  * g_key_file_load_from_data:
  * @key_file: an empty #GKeyFile struct
  * @data: key file loaded in memory
- * @length: the length of @data in bytes (or -1 if data is nul-terminated)
+ * @length: the length of @data in bytes (or (gsize)-1 if data is nul-terminated)
  * @flags: flags from #GKeyFileFlags
  * @error: return location for a #GError, or %NULL
  *
@@ -20658,10 +20694,7 @@
  * Copies a block of memory @len bytes long, from @src to @dest.
  * The source and destination areas may overlap.
  *
- * In order to use this function, you must include
- * <filename>string.h</filename> yourself, because this macro will
- * typically simply resolve to memmove() and GLib does not include
- * <filename>string.h</filename> for you.
+ * Deprecated: 2.40: Just use memmove().
  */
 
 
@@ -22440,15 +22473,16 @@
 
 /**
  * g_ptr_array_remove_range:
- * @array: a @GPtrArray.
- * @index_: the index of the first pointer to remove.
- * @length: the number of pointers to remove.
+ * @array: a @GPtrArray
+ * @index_: the index of the first pointer to remove
+ * @length: the number of pointers to remove
  *
  * Removes the given number of pointers starting at the given index
  * from a #GPtrArray.  The following elements are moved to close the
  * gap. If @array has a non-%NULL #GDestroyNotify function it is called
  * for the removed elements.
  *
+ * Returns: the @array
  * Since: 2.4
  */
 
@@ -28795,7 +28829,9 @@
  *        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.
+ * @...: %NULL-terminated list of special options. Currently the only
+ *       defined option is <literal>"no_g_set_prgname"</literal>, which
+ *       will cause g_test_init() to not call g_set_prgname().
  *
  * Initialize the GLib testing framework, e.g. by seeding the
  * test random number generator, the name for g_get_prgname()
@@ -29169,7 +29205,9 @@
  * g_assert_true(), g_assert_false(), g_assert_null(), g_assert_no_error(),
  * g_assert_error(), g_test_assert_expected_messages() and the various
  * g_test_trap_assert_*() macros to not abort to program, but instead
- * call g_test_fail() and continue.
+ * call g_test_fail() and continue. (This also changes the behavior of
+ * g_test_fail() so that it will not cause the test program to abort
+ * after completing the failed test.)
  *
  * Note that the g_assert_not_reached() and g_assert() are not
  * affected by this.
@@ -32344,7 +32382,7 @@
 
 
 /**
- * g_variant_builder_add: (skp)
+ * g_variant_builder_add: (skip)
  * @builder: a #GVariantBuilder
  * @format_string: a #GVariant varargs format string
  * @...: arguments, as per @format_string
@@ -32356,25 +32394,25 @@
  *
  * This function might be used as follows:
  *
- * <programlisting>
+ * |[
  * GVariant *
  * make_pointless_dictionary (void)
  * {
- *   GVariantBuilder *builder;
+ *   GVariantBuilder builder;
  *   int i;
  *
- *   builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
+ *   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
  *   for (i = 0; i < 16; i++)
  *     {
  *       gchar buf[3];
  *
  *       sprintf (buf, "%d", i);
- *       g_variant_builder_add (builder, "{is}", i, buf);
+ *       g_variant_builder_add (&builder, "{is}", i, buf);
  *     }
  *
- *   return g_variant_builder_end (builder);
+ *   return g_variant_builder_end (&builder);
  * }
- * </programlisting>
+ * ]|
  *
  * Since: 2.24
  */
@@ -32394,20 +32432,20 @@
  *
  * This function might be used as follows:
  *
- * <programlisting>
+ * |[
  * GVariant *
  * make_pointless_dictionary (void)
  * {
- *   GVariantBuilder *builder;
+ *   GVariantBuilder builder;
  *   int i;
  *
- *   builder = g_variant_builder_new (G_VARIANT_TYPE_ARRAY);
- *   g_variant_builder_add_parsed (builder, "{'width', <%i>}", 600);
- *   g_variant_builder_add_parsed (builder, "{'title', <%s>}", "foo");
- *   g_variant_builder_add_parsed (builder, "{'transparency', <0.5>}");
- *   return g_variant_builder_end (builder);
+ *   g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY);
+ *   g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600);
+ *   g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo");
+ *   g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}");
+ *   return g_variant_builder_end (&builder);
  * }
- * </programlisting>
+ * ]|
  *
  * Since: 2.26
  */
diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c
index 0b40df3..ccfbcca 100644
--- a/gir/gmodule-2.0.c
+++ b/gir/gmodule-2.0.c
@@ -74,8 +74,8 @@
  * G_MODULE_SUFFIX:
  *
  * Expands to the proper shared library suffix for the current platform
- * without the leading dot. For the most Unices and Linux this is "so",
- * for some HP-UX versions this is "sl" and for Windows this is "dll".
+ * without the leading dot. For most Unices and Linux this is "so", and
+ * for Windows this is "dll".
  */
 
 
@@ -87,7 +87,7 @@
  * These functions provide a portable way to dynamically load object files
  * (commonly known as 'plug-ins'). The current implementation supports all
  * systems that provide an implementation of dlopen() (e.g. Linux/Sun), as
- * well as HP-UX via its shl_load() mechanism, and Windows platforms via DLLs.
+ * well as Windows platforms via DLLs.
  *
  * A program which wants to use these functions must be linked to the
  * libraries output by the command
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 2a0d276..89c083c 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -1558,7 +1558,7 @@
 /**
  * g_enum_complete_type_info:
  * @g_enum_type: the type identifier of the type being completed
- * @info: the #GTypeInfo struct to be filled in
+ * @info: (out callee-allocates): 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.
@@ -1593,8 +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: (transfer none): the #GEnumValue for @value, or %NULL
+ *          if @value is not a member of the enumeration
  */
 
 
@@ -1605,8 +1605,9 @@
  *
  * 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: (transfer none): the #GEnumValue with name @name,
+ *          or %NULL if the enumeration doesn't have a member
+ *          with that name
  */
 
 
@@ -1617,8 +1618,9 @@
  *
  * 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: (transfer none): the #GEnumValue with nickname @nick,
+ *          or %NULL if the enumeration doesn't have a member
+ *          with that nickname
  */
 
 
@@ -1644,7 +1646,7 @@
 /**
  * g_flags_complete_type_info:
  * @g_flags_type: the type identifier of the type being completed
- * @info: the #GTypeInfo struct to be filled in
+ * @info: (out callee-allocates): 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.
@@ -1662,8 +1664,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: (transfer none): the first #GFlagsValue which is set in
+ *          @value, or %NULL if none is set
  */
 
 
@@ -1674,8 +1676,8 @@
  *
  * Looks up a #GFlagsValue by name.
  *
- * Returns: the #GFlagsValue with name @name, or %NULL if there is no
- *          flag with that name
+ * Returns: (transfer none): the #GFlagsValue with name @name,
+ *          or %NULL if there is no flag with that name
  */
 
 
@@ -1686,8 +1688,8 @@
  *
  * Looks up a #GFlagsValue by nickname.
  *
- * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is
- *          no flag with that nickname
+ * Returns: (transfer none): the #GFlagsValue with nickname @nick,
+ *          or %NULL if there is no flag with that nickname
  */
 
 
@@ -2438,6 +2440,11 @@
  * When possible, eg. when signaling a property change from within the class
  * that registered the property, you should use g_object_notify_by_pspec()
  * instead.
+ *
+ * Note that emission of the notify signal may be blocked with
+ * g_object_freeze_notify(). In this case, the signal emissions are queued
+ * and will be emitted (in reverse order) when g_object_thaw_notify() is
+ * called.
  */
 
 
@@ -2621,6 +2628,10 @@
  *  name/value pairs, followed by %NULL
  *
  * Sets properties on an object.
+ *
+ * Note that the "notify" signals are queued and only emitted (in
+ * reverse order) after all properties have been set. See
+ * g_object_freeze_notify().
  */
 
 
@@ -2773,7 +2784,8 @@
  * and when it reaches zero, queued "notify" signals are emitted.
  *
  * Duplicate notifications for each property are squashed so that at most one
- * #GObject::notify signal is emitted for each property.
+ * #GObject::notify signal is emitted for each property, in the reverse order
+ * in which they have been queued.
  *
  * It is an error to call this function when the freeze count is zero.
  */