From: Ben Darnell <ben@bendarnell.com>
Date: Sun, 18 Aug 2013 23:17:15 +0000 (-0400)
Subject: Emphasize and clarify docs for AsyncHTTPClient.close.
X-Git-Tag: v3.2.0b1~93
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=96977453e85dd075f3ea8cf6a86f96306e3d87ff;p=thirdparty%2Ftornado.git

Emphasize and clarify docs for AsyncHTTPClient.close.
---

diff --git a/tornado/httpclient.py b/tornado/httpclient.py
index b611ad95b..676758942 100644
--- a/tornado/httpclient.py
+++ b/tornado/httpclient.py
@@ -144,9 +144,16 @@ class AsyncHTTPClient(Configurable):
 
     def close(self):
         """Destroys this HTTP client, freeing any file descriptors used.
-        Not needed in normal use, but may be helpful in unittests that
-        create and destroy http clients.  No other methods may be called
-        on the `AsyncHTTPClient` after ``close()``.
+
+        This method is **not needed in normal use** due to the way
+        that `AsyncHTTPClient` objects are transparently reused.
+        ``close()`` is generally only necessary when either the
+        `.IOLoop` is also being closed, or the ``force_instance=True``
+        argument was used when creating the `AsyncHTTPClient`.
+
+        No other methods may be called on the `AsyncHTTPClient` after
+        ``close()``.
+
         """
         if self._async_clients().get(self.io_loop) is self:
             del self._async_clients()[self.io_loop]