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

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 596546974cec9a9cf3f2ab145cd89c848c144800
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/gtlsconnection.c | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)
---
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.