From 7996257738a821af4538c32b5d334350813f67e0 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Tue, 28 Apr 2020 07:38:45 +0200 Subject: gir: Update annotations from glib git master --- gir/gio-2.0.c | 57 ++++++++++++++++++++++++++++++------------------------ gir/glib-2.0.c | 58 ++++++++++++++++++++++++++++++++++++++++++++++--------- gir/gobject-2.0.c | 36 ++++++++++++++++++++++++++++++++-- 3 files changed, 115 insertions(+), 36 deletions(-) (limited to 'gir') 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: * |[ @@ -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: * |[ * 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: + * |[ + * 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()). * @@ -3795,6 +3795,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 @@ -4718,6 +4734,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. -- cgit v1.2.1