gir: Update annotations from GLib git master

3 files changed, 263 insertions, 123 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index ecdb2cf2..365cd2a2 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -2366,13 +2366,9 @@
 /**
  * GNetworkMonitor::network-changed:
  * @monitor: a #GNetworkMonitor
- * @available: the current value of #GNetworkMonitor:network-available
+ * @network_available: the current value of #GNetworkMonitor:network-available
  *
- * Emitted when the network configuration changes. If @available is
- * %TRUE, then some hosts may be reachable that were not reachable
- * before, while others that were reachable before may no longer be
- * reachable. If @available is %FALSE, then no remote hosts are
- * reachable.
+ * Emitted when the network configuration changes.
  *
  * Since: 2.32
  */
@@ -3567,18 +3563,20 @@
 /**
  * GTlsClientConnection:use-ssl3:
  *
- * If %TRUE, tells the connection to use a fallback version of TLS
+ * If %TRUE, forces the connection to use a fallback version of TLS
  * or SSL, rather than trying to negotiate the best version of TLS
  * to use. This can be used when talking to servers that don't
  * implement version negotiation correctly and therefore refuse to
- * handshake at all with a "modern" TLS handshake.
+ * handshake at all with a modern TLS handshake.
  *
- * Despite the property name, the fallback version is not
- * necessarily SSL 3.0; if SSL 3.0 has been disabled, the
- * #GTlsClientConnection will use the next highest available version
- * (normally TLS 1.0) as the fallback version.
+ * Despite the property name, the fallback version is usually not
+ * SSL 3.0, because SSL 3.0 is generally disabled by the #GTlsBackend.
+ * #GTlsClientConnection will use the next-highest available version
+ * as the fallback version.
  *
  * Since: 2.28
+ * Deprecated: 2.56: SSL 3.0 is insecure, and this property does not
+ * generally enable or disable it, despite its name.
  */
 
 
@@ -5819,6 +5817,9 @@
  * 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).
+ *
+ * TCP D-Bus connections are supported, but accessing them via a proxy is
+ * currently not supported.
  */
 
 
@@ -6274,7 +6275,7 @@
  * both well-known and unique names.
  *
  * By default, #GDBusProxy will cache all properties (and listen to
- * changes) of the remote object, and proxy all signals that gets
+ * changes) of the remote object, and proxy all signals that get
  * emitted. This behaviour can be changed by passing suitable
  * #GDBusProxyFlags when the proxy is created. If the proxy is for a
  * well-known name, the property cache is flushed when the name owner
@@ -16044,6 +16045,8 @@
  *     before encountering any of the stop characters. Set @length to
  *     a #gsize to get the length of the string. This function will
  *     return %NULL on an error.
+ * Deprecated: 2.56: Use g_data_input_stream_read_upto() instead, which has more
+ *     consistent behaviour regarding the stop character.
  */
 
 
@@ -16073,6 +16076,8 @@
  * g_data_input_stream_read_upto_async() instead.
  *
  * Since: 2.20
+ * Deprecated: 2.56: Use g_data_input_stream_read_upto_async() instead, which
+ *     has more consistent behaviour regarding the stop character.
  */
 
 
@@ -16091,6 +16096,8 @@
  *     before encountering any of the stop characters. Set @length to
  *     a #gsize to get the length of the string. This function will
  *     return %NULL on an error.
+ * Deprecated: 2.56: Use g_data_input_stream_read_upto_finish() instead, which
+ *     has more consistent behaviour regarding the stop character.
  */
 
 
@@ -16826,7 +16833,8 @@
  * @method_name: the name of the method to invoke
  * @parameters: (nullable): a #GVariant tuple with parameters for the method
  *     or %NULL if not passing parameters
- * @reply_type: (nullable): the expected type of the reply, or %NULL
+ * @reply_type: (nullable): the expected type of the reply (which will be a
+ *     tuple), or %NULL
  * @flags: flags from the #GDBusCallFlags enumeration
  * @timeout_msec: the timeout in milliseconds, -1 to use the default
  *     timeout or %G_MAXINT for no timeout
@@ -16848,7 +16856,9 @@
  *
  * If @reply_type is non-%NULL then the reply will be checked for having this type and an
  * error will be raised if it does not match.  Said another way, if you give a @reply_type
- * then any non-%NULL return value will be of this type.
+ * then any non-%NULL return value will be of this type. Unless it’s
+ * %G_VARIANT_TYPE_UNIT, the @reply_type will be a tuple containing one or more
+ * values.
  *
  * If the @parameters #GVariant is floating, it is consumed. This allows
  * convenient 'inline' use of g_variant_new(), e.g.:
@@ -18417,7 +18427,7 @@
  *
  * For example, an exported D-Bus interface may queue up property
  * changes and emit the
- * `org.freedesktop.DBus.Properties::PropertiesChanged`
+ * `org.freedesktop.DBus.Properties.PropertiesChanged`
  * signal later (e.g. in an idle handler). This technique is useful
  * for collapsing multiple property changes into one.
  *
@@ -19602,7 +19612,7 @@
  *   g_dbus_method_invocation_return_value (invocation,
  *                                          g_variant_new ("(s)", result_string));
  *
- * /<!-- -->* Do not free @invocation here; returning a value does that *<!-- -->/
+ * // Do not free @invocation here; returning a value does that
  * ]|
  *
  * This method will take ownership of @invocation. See
@@ -20427,9 +20437,9 @@
  * #GDBusProxy:g-interface-info) and @property_name is referenced by
  * it, then @value is checked against the type of the property.
  *
- * Returns: A reference to the #GVariant instance that holds the value
- * for @property_name or %NULL if the value is not in the cache. The
- * returned reference must be freed with g_variant_unref().
+ * Returns: (transfer full) (nullable): A reference to the #GVariant instance
+ *    that holds the value for @property_name or %NULL if the value is not in
+ *    the cache. The returned reference must be freed with g_variant_unref().
  * Since: 2.26
  */
 
@@ -20440,7 +20450,8 @@
  *
  * Gets the names of all cached properties on @proxy.
  *
- * Returns: (transfer full): A %NULL-terminated array of strings or %NULL if
+ * Returns: (transfer full) (nullable) (array zero-terminated=1): A
+ *          %NULL-terminated array of strings or %NULL if
  *          @proxy has no cached properties. Free the returned array with
  *          g_strfreev().
  * Since: 2.26
@@ -20492,8 +20503,8 @@
  * that @proxy conforms to. See the #GDBusProxy:g-interface-info
  * property for more details.
  *
- * Returns: A #GDBusInterfaceInfo or %NULL. Do not unref the returned
- * object, it is owned by @proxy.
+ * Returns: (transfer none) (nullable): A #GDBusInterfaceInfo or %NULL.
+ *    Do not unref the returned object, it is owned by @proxy.
  * Since: 2.26
  */
 
@@ -20529,7 +20540,8 @@
  * #GObject::notify signal to track changes to the
  * #GDBusProxy:g-name-owner property.
  *
- * Returns: The name owner or %NULL if no name owner exists. Free with g_free().
+ * Returns: (transfer full) (nullable): The name owner or %NULL if no name
+ *    owner exists. Free with g_free().
  * Since: 2.26
  */
 
@@ -20592,7 +20604,8 @@
  *
  * Finishes creating a #GDBusProxy.
  *
- * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set.
+ *    Free with g_object_unref().
  * Since: 2.26
  */
 
@@ -20624,7 +20637,8 @@
  *
  * Finishes creating a #GDBusProxy.
  *
- * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if @error is set.
+ *    Free with g_object_unref().
  * Since: 2.26
  */
 
@@ -20645,7 +20659,8 @@
  *
  * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
  *
- * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if error is set.
+ *    Free with g_object_unref().
  * Since: 2.26
  */
 
@@ -20680,7 +20695,8 @@
  *
  * #GDBusProxy is used in this [example][gdbus-wellknown-proxy].
  *
- * Returns: A #GDBusProxy or %NULL if error is set. Free with g_object_unref().
+ * Returns: (transfer full): A #GDBusProxy or %NULL if error is set.
+ *    Free with g_object_unref().
  * Since: 2.26
  */
 
@@ -20747,7 +20763,8 @@
 /**
  * g_dbus_proxy_set_interface_info:
  * @proxy: A #GDBusProxy
- * @info: (nullable): Minimum interface this proxy conforms to or %NULL to unset.
+ * @info: (transfer none) (nullable): Minimum interface this proxy conforms to
+ *    or %NULL to unset.
  *
  * Ensure that interactions with @proxy conform to the given
  * interface. See the #GDBusProxy:g-interface-info property for more
@@ -25345,6 +25362,24 @@
 
 
 /**
+ * g_file_peek_path:
+ * @file: input #GFile
+ *
+ * Exactly like g_file_get_path(), but caches the result via
+ * g_object_set_qdata_full().  This is useful for example in C
+ * applications which mix `g_file_*` APIs with native ones.  It
+ * also avoids an extra duplicated string when possible, so will be
+ * generally more efficient.
+ *
+ * This call does no blocking I/O.
+ *
+ * Returns: (type filename) (nullable): string containing the #GFile's path,
+ *     or %NULL if no such path exists. The returned string is owned by @file.
+ * Since: 2.56
+ */
+
+
+/**
  * g_file_poll_mountable:
  * @file: input #GFile
  * @cancellable: optional #GCancellable object, %NULL to ignore
@@ -25411,7 +25446,7 @@
  * Utility function to check if a particular file exists. This is
  * implemented using g_file_query_info() and as such does blocking I/O.
  *
- * Note that in many cases it is racy to first check for file existence
+ * Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use)
  * and then execute something based on the outcome of that, because the
  * file might have been created or removed in between the operations. The
  * general approach to handling that is to not check, but just do the
@@ -30911,6 +30946,8 @@
  * Deprecated in favor of g_notification_set_priority().
  *
  * Since: 2.40
+ * Deprecated: 2.42: Since 2.42, this has been deprecated in favour of
+ *    g_notification_set_priority().
  */
 
 
@@ -31798,6 +31835,9 @@
  * may happen if you call this method after a source triggers due
  * to having been cancelled.
  *
+ * Also note that if %G_IO_ERROR_WOULD_BLOCK is returned some underlying
+ * transports like D/TLS require that you send the same @buffer and @count.
+ *
  * Returns: the number of bytes written, or -1 on error (including
  *   %G_IO_ERROR_WOULD_BLOCK).
  */
@@ -33688,7 +33728,7 @@
 /**
  * g_settings_list_relocatable_schemas:
  *
- * <!-- -->
+ * Deprecated.
  *
  * Returns: (element-type utf8) (transfer none): a list of relocatable
  *   #GSettings schemas that are available.  The list must not be
@@ -33701,7 +33741,7 @@
 /**
  * g_settings_list_schemas:
  *
- * <!-- -->
+ * Deprecated.
  *
  * Returns: (element-type utf8) (transfer none): a list of #GSettings
  *   schemas that are available.  The list must not be modified or
@@ -39853,12 +39893,14 @@
  * g_tls_client_connection_get_use_ssl3:
  * @conn: the #GTlsClientConnection
  *
- * Gets whether @conn will use SSL 3.0 rather than the
- * highest-supported version of TLS; see
- * g_tls_client_connection_set_use_ssl3().
+ * Gets whether @conn will force the lowest-supported TLS protocol
+ * version rather than attempt to negotiate the highest mutually-
+ * supported version of TLS; see g_tls_client_connection_set_use_ssl3().
  *
- * Returns: whether @conn will use SSL 3.0
+ * Returns: whether @conn will use the lowest-supported TLS protocol version
  * Since: 2.28
+ * Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+ * actually indicate whether it is enabled.
  */
 
 
@@ -39910,15 +39952,20 @@
 /**
  * g_tls_client_connection_set_use_ssl3:
  * @conn: the #GTlsClientConnection
- * @use_ssl3: whether to use SSL 3.0
+ * @use_ssl3: whether to use the lowest-supported protocol version
+ *
+ * If @use_ssl3 is %TRUE, this forces @conn to use the lowest-supported
+ * TLS protocol version rather than trying to properly negotiate the
+ * highest mutually-supported protocol version with the peer. This can
+ * be used when talking to broken TLS servers that exhibit protocol
+ * version intolerance.
  *
- * If @use_ssl3 is %TRUE, this forces @conn to use SSL 3.0 rather than
- * trying to properly negotiate the right version of TLS or SSL to use.
- * This can be used when talking to servers that do not implement the
- * fallbacks correctly and which will therefore fail to handshake with
- * a "modern" TLS handshake attempt.
+ * Be aware that SSL 3.0 is generally disabled by the #GTlsBackend, so
+ * the lowest-supported protocol version is probably not SSL 3.0.
  *
  * Since: 2.28
+ * Deprecated: 2.56: SSL 3.0 is insecure, and this function does not
+ * generally enable or disable it, despite its name.
  */
 
 
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 854cee12..01f1c051 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -593,7 +593,7 @@
  * g_direct_hash() is also the appropriate hash function for keys
  * of the form `GINT_TO_POINTER (n)` (or similar macros).
  *
- * <!-- FIXME: Need more here. --> A good hash functions should produce
+ * A good hash functions should produce
  * hash values that are evenly distributed over a fairly large range.
  * The modulus is taken with the hash table size (a prime number) to
  * find the 'bucket' to place each key into. The function should also
@@ -5443,7 +5443,7 @@
  * in it ("/"). However, displaying file names may require conversion:
  * from the character set in which they were created, to the character
  * set in which the application operates. Consider the Spanish file name
- * "Presentaci&oacute;n.sxi". If the application which created it uses
+ * "Presentación.sxi". If the application which created it uses
  * ISO-8859-1 for its encoding,
  * |[
  * Character:  P  r  e  s  e  n  t  a  c  i  ó  n  .  s  x  i
@@ -5456,31 +5456,31 @@
  * Hex code:   50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
  * ]|
  * Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
- * Glib do the same thing. If you get a file name from the file system,
+ * GLib do the same thing. If you get a file name from the file system,
  * for example, from readdir() or from g_dir_read_name(), and you wish
  * to display the file name to the user, you  will need to convert it
  * into UTF-8. The opposite case is when the user types the name of a
- * file he wishes to save: the toolkit will give you that string in
+ * file they wish to save: the toolkit will give you that string in
  * UTF-8 encoding, and you will need to convert it to the character
  * set used for file names before you can create the file with open()
  * or fopen().
  *
- * By default, Glib assumes that file names on disk are in UTF-8
+ * By default, GLib assumes that file names on disk are in UTF-8
  * encoding. This is a valid assumption for file systems which
  * were created relatively recently: most applications use UTF-8
  * encoding for their strings, and that is also what they use for
  * the file names they create. However, older file systems may
  * still contain file names created in "older" encodings, such as
  * ISO-8859-1. In this case, for compatibility reasons, you may want
- * to instruct Glib to use that particular encoding for file names
+ * to instruct GLib to use that particular encoding for file names
  * rather than UTF-8. You can do this by specifying the encoding for
  * file names in the [`G_FILENAME_ENCODING`][G_FILENAME_ENCODING]
  * environment variable. For example, if your installation uses
- * ISO-8859-1 for file names, you can put this in your `~/.profile`
+ * ISO-8859-1 for file names, you can put this in your `~/.profile`:
  * |[
  * export G_FILENAME_ENCODING=ISO-8859-1
  * ]|
- * Glib provides the functions g_filename_to_utf8() and
+ * GLib provides the functions g_filename_to_utf8() and
  * g_filename_from_utf8() to perform the necessary conversions.
  * These functions convert file names from the encoding specified
  * in `G_FILENAME_ENCODING` to UTF-8 and vice-versa. This
@@ -7235,8 +7235,13 @@
  *
  * These functions provide support for allocating and freeing memory.
  *
- * If any call to allocate memory fails, the application is terminated.
- * This also means that there is no need to check if the call succeeded.
+ * If any call to allocate memory using functions g_new(), g_new0(), g_renew(),
+ * g_malloc(), g_malloc0(), g_malloc0_n(), g_realloc(), and g_realloc_n()
+ * fails, the application is terminated. This also means that there is no
+ * need to check if the call succeeded. On the other hand, g_try_...() family
+ * of functions returns %NULL on failure that can be used as a check
+ * for unsuccessful memory allocation. The application is not terminated
+ * in this case.
  *
  * It's important to match g_malloc() (and wrappers such as g_new()) with
  * g_free(), g_slice_alloc() (and wrappers such as g_slice_new()) with
@@ -7836,6 +7841,12 @@
  * g_sequence_move_range() will not invalidate the iterators pointing
  * to it. The only operation that will invalidate an iterator is when
  * the element it points to is removed from any sequence.
+ *
+ * To sort the data, either use g_sequence_insert_sorted() or
+ * g_sequence_insert_sorted_iter() to add data to the #GSequence or, if
+ * you want to add a large amount of data, it is more efficient to call
+ * g_sequence_sort() or g_sequence_sort_iter() after doing unsorted
+ * insertions.
  */
 
 
@@ -10606,9 +10617,9 @@
  *
  *   membuf = g_malloc (8192);
  *
- *   /<!-- -->* Some computation on membuf *<!-- -->/
+ *   // Some computation on membuf
  *
- *   /<!-- -->* membuf will be automatically freed here *<!-- -->/
+ *   // membuf will be automatically freed here
  *   return TRUE;
  * }
  * ]|
@@ -12096,6 +12107,12 @@
  * A reference to @bytes will be held by the newly created #GBytes until
  * the byte data is no longer needed.
  *
+ * Since 2.56, if @offset is 0 and @length matches the size of @bytes, then
+ * @bytes will be returned with the reference count incremented by 1. If @bytes
+ * is a slice of another #GBytes, then the resulting #GBytes will reference
+ * the same #GBytes instead of @bytes. This allows consumers to simplify the
+ * usage of #GBytes when asynchronously writing to streams.
+ *
  * Returns: (transfer full): a new #GBytes
  * Since: 2.32
  */
@@ -12813,30 +12830,31 @@
 
 /**
  * g_convert:
- * @str: the string to convert
+ * @str: (array length=len) (element-type guint8):
+ *                 the string to convert.
  * @len: the length of the string in bytes, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
  *                 bytes to occur inside strings. In that case, using -1
  *                 for the @len parameter is unsafe)
  * @to_codeset: name of character set into which to convert @str
  * @from_codeset: character set of @str.
- * @bytes_read: (out): location to store the number of bytes in the
- *                 input string that were successfully converted, or %NULL.
+ * @bytes_read: (out) (optional): location to store the number of bytes in
+ *                 the input string that were successfully converted, or %NULL.
  *                 Even if the conversion was successful, this may be
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
- * @bytes_written: (out): the number of bytes stored in the output buffer (not
- *                 including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ *                 the output buffer (not including the terminating nul).
  * @error: location to store the error occurring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  *
  * Converts a string from one character set to another.
  *
  * Note that you should use g_iconv() for streaming conversions.
- * Despite the fact that @byes_read can return information about partial
+ * Despite the fact that @bytes_read can return information about partial
  * characters, the g_convert_... functions are not generally suitable
  * for streaming. If the underlying converter maintains internal state,
  * then this won't be preserved across successive calls to g_convert(),
@@ -12848,33 +12866,35 @@
  * Using extensions such as "//TRANSLIT" may not work (or may not work
  * well) on many platforms.  Consider using g_str_to_ascii() instead.
  *
- * Returns: If the conversion was successful, a newly allocated
- *               nul-terminated string, which must be freed with
- *               g_free(). Otherwise %NULL and @error will be set.
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ *          If the conversion was successful, a newly allocated buffer
+ *          containing the converted string, which must be freed with g_free().
+ *          Otherwise %NULL and @error will be set.
  */
 
 
 /**
  * g_convert_with_fallback:
- * @str: the string to convert
+ * @str: (array length=len) (element-type guint8):
+ *                the string to convert.
  * @len: the length of the string in bytes, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
  *                 bytes to occur inside strings. In that case, using -1
  *                 for the @len parameter is unsafe)
  * @to_codeset: name of character set into which to convert @str
  * @from_codeset: character set of @str.
- * @fallback: UTF-8 string to use in place of character not
+ * @fallback: UTF-8 string to use in place of characters not
  *                present in the target encoding. (The string must be
  *                representable in the target encoding).
  *                If %NULL, characters not in the target encoding will
  *                be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
- * @bytes_read: location to store the number of bytes in the
- *                input string that were successfully converted, or %NULL.
+ * @bytes_read: (out) (optional): location to store the number of bytes in
+ *                the input string that were successfully converted, or %NULL.
  *                Even if the conversion was successful, this may be
  *                less than @len if there were partial characters
  *                at the end of the input.
- * @bytes_written: the number of bytes stored in the output buffer (not
- *                including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ *                 the output buffer (not including the terminating nul).
  * @error: location to store the error occurring, or %NULL to ignore
  *                errors. Any of the errors in #GConvertError may occur.
  *
@@ -12887,7 +12907,7 @@
  * in which case GLib will simply return that approximate conversion.
  *
  * Note that you should use g_iconv() for streaming conversions.
- * Despite the fact that @byes_read can return information about partial
+ * Despite the fact that @bytes_read can return information about partial
  * characters, the g_convert_... functions are not generally suitable
  * for streaming. If the underlying converter maintains internal state,
  * then this won't be preserved across successive calls to g_convert(),
@@ -12896,37 +12916,39 @@
  * character until it knows that the next character is not a mark that
  * could combine with the base character.)
  *
- * Returns: If the conversion was successful, a newly allocated
- *               nul-terminated string, which must be freed with
- *               g_free(). Otherwise %NULL and @error will be set.
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ *          If the conversion was successful, a newly allocated buffer
+ *          containing the converted string, which must be freed with g_free().
+ *          Otherwise %NULL and @error will be set.
  */
 
 
 /**
  * g_convert_with_iconv: (skip)
- * @str: the string to convert
+ * @str: (array length=len) (element-type guint8):
+ *                 the string to convert.
  * @len: the length of the string in bytes, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
  *                 bytes to occur inside strings. In that case, using -1
  *                 for the @len parameter is unsafe)
  * @converter: conversion descriptor from g_iconv_open()
- * @bytes_read: location to store the number of bytes in the
- *                 input string that were successfully converted, or %NULL.
+ * @bytes_read: (out) (optional): location to store the number of bytes in
+ *                 the input string that were successfully converted, or %NULL.
  *                 Even if the conversion was successful, this may be
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
  *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
- * @bytes_written: the number of bytes stored in the output buffer (not
- *                 including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ *                 the output buffer (not including the terminating nul).
  * @error: location to store the error occurring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  *
  * Converts a string from one character set to another.
  *
  * Note that you should use g_iconv() for streaming conversions.
- * Despite the fact that @byes_read can return information about partial
+ * Despite the fact that @bytes_read can return information about partial
  * characters, the g_convert_... functions are not generally suitable
  * for streaming. If the underlying converter maintains internal state,
  * then this won't be preserved across successive calls to g_convert(),
@@ -12935,8 +12957,17 @@
  * character until it knows that the next character is not a mark that
  * could combine with the base character.)
  *
- * Returns: If the conversion was successful, a newly allocated
- *               nul-terminated string, which must be freed with
+ * Characters which are valid in the input character set, but which have no
+ * representation in the output character set will result in a
+ * %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error. This is in contrast to the iconv()
+ * specification, which leaves this behaviour implementation defined. Note that
+ * this is the same error code as is returned for an invalid byte sequence in
+ * the input character set. To get defined behaviour for conversion of
+ * unrepresentable characters, use g_convert_with_fallback().
+ *
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ *               If the conversion was successful, a newly allocated buffer
+ *               containing the converted string, which must be freed with
  *               g_free(). Otherwise %NULL and @error will be set.
  */
 
@@ -13144,7 +13175,7 @@
  *
  * If the previous value was replaced then ownership of the
  * old value (@oldval) is passed to the caller, including
- * the registred destroy notify for it (passed out in @old_destroy).
+ * the registered destroy notify for it (passed out in @old_destroy).
  * Its up to the caller to free this as he wishes, which may
  * or may not include using @old_destroy as sometimes replacement
  * should not destroy the object in the normal way.
@@ -15668,7 +15699,7 @@
 
 /**
  * g_filename_from_utf8:
- * @utf8string: a UTF-8 encoded string.
+ * @utf8string: (type utf8): a UTF-8 encoded string.
  * @len: the length of the string, or -1 if the string is
  *                 nul-terminated.
  * @bytes_read: (out) (optional): location to store the number of bytes in
@@ -15676,11 +15707,11 @@
  *                 Even if the conversion was successful, this may be
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
- *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ *                 %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
- * @bytes_written: (out): the number of bytes stored in the output buffer (not
- *                 including the terminating nul).
+ * @bytes_written: (out) (optional): the number of bytes stored in
+ *                 the output buffer (not including the terminating nul).
  * @error: location to store the error occurring, or %NULL to ignore
  *                 errors. Any of the errors in #GConvertError may occur.
  *
@@ -15689,7 +15720,13 @@
  * on other platforms, this function indirectly depends on the
  * [current locale][setlocale].
  *
- * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ * The input string shall not contain nul characters even if the @len
+ * argument is positive. A nul character found inside the string will result
+ * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. If the filename encoding is
+ * not UTF-8 and the conversion output contains a nul character, the error
+ * %G_CONVERT_ERROR_EMBEDDED_NUL is set and the function returns %NULL.
+ *
+ * Returns: (type filename):
  *               The converted string, or %NULL on an error.
  */
 
@@ -15723,7 +15760,7 @@
  *                 Even if the conversion was successful, this may be
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
- *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ *                 %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: (out) (optional): the number of bytes stored in the output
@@ -15736,7 +15773,15 @@
  * for filenames; on other platforms, this function indirectly depends on
  * the [current locale][setlocale].
  *
- * Returns: The converted string, or %NULL on an error.
+ * The input string shall not contain nul characters even if the @len
+ * argument is positive. A nul character found inside the string will result
+ * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE.
+ * If the source encoding is not UTF-8 and the conversion output contains a
+ * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+ * function returns %NULL. Use g_convert() to produce output that
+ * may contain embedded nul characters.
+ *
+ * Returns: (type utf8): The converted string, or %NULL on an error.
  */
 
 
@@ -15929,6 +15974,10 @@
  * handle file names. It might be different from the character set
  * used by the C library's current locale.
  *
+ * On Linux, the character set is found by consulting nl_langinfo() if
+ * available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG`
+ * and `CHARSET` are queried in order.
+ *
  * The return value is %TRUE if the locale's encoding is UTF-8, in that
  * case you can perhaps avoid calling g_convert().
  *
@@ -15999,7 +16048,8 @@
 
 /**
  * g_get_filename_charsets:
- * @charsets: return location for the %NULL-terminated list of encoding names
+ * @filename_charsets: (out) (transfer none) (array zero-terminated=1):
+ *    return location for the %NULL-terminated list of encoding names
  *
  * Determines the preferred character sets used for filenames.
  * The first character set from the @charsets is the filename encoding, the
@@ -17492,6 +17542,13 @@
  * GLib provides g_convert() and g_locale_to_utf8() which are likely
  * more convenient than the raw iconv wrappers.
  *
+ * Note that the behaviour of iconv() for characters which are valid in the
+ * input character set, but which have no representation in the output character
+ * set, is implementation defined. This function may return success (with a
+ * positive number of non-reversible conversions as replacement characters were
+ * used), or it may return -1 and set an error such as %EILSEQ, in such a
+ * situation.
+ *
  * Returns: count of non-reversible conversions, or -1 on error
  */
 
@@ -18603,6 +18660,29 @@
 
 
 /**
+ * g_key_file_get_locale_for_key:
+ * @key_file: a #GKeyFile
+ * @group_name: a group name
+ * @key: a key
+ * @locale: (nullable): a locale identifier or %NULL
+ *
+ * Returns the actual locale which the result of
+ * g_key_file_get_locale_string() or g_key_file_get_locale_string_list()
+ * came from.
+ *
+ * If calling g_key_file_get_locale_string() or
+ * g_key_file_get_locale_string_list() with exactly the same @key_file,
+ * @group_name, @key and @locale, the result of those functions will
+ * have originally been tagged with the locale that is the result of
+ * this function.
+ *
+ * Returns: (nullable): the locale from the file, or %NULL if the key was not
+ *   found or the entry in the file was was untranslated
+ * Since: 2.56
+ */
+
+
+/**
  * g_key_file_get_locale_string:
  * @key_file: a #GKeyFile
  * @group_name: a group name
@@ -19788,15 +19868,13 @@
  * g_locale_from_utf8:
  * @utf8string: a UTF-8 encoded string
  * @len: the length of the string, or -1 if the string is
- *                 nul-terminated (Note that some encodings may allow nul
- *                 bytes to occur inside strings. In that case, using -1
- *                 for the @len parameter is unsafe)
+ *                 nul-terminated.
  * @bytes_read: (out) (optional): location to store the number of bytes in the
  *                 input string that were successfully converted, or %NULL.
  *                 Even if the conversion was successful, this may be
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
- *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ *                 %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: (out) (optional): the number of bytes stored in the output
@@ -19809,14 +19887,21 @@
  * system) in the [current locale][setlocale]. On Windows this means
  * the system codepage.
  *
- * Returns: A newly-allocated buffer containing the converted string,
- *               or %NULL on an error, and error will be set.
+ * The input string shall not contain nul characters even if the @len
+ * argument is positive. A nul character found inside the string will result
+ * in error %G_CONVERT_ERROR_ILLEGAL_SEQUENCE. Use g_convert() to convert
+ * input that may contain embedded nul characters.
+ *
+ * Returns: (array length=bytes_written) (element-type guint8) (transfer full):
+ *          A newly-allocated buffer containing the converted string,
+ *          or %NULL on an error, and error will be set.
  */
 
 
 /**
  * g_locale_to_utf8:
- * @opsysstring: a string in the encoding of the current locale. On Windows
+ * @opsysstring: (array length=len) (element-type guint8): a string in the
+ *                 encoding of the current locale. On Windows
  *                 this means the system codepage.
  * @len: the length of the string, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
@@ -19827,7 +19912,7 @@
  *                 Even if the conversion was successful, this may be
  *                 less than @len if there were partial characters
  *                 at the end of the input. If the error
- *                 #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
+ *                 %G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
  *                 stored will the byte offset after the last valid
  *                 input sequence.
  * @bytes_written: (out) (optional): the number of bytes stored in the output
@@ -19839,8 +19924,15 @@
  * the C runtime (usually the same as that used by the operating
  * system) in the [current locale][setlocale] into a UTF-8 string.
  *
- * Returns: A newly-allocated buffer containing the converted string,
- *               or %NULL on an error, and error will be set.
+ * If the source encoding is not UTF-8 and the conversion output contains a
+ * nul character, the error %G_CONVERT_ERROR_EMBEDDED_NUL is set and the
+ * function returns %NULL.
+ * If the source encoding is UTF-8, an embedded nul character is treated with
+ * the %G_CONVERT_ERROR_ILLEGAL_SEQUENCE error for backward compatibility with
+ * earlier versions of this library. Use g_convert() to produce output that
+ * may contain embedded nul characters.
+ *
+ * Returns: (type utf8): The converted string, or %NULL on an error.
  */
 
 
@@ -26324,6 +26416,10 @@
  * if the first item comes before the second, and a positive value
  * if the second  item comes before the first.
  *
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then call
+ * g_sequence_sort() or g_sequence_sort_iter().
+ *
  * Returns: (transfer none): a #GSequenceIter pointing to the new item.
  * Since: 2.14
  */
@@ -26350,6 +26446,10 @@
  * first iterator comes before the second, and a positive value
  * if the second iterator comes before the first.
  *
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then call
+ * g_sequence_sort() or g_sequence_sort_iter().
+ *
  * Returns: (transfer none): a #GSequenceIter pointing to the new item
  * Since: 2.14
  */
@@ -26490,10 +26590,7 @@
  * the second item comes before the first.
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of the
  *     first item found equal to @data according to @cmp_func and
@@ -26518,10 +26615,7 @@
  * value if the second iterator comes before the first.
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of
  *     the first item found equal to @data according to @cmp_func
@@ -26654,10 +26748,7 @@
  * consider using g_sequence_lookup().
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none): an #GSequenceIter pointing to the position where @data
  *     would have been inserted according to @cmp_func and @cmp_data
@@ -26684,10 +26775,7 @@
  * consider using g_sequence_lookup_iter().
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none): a #GSequenceIter pointing to the position in @seq
  *     where @data would have been inserted according to @iter_cmp
@@ -28506,7 +28594,7 @@
  * standard error. If you use this flag, @standard_error must be %NULL.
  * %G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's
  * standard input (by default, the child's standard input is attached to
- * /dev/null). If you use this flag, @standard_input must be %NULL.
+ * `/dev/null`). If you use this flag, @standard_input must be %NULL.
  * %G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is
  * the file to execute, while the remaining elements are the actual
  * argument vector to pass to the file. Normally g_spawn_async_with_pipes()
@@ -28543,8 +28631,8 @@
  * when they are no longer in use. If these parameters are %NULL, the
  * corresponding pipe won't be created.
  *
- * If @standard_input is NULL, the child's standard input is attached to
- * /dev/null unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
+ * If @standard_input is %NULL, the child's standard input is attached to
+ * `/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set.
  *
  * If @standard_error is NULL, the child's standard error goes to the same
  * location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL
@@ -34069,6 +34157,9 @@
  * must be valid UTF-8 encoded text. (Use g_utf8_validate() on all
  * text before trying to use UTF-8 utility functions with it.)
  *
+ * Note you must ensure @dest is at least 4 * @n to fit the
+ * largest possible UTF-8 characters
+ *
  * Returns: @dest
  */
 
@@ -36039,7 +36130,7 @@
  * GVariant *new_variant;
  *
  * new_variant = g_variant_new ("(t^as)",
- *                              /<!-- -->* This cast is required. *<!-- -->/
+ *                              // This cast is required.
  *                              (guint64) some_flags,
  *                              some_strings);
  * ]|
@@ -38090,7 +38181,9 @@
  * goffset:
  *
  * A signed integer type that is used for file offsets,
- * corresponding to the C99 type off64_t.
+ * corresponding to the POSIX type `off_t` as if compiling with
+ * `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on
+ * 32-bit architectures.
  * Values of this type can range from #G_MINOFFSET to
  * #G_MAXOFFSET.
  *
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index f52cc7ca..b0688076 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -3202,7 +3202,7 @@
  * If the previous value was replaced then ownership of the
  * old value (@oldval) is passed to the caller, including
  * the registered destroy notify for it (passed out in @old_destroy).
- * Its up to the caller to free this as he wishes, which may
+ * It’s up to the caller to free this as needed, which may
  * or may not include using @old_destroy as sometimes replacement
  * should not destroy the object in the normal way.
  *
@@ -3231,7 +3231,7 @@
  * If the previous value was replaced then ownership of the
  * old value (@oldval) is passed to the caller, including
  * the registered destroy notify for it (passed out in @old_destroy).
- * Its up to the caller to free this as he wishes, which may
+ * It’s up to the caller to free this as needed, which may
  * or may not include using @old_destroy as sometimes replacement
  * should not destroy the object in the normal way.
  *