[gobject-introspection] gir: Update annotations from GLib 2.52.1

[Rico Tzschichholz <ricotz src gnome org>]

commit 8964b1bab05ecfbd47f2185476ef48c86a6b76c9
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Mon Apr 10 08:58:21 2017 +0200

    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 105a47c..7852855 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 <em>may not</em> 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 bddd8c5..bd277b8 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 145d477..a57ce31 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`.
  */