diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index 16d4a3720..590aef211 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.
  *