gir: Update annotations from glib git master

3 files changed, 115 insertions, 36 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 2d4e7bac..64812d38 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -1649,7 +1649,7 @@
 
 
 /**
- * GDtlsConnection:advertised-protocols:
+ * GDtlsConnection:advertised-protocols: (nullable)
  *
  * The list of application-layer protocols that the connection
  * advertises that it is willing to speak. See
@@ -1680,7 +1680,7 @@
 
 
 /**
- * GDtlsConnection:database:
+ * GDtlsConnection:database: (nullable)
  *
  * The certificate database to use when verifying this TLS connection.
  * If no certificate database is set, then the default database will be
@@ -1691,7 +1691,7 @@
 
 
 /**
- * GDtlsConnection:interaction:
+ * GDtlsConnection:interaction: (nullable)
  *
  * A #GTlsInteraction object to be used when the connection or certificate
  * database need to interact with the user. This will be used to prompt the
@@ -1712,7 +1712,7 @@
 
 
 /**
- * GDtlsConnection:peer-certificate:
+ * GDtlsConnection:peer-certificate: (nullable)
  *
  * The connection's peer's certificate, after the TLS handshake has
  * completed and the certificate has been accepted. Note in
@@ -3791,7 +3791,7 @@
 
 
 /**
- * GTlsConnection:advertised-protocols:
+ * GTlsConnection:advertised-protocols: (nullable)
  *
  * The list of application-layer protocols that the connection
  * advertises that it is willing to speak. See
@@ -3825,7 +3825,7 @@
 
 
 /**
- * GTlsConnection:database:
+ * GTlsConnection:database: (nullable)
  *
  * The certificate database to use when verifying this TLS connection.
  * If no certificate database is set, then the default database will be
@@ -3836,7 +3836,7 @@
 
 
 /**
- * GTlsConnection:interaction:
+ * GTlsConnection:interaction: (nullable)
  *
  * A #GTlsInteraction object to be used when the connection or certificate
  * database need to interact with the user. This will be used to prompt the
@@ -3857,7 +3857,7 @@
 
 
 /**
- * GTlsConnection:peer-certificate:
+ * GTlsConnection:peer-certificate: (nullable)
  *
  * The connection's peer's certificate, after the TLS handshake has
  * completed and the certificate has been accepted. Note in
@@ -4736,7 +4736,7 @@
  * arguments are passed through platform communication to the already
  * running program. The already running instance of the program is
  * called the "primary instance"; for non-unique applications this is
- * the always the current instance. On Linux, the D-Bus session bus
+ * always the current instance. On Linux, the D-Bus session bus
  * is used for communication.
  *
  * The use of #GApplication differs from some other commonly-used
@@ -6919,6 +6919,13 @@
  * - Run a garbage collection cycle
  * - Try and compress fragmented allocations
  * - Exit on idle if the process has no reason to stay around
+ * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to
+ *   the kernel (if supported by your libc)
+ *
+ * Note that some actions may not always improve system performance, and so
+ * should be profiled for your application. `malloc_trim()`, for example, may
+ * make future heap allocations slower (due to releasing cached heap pages back
+ * to the kernel).
  *
  * See #GMemoryMonitorWarningLevel for details on the various warning levels.
  *
@@ -20396,7 +20403,7 @@
  * Gets @conn's certificate, as set by
  * g_dtls_connection_set_certificate().
  *
- * Returns: (transfer none): @conn's certificate, or %NULL
+ * Returns: (transfer none) (nullable): @conn's certificate, or %NULL
  * Since: 2.48
  */
 
@@ -20408,7 +20415,7 @@
  * Gets the certificate database that @conn uses to verify
  * peer certificates. See g_dtls_connection_set_database().
  *
- * Returns: (transfer none): the certificate database that @conn uses or %NULL
+ * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL
  * Since: 2.48
  */
 
@@ -20421,7 +20428,7 @@
  * for things like prompting the user for passwords. If %NULL is returned, then
  * no user interaction will occur for this connection.
  *
- * Returns: (transfer none): The interaction object.
+ * Returns: (transfer none) (nullable): The interaction object.
  * Since: 2.48
  */
 
@@ -20451,7 +20458,7 @@
  * (It is not set during the emission of
  * #GDtlsConnection::accept-certificate.)
  *
- * Returns: (transfer none): @conn's peer's certificate, or %NULL
+ * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
  * Since: 2.48
  */
 
@@ -20617,7 +20624,7 @@
 /**
  * g_dtls_connection_set_database:
  * @conn: a #GDtlsConnection
- * @database: a #GTlsDatabase
+ * @database: (nullable): a #GTlsDatabase
  *
  * Sets the certificate database that is used to verify peer certificates.
  * This is set to the default database by default. See
@@ -25372,7 +25379,7 @@
 
 /**
  * g_icon_deserialize:
- * @value: a #GVariant created with g_icon_serialize()
+ * @value: (transfer none): a #GVariant created with g_icon_serialize()
  *
  * Deserializes a #GIcon previously serialized using g_icon_serialize().
  *
@@ -25431,7 +25438,7 @@
  * makes sense to transfer the #GVariant between processes on the same machine,
  * (as opposed to over the network), and within the same file system namespace.
  *
- * Returns: (transfer full): a #GVariant, or %NULL when serialization fails.
+ * Returns: (transfer full): a #GVariant, or %NULL when serialization fails. The #GVariant will not be floating.
  * Since: 2.38
  */
 
@@ -25747,8 +25754,8 @@
  *
  * Parses @string as an IP address and creates a new #GInetAddress.
  *
- * Returns: a new #GInetAddress corresponding to @string, or %NULL if
- * @string could not be parsed.
+ * Returns: (nullable) (transfer full): a new #GInetAddress corresponding
+ * to @string, or %NULL if @string could not be parsed.
  *     Free the returned object with g_object_unref().
  * Since: 2.22
  */
@@ -25861,8 +25868,8 @@
  * If @address is an IPv6 address, it can also contain a scope ID
  * (separated from the address by a `%`).
  *
- * Returns: a new #GInetSocketAddress, or %NULL if @address cannot be
- * parsed.
+ * Returns: (nullable) (transfer full): a new #GInetSocketAddress,
+ * or %NULL if @address cannot be parsed.
  * Since: 2.40
  */
 
@@ -39321,7 +39328,7 @@
  * Gets @conn's certificate, as set by
  * g_tls_connection_set_certificate().
  *
- * Returns: (transfer none): @conn's certificate, or %NULL
+ * Returns: (transfer none) (nullable): @conn's certificate, or %NULL
  * Since: 2.28
  */
 
@@ -39333,7 +39340,7 @@
  * Gets the certificate database that @conn uses to verify
  * peer certificates. See g_tls_connection_set_database().
  *
- * Returns: (transfer none): the certificate database that @conn uses or %NULL
+ * Returns: (transfer none) (nullable): the certificate database that @conn uses or %NULL
  * Since: 2.30
  */
 
@@ -39346,7 +39353,7 @@
  * for things like prompting the user for passwords. If %NULL is returned, then
  * no user interaction will occur for this connection.
  *
- * Returns: (transfer none): The interaction object.
+ * Returns: (transfer none) (nullable): The interaction object.
  * Since: 2.30
  */
 
@@ -39376,7 +39383,7 @@
  * (It is not set during the emission of
  * #GTlsConnection::accept-certificate.)
  *
- * Returns: (transfer none): @conn's peer's certificate, or %NULL
+ * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
  * Since: 2.28
  */
 
@@ -39560,7 +39567,7 @@
 /**
  * g_tls_connection_set_database:
  * @conn: a #GTlsConnection
- * @database: a #GTlsDatabase
+ * @database: (nullable): a #GTlsDatabase
  *
  * Sets the certificate database that is used to verify peer certificates.
  * This is set to the default database by default. See
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 76876983..931caca0 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -4889,14 +4889,15 @@
  * To create a new array use g_array_new().
  *
  * To add elements to an array, use g_array_append_val(),
- * g_array_append_vals(), g_array_prepend_val(), and
- * g_array_prepend_vals().
+ * g_array_append_vals(), g_array_prepend_val(), g_array_prepend_vals(),
+ * g_array_insert_val() and g_array_insert_vals().
  *
- * To access an element of an array, use g_array_index().
+ * To access an element of an array (to read it or write it),
+ * use g_array_index().
  *
  * To set the size of an array, use g_array_set_size().
  *
- * To free an array, use g_array_free().
+ * To free an array, use g_array_unref() or g_array_free().
  *
  * Here is an example that stores integers in a #GArray:
  * |[<!-- language="C" -->
@@ -8633,9 +8634,23 @@
  * The implementations of the Unicode functions in GLib are based
  * on the Unicode Character Data tables, which are available from
  * [www.unicode.org](http://www.unicode.org/).
- * GLib 2.8 supports Unicode 4.0, GLib 2.10 supports Unicode 4.1,
- * GLib 2.12 supports Unicode 5.0, GLib 2.16.3 supports Unicode 5.1,
- * GLib 2.30 supports Unicode 6.0.
+ *
+ *  * Unicode 4.0 was added in GLib 2.8
+ *  * Unicode 4.1 was added in GLib 2.10
+ *  * Unicode 5.0 was added in GLib 2.12
+ *  * Unicode 5.1 was added in GLib 2.16.3
+ *  * Unicode 6.0 was added in GLib 2.30
+ *  * Unicode 6.1 was added in GLib 2.32
+ *  * Unicode 6.2 was added in GLib 2.36
+ *  * Unicode 6.3 was added in GLib 2.40
+ *  * Unicode 7.0 was added in GLib 2.42
+ *  * Unicode 8.0 was added in GLib 2.48
+ *  * Unicode 9.0 was added in GLib 2.50.1
+ *  * Unicode 10.0 was added in GLib 2.54
+ *  * Unicode 11.10 was added in GLib 2.58
+ *  * Unicode 12.0 was added in GLib 2.62
+ *  * Unicode 12.1 was added in GLib 2.62
+ *  * Unicode 13.0 was added in GLib 2.66
  */
 
 
@@ -8935,14 +8950,29 @@
  * @i: the index of the element to return
  *
  * Returns the element of a #GArray at the given index. The return
- * value is cast to the given type.
+ * value is cast to the given type. This is the main way to read or write an
+ * element in a #GArray.
  *
- * This example gets a pointer to an element in a #GArray:
+ * Writing an element is typically done by reference, as in the following
+ * example. This example gets a pointer to an element in a #GArray, and then
+ * writes to a field in it:
  * |[<!-- language="C" -->
  *   EDayViewEvent *event;
  *   // This gets a pointer to the 4th element in the array of
  *   // EDayViewEvent structs.
  *   event = &g_array_index (events, EDayViewEvent, 3);
+ *   event->start_time = g_get_current_time ();
+ * ]|
+ *
+ * This example reads from and writes to an array of integers:
+ * |[<!-- language="C" -->
+ *   g_autoptr(GArray) int_array = g_array_new (FALSE, FALSE, sizeof (guint));
+ *   for (guint i = 0; i < 10; i++)
+ *     g_array_append_val (int_array, i);
+ *
+ *   guint *my_int = &g_array_index (int_array, guint, 1);
+ *   g_print ("Int at index 1 is %u; decrementing it\n", *my_int);
+ *   *my_int = *my_int - 1;
  * ]|
  *
  * Returns: the element of the #GArray at the index given by @i
@@ -8979,6 +9009,10 @@
  * will be initialised to zero if the array was configured to clear elements;
  * otherwise their values will be undefined.
  *
+ * If @index_ is less than the array’s current length, new entries will be
+ * inserted into the array, and the existing entries above @index_ will be moved
+ * upwards.
+ *
  * @data may be %NULL if (and only if) @len is zero. If @len is zero, this
  * function is a no-op.
  *
@@ -36997,6 +37031,12 @@
  * The returned value is never floating.  You should free it with
  * g_variant_unref() when you're done with it.
  *
+ * Note that values borrowed from the returned child are not guaranteed to
+ * still be valid after the child is freed even if you still hold a reference
+ * to @value, if @value has not been serialised at the time this function is
+ * called. To avoid this, you can serialize @value by calling
+ * g_variant_get_data() and optionally ignoring the return value.
+ *
  * 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
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 9ea50c91..f773584b 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -419,8 +419,8 @@
  *
  * ## Parameter names # {#canonical-parameter-names}
  *
- * A property name consists of segments consisting of ASCII letters and
- * digits, separated by either the `-` or `_` character. The first
+ * A property name consists of one or more segments consisting of ASCII letters
+ * and digits, separated by either the `-` or `_` character. The first
  * character of a property name must be a letter. These are the same rules as
  * for signal naming (see g_signal_new()).
  *
@@ -3796,6 +3796,22 @@
 
 
 /**
+ * g_param_spec_is_valid_name:
+ * @name: the canonical name of the property
+ *
+ * Validate a property name for a #GParamSpec. This can be useful for
+ * dynamically-generated properties which need to be validated at run-time
+ * before actually trying to create them.
+ *
+ * See [canonical parameter names][canonical-parameter-names] for details of
+ * the rules for valid names.
+ *
+ * Returns: %TRUE if @name is a valid property name, %FALSE otherwise.
+ * Since: 2.66
+ */
+
+
+/**
  * g_param_spec_long:
  * @name: canonical name of the property specified
  * @nick: nick name for the property specified
@@ -4719,6 +4735,22 @@
 
 
 /**
+ * g_signal_is_valid_name:
+ * @name: the canonical name of the signal
+ *
+ * Validate a signal name. This can be useful for dynamically-generated signals
+ * which need to be validated at run-time before actually trying to create them.
+ *
+ * See [canonical parameter names][canonical-parameter-names] for details of
+ * the rules for valid names. The rules for signal names are the same as those
+ * for property names.
+ *
+ * Returns: %TRUE if @name is a valid signal name, %FALSE otherwise.
+ * Since: 2.66
+ */
+
+
+/**
  * g_signal_list_ids:
  * @itype: Instance or interface type.
  * @n_ids: Location to store the number of signal ids for @itype.