From f27b49a743fadb7d215594e7471ea8977e41c036 Mon Sep 17 00:00:00 2001
From: Ben Darnell <ben@bendarnell.com>
Date: Thu, 29 Dec 2011 22:58:03 -0800
Subject: [PATCH] Misc doc updates.

---
 tornado/curl_httpclient.py       |  2 +-
 tornado/httpclient.py            |  4 ++++
 tornado/stack_context.py         | 19 +++++++++++++++++++
 tornado/testing.py               |  9 ++++++++-
 website/sphinx/releases/next.rst |  4 ++--
 5 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/tornado/curl_httpclient.py b/tornado/curl_httpclient.py
index 5a3e6248..b8fd4052 100644
--- a/tornado/curl_httpclient.py
+++ b/tornado/curl_httpclient.py
@@ -351,7 +351,7 @@ def _curl_setup_request(curl, request, buffer, headers):
         # (but see version check in _process_queue above)
         curl.setopt(pycurl.IPRESOLVE, pycurl.IPRESOLVE_V4)
 
-    # Set the request method through curl's retarded interface which makes
+    # Set the request method through curl's irritating interface which makes
     # up names for almost every single method
     curl_options = {
         "GET": pycurl.HTTPGET,
diff --git a/tornado/httpclient.py b/tornado/httpclient.py
index b8f97c62..443657c0 100644
--- a/tornado/httpclient.py
+++ b/tornado/httpclient.py
@@ -10,6 +10,10 @@ The default implementation is `simple_httpclient`, and this is expected
 to be suitable for most users' needs.  However, some applications may wish
 to switch to `curl_httpclient` for reasons such as the following:
 
+* `curl_httpclient` has some features not found in `simple_httpclient`,
+  including support for HTTP proxies and the ability to use a specified
+  network interface.
+
 * `curl_httpclient` is more likely to be compatible with sites that are
   not-quite-compliant with the HTTP spec, or sites that use little-exercised
   features of HTTP.
diff --git a/tornado/stack_context.py b/tornado/stack_context.py
index d64e3cfd..1ba3730c 100644
--- a/tornado/stack_context.py
+++ b/tornado/stack_context.py
@@ -45,6 +45,25 @@ Example usage::
         # in the ioloop.
         http_client.fetch(url, callback)
     ioloop.start()
+
+Most applications shouln't have to work with `StackContext` directly.
+Here are a few rules of thumb for when it's necessary:
+
+* If you're writing an asynchronous library that doesn't rely on a
+  stack_context-aware library like `tornado.ioloop` or `tornado.iostream`
+  (for example, if you're writing a thread pool), use
+  `stack_context.wrap()` before any asynchronous operations to capture the
+  stack context from where the operation was started.
+
+* If you're writing an asynchronous library that has some shared
+  resources (such as a connection pool), create those shared resources
+  within a ``with stack_context.NullContext():`` block.  This will prevent
+  ``StackContexts`` from leaking from one request to another.
+
+* If you want to write something like an exception handler that will
+  persist across asynchronous calls, create a new `StackContext` (or
+  `ExceptionStackContext`), and make your asynchronous calls in a ``with``
+  block that references your `StackContext`.
 '''
 
 from __future__ import with_statement
diff --git a/tornado/testing.py b/tornado/testing.py
index 1cbabe59..b2b983dd 100644
--- a/tornado/testing.py
+++ b/tornado/testing.py
@@ -80,16 +80,23 @@ class AsyncTestCase(unittest.TestCase):
                 # Test contents of response (failures and exceptions here
                 # will cause self.wait() to throw an exception and end the
                 # test).
+                # Exceptions thrown here are magically propagated to
+                # self.wait() in test_http_fetch() via stack_context.
+                self.assertIn("FriendFeed", response.body)
                 self.stop()
 
         # This test uses the argument passing between self.stop and self.wait
-        # for a simpler, more synchronous style
+        # for a simpler, more synchronous style.
+        # This style is recommended over the preceding example because it
+        # keeps the assertions in the test method itself, and is therefore
+        # less sensitive to the subtleties of stack_context.
         class MyTestCase2(AsyncTestCase):
             def test_http_fetch(self):
                 client = AsyncHTTPClient(self.io_loop)
                 client.fetch("http://www.tornadoweb.org/", self.stop)
                 response = self.wait()
                 # Test contents of response
+                self.assertIn("FriendFeed", response.body)
     """
     def __init__(self, *args, **kwargs):
         super(AsyncTestCase, self).__init__(*args, **kwargs)
diff --git a/website/sphinx/releases/next.rst b/website/sphinx/releases/next.rst
index f63d9f6f..130c9b8f 100644
--- a/website/sphinx/releases/next.rst
+++ b/website/sphinx/releases/next.rst
@@ -18,8 +18,8 @@ Other modules
 
 * `tornado.iostream.IOStream.write` now works correctly when given an
   empty string.
-* `tornado.simple_httpclient` no longer hangs on ``HEAD`` requests
-  and responses with no content.
+* `tornado.simple_httpclient` no longer hangs on ``HEAD`` requests,
+  responses with no content, or empty ``POST``/``PUT`` response bodies.
 * `tornado.websocket` has been updated to support the latest protocol
   (as finalized in RFC 6455).
 * `tornado.platform.twisted` compatibility has been improved.  However,