[glib/glib-2-52] docs: Clarify the use of the GError in g_tls_database_verify_chain*

[Matthias Clasen <matthiasc src gnome org>]

commit c3f555b69edb67c3bf353f5160428fcafa6977bd
Author: Debarshi Ray <debarshir gnome org>
Date:   Wed Mar 22 19:23:46 2017 +0100

    docs: Clarify the use of the GError in g_tls_database_verify_chain*
    
    Being able to determine that a certificate chain is invalid is not
    considered an error, but success. This might not be obvious at first
    due to the way the method is named and described currently. Since we
    cannot change the name, let's improve the description and clarify this
    aspect of its behaviour.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=780310

 gio/gtlsdatabase.c |   31 +++++++++++++++++++++++++------
 1 files changed, 25 insertions(+), 6 deletions(-)
---
diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index 16d4a37..590aef2 100644
--- a/gio/gtlsdatabase.c
+++ b/gio/gtlsdatabase.c
@@ -455,8 +455,8 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
  * @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
@@ -477,6 +477,15 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
  * 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.
  *
@@ -532,9 +541,9 @@ g_tls_database_verify_chain (GTlsDatabase           *self,
  * @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
  */
@@ -576,7 +585,17 @@ g_tls_database_verify_chain_async (GTlsDatabase           *self,
  * @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.
  *