--- AnyEvent-HTTP/HTTP.pm	2018/08/30 17:04:28	1.131
+++ AnyEvent-HTTP/HTTP.pm	2018/09/07 22:11:31	1.134
@@ -266,6 +266,12 @@
 obviously, it has to follow the same calling conventions, except that it
 may always return a connection guard object.
 
+The connections made by this hook will be treated as equivalent to
+connecitons made the built-in way, specifically, they will be put into
+and taken from the persistent conneciton cache. If your C<$tcp_connect>
+function is incompatible with this kind of re-use, consider switching off
+C<persistent> connections and/or providing a C<session> identifier.
+
 There are probably lots of weird uses for this function, starting from
 tracing the hosts C<http_request> actually tries to connect, to (inexact
 but fast) host => IP address caching or even socks protocol support.
@@ -344,8 +350,8 @@
 Try to create/reuse a persistent connection. When this flag is set
 (default: true for idempotent requests, false for all others), then
 C<http_request> tries to re-use an existing (previously-created)
-persistent connection to the host and, failing that, tries to create a new
-one.
+persistent connection to same host (i.e. identical URL scheme, hostname,
+port and session) and, failing that, tries to create a new one.
 
 Requests failing in certain ways will be automatically retried once, which
 is dangerous for non-idempotent requests, which is why it defaults to off
@@ -1311,7 +1317,7 @@
 chance of understanding the above paragraph:
 
    {
-      version    => 1,
+      version    => 2,
       "10.0.0.1" => {
          "/" => {
             "mythweb_id" => {