[glib/mcatanzaro/verify-chain-docs: 16/16] Improve documentation of g_tls_database_verify_chain()

[Philip Withnall <pwithnall src gnome org>]

commit 33c9c305e30aea9d3147882bac07df373a5043b4
Author: Michael Catanzaro <mcatanzaro gnome org>
Date:   Mon May 4 17:13:39 2020 -0500

    Improve documentation of g_tls_database_verify_chain()
    
    It is critical to mention how the identity parameter is expected to be
    handled. In particular, if identity is not passed, then the identity of
    the server certificate will not be checked at all. This is in contrast
    to the connection-level APIs, which are supposed to be fail-safe. The
    database and certificate-level APIs are more manual.

 gio/gtlsdatabase.c | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)
---
diff --git a/gio/gtlsdatabase.c b/gio/gtlsdatabase.c
index f06dabf0a..256369da3 100644
--- a/gio/gtlsdatabase.c
+++ b/gio/gtlsdatabase.c
@@ -473,9 +473,13 @@ g_tls_database_class_init (GTlsDatabaseClass *klass)
  * which means that the certificate is being used to authenticate a server
  * (and we are acting as the client).
  *
- * The @identity is used to check for pinned certificates (trust exceptions)
- * in the database. These will override the normal verification process on a
- * host by host basis.
+ * The @identity is used to ensure the server certificate is valid for
+ * the expected peer identity. If the identity does not match the
+ * certificate, %G_TLS_CERTIFICATE_BAD_IDENTITY will be set in the
+ * return value. If @identity is %NULL, that bit will never be set in
+ * the return value. The peer identity may also be used to check for
+ * pinned certificates (trust exceptions) in the database. These may
+ * override the normal verification process on a host-by-host basis.
  *
  * Currently there are no @flags, and %G_TLS_DATABASE_VERIFY_NONE should be
  * used.