--- AnyEvent-HTTP/README	2008/07/24 06:01:10	1.4
+++ AnyEvent-HTTP/README	2008/10/24 01:27:29	1.6
@@ -30,20 +30,27 @@
   METHODS
     http_get $url, key => value..., $cb->($data, $headers)
         Executes an HTTP-GET request. See the http_request function for
-        details on additional parameters.
+        details on additional parameters and the return value.
 
     http_head $url, key => value..., $cb->($data, $headers)
         Executes an HTTP-HEAD request. See the http_request function for
-        details on additional parameters.
+        details on additional parameters and the return value.
 
     http_post $url, $body, key => value..., $cb->($data, $headers)
         Executes an HTTP-POST request with a request body of $body. See the
-        http_request function for details on additional parameters.
+        http_request function for details on additional parameters and the
+        return value.
 
     http_request $method => $url, key => value..., $cb->($data, $headers)
         Executes a HTTP request of type $method (e.g. "GET", "POST"). The
         URL must be an absolute http or https URL.
 
+        When called in void context, nothing is returned. In other contexts,
+        "http_request" returns a "cancellation guard" - you have to keep the
+        object at least alive until the callback get called. If the object
+        gets destroyed before the callbakc is called, the request will be
+        cancelled.
+
         The callback will be called with the response data as first argument
         (or "undef" if it wasn't available due to errors), and a hash-ref
         with response headers as second argument.
@@ -54,8 +61,8 @@
         name. The pseudo-header "URL" contains the original URL (which can
         differ from the requested URL when following redirects).
 
-        If the server sends a header multiple lines, then their contents
-        will be joined together with "\x00".
+        If the server sends a header multiple times, then their contents
+        will be joined together with a comma (","), as per the HTTP spec.
 
         If an internal error occurs, such as not being able to resolve a
         hostname, then $data will be "undef", "$headers->{Status}" will be
@@ -140,6 +147,16 @@
               }
            ;
 
+        Example: make another simple HTTP GET request, but immediately try
+        to cancel it.
+
+           my $request = http_request GET => "http://www.nethype.de/", sub {
+              my ($body, $hdr) = @_;
+              print "$body\n";
+           };
+
+           undef $request;
+
   GLOBAL FUNCTIONS AND VARIABLES
     AnyEvent::HTTP::set_proxy "proxy-url"
         Sets the default proxy server to use. The proxy-url must begin with