summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRico Tzschichholz <ricotz@ubuntu.com>2020-04-28 07:38:45 +0200
committerRico Tzschichholz <ricotz@ubuntu.com>2020-05-02 09:53:03 +0200
commit7996257738a821af4538c32b5d334350813f67e0 (patch)
tree4577d7b9d632be943e6a99582206b39df2802a69
parentbb364bd25d50215b0c40d98ba5ecf2aa779e53a2 (diff)
downloadgobject-introspection-7996257738a821af4538c32b5d334350813f67e0.tar.gz
gir: Update annotations from glib git master
-rw-r--r--gir/gio-2.0.c57
-rw-r--r--gir/glib-2.0.c58
-rw-r--r--gir/gobject-2.0.c36
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.