--- AnyEvent-HTTP/README	2008/06/05 18:42:16	1.2
+++ AnyEvent-HTTP/README	2008/10/23 02:46:20	1.5
@@ -4,6 +4,10 @@
 SYNOPSIS
        use AnyEvent::HTTP;
 
+       http_get "http://www.nethype.de/", sub { print $_[1] };
+
+       # ... do something else here
+
 DESCRIPTION
     This module is an AnyEvent user, you need to make sure that you use and
     run a supported event loop.
@@ -26,29 +30,39 @@
   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 $bod. See the
-        http_request function for details on additional parameters.
+        Executes an HTTP-POST request with a request body of $body. See the
+        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.
 
         All the headers in that hash are lowercased. In addition to the
-        response headers, the three "pseudo-headers" "HTTPVersion", "Status"
-        and "Reason" contain the three parts of the HTTP Status-Line of the
-        same name. If the server sends a header multiple lines, then their
-        contents will be joined together with "\x00".
+        response headers, the "pseudo-headers" "HTTPVersion", "Status" and
+        "Reason" contain the three parts of the HTTP Status-Line of the same
+        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 an internal error occurs, such as not being able to resolve a
         hostname, then $data will be "undef", "$headers->{Status}" will be
@@ -133,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
@@ -168,6 +192,6 @@
     AnyEvent.
 
 AUTHOR
-     Marc Lehmann <schmorp@schmorp.de>
-     http://home.schmorp.de/
+       Marc Lehmann <schmorp@schmorp.de>
+       http://home.schmorp.de/