[glib/mcatanzaro/tls1.3-handshake: 1/2] Update documentation of g_tls_connection_handshake() one last time

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 2031e37dfca0ac8543bb06c0648c28b2b92ee701
Author: Michael Catanzaro <mcatanzaro igalia com>
Date:   Sat Nov 17 11:14:27 2018 -0600

    Update documentation of g_tls_connection_handshake() one last time
    
    Let's entirely deprecate calling this function for rehandshaking. The
    current documentation is OK, but guarantees defined behavior (to attempt
    a rehandshake) when TLS 1.2 is in use. But there's no way to force TLS
    1.2, and also no way to check which version of TLS is in use. I really
    should have deprecated use of this function for rehandshaking entirely
    last time I updated it.
    
    Fortunately, there should be no compatibility risk for existing code,
    because rehandshaking has no visible effects at the API level.

 gio/gdtlsconnection.c | 11 +++++++++--
 gio/gtlsconnection.c  | 14 +++++++++-----
 2 files changed, 18 insertions(+), 7 deletions(-)
---
diff --git a/gio/gdtlsconnection.c b/gio/gdtlsconnection.c
index cbcb720dc..a51910eb5 100644
--- a/gio/gdtlsconnection.c
+++ b/gio/gdtlsconnection.c
@@ -656,8 +656,15 @@ g_dtls_connection_get_rehandshake_mode (GDtlsConnection       *conn)
  * Likewise, on the server side, although a handshake is necessary at
  * the beginning of the communication, you do not need to call this
  * function explicitly unless you want clearer error reporting.
- * However, you may call g_dtls_connection_handshake() later on to
- * renegotiate parameters (encryption methods, etc) with the client.
+ *
+ * If TLS 1.2 or older is in use, you may call
+ * g_dtls_connection_handshake() after the initial handshake to
+ * rehandshake; however, this usage is deprecated because rehandshaking
+ * is no longer part of the TLS protocol in TLS 1.3. Accordingly, the
+ * behavior of calling this function after the initial handshake is now
+ * undefined, except it is guaranteed to be reasonable and
+ * nondestructive so as to preserve compatibility with code written for
+ * older versions of GLib.
  *
  * #GDtlsConnection::accept_certificate may be emitted during the
  * handshake.
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index 4364c1253..3dba7d7d9 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -756,11 +756,15 @@ g_tls_connection_get_rehandshake_mode (GTlsConnection       *conn)
  * Likewise, on the server side, although a handshake is necessary at
  * the beginning of the communication, you do not need to call this
  * function explicitly unless you want clearer error reporting.
- * However, you may call g_tls_connection_handshake() later on to
- * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, the
- * behavior is undefined but guaranteed to be reasonable and
- * nondestructive, so most older code should be expected to continue to
- * work without changes.
+ *
+ * If TLS 1.2 or older is in use, you may call
+ * g_tls_connection_handshake() after the initial handshake to
+ * rehandshake; however, this usage is deprecated because rehandshaking
+ * is no longer part of the TLS protocol in TLS 1.3. Accordingly, the
+ * behavior of calling this function after the initial handshake is now
+ * undefined, except it is guaranteed to be reasonable and
+ * nondestructive so as to preserve compatibility with code written for
+ * older versions of GLib.
  *
  * #GTlsConnection::accept_certificate may be emitted during the
  * handshake.