--- AnyEvent/lib/AnyEvent/Handle.pm	2011/09/01 04:07:18	1.223
+++ 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 warn => "got error $msg\n";
+         AE::log error => "Got error $msg!";
          $hdl->destroy;
          $cv->send;
       };
@@ -24,7 +24,7 @@
    # read the response line
    $hdl->push_read (line => sub {
       my ($hdl, $line) = @_;
-      AE::log warn => "got line <$line>\n";
+      say "got line <$line>";
       $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
 
@@ -1083,7 +1089,7 @@
 register_write_type storable => sub {
    my ($self, $ref) = @_;
 
-   require Storable;
+   require Storable unless $Storable::VERSION;
 
    pack "w/a*", Storable::nfreeze ($ref)
 };
@@ -1434,7 +1440,7 @@
 Example: read 2 bytes.
 
    $handle->push_read (chunk => 2, sub {
-      AE::log debug => "yay " . unpack "H*", $_[1];
+      say "yay " . unpack "H*", $_[1];
    });
 
 =cut
@@ -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
       }
    }
@@ -1713,7 +1719,7 @@
 register_read_type storable => sub {
    my ($self, $cb) = @_;
 
-   require Storable;
+   require Storable unless $Storable::VERSION;
 
    sub {
       # when we can use 5.10 we can use ".", but for 5.8 we use the re-pack method
@@ -1794,7 +1800,7 @@
 during a rehandshake.
 
 As a guideline, during the initial handshake, you should not stop reading,
-and as a client, it might cause problems, depending on your applciation.
+and as a client, it might cause problems, depending on your application.
 
 =cut
 
@@ -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
+