[glib/mcatanzaro/#2211: 5/8] gsocketclient: document Happy Eyeballs

[Michael Catanzaro <mcatanzaro src gnome org>]

commit 290d5722beb9405ffbb1a6262e94bf6de4db6f5e
Author: Michael Catanzaro <mcatanzaro gnome org>
Date:   Thu Oct 8 19:08:34 2020 -0500

    gsocketclient: document Happy Eyeballs
    
    This isn't an API guarantee, but it's a potentially-surprising
    behavior difference between the sync and async functions that is good
    to know about, especially because our sync and async functions are
    normally identical.

 gio/gsocketclient.c | 9 +++++++++
 1 file changed, 9 insertions(+)
---
diff --git a/gio/gsocketclient.c b/gio/gsocketclient.c
index 0a9e9df82..8a663c3de 100644
--- a/gio/gsocketclient.c
+++ b/gio/gsocketclient.c
@@ -1936,6 +1936,15 @@ g_socket_client_enumerator_callback (GObject      *object,
  *
  * This is the asynchronous version of g_socket_client_connect().
  *
+ * You may wish to prefer the asynchronous version even in synchronous
+ * command line programs because, since 2.60, it implements
+ * [RFC 8305](https://tools.ietf.org/html/rfc8305) "Happy Eyeballs"
+ * recommendations to work around long connection timeouts in networks
+ * where IPv6 is broken by performing an IPv4 connection simultaneously
+ * without waiting for IPv6 to time out, which is not supported by the
+ * synchronous call. (This is not an API guarantee, and may change in
+ * the future.)
+ *
  * When the operation is finished @callback will be
  * called. You can then call g_socket_client_connect_finish() to get
  * the result of the operation.