--- AnyEvent/lib/AnyEvent/Handle.pm	2011/12/12 12:56:04	1.226
+++ AnyEvent/lib/AnyEvent/Handle.pm	2012/03/27 23:47:57	1.231
@@ -13,7 +13,7 @@
       fh => \*STDIN,
       on_error => sub {
          my ($hdl, $fatal, $msg) = @_;
-         AE::log error => "got error $msg\n";
+         AE::log error => "Got error $msg!";
          $hdl->destroy;
          $cv->send;
       };
@@ -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.
-
-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.
+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.
+
+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.
 
@@ -226,8 +232,8 @@
 
 =item on_drain => $cb->($handle)
 
-This sets the callback that is called when the write buffer becomes empty
-(or immediately if the buffer is empty already).
+This sets the callback that is called once when the write buffer becomes
+empty (and immediately when the handle object is created).
 
 To append to the write buffer, use the C<< ->push_write >> method.
 
@@ -882,7 +888,7 @@
 AnyEvent::Handle will automatically try to get rid of it for you.
 
 When data could be written and the write buffer is shorter then the low
-water mark, the C<on_drain> callback will be invoked.
+water mark, the C<on_drain> callback will be invoked once.
 
 =over 4
 
@@ -1478,7 +1484,7 @@
       sub {
          $_[0]{rbuf} =~ s/^([^\015\012]*)(\015?\012)// or return;
 
-         $cb->($_[0], $1, $2);
+         $cb->($_[0], "$1", "$2");
          1
       }
    } else {
@@ -1488,7 +1494,7 @@
       sub {
          $_[0]{rbuf} =~ s/$eol// or return;
 
-         $cb->($_[0], $1, $2);
+         $cb->($_[0], "$1", "$2");
          1
       }
    }
@@ -2332,7 +2338,7 @@
 
    $handle->push_write (...);
    $handle->on_drain (sub {
-      AE::log debug => "all data submitted to the kernel\n";
+      AE::log debug => "All data submitted to the kernel.";
       undef $handle;
    });
 
@@ -2426,7 +2432,6 @@
 
 =back
 
-
 =head1 SUBCLASSING AnyEvent::Handle
 
 In many cases, you might want to subclass AnyEvent::Handle.
@@ -2462,4 +2467,5 @@
 
 =cut
 
-1; # End of AnyEvent::Handle
+1
+