[glib/mcatanzaro/peer-certificate] gtlsconnection: Improve documentation of peer-certificate[-errors]

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 4db1336ff681ef69aac97844bafc8a61275f266f
Author: Michael Catanzaro <mcatanzaro gnome org>
Date:   Wed Jun 10 09:56:47 2020 -0500

    gtlsconnection: Improve documentation of peer-certificate[-errors]
    
    In glib-networking#127, it was reported that we don't properly implement
    the documented behavior of these properties. However, we cannot fix it
    because libsoup relies on the implemented behavior, and it's hard to
    change that without cascading breakage. The practical solution is to
    adjust our documentation to match reality. There should be no downsides
    to this, and compat risk of changing the documentation is much smaller
    than risk of changing the implementation, so I think this is the best we
    can make of an unfortunate situation. See glib-networking#127 for full
    discussion and glib-networking#129 for the regression when we attempted
    to match the documented behavior.

 gio/gdtlsconnection.c | 15 +++++++--------
 gio/gtlsconnection.c  | 15 +++++++--------
 2 files changed, 14 insertions(+), 16 deletions(-)
---
diff --git a/gio/gdtlsconnection.c b/gio/gdtlsconnection.c
index c186a2613..2704133ff 100644
--- a/gio/gdtlsconnection.c
+++ b/gio/gdtlsconnection.c
@@ -195,9 +195,8 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
    * GDtlsConnection:peer-certificate: (nullable)
    *
    * The connection's peer's certificate, after the TLS handshake has
-   * completed and the certificate has been accepted. Note in
-   * particular that this is not yet set during the emission of
-   * #GDtlsConnection::accept-certificate.
+   * completed or failed. Note in particular that this is not yet set
+   * during the emission of #GDtlsConnection::accept-certificate.
    *
    * (You can watch for a #GObject::notify signal on this property to
    * detect when a handshake has occurred.)
@@ -214,7 +213,7 @@ g_dtls_connection_default_init (GDtlsConnectionInterface *iface)
   /**
    * GDtlsConnection:peer-certificate-errors:
    *
-   * The errors noticed-and-ignored while verifying
+   * The errors noticed while verifying
    * #GDtlsConnection:peer-certificate. Normally this should be 0, but
    * it may not be if #GDtlsClientConnection:validation-flags is not
    * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
@@ -494,8 +493,8 @@ g_dtls_connection_get_interaction (GDtlsConnection       *conn)
  * g_dtls_connection_get_peer_certificate:
  * @conn: a #GDtlsConnection
  *
- * Gets @conn's peer's certificate after the handshake has completed.
- * (It is not set during the emission of
+ * Gets @conn's peer's certificate after the handshake has completed
+ * or failed. (It is not set during the emission of
  * #GDtlsConnection::accept-certificate.)
  *
  * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
@@ -521,8 +520,8 @@ g_dtls_connection_get_peer_certificate (GDtlsConnection *conn)
  * @conn: a #GDtlsConnection
  *
  * Gets the errors associated with validating @conn's peer's
- * certificate, after the handshake has completed. (It is not set
- * during the emission of #GDtlsConnection::accept-certificate.)
+ * certificate, after the handshake has completed or failed. (It is
+ * not set during the emission of #GDtlsConnection::accept-certificate.)
  *
  * Returns: @conn's peer's certificate errors
  *
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index 4d5e1c247..f01e492d5 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -228,9 +228,8 @@ g_tls_connection_class_init (GTlsConnectionClass *klass)
    * GTlsConnection:peer-certificate: (nullable)
    *
    * The connection's peer's certificate, after the TLS handshake has
-   * completed and the certificate has been accepted. Note in
-   * particular that this is not yet set during the emission of
-   * #GTlsConnection::accept-certificate.
+   * completed or failed. Note in particular that this is not yet set
+   * during the emission of #GTlsConnection::accept-certificate.
    *
    * (You can watch for a #GObject::notify signal on this property to
    * detect when a handshake has occurred.)
@@ -247,7 +246,7 @@ g_tls_connection_class_init (GTlsConnectionClass *klass)
   /**
    * GTlsConnection:peer-certificate-errors:
    *
-   * The errors noticed-and-ignored while verifying
+   * The errors noticed while verifying
    * #GTlsConnection:peer-certificate. Normally this should be 0, but
    * it may not be if #GTlsClientConnection:validation-flags is not
    * %G_TLS_CERTIFICATE_VALIDATE_ALL, or if
@@ -611,8 +610,8 @@ g_tls_connection_get_interaction (GTlsConnection       *conn)
  * g_tls_connection_get_peer_certificate:
  * @conn: a #GTlsConnection
  *
- * Gets @conn's peer's certificate after the handshake has completed.
- * (It is not set during the emission of
+ * Gets @conn's peer's certificate after the handshake has completed
+ * or failed. (It is not set during the emission of
  * #GTlsConnection::accept-certificate.)
  *
  * Returns: (transfer none) (nullable): @conn's peer's certificate, or %NULL
@@ -638,8 +637,8 @@ g_tls_connection_get_peer_certificate (GTlsConnection *conn)
  * @conn: a #GTlsConnection
  *
  * Gets the errors associated with validating @conn's peer's
- * certificate, after the handshake has completed. (It is not set
- * during the emission of #GTlsConnection::accept-certificate.)
+ * certificate, after the handshake has completed or failed. (It is
+ * not set during the emission of #GTlsConnection::accept-certificate.)
  *
  * Returns: @conn's peer's certificate errors
  *