--- AnyEvent/lib/AnyEvent/Handle.pm	2012/01/10 13:32:23	1.227
+++ AnyEvent/lib/AnyEvent/Handle.pm	2012/02/06 00:17:26	1.228
@@ -130,13 +130,19 @@
 This callback is called when a connection has been successfully established.
 
 The peer's numeric host and port (the socket peername) are passed as
-parameters, together with a retry callback.
+parameters, together with a retry callback. At the time it is called the
+read and write queues, EOF status, TLS status and similar properties of
+the handle will have been reset.
 
-If, for some reason, the handle is not acceptable, calling C<$retry>
-will continue with the next connection target (in case of multi-homed
-hosts or SRV records there can be multiple connection endpoints). At the
-time it is called the read and write queues, eof status, tls status and
-similar properties of the handle will have been reset.
+It is not allowed to use the read or write queues while the handle object
+is connecting.
+
+If, for some reason, the handle is not acceptable, calling C<$retry> will
+continue with the next connection target (in case of multi-homed hosts or
+SRV records there can be multiple connection endpoints). The C<$retry>
+callback can be invoked after the connect callback returns, i.e. one can
+start a handshake and then decide to retry with the next host if the
+handshake fails.
 
 In most cases, you should ignore the C<$retry> parameter.