gsocketclient: Document async operation timeout/completion behaviour

These calls are where the `GSocketClient` Happy Eyeballs code relies on
other components within GLib (and glib-networking) to complete
asynchronous operations in a timely manner. `GSocketClient` doesn’t add
its own timeouts to monitor these async operations, so if the
implementations are buggy then a `GSocketClient` operation could stall
forever.

Make that a bit clearer.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

gio/gsocketconnection.c

@@ -177,6 +177,10 @@ static gboolean g_socket_connection_connect_callback (GSocket      *socket,
  * This clears the #GSocket:blocking flag on @connection's underlying
  * socket if it is currently set.
  *
+ * If #GSocket:timeout is set, the operation will time out and return
+ * %G_IO_ERROR_TIMED_OUT after that period. Otherwise, it will continue
+ * indefinitely until operating system timeouts (if any) are hit.
+ *
  * Use g_socket_connection_connect_finish() to retrieve the result.
  *
  * Since: 2.32