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

[Michael Catanzaro <mcatanzaro src gnome org>]

commit eebd161eaa6061471f08366bdd4508651e779827
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, 12 insertions(+), 9 deletions(-)
---
diff --git a/gio/gtlsconnection.c b/gio/gtlsconnection.c
index 2e431ae7e..5150d7846 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
@@ -908,7 +909,9 @@ g_tls_connection_get_negotiated_protocol (GTlsConnection *conn)
  * 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.
+ * 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.