[glib/mcatanzaro/gtlsconnection-confusion] gtlsconnection: clarify handshake() documentation

[Michael Catanzaro <mcatanzaro src gnome org>]

commit b75dd395bad3a4109a7ebd1d8c4c3356f8797462
Author: Michael Catanzaro <mcatanzaro gnome org>
Date:   Wed Nov 13 20:53:37 2019 -0600

    gtlsconnection: clarify handshake() documentation
    
    This tries to clarify some confusing aspects of the
    g_tls_connection_handshake() that can trip up experienced developers.

 gio/gtlsconnection.c | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)
---
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index 2e431ae7e..5bdea96e5 100644
--- a/gio/gtlsconnection.c
+++ b/gio/gtlsconnection.c
@@ -887,15 +887,16 @@ g_tls_connection_get_negotiated_protocol (GTlsConnection *conn)
  *
  * On the client side, it is never necessary to call this method;
  * although the connection needs to perform a handshake after
- * connecting (or after sending a "STARTTLS"-type command) and may
- * need to rehandshake later if the server requests it,
+ * connecting (or after sending a "STARTTLS"-type command),
  * #GTlsConnection will handle this for you automatically when you try
- * to send or receive data on the connection. However, you can call
- * g_tls_connection_handshake() manually if you want to know for sure
- * whether the initial handshake succeeded or failed (as opposed to
- * just immediately trying to write to @conn's output stream, in which
- * case if it fails, it may not be possible to tell if it failed
- * before or after completing the handshake).
+ * to send or receive data on the connection. You can call
+ * g_tls_connection_handshake() manually if you want to know whether
+ * the initial handshake succeeded or failed (as opposed to just
+ * immediately trying to use @conn to read or write, in which case,
+ * if it fails, it may not be possible to tell if it failed before or
+ * after completing the handshake), but beware that servers may reject
+ * client authentication after the handshake has completed, so a
+ * successful handshake does not indicate the connection will be usable.
  *
  * Likewise, on the server side, although a handshake is necessary at
  * the beginning of the communication, you do not need to call this
@@ -910,6 +911,10 @@ g_tls_connection_get_negotiated_protocol (GTlsConnection *conn)
  * nondestructive so as to preserve compatibility with code written for
  * older versions of GLib.
  *
+ * When using a #GTlsConnection created by #GSocketClient, the
+ * #GSocketClient performs the initial handshake, so calling this
+ * function manually is not recommended.
+ *
  * #GTlsConnection::accept_certificate may be emitted during the
  * handshake.
  *