From b03e687287433c0fa57910d8f8e2ffa2d2e3fdc5 Mon Sep 17 00:00:00 2001 From: Christoph Reiter Date: Wed, 26 Dec 2018 21:48:13 +0100 Subject: Update glib annotations (glib-2-58) --- gir/gio-2.0.c | 24 ++++++++++++++++-------- gir/glib-2.0.c | 31 +++++++++++++++++++++++-------- gir/gobject-2.0.c | 2 +- 3 files changed, 40 insertions(+), 17 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index ce76cdb8..766c0cd1 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -14916,7 +14916,7 @@ * dispatched anywhere else - not even the standard dispatch machinery * (that API such as g_dbus_connection_signal_subscribe() and * g_dbus_connection_send_message_with_reply() relies on) will see the - * message. Similary, if a filter consumes an outgoing message, the + * message. Similarly, if a filter consumes an outgoing message, the * message will not be sent to the other peer. * * If @user_data_free_func is non-%NULL, it will be called (in the @@ -16798,7 +16798,7 @@ /** * g_dbus_message_bytes_needed: - * @blob: (array length=blob_len) (element-type guint8): A blob represent a binary D-Bus message. + * @blob: (array length=blob_len) (element-type guint8): A blob representing a binary D-Bus message. * @blob_len: The length of @blob (must be at least 16). * @error: Return location for error or %NULL. * @@ -16904,7 +16904,10 @@ * * Gets a header field on @message. * - * Returns: A #GVariant with the value if the header was found, %NULL + * The caller is responsible for checking the type of the returned #GVariant + * matches what is expected. + * + * Returns: (transfer none) (nullable): A #GVariant with the value if the header was found, %NULL * otherwise. Do not free, it is owned by @message. * Since: 2.26 */ @@ -17080,6 +17083,9 @@ * order that the message was in can be retrieved using * g_dbus_message_get_byte_order(). * + * If the @blob cannot be parsed, contains invalid fields, or contains invalid + * headers, %G_IO_ERROR_INVALID_ARGUMENT will be returned. + * * Returns: A new #GDBusMessage or %NULL if @error is set. Free with * g_object_unref(). * Since: 2.26 @@ -24907,8 +24913,8 @@ * native, the returned string is the result of g_file_get_uri() * (such as `sftp://path/to/my%20icon.png`). * - * - If @icon is a #GThemedIcon with exactly one name, the encoding is - * simply the name (such as `network-server`). + * - If @icon is a #GThemedIcon with exactly one name and no fallbacks, + * the encoding is simply the name (such as `network-server`). * * Returns: (nullable): An allocated NUL-terminated UTF8 string or * %NULL if @icon can't be serialized. Use g_free() to free. @@ -38394,8 +38400,10 @@ * the beginning of the communication, you do not need to call this * function explicitly unless you want clearer error reporting. * However, you may call g_tls_connection_handshake() later on to - * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, this will - * instead perform a rekey. + * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, the + * behavior is undefined but guaranteed to be reasonable and + * nondestructive, so most older code should be expected to continue to + * work without changes. * * #GTlsConnection::accept_certificate may be emitted during the * handshake. @@ -40809,7 +40817,7 @@ * also listen for the "removed" signal on the returned object * and give up its reference when handling that signal * - * Similary, if implementing g_volume_monitor_adopt_orphan_mount(), + * Similarly, if implementing g_volume_monitor_adopt_orphan_mount(), * the implementor must take a reference to @mount and return it in * its g_volume_get_mount() implemented. Also, the implementor must * listen for the "unmounted" signal on @mount and give up its diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index 66ab9a05..46149833 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -2108,7 +2108,9 @@ * * GLib is attempting to unify around the use of 64bit integers to * represent microsecond-precision time. As such, this type will be - * removed from a future version of GLib. + * removed from a future version of GLib. A consequence of using `glong` for + * `tv_sec` is that on 32-bit systems `GTimeVal` is subject to the year 2038 + * problem. */ @@ -6708,7 +6710,10 @@ * * The above definition is recursive to arbitrary depth. "aaaaai" and * "(ui(nq((y)))s)" are both valid type strings, as is - * "a(aa(ui)(qna{ya(yd)}))". + * "a(aa(ui)(qna{ya(yd)}))". In order to not hit memory limits, #GVariant + * imposes a limit on recursion depth of 65 nested containers. This is the + * limit in the D-Bus specification (64) plus one to allow a #GDBusMessage to + * be nested in a top-level tuple. * * The meaning of each of the characters is as follows: * - `b`: the type string of %G_VARIANT_TYPE_BOOLEAN; a boolean value. @@ -11729,8 +11734,8 @@ * @stamp: (out) (optional): return location for the last registration time, or %NULL * @error: return location for a #GError, or %NULL * - * Gets the registration informations of @app_name for the bookmark for - * @uri. See g_bookmark_file_set_app_info() for more informations about + * Gets the registration information of @app_name for the bookmark for + * @uri. See g_bookmark_file_set_app_info() for more information about * the returned data. * * The string returned in @app_exec must be freed. @@ -33031,10 +33036,12 @@ * variation of ISO 8601 format is required. * * If @time_ represents a date which is too large to fit into a `struct tm`, - * %NULL will be returned. This is platform dependent, but it is safe to assume - * years up to 3000 are supported. The return value of g_time_val_to_iso8601() - * has been nullable since GLib 2.54; before then, GLib would crash under the - * same conditions. + * %NULL will be returned. This is platform dependent. Note also that since + * `GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it + * is subject to the year 2038 problem. + * + * The return value of g_time_val_to_iso8601() has been nullable since GLib + * 2.54; before then, GLib would crash under the same conditions. * * Returns: (nullable): a newly allocated string containing an ISO 8601 date, * or %NULL if @time_ was too large @@ -36438,6 +36445,11 @@ * The returned value is never floating. You should free it with * g_variant_unref() when you're done with it. * + * 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 + * nesting up to at least 64 levels. + * * This function is O(1). * * Returns: (transfer full): the child at the specified index @@ -36923,6 +36935,9 @@ * being trusted. If the value was already marked as being trusted then * this function will immediately return %TRUE. * + * There may be implementation specific restrictions on deeply nested values. + * GVariant is guaranteed to handle nesting up to at least 64 levels. + * * Returns: %TRUE if @value is in normal form * Since: 2.24 */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 1a4f3bcb..89091e1b 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -6509,7 +6509,7 @@ * * Get the contents of a variant #GValue. * - * Returns: (nullable): variant contents of @value (may be %NULL) + * Returns: (transfer none) (nullable): variant contents of @value (may be %NULL) * Since: 2.26 */ -- cgit v1.2.1