gir: Update annotations from GLib git master

2 files changed, 162 insertions, 32 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 841cad4b..10a2f672 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -5653,8 +5653,9 @@
  * @include: gio/gio.h
  *
  * Routines for working with D-Bus addresses. A D-Bus address is a string
- * like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
- * is explained in detail in the [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html\#addresses).
+ * like `unix:tmpdir=/tmp/my-app-name`. The exact format of addresses
+ * is explained in detail in the
+ * [D-Bus specification](http://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
  */
 
 
@@ -16326,6 +16327,9 @@
  * bus instance specified by @bus_type. This may involve using various
  * platform specific mechanisms.
  *
+ * The returned address will be in the
+ * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
+ *
  * Returns: a valid D-Bus address string for @bus_type or %NULL if
  *     @error is set
  * Since: 2.26
@@ -16341,7 +16345,8 @@
  *
  * Asynchronously connects to an endpoint specified by @address and
  * sets up the connection so it is in a state to run the client-side
- * of the D-Bus authentication conversation.
+ * of the D-Bus authentication conversation. @address must be in the
+ * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
  *
  * When the operation is finished, @callback will be invoked. You can
  * then call g_dbus_address_get_stream_finish() to get the result of
@@ -16376,7 +16381,8 @@
  *
  * Synchronously connects to an endpoint specified by @address and
  * sets up the connection so it is in a state to run the client-side
- * of the D-Bus authentication conversation.
+ * of the D-Bus authentication conversation. @address must be in the
+ * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
  *
  * This is a synchronous failable function. See
  * g_dbus_address_get_stream() for the asynchronous version.
@@ -17122,7 +17128,8 @@
  *
  * Asynchronously connects and sets up a D-Bus client connection for
  * exchanging D-Bus messages with an endpoint specified by @address
- * which must be in the D-Bus address format.
+ * which must be in the
+ * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
  *
  * This constructor can only be used to initiate client-side
  * connections - use g_dbus_connection_new() if you need to act as the
@@ -17169,7 +17176,8 @@
  *
  * Synchronously connects and sets up a D-Bus client connection for
  * exchanging D-Bus messages with an endpoint specified by @address
- * which must be in the D-Bus address format.
+ * which must be in the
+ * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
  *
  * This constructor can only be used to initiate client-side
  * connections - use g_dbus_connection_new_sync() if you need to act
@@ -18270,7 +18278,8 @@
  * g_dbus_is_address:
  * @string: A string.
  *
- * Checks if @string is a D-Bus address.
+ * Checks if @string is a
+ * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
  *
  * This doesn't check if @string is actually supported by #GDBusServer
  * or #GDBusConnection - use g_dbus_is_supported_address() to do more
@@ -18333,9 +18342,10 @@
  * @string: A string.
  * @error: Return location for error or %NULL.
  *
- * Like g_dbus_is_address() but also checks if the library suppors the
+ * Like g_dbus_is_address() but also checks if the library supports the
  * transports in @string and that key/value pairs for each transport
- * are valid.
+ * are valid. See the specification of the
+ * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses).
  *
  * Returns: %TRUE if @string is a valid D-Bus address that is
  * supported by this library, %FALSE if @error is set.
@@ -19284,7 +19294,26 @@
  * Finishes handling a D-Bus method call by returning @parameters.
  * If the @parameters GVariant is floating, it is consumed.
  *
- * It is an error if @parameters is not of the right format.
+ * It is an error if @parameters is not of the right format: it must be a tuple
+ * containing the out-parameters of the D-Bus method. Even if the method has a
+ * single out-parameter, it must be contained in a tuple. If the method has no
+ * out-parameters, @parameters may be %NULL or an empty tuple.
+ *
+ * |[<!-- language="C" -->
+ * GDBusMethodInvocation *invocation = some_invocation;
+ * g_autofree gchar *result_string = NULL;
+ * g_autoptr (GError) error = NULL;
+ *
+ * result_string = calculate_result (&error);
+ *
+ * if (error != NULL)
+ *   g_dbus_method_invocation_return_gerror (invocation, error);
+ * else
+ *   g_dbus_method_invocation_return_value (invocation,
+ *                                          g_variant_new ("(s)", result_string));
+ *
+ * /<!-- -->* Do not free @invocation here; returning a value does that *<!-- -->/
+ * ]|
  *
  * This method will take ownership of @invocation. See
  * #GDBusInterfaceVTable for more information about the ownership of
@@ -20442,8 +20471,9 @@
  * g_dbus_server_get_client_address:
  * @server: A #GDBusServer.
  *
- * Gets a D-Bus address string that can be used by clients to connect
- * to @server.
+ * Gets a
+ * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
+ * string that can be used by clients to connect to @server.
  *
  * Returns: A D-Bus address string. Do not free, the string is owned
  * by @server.
@@ -30540,7 +30570,7 @@
  *
  * For behaviour details see g_output_stream_close().
  *
- * The asyncronous methods have a default fallback that uses threads
+ * The asynchronous methods have a default fallback that uses threads
  * to implement asynchronicity, so they are optional for inheriting
  * classes. However, if you override one you must override all.
  */
@@ -30614,7 +30644,7 @@
  * g_output_stream_has_pending:
  * @stream: a #GOutputStream.
  *
- * Checks if an ouput stream has pending actions.
+ * Checks if an output stream has pending actions.
  *
  * Returns: %TRUE if @stream has pending actions.
  */
@@ -30923,7 +30953,7 @@
  * value) will be executed before an outstanding request with lower
  * priority. Default priority is %G_PRIORITY_DEFAULT.
  *
- * The asyncronous methods have a default fallback that uses threads
+ * The asynchronous methods have a default fallback that uses threads
  * to implement asynchronicity, so they are optional for inheriting
  * classes. However, if you override one you must override all.
  *
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 97296056..9a35f49d 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -8347,6 +8347,29 @@
 
 
 /**
+ * SECTION:uuid
+ * @title: GUuid
+ * @short_description: a universally unique identifier
+ *
+ * A UUID, or Universally unique identifier, is intended to uniquely
+ * identify information in a distributed environment. For the
+ * definition of UUID, see [RFC 4122](https://tools.ietf.org/html/rfc4122.html).
+ *
+ * The creation of UUIDs does not require a centralized authority.
+ *
+ * UUIDs are of relatively small size (128 bits, or 16 bytes). The
+ * common string representation (ex:
+ * 1d6c0810-2bd6-45f3-9890-0268422a6f14) needs 37 bytes.
+ *
+ * The UUID specification defines 5 versions, and calling
+ * g_uuid_string_random() will generate a unique (or rather random)
+ * UUID of the most common version, version 4.
+ *
+ * Since: 2.52
+ */
+
+
+/**
  * SECTION:version
  * @Title: Version Information
  * @Short_description: variables and functions to check the GLib version
@@ -18040,7 +18063,8 @@
  *
  * If @key cannot be found then 0 is returned and @error is set to
  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the value associated
- * with @key cannot be interpreted as an integer then 0 is returned
+ * with @key cannot be interpreted as an integer, or is out of range
+ * for a #gint, then 0 is returned
  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
  *
  * Returns: the value associated with the key as an integer, or
@@ -18062,7 +18086,8 @@
  *
  * If @key cannot be found then %NULL is returned and @error is set to
  * #G_KEY_FILE_ERROR_KEY_NOT_FOUND. Likewise, if the values associated
- * with @key cannot be interpreted as integers then %NULL is returned
+ * with @key cannot be interpreted as integers, or are out of range for
+ * #gint, then %NULL is returned
  * and @error is set to #G_KEY_FILE_ERROR_INVALID_VALUE.
  *
  * Returns: (array length=length) (element-type gint) (transfer container):
@@ -18334,9 +18359,13 @@
  *
  * This function looks for a key file named @file in the paths
  * specified in @search_dirs, loads the file into @key_file and
- * returns the file's full path in @full_path.  If the file could not
- * be loaded then an %error is set to either a #GFileError or
- * #GKeyFileError.
+ * returns the file's full path in @full_path.
+ *
+ * If the file could not be found in any of the @search_dirs,
+ * %G_KEY_FILE_ERROR_NOT_FOUND is returned. If
+ * the file is found but the OS returns an error when opening or reading the
+ * file, a %G_FILE_ERROR is returned. If there is a problem parsing the file, a
+ * %G_KEY_FILE_ERROR is returned.
  *
  * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
  * Since: 2.14
@@ -18351,8 +18380,13 @@
  * @error: return location for a #GError, or %NULL
  *
  * Loads a key file into an empty #GKeyFile structure.
- * If the file could not be loaded then @error is set to
- * either a #GFileError or #GKeyFileError.
+ *
+ * If the OS returns an error when opening or reading the file, a
+ * %G_FILE_ERROR is returned. If there is a problem parsing the file, a
+ * %G_KEY_FILE_ERROR is returned.
+ *
+ * This function will never return a %G_KEY_FILE_ERROR_NOT_FOUND error. If the
+ * @file is not found, %G_FILE_ERROR_NOENT is returned.
  *
  * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
  * Since: 2.6
@@ -21553,7 +21587,7 @@
 
 
 /**
- * g_mkdtemp:
+ * g_mkdtemp: (skip)
  * @tmpl: (type filename): template directory name
  *
  * Creates a temporary directory. See the mkdtemp() documentation
@@ -21562,12 +21596,16 @@
  * The parameter is a string that should follow the rules for
  * mkdtemp() templates, i.e. contain the string "XXXXXX".
  * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
- * sequence does not have to occur at the very end of the template
- * and you can pass a @mode and additional @flags. The X string will
- * be modified to form the name of a directory that didn't exist.
+ * sequence does not have to occur at the very end of the template.
+ * The X string will be modified to form the name of a directory that
+ * didn't exist.
  * The string should be in the GLib file name encoding. Most importantly,
  * on Windows it should be in UTF-8.
  *
+ * If you are going to be creating a temporary directory inside the
+ * directory returned by g_get_tmp_dir(), you might want to use
+ * g_dir_make_tmp() instead.
+ *
  * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
  *     modified to hold the directory name.  In case of errors, %NULL is
  *     returned and %errno will be set.
@@ -21576,7 +21614,7 @@
 
 
 /**
- * g_mkdtemp_full:
+ * g_mkdtemp_full: (skip)
  * @tmpl: (type filename): template directory name
  * @mode: permissions to create the temporary directory with
  *
@@ -21585,13 +21623,17 @@
  *
  * The parameter is a string that should follow the rules for
  * mkdtemp() templates, i.e. contain the string "XXXXXX".
- * g_mkdtemp() is slightly more flexible than mkdtemp() in that the
+ * g_mkdtemp_full() is slightly more flexible than mkdtemp() in that the
  * sequence does not have to occur at the very end of the template
  * and you can pass a @mode. The X string will be modified to form
  * the name of a directory that didn't exist. The string should be
  * in the GLib file name encoding. Most importantly, on Windows it
  * should be in UTF-8.
  *
+ * If you are going to be creating a temporary directory inside the
+ * directory returned by g_get_tmp_dir(), you might want to use
+ * g_dir_make_tmp() instead.
+ *
  * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
  *     modified to hold the directory name. In case of errors, %NULL is
  *     returned, and %errno will be set.
@@ -21600,7 +21642,7 @@
 
 
 /**
- * g_mkstemp:
+ * g_mkstemp: (skip)
  * @tmpl: (type filename): template filename
  *
  * Opens a temporary file. See the mkstemp() documentation
@@ -21623,7 +21665,7 @@
 
 
 /**
- * g_mkstemp_full:
+ * g_mkstemp_full: (skip)
  * @tmpl: (type filename): template filename
  * @flags: flags to pass to an open() call in addition to O_EXCL
  *     and O_CREAT, which are passed automatically
@@ -33559,6 +33601,34 @@
 
 
 /**
+ * g_uuid_string_is_valid:
+ * @str: a string representing a UUID
+ *
+ * Parses the string @str and verify if it is a UUID.
+ *
+ * The function accepts the following syntax:
+ *
+ * - simple forms (e.g. `f81d4fae-7dec-11d0-a765-00a0c91e6bf6`)
+ *
+ * Note that hyphens are required within the UUID string itself,
+ * as per the aforementioned RFC.
+ *
+ * Returns: %TRUE if @str is a valid UUID, %FALSE otherwise.
+ * Since: 2.52
+ */
+
+
+/**
+ * g_uuid_string_random:
+ *
+ * Generates a random UUID (RFC 4122 version 4) as a string.
+ *
+ * Returns: (transfer full): A string that should be freed with g_free().
+ * Since: 2.52
+ */
+
+
+/**
  * g_variant_builder_add: (skip)
  * @builder: a #GVariantBuilder
  * @format_string: a #GVariant varargs format string
@@ -33782,15 +33852,45 @@
 /**
  * g_variant_builder_open:
  * @builder: a #GVariantBuilder
- * @type: a #GVariantType
+ * @type: the #GVariantType of the container
  *
  * Opens a subcontainer inside the given @builder.  When done adding
- * items to the subcontainer, g_variant_builder_close() must be called.
+ * items to the subcontainer, g_variant_builder_close() must be called. @type
+ * is the type of the container: so to build a tuple of several values, @type
+ * must include the tuple itself.
  *
  * It is an error to call this function in any way that would cause an
  * inconsistent value to be constructed (ie: adding too many values or
  * a value of an incorrect type).
  *
+ * Example of building a nested variant:
+ * |[<!-- language="C" -->
+ * GVariantBuilder builder;
+ * guint32 some_number = get_number ();
+ * g_autoptr (GHashTable) some_dict = get_dict ();
+ * GHashTableIter iter;
+ * const gchar *key;
+ * const GVariant *value;
+ * g_autoptr (GVariant) output = NULL;
+ *
+ * g_variant_builder_init (&builder, G_VARIANT_TYPE ("(ua{sv})"));
+ * g_variant_builder_add (&builder, "u", some_number);
+ * g_variant_builder_open (&builder, G_VARIANT_TYPE ("a{sv}"));
+ *
+ * g_hash_table_iter_init (&iter, some_dict);
+ * while (g_hash_table_iter_next (&iter, (gpointer *) &key, (gpointer *) &value))
+ *   {
+ *     g_variant_builder_open (&builder, G_VARIANT_TYPE ("{sv}"));
+ *     g_variant_builder_add (&builder, "s", key);
+ *     g_variant_builder_add (&builder, "v", value);
+ *     g_variant_builder_close (&builder);
+ *   }
+ *
+ * g_variant_builder_close (&builder);
+ *
+ * output = g_variant_builder_end (&builder);
+ * ]|
+ *
  * Since: 2.24
  */