gir: Update annotations from glib git master

3 files changed, 259 insertions, 30 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 485355a9..1a08a9c5 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -217,6 +217,162 @@
 
 
 /**
+ * GAppInfo:can-delete:
+ *
+ * %TRUE if it makes sense to call g_app_info_delete() for this
+ * #GAppInfo.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:commandline: (nullable)
+ *
+ * The commandline with which the application will be launched.
+ *
+ * In #GAppInfos created from [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/),
+ * this is the value of the `Exec` key.
+ *
+ * May be %NULL, depending on how the #GAppInfo has been constructed.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:description: (nullable)
+ *
+ * A human-readable description of the application.
+ *
+ * In #GAppInfos created from [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/),
+ * this is the value of the `Comment` key.
+ *
+ * May be %NULL, depending on how the #GAppInfo has been constructed.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:display-name: (nullable)
+ *
+ * The display name of the application.
+ *
+ * This string is meant to be displayed to the user; it is often more
+ * descriptive than #GAppInfo:name.
+ *
+ * In #GAppInfos created from [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/),
+ * this is the value of the `X-GNOME-FullName` key, falling back to the `Name` key.
+ *
+ * May be %NULL, depending on how the #GAppInfo has been constructed.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:executable: (nullable)
+ *
+ * The executable's name for the application.
+ *
+ * In #GAppInfos created from [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/),
+ * this is the first word of the `Exec` key.
+ *
+ * May be %NULL, depending on how the #GAppInfo has been constructed.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:icon: (nullable)
+ *
+ * The icon for the application.
+ *
+ * May be %NULL, depending on how the #GAppInfo has been constructed.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:id: (nullable)
+ *
+ * The ID of an application -- a string that identifies the application.
+ *
+ * The exact format of the ID is platform dependent. For instance,
+ * on Unix this is the desktop file ID from the xdg menu specification.
+ *
+ * May be %NULL, depending on how the GAppInfo has been constructed.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:name:
+ *
+ * The name of the application.
+ *
+ * In #GAppInfos created from [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/),
+ * this is the value of the `Name` key.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:should-show:
+ *
+ * %TRUE if the application should be shown in menus that list
+ * available applications.
+ *
+ * In #GAppInfos created from [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/),
+ * this is the (inverted) value of the `NoDisplay` key.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:supported-types:
+ *
+ * The list of content types that the application claims to support.
+ * Note that this property does not take into account associations
+ * added with g_app_info_add_supports_type(), but only those exported
+ * directly by the application.
+ *
+ * In #GAppInfos created from [desktop files](https://specifications.freedesktop.org/desktop-entry-spec/latest/),
+ * this is the value of the `MimeType` key.
+ *
+ * May be %NULL, depending on how the #GAppInfo has been constructed.
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:supports-files:
+ *
+ * %TRUE if the application supports files as arguments when launched.
+ * See g_app_info_launch_uris().
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * GAppInfo:supports-uris:
+ *
+ * %TRUE if the application supports reading files and directories
+ * from URIs when launched. See g_app_info_launch_uris().
+ *
+ * Since: 2.66
+ */
+
+
+/**
  * GAppInfoMonitor:
  *
  * The only thing you can do with this is to get it via
@@ -5054,6 +5210,7 @@
  *   GTask *task;
  *
  *   task = g_task_new (initable, cancellable, callback, user_data);
+ *   g_task_set_name (task, G_STRFUNC);
  *
  *   switch (self->priv->state)
  *     {
@@ -22516,9 +22673,9 @@
  * g_file_info_get_display_name:
  * @info: a #GFileInfo.
  *
- * Gets a display name for a file.
+ * Gets a display name for a file. This is guaranteed to always be set.
  *
- * Returns: a string containing the display name.
+ * Returns: (not nullable): a string containing the display name.
  */
 
 
@@ -22627,9 +22784,9 @@
  * g_file_info_get_name:
  * @info: a #GFileInfo.
  *
- * Gets the name for a file.
+ * Gets the name for a file. This is guaranteed to always be set.
  *
- * Returns: (type filename): a string containing the file name.
+ * Returns: (type filename) (not nullable): a string containing the file name.
  */
 
 
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index a9f47372..3901e323 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -2587,7 +2587,10 @@
  *   g_assert_error(err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
  * ]|
  *
- * (you should pass %G_URI_FLAGS_ENCODED if you need to handle that case manually).
+ * You should pass %G_URI_FLAGS_ENCODED or %G_URI_FLAGS_ENCODED_QUERY if you
+ * need to handle that case manually. In particular, if the query string
+ * contains '=' characters that are '%'-encoded, you should let
+ * g_uri_parse_params() do the decoding once of the query.
  *
  * #GUri is immutable once constructed, and can safely be accessed from
  * multiple threads. Its reference counting is atomic.
@@ -16571,11 +16574,43 @@
  * @length: length of @contents, or -1 if @contents is a nul-terminated string
  * @error: return location for a #GError, or %NULL
  *
+ * Writes all of @contents to a file named @filename. This is a convenience
+ * wrapper around calling g_file_set_contents() with `flags` set to
+ * `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and
+ * `mode` set to `0666`.
+ *
+ * Returns: %TRUE on success, %FALSE if an error occurred
+ * Since: 2.8
+ */
+
+
+/**
+ * g_file_set_contents_full:
+ * @filename: (type filename): name of a file to write @contents to, in the GLib file name
+ *   encoding
+ * @contents: (array length=length) (element-type guint8): string to write to the file
+ * @length: length of @contents, or -1 if @contents is a nul-terminated string
+ * @flags: flags controlling the safety vs speed of the operation
+ * @mode: file mode, as passed to `open()`; typically this will be `0666`
+ * @error: return location for a #GError, or %NULL
+ *
  * Writes all of @contents to a file named @filename, with good error checking.
  * If a file called @filename already exists it will be overwritten.
  *
- * This write is atomic in the sense that it is first written to a temporary
- * file which is then renamed to the final name. Notes:
+ * @flags control the properties of the write operation: whether it’s atomic,
+ * and what the tradeoff is between returning quickly or being resilient to
+ * system crashes.
+ *
+ * As this function performs file I/O, it is recommended to not call it anywhere
+ * where blocking would cause problems, such as in the main loop of a graphical
+ * application. In particular, if @flags has any value other than
+ * %G_FILE_SET_CONTENTS_NONE then this function may call `fsync()`.
+ *
+ * If %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the operation is atomic
+ * in the sense that it is first written to a temporary file which is then
+ * renamed to the final name.
+ *
+ * Notes:
  *
  * - On UNIX, if @filename already exists hard links to @filename will break.
  *   Also since the file is recreated, existing permissions, access control
@@ -16583,15 +16618,17 @@
  *   the link itself will be replaced, not the linked file.
  *
  * - On UNIX, if @filename already exists and is non-empty, and if the system
- *   supports it (via a journalling filesystem or equivalent), the fsync()
- *   call (or equivalent) will be used to ensure atomic replacement: @filename
+ *   supports it (via a journalling filesystem or equivalent), and if
+ *   %G_FILE_SET_CONTENTS_CONSISTENT is set in @flags, the `fsync()` call (or
+ *   equivalent) will be used to ensure atomic replacement: @filename
  *   will contain either its old contents or @contents, even in the face of
  *   system power loss, the disk being unsafely removed, etc.
  *
  * - On UNIX, if @filename does not already exist or is empty, there is a
  *   possibility that system power loss etc. after calling this function will
  *   leave @filename empty or full of NUL bytes, depending on the underlying
- *   filesystem.
+ *   filesystem, unless %G_FILE_SET_CONTENTS_DURABLE and
+ *   %G_FILE_SET_CONTENTS_CONSISTENT are set in @flags.
  *
  * - On Windows renaming a file will not remove an existing file with the
  *   new name, so on Windows there is a race condition between the existing
@@ -16608,8 +16645,12 @@
  * Note that the name for the temporary file is constructed by appending up
  * to 7 characters to @filename.
  *
+ * If the file didn’t exist before and is created, it will be given the
+ * permissions from @mode. Otherwise, the permissions of the existing file may
+ * be changed to @mode depending on @flags, or they may remain unchanged.
+ *
  * Returns: %TRUE on success, %FALSE if an error occurred
- * Since: 2.8
+ * Since: 2.66
  */
 
 
@@ -16872,7 +16913,7 @@
  *
  * As `close()` and `fclose()` are part of the C library, this implies that it is
  * currently impossible to close a file if the application C library and the C library
- * used by GLib are different. Convenience functions like g_file_set_contents()
+ * used by GLib are different. Convenience functions like g_file_set_contents_full()
  * avoid this problem.
  *
  * Returns: A `FILE*` if the file was successfully opened, or %NULL if
@@ -16993,10 +17034,13 @@
  * g_fsync:
  * @fd: a file descriptor
  *
- * A wrapper for the POSIX fsync() function (_commit() on Windows).
- * The fsync() function is used to synchronize a file's in-core
+ * A wrapper for the POSIX `fsync()` function. On Windows, `_commit()` will be
+ * used. On macOS, `fcntl(F_FULLFSYNC)` will be used.
+ * The `fsync()` function is used to synchronize a file's in-core
  * state with that of the disk.
  *
+ * This wrapper will handle retrying on `EINTR`.
+ *
  * See the C library manual for more details about fsync().
  *
  * Returns: 0 on success, or -1 if an error occurred.
@@ -20245,7 +20289,9 @@
  * @error: a pointer to a %NULL #GError, or %NULL
  *
  * Writes the contents of @key_file to @filename using
- * g_file_set_contents().
+ * g_file_set_contents(). If you need stricter guarantees about durability of
+ * the written file than are provided by g_file_set_contents(), use
+ * g_file_set_contents_full() with the return value of g_key_file_to_data().
  *
  * This function can fail for any of the reasons that
  * g_file_set_contents() may fail.
@@ -32131,7 +32177,8 @@
  * g_strsplit_set:
  * @string: The string to be tokenized
  * @delimiters: A nul-terminated string containing bytes that are used
- *     to split the string.
+ *     to split the string (it can accept an empty string, which will result
+ *     in no string splitting).
  * @max_tokens: The maximum number of tokens to split @string into.
  *     If this is less than 1, the string is split completely
  *
@@ -32426,8 +32473,11 @@
  * @data_test: (scope async): the actual test function
  * @data_teardown: (scope async): the function to teardown the fixture data
  *
- * Create a new #GTestCase, named @test_name, this API is fairly
- * low level, calling g_test_add() or g_test_add_func() is preferable.
+ * Create a new #GTestCase, named @test_name.
+ *
+ * This API is fairly low level, and calling g_test_add() or g_test_add_func()
+ * is preferable.
+ *
  * When this test is executed, a fixture structure of size @data_size
  * will be automatically allocated and filled with zeros. Then @data_setup is
  * called to initialize the fixture. After fixture setup, the actual test
@@ -32436,10 +32486,10 @@
  * after that the memory is automatically released by the test framework.
  *
  * Splitting up a test run into fixture setup, test function and
- * fixture teardown is most useful if the same fixture is used for
+ * fixture teardown is most useful if the same fixture type is used for
  * multiple tests. In this cases, g_test_create_case() will be
- * called with the same fixture, but varying @test_name and
- * @data_test arguments.
+ * called with the same type of fixture (the @data_size argument), but varying
+ * @test_name and @data_test arguments.
  *
  * Returns: a newly allocated #GTestCase.
  * Since: 2.16
@@ -33583,6 +33633,10 @@
  * with the two arguments. The first one is the parameter to
  * g_thread_pool_push() and the second one is @user_data.
  *
+ * Pass g_get_num_processors() to @max_threads to create as many threads as
+ * there are logical processors on the system. This will not pin each thread to
+ * a specific processor.
+ *
  * The parameter @exclusive determines whether the thread pool owns
  * all threads exclusive or shares them with other thread pools.
  * If @exclusive is %TRUE, @max_threads threads are started
@@ -36111,16 +36165,20 @@
  * @params: a `%`-encoded string containing "attribute=value"
  *   parameters
  * @length: the length of @params, or -1 if it is NUL-terminated
- * @separator: the separator character between parameters.
- *   (usually ';', but sometimes '&')
- * @case_insensitive: whether parameter names are case insensitive
+ * @separators: the separator byte character set between parameters. (usually
+ *   "&", but sometimes ";" or both "&;"). Note that this function works on
+ *   bytes not characters, so it can't be used to delimit UTF-8 strings for
+ *   anything but ASCII characters. You may pass an empty set, in which case
+ *   no splitting will occur.
+ * @flags: flags to modify the way the parameters are handled.
+ * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Many URI schemes include one or more attribute/value pairs as part of the URI
  * value. This method can be used to parse them into a hash table.
  *
  * The @params string is assumed to still be `%`-encoded, but the returned
  * values will be fully decoded. (Thus it is possible that the returned values
- * may contain '=' or @separator, if the value was encoded in the input.)
+ * may contain '=' or @separators, if the value was encoded in the input.)
  * Invalid `%`-encoding is treated as with the non-%G_URI_FLAGS_PARSE_STRICT
  * rules for g_uri_parse(). (However, if @params is the path or query string
  * from a #GUri that was parsed with %G_URI_FLAGS_PARSE_STRICT and
@@ -36129,7 +36187,7 @@
  *
  * Returns: (transfer full) (element-type utf8 utf8): a hash table of
  * attribute/value pairs. Both names and values will be fully-decoded. If
- * @params cannot be parsed (eg, it contains two @separator characters in a
+ * @params cannot be parsed (eg, it contains two @separators characters in a
  * row), then %NULL is returned.
  * Since: 2.66
  */
@@ -36362,15 +36420,24 @@
  * @escaped_string: A URI-escaped string
  * @length: the length of @escaped_string to escape, or -1 if it
  *   is NUL-terminated.
+ * @illegal_characters: (nullable): a string of illegal characters
+ *   not to be allowed, or %NULL.
+ * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Unescapes a segment of an escaped string as binary data.
  *
  * Note that in contrast to g_uri_unescape_string(), this does allow
  * `NUL` bytes to appear in the output.
  *
- * Returns: (transfer full): an unescaped version of @escaped_string
- * or %NULL on error. The returned #GBytes should be unreffed when no
- * longer needed.
+ * If any of the characters in @illegal_characters or the NUL
+ * character appears as an escaped character in @escaped_string, then
+ * that is an error and %NULL will be returned. This is useful if you
+ * want to avoid for instance having a slash being expanded in an
+ * escaped path element, which might confuse pathname handling.
+ *
+ * Returns: (transfer full): an unescaped version of @escaped_string or %NULL on
+ * error (if decoding failed, using %G_URI_ERROR_MISC error code). The returned
+ * #GBytes should be unreffed when no longer needed.
  * Since: 2.66
  */
 
@@ -36391,6 +36458,9 @@
  * want to avoid for instance having a slash being expanded in an
  * escaped path element, which might confuse pathname handling.
  *
+ * Note: `NUL` byte is not accepted in the output, in contrast to
+ * g_uri_unescape_bytes().
+ *
  * Returns: an unescaped version of @escaped_string or %NULL on error.
  * The returned string should be freed when no longer needed.  As a
  * special case if %NULL is given for @escaped_string, this function
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index ef504701..56947b35 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -2970,7 +2970,9 @@
  * Creates a new instance of a #GObject subtype and sets its properties.
  *
  * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
- * which are not explicitly specified are set to their default values.
+ * which are not explicitly specified are set to their default values. Any
+ * private data for the object is guaranteed to be initialized with zeros, as
+ * per g_type_create_instance().
  *
  * Note that in C, small integer types in variable argument lists are promoted
  * up to #gint or #guint as appropriate, and read back accordingly. #gint is 32