[glib/glib-2-58] Update documentation of g_tls_connection_handshake() again

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 8616425bc0a392d6adef2a0fd283c9bd3ae8cc98
Author: Michael Catanzaro <mcatanzaro igalia com>
Date:   Mon Nov 12 19:55:28 2018 +0000

    Update documentation of g_tls_connection_handshake() again
    
    I made a mistake when last updating the documentation in 94a99ae9. I
    wrote that, with TLS 1.3, this would perform a rekey instead of a
    rehandshake. In fact, that's only true for client connections. For
    server connections, it's a no-op.
    
    I was a bit nervous about how to document the behavior anyway, because
    we really don't know what behavior will be reasonable with non-GnuTLS
    crypto backends. This behavior is reasonable for the GnuTLS backend, but
    might not necessarily make sense for OpenSSL. Ideally, we would
    discourage API users from doing things which could have unexpected
    effects, so instead of documenting what the GnuTLS backend does, I think
    it'd be better to document that this is "undefined but not dangerous,"
    since of course we want to make sure that existing code that doesn't
    know about TLS 1.3 is not broken.
    
    
    (cherry picked from commit 68878ab50b2a25f2ec9b3caf0d49a83bc489914a)

 gio/gtlsconnection.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
---
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index b0353af9d..4364c1253 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -757,8 +757,10 @@ g_tls_connection_get_rehandshake_mode (GTlsConnection       *conn)
  * 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, this will
- * instead perform a rekey.
+ * 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.
  *
  * #GTlsConnection::accept_certificate may be emitted during the
  * handshake.