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

[Rico Tzschichholz <ricotz src gnome org>]

commit 89a4c269a517f34a7732c276c6a55b56874fc8b5
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Wed Nov 14 10:36:15 2018 +0100

    gir: Update annotations from glib git master

 gir/gio-2.0.c     | 121 +++++++++++++++++++++++++++++++++++++++++----------
 gir/glib-2.0.c    | 128 +++++++++++++++++++++++++++++++++++++++++++++---------
 gir/gobject-2.0.c |  10 +++--
 3 files changed, 213 insertions(+), 46 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index ce76cdb8..947b71f6 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -5804,8 +5804,7 @@
  * well-known name, the property cache is flushed when the name owner
  * vanishes and reloaded when a name owner appears.
  *
- * If a #GDBusProxy is used for a well-known name, the owner of the
- * name is tracked and can be read from
+ * The unique name owner of the proxy's name is tracked and can be read from
  * #GDBusProxy:g-name-owner. Connect to the #GObject::notify signal to
  * get notified of changes. Additionally, only signals and property
  * changes emitted from the current name owner are considered and
@@ -6976,7 +6975,7 @@
  * then attempt to connect to that host, handling the possibility of
  * multiple IP addresses and multiple address families.
  *
- * See #GSocketConnectable for and example of using the connectable
+ * See #GSocketConnectable for an example of using the connectable
  * interface.
  */
 
@@ -7034,7 +7033,7 @@
  * address families.
  *
  * See #GSrvTarget for more information about SRV records, and see
- * #GSocketConnectable for and example of using the connectable
+ * #GSocketConnectable for an example of using the connectable
  * interface.
  */
 
@@ -7452,7 +7451,7 @@
  * fixed-size.
  *
  * #GSeekable on fixed-sized streams is approximately the same as POSIX
- * lseek() on a block device (for example: attmepting to seek past the
+ * lseek() on a block device (for example: attempting to seek past the
  * end of the device is an error).  Fixed streams typically cannot be
  * truncated.
  *
@@ -7588,6 +7587,11 @@
  *       <default>(20,30)</default>
  *     </key>
  *
+ *     <key name="empty-string" type="s">
+ *       <default>""</default>
+ *       <summary>Empty strings have to be provided in GVariant form</summary>
+ *     </key>
+ *
  *   </schema>
  * </schemalist>
  * ]|
@@ -9290,6 +9294,9 @@
  * from a certificate or key store. It is an abstract base class which
  * TLS library specific subtypes override.
  *
+ * A #GTlsDatabase may be accessed from multiple threads by the TLS backend.
+ * All implementations are required to be fully thread-safe.
+ *
  * Most common client applications will not directly interact with
  * #GTlsDatabase. It is used internally by #GTlsConnection.
  *
@@ -9588,6 +9595,9 @@
  * [thread-default-context aware][g-main-context-push-thread-default],
  * and so should not be used other than from the main thread, with no
  * thread-default-context active.
+ *
+ * In order to receive updates about volumes and mounts monitored through GVFS,
+ * a main loop must be running.
  */
 
 
@@ -14916,7 +14926,7 @@
  * dispatched anywhere else - not even the standard dispatch machinery
  * (that API such as g_dbus_connection_signal_subscribe() and
  * g_dbus_connection_send_message_with_reply() relies on) will see the
- * message. Similary, if a filter consumes an outgoing message, the
+ * message. Similarly, if a filter consumes an outgoing message, the
  * message will not be sent to the other peer.
  *
  * If @user_data_free_func is non-%NULL, it will be called (in the
@@ -15996,6 +16006,11 @@
  * signal is unsubscribed from, and may be called after @connection
  * has been destroyed.)
  *
+ * The returned subscription identifier is an opaque value which is guaranteed
+ * to never be zero.
+ *
+ * This function can never fail.
+ *
  * Returns: a subscription identifier that can be used with g_dbus_connection_signal_unsubscribe()
  * Since: 2.26
  */
@@ -16798,7 +16813,7 @@
 
 /**
  * g_dbus_message_bytes_needed:
- * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message.
+ * @blob: (array length=blob_len) (element-type guint8): A blob representing a binary D-Bus message.
  * @blob_len: The length of @blob (must be at least 16).
  * @error: Return location for error or %NULL.
  *
@@ -16904,7 +16919,10 @@
  *
  * Gets a header field on @message.
  *
- * Returns: A #GVariant with the value if the header was found, %NULL
+ * The caller is responsible for checking the type of the returned #GVariant
+ * matches what is expected.
+ *
+ * Returns: (transfer none) (nullable): A #GVariant with the value if the header was found, %NULL
  * otherwise. Do not free, it is owned by @message.
  * Since: 2.26
  */
@@ -17080,6 +17098,9 @@
  * order that the message was in can be retrieved using
  * g_dbus_message_get_byte_order().
  *
+ * If the @blob cannot be parsed, contains invalid fields, or contains invalid
+ * headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned.
+ *
  * Returns: A new #GDBusMessage or %NULL if @error is set. Free with
  * g_object_unref().
  * Since: 2.26
@@ -18691,6 +18712,10 @@
  * match rules for signals. Connect to the #GDBusProxy::g-signal signal
  * to handle signals from the remote object.
  *
+ * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
+ * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
+ * guaranteed to complete immediately without blocking.
+ *
  * If @name is a well-known name and the
  * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
  * flags aren't set and no name owner currently exists, the message bus
@@ -18796,6 +18821,10 @@
  * match rules for signals. Connect to the #GDBusProxy::g-signal signal
  * to handle signals from the remote object.
  *
+ * If both %G_DBUS_PROXY_FLAGS_DO_NOT_LOAD_PROPERTIES and
+ * %G_DBUS_PROXY_FLAGS_DO_NOT_CONNECT_SIGNALS are set, this constructor is
+ * guaranteed to return immediately without blocking.
+ *
  * If @name is a well-known name and the
  * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START and %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START_AT_CONSTRUCTION
  * flags aren't set and no name owner currently exists, the message bus
@@ -19194,6 +19223,23 @@
  */
 
 
+/**
+ * g_desktop_app_info_get_string_list:
+ * @info: a #GDesktopAppInfo
+ * @key: the key to look up
+ * @length: (out) (optional): return location for the number of returned strings, or %NULL
+ *
+ * Looks up a string list value in the keyfile backing @info.
+ *
+ * The @key is looked up in the "Desktop Entry" group.
+ *
+ * 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.59.0
+ */
+
+
 /**
  * g_desktop_app_info_has_key:
  * @info: a #GDesktopAppInfo
@@ -24907,8 +24953,8 @@
  *   native, the returned string is the result of g_file_get_uri()
  *   (such as `sftp://path/to/my%20icon.png`).
  *
- * - If @icon is a #GThemedIcon with exactly one name, the encoding is
- *    simply the name (such as `network-server`).
+ * - If @icon is a #GThemedIcon with exactly one name and no fallbacks,
+ *   the encoding is simply the name (such as `network-server`).
  *
  * Returns: (nullable): An allocated NUL-terminated UTF8 string or
  * %NULL if @icon can't be serialized. Use g_free() to free.
@@ -31915,16 +31961,9 @@
  * The list is exactly the list of strings for which it is not an error
  * to call g_settings_get_child().
  *
- * For GSettings objects that are lists, this value can change at any
- * time. Note that there is a race condition here: you may
- * request a child after listing it only for it to have been destroyed
- * in the meantime.  For this reason, g_settings_get_child() may return
- * %NULL even for a child that was listed by this function.
- *
- * For GSettings objects that are not lists, you should probably not be
- * calling this function from "normal" code (since you should already
- * know what children are in your schema).  This function may still be
- * useful there for introspection reasons, however.
+ * There is little reason to call this function from "normal" code, since
+ * you should already know what children are in your schema. This function
+ * may still be useful there for introspection reasons, however.
  *
  * You should free the return value with g_strfreev() when you are done
  * with it.
@@ -37928,6 +37967,24 @@
  */
 
 
+/**
+ * g_tls_backend_set_default_database:
+ * @backend: the #GTlsBackend
+ * @database: (nullable): the #GTlsDatabase
+ *
+ * Set the default #GTlsDatabase used to verify TLS connections
+ *
+ * Any subsequent call to g_tls_backend_get_default_database() will return
+ * the database set in this call.  Existing databases and connections are not
+ * modified.
+ *
+ * Setting a %NULL default database will reset to using the system default
+ * database as if g_tls_backend_set_default_database() had never been called.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * g_tls_backend_supports_dtls:
  * @backend: the #GTlsBackend
@@ -38394,8 +38451,10 @@
  * the beginning of the communication, you do not need to call this
  * function explicitly unless you want clearer error reporting.
  * However, you may call g_tls_connection_handshake() later on to
- * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, this will
- * instead perform a rekey.
+ * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, the
+ * behavior is undefined but guaranteed to be reasonable and
+ * nondestructive, so most older code should be expected to continue to
+ * work without changes.
  *
  * #GTlsConnection::accept_certificate may be emitted during the
  * handshake.
@@ -39896,6 +39955,22 @@
  */
 
 
+/**
+ * g_unix_mount_get_root_path:
+ * @mount_entry: a #GUnixMountEntry.
+ *
+ * Gets the root of the mount within the filesystem. This is useful e.g. for
+ * mounts created by bind operation, or btrfs subvolumes.
+ *
+ * For example, the root path is equal to "/" for mount created by
+ * "mount /dev/sda1 /mnt/foo" and "/bar" for
+ * "mount --bind /mnt/foo/bar /mnt/bar".
+ *
+ * Returns: (nullable): a string containing the root, or %NULL if not supported.
+ * Since: 2.60
+ */
+
+
 /**
  * g_unix_mount_guess_can_eject:
  * @mount_entry: a #GUnixMountEntry
@@ -40809,7 +40884,7 @@
  * also listen for the "removed" signal on the returned object
  * and give up its reference when handling that signal
  *
- * Similary, if implementing g_volume_monitor_adopt_orphan_mount(),
+ * Similarly, if implementing g_volume_monitor_adopt_orphan_mount(),
  * the implementor must take a reference to @mount and return it in
  * its g_volume_get_mount() implemented. Also, the implementor must
  * listen for the "unmounted" signal on @mount and give up its
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 66ab9a05..8a8ce87a 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -2108,7 +2108,9 @@
  *
  * GLib is attempting to unify around the use of 64bit integers to
  * represent microsecond-precision time. As such, this type will be
- * removed from a future version of GLib.
+ * removed from a future version of GLib. A consequence of using `glong` for
+ * `tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038
+ * problem.
  */
 
 
@@ -3324,6 +3326,23 @@
  */
 
 
+/**
+ * G_GNUC_FALLTHROUGH:
+ *
+ * Expands to the GNU C fallthrough statement attribute if the compiler is gcc.
+ * This allows declaring case statement to explicitly fall through in switch
+ * statements. To enable this feature, use -Wimplicit-fallthrough during
+ * compilation.
+ *
+ * Put the attribute right before the case statement you want to fall through
+ * to.
+ *
+ * See the GNU C documentation for more details.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * G_GNUC_FORMAT:
  * @arg_idx: the index of the argument
@@ -3564,6 +3583,24 @@
  */
 
 
+/**
+ * G_GNUC_STRFTIME:
+ * @format_idx: the index of the argument corresponding to
+ *     the format string (the arguments are numbered from 1)
+ *
+ * Expands to the GNU C strftime format function attribute if the compiler
+ * is gcc. This is used for declaring functions which take a format argument
+ * which is passed to strftime() or an API implementing its formats. It allows
+ * the compiler check the format passed to the function.
+ *
+ * See the
+ * [GNU C 
documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-Wformat-3288)
+ * for details.
+ *
+ * Since: 2.60
+ */
+
+
 /**
  * G_GNUC_UNUSED:
  *
@@ -6708,7 +6745,10 @@
  *
  * The above definition is recursive to arbitrary depth. "aaaaai" and
  * "(ui(nq((y)))s)" are both valid type strings, as is
- * "a(aa(ui)(qna{ya(yd)}))".
+ * "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant
+ * imposes a limit on recursion depth of 65 nested containers. This is the
+ * limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to
+ * be nested in a top-level tuple.
  *
  * The meaning of each of the characters is as follows:
  * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value.
@@ -9137,15 +9177,15 @@
  * @free_segment: if %TRUE the actual element data is freed as well
  *
  * Frees the memory allocated for the #GArray. If @free_segment is
- * %TRUE it frees the memory block holding the elements as well and
- * also each element if @array has a @element_free_func set. Pass
+ * %TRUE it frees the memory block holding the elements as well. Pass
  * %FALSE if you want to free the #GArray wrapper but preserve the
- * underlying array for use elsewhere. If the reference count of @array
- * is greater than one, the #GArray wrapper is preserved but the size
- * of @array will be set to zero.
+ * underlying array for use elsewhere. If the reference count of
+ * @array is greater than one, the #GArray wrapper is preserved but
+ * the size of  @array will be set to zero.
  *
- * If array elements contain dynamically-allocated memory, they should
- * be freed separately.
+ * If array contents point to dynamically-allocated memory, they should
+ * be freed separately if @free_seg is %TRUE and no @clear_func
+ * function has been set for @array.
  *
  * This function is not thread-safe. If using a #GArray from multiple
  * threads, use only the atomic g_array_ref() and g_array_unref()
@@ -11729,8 +11769,8 @@
  * @stamp: (out) (optional): return location for the last registration time, or %NULL
  * @error: return location for a #GError, or %NULL
  *
- * Gets the registration informations of @app_name for the bookmark for
- * @uri.  See g_bookmark_file_set_app_info() for more informations about
+ * Gets the registration information of @app_name for the bookmark for
+ * @uri.  See g_bookmark_file_set_app_info() for more information about
  * the returned data.
  *
  * The string returned in @app_exec must be freed.
@@ -16904,8 +16944,9 @@
  *
  * g_get_language_names() returns g_get_language_names_with_category("LC_MESSAGES").
  *
- * 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
+ *    the thread g_get_language_names_with_category was called from.
+ *    It must not be modified or freed. It must be copied if planned to be used in another thread.
  * Since: 2.58
  */
 
@@ -19303,7 +19344,9 @@
  * @group_name. If both @key and @group_name are %NULL, then
  * @comment will be read from above the first group in the file.
  *
- * Note that the returned string includes the '#' comment markers.
+ * Note that the returned string does not include the '#' comment markers,
+ * but does include any whitespace after them (on each line). It includes
+ * the line breaks between lines, but does not include the final line break.
  *
  * Returns: a comment that should be freed with g_free()
  * Since: 2.6
@@ -24277,7 +24320,9 @@
  * g_path_get_dirname:
  * @file_name: (type filename): the name of the file
  *
- * Gets the directory components of a file name.
+ * Gets the directory components of a file name. For example, the directory
+ * component of `/usr/bin/test` is `/usr/bin`. The directory component of `/`
+ * is `/`.
  *
  * If the file name has no directory components "." is returned.
  * The returned string should be freed when no longer needed.
@@ -29391,7 +29436,11 @@
  * on how to handle memory management of @data.
  *
  * Typically, you won't use this function. Instead use functions specific
- * to the type of source you are using.
+ * to the type of source you are using, such as g_idle_add() or g_timeout_add().
+ *
+ * It is safe to call this function multiple times on a source which has already
+ * been attached to a context. The changes will take effect for the next time
+ * the source is dispatched after this call returns.
  */
 
 
@@ -29408,6 +29457,10 @@
  * an initial reference count on @callback_data, and thus
  * @callback_funcs->unref will eventually be called once more
  * than @callback_funcs->ref.
+ *
+ * It is safe to call this function multiple times on a source which has already
+ * been attached to a context. The changes will take effect for the next time
+ * the source is dispatched after this call returns.
  */
 
 
@@ -33031,10 +33084,12 @@
  * variation of ISO 8601 format is required.
  *
  * If @time_ represents a date which is too large to fit into a `struct tm`,
- * %NULL will be returned. This is platform dependent, but it is safe to assume
- * years up to 3000 are supported. The return value of g_time_val_to_iso8601()
- * has been nullable since GLib 2.54; before then, GLib would crash under the
- * same conditions.
+ * %NULL will be returned. This is platform dependent. Note also that since
+ * `GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it
+ * is subject to the year 2038 problem.
+ *
+ * The return value of g_time_val_to_iso8601() has been nullable since GLib
+ * 2.54; before then, GLib would crash under the same conditions.
  *
  * Returns: (nullable): a newly allocated string containing an ISO 8601 date,
  *    or %NULL if @time_ was too large
@@ -35535,6 +35590,22 @@
  */
 
 
+/**
+ * g_utf8_validate_len:
+ * @str: (array length=max_len) (element-type guint8): a pointer to character data
+ * @max_len: max bytes to validate
+ * @end: (out) (optional) (transfer none): return location for end of valid data
+ *
+ * Validates UTF-8 encoded text.
+ *
+ * As with g_utf8_validate(), but @max_len must be set, and hence this function
+ * will always return %FALSE if any of the bytes of @str are nul.
+ *
+ * Returns: %TRUE if the text was valid UTF-8
+ * Since: 2.60
+ */
+
+
 /**
  * g_utime:
  * @filename: (type filename): a pathname in the GLib file name encoding
@@ -36438,6 +36509,11 @@
  * The returned value is never floating.  You should free it with
  * g_variant_unref() when you're done with it.
  *
+ * There may be implementation specific restrictions on deeply nested values,
+ * which would result in the unit tuple being returned as the child value,
+ * instead of further nested children. #GVariant is guaranteed to handle
+ * nesting up to at least 64 levels.
+ *
  * This function is O(1).
  *
  * Returns: (transfer full): the child at the specified index
@@ -36923,6 +36999,9 @@
  * being trusted.  If the value was already marked as being trusted then
  * this function will immediately return %TRUE.
  *
+ * There may be implementation specific restrictions on deeply nested values.
+ * GVariant is guaranteed to handle nesting up to at least 64 levels.
+ *
  * Returns: %TRUE if @value is in normal form
  * Since: 2.24
  */
@@ -37488,6 +37567,10 @@
  *
  * A reference is taken on @bytes.
  *
+ * The data in @bytes must be aligned appropriately for the @type being loaded.
+ * Otherwise this function will internally create a copy of the memory (since
+ * GLib 2.60) or (in older versions) fail and exit the process.
+ *
  * Returns: (transfer none): a new #GVariant with a floating reference
  * Since: 2.36
  */
@@ -37527,6 +37610,11 @@
  * needed.  The exact time of this call is unspecified and might even be
  * before this function returns.
  *
+ * Note: @data must be backed by memory that is aligned appropriately for the
+ * @type being loaded. Otherwise this function will internally create a copy of
+ * the memory (since GLib 2.60) or (in older versions) fail and exit the
+ * process.
+ *
  * Returns: (transfer none): a new floating #GVariant of type @type
  * Since: 2.24
  */
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 1a4f3bcb..b6c3f152 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -1821,6 +1821,8 @@
  * Creates a new closure which invokes @callback_func with @user_data as
  * the last parameter.
  *
+ * @destroy_data will be called as a finalize notifier on the #GClosure.
+ *
  * Returns: (transfer none): a floating reference to a new #GCClosure
  */
 
@@ -1864,6 +1866,8 @@
  * Creates a new closure which invokes @callback_func with @user_data as
  * the first parameter.
  *
+ * @destroy_data will be called as a finalize notifier on the #GClosure.
+ *
  * Returns: (transfer none): a floating reference to a new #GCClosure
  */
 
@@ -1934,7 +1938,7 @@
 
 /**
  * g_closure_invalidate:
- * @closure: GClosure to invalidate
+ * @closure: #GClosure to invalidate
  *
  * Sets a flag on the closure to indicate that its calling
  * environment has become invalid, and thus causes any future
@@ -3466,8 +3470,8 @@
 
 /**
  * g_object_watch_closure:
- * @object: GObject restricting lifetime of @closure
- * @closure: GClosure to watch
+ * @object: #GObject restricting lifetime of @closure
+ * @closure: #GClosure to watch
  *
  * This function essentially limits the life time of the @closure to
  * the life time of the object. That is, when the object is finalized,