--- AnyEvent-HTTP/HTTP.pm	2008/09/29 13:50:39	1.28
+++ AnyEvent-HTTP/HTTP.pm	2008/10/22 23:28:11	1.29
@@ -73,23 +73,29 @@
 =item http_get $url, key => value..., $cb->($data, $headers)
 
 Executes an HTTP-GET request. See the http_request function for details on
-additional parameters.
+additional parameters and the return value.
 
 =item http_head $url, key => value..., $cb->($data, $headers)
 
-Executes an HTTP-HEAD request. See the http_request function for details on
-additional parameters.
+Executes an HTTP-HEAD request. See the http_request function for details
+on additional parameters and the return value.
 
 =item http_post $url, $body, key => value..., $cb->($data, $headers)
 
 Executes an HTTP-POST request with a request body of C<$body>. See the
-http_request function for details on additional parameters.
+http_request function for details on additional parameters and the return
+value.
 
 =item http_request $method => $url, key => value..., $cb->($data, $headers)
 
 Executes a HTTP request of type C<$method> (e.g. C<GET>, C<POST>). The URL
 must be an absolute http or https URL.
 
+When called in void context, nothing is returned. In other contexts,
+C<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 C<undef> if it wasn't available due to errors), and a hash-ref with
 response headers as second argument.
@@ -191,6 +197,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;
+
 =cut
 
 sub _slot_schedule;