From 8964b1bab05ecfbd47f2185476ef48c86a6b76c9 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Mon, 10 Apr 2017 08:58:21 +0200 Subject: gir: Update annotations from GLib 2.52.1 --- gir/gio-2.0.c | 34 ++++++++++++++++++++++++++++------ gir/glib-2.0.c | 19 +++++++++++++++---- gir/gmodule-2.0.c | 12 +++++++++--- 3 files changed, 52 insertions(+), 13 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 105a47c1..78528551 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -12380,6 +12380,10 @@ * * Checks if two #GAppInfos are equal. * + * Note that the check may not compare each individual field, and + * only does an identity check. In case detecting changes in the contents + * is needed, program code must additionally compare relevant fields. + * * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. */ @@ -40012,8 +40016,8 @@ * @cancellable: (nullable): a #GCancellable, or %NULL * @error: (nullable): a #GError, or %NULL * - * Verify's a certificate chain after looking up and adding any missing - * certificates to the chain. + * Determines the validity of a certificate chain after looking up and + * adding any missing certificates to the chain. * * @chain is a chain of #GTlsCertificate objects each pointing to the next * certificate in the chain by its %issuer property. The chain may initially @@ -40034,6 +40038,15 @@ * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be * used. * + * If @chain is found to be valid, then the return value will be 0. If + * @chain is found to be invalid, then the return value will indicate + * the problems found. If the function is unable to determine whether + * @chain is valid or not (eg, because @cancellable is triggered + * before it completes) then the return value will be + * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set + * accordingly. @error is not set when @chain is successfully analyzed + * but found to be invalid. + * * This function can block, use g_tls_database_verify_chain_async() to perform * the verification operation asynchronously. * @@ -40055,9 +40068,9 @@ * @callback: callback to call when the operation completes * @user_data: the data to pass to the callback function * - * Asynchronously verify's a certificate chain after looking up and adding - * any missing certificates to the chain. See g_tls_database_verify_chain() - * for more information. + * Asynchronously determines the validity of a certificate chain after + * looking up and adding any missing certificates to the chain. See + * g_tls_database_verify_chain() for more information. * * Since: 2.30 */ @@ -40070,7 +40083,16 @@ * @error: a #GError pointer, or %NULL * * Finish an asynchronous verify chain operation. See - * g_tls_database_verify_chain() for more information. * + * g_tls_database_verify_chain() for more information. + * + * If @chain is found to be valid, then the return value will be 0. If + * @chain is found to be invalid, then the return value will indicate + * the problems found. If the function is unable to determine whether + * @chain is valid or not (eg, because @cancellable is triggered + * before it completes) then the return value will be + * %G_TLS_CERTIFICATE_GENERIC_ERROR and @error will be set + * accordingly. @error is not set when @chain is successfully analyzed + * but found to be invalid. * * Returns: the appropriate #GTlsCertificateFlags which represents the * result of verification. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index bddd8c58..bd277b80 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -16343,7 +16343,9 @@ * and g_str_equal() functions are provided for the most common types * of keys. If @key_equal_func is %NULL, keys are compared directly in * a similar fashion to g_direct_equal(), but without the overhead of - * a function call. + * a function call. @key_equal_func is called with the key from the hash table + * as its first parameter, and the user-provided key to check against as + * its second. * * Returns: a new #GHashTable */ @@ -16369,7 +16371,7 @@ * recursively remove further items from the hash table. This is only * permissible if the application still holds a reference to the hash table. * This means that you may need to ensure that the hash table is empty by - * calling g_hash_table_remove_all before releasing the last reference using + * calling g_hash_table_remove_all() before releasing the last reference using * g_hash_table_unref(). * * Returns: a new #GHashTable @@ -27413,6 +27415,12 @@ * } * ]| * + * Calls to this function from a thread other than the one acquired by the + * #GMainContext the #GSource is attached to are typically redundant, as the + * source could be destroyed immediately after this function returns. However, + * once a source is destroyed it cannot be un-destroyed, so this function can be + * used for opportunistic checks from any thread. + * * Returns: %TRUE if the source has been destroyed * Since: 2.12 */ @@ -27746,6 +27754,9 @@ * for both sources is reached during the same main context iteration * then the order of dispatch is undefined. * + * It is a no-op to call this function on a #GSource which has already been + * destroyed with g_source_destroy(). + * * This API is only intended to be used by implementations of #GSource. * Do not call this API on a #GSource that you did not create. * @@ -34586,11 +34597,11 @@ * - %G_VARIANT_TYPE_DOUBLE: #gdouble * * For example, if calling this function for an array of 32-bit integers, - * you might say sizeof(gint32). This value isn't used except for the purpose + * you might say `sizeof(gint32)`. This value isn't used except for the purpose * of a double-check that the form of the serialised data matches the caller's * expectation. * - * @n_elements, which must be non-%NULL is set equal to the number of + * @n_elements, which must be non-%NULL, is set equal to the number of * items in the array. * * Returns: (array length=n_elements) (transfer none): a pointer to diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c index 145d4772..a57ce315 100644 --- a/gir/gmodule-2.0.c +++ b/gir/gmodule-2.0.c @@ -55,9 +55,15 @@ /** * G_MODULE_EXPORT: * - * Used to declare functions exported by modules. This is a no-op on Linux - * and Unices, but when compiling for Windows, it marks a symbol to be - * exported from the library or executable being built. + * Used to declare functions exported by libraries or modules. + * + * When compiling for Windows, it marks the symbol as `dllexport`. + * + * When compiling for Linux and Unices, it marks the symbol as having `default` + * visibility. This is no-op unless the code is being compiled with a + * non-default + * [visibility flag](https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#index-fvisibility-1260) + * such as `hidden`. */ -- cgit v1.2.1