Clarify the role and meaning of self.fetch() in AsyncHTTPTestCase.

The example code should just show the simple, obvious thing to do:
call self.fetch(). Text afterwards explains how this relates to stop()
and wait().

diff --git a/tornado/testing.py b/tornado/testing.py
index 93f0dbe14196569f467b015789140e88eae4a8fc..5bac5de7063a8dccfff05bf2681b39c5d2924af3 100644 (file)
--- a/tornado/testing.py
+++ b/tornado/testing.py
@@ -338,13 +338,17 @@ class AsyncHTTPTestCase(AsyncTestCase):
                 return Application([('/', MyHandler)...])
 
             def test_homepage(self):
-                # The following two lines are equivalent to
-                #   response = self.fetch('/')
-                # but are shown in full here to demonstrate explicit use
-                # of self.stop and self.wait.
-                self.http_client.fetch(self.get_url('/'), self.stop)
-                response = self.wait()
-                # test contents of response
+                response = self.fetch('/')
+
+    That call to ``self.fetch()`` is equivalent to ::
+
+        self.http_client.fetch(self.get_url('/'), self.stop)
+        response = self.wait()
+
+    which illustrates how AsyncTestCase can turn an asynchronous operation,
+    like ``http_client.fetch()``, into a synchronous operation. If you need
+    to do other asynchronous operations in tests, you'll probably need to use
+    ``stop()`` and ``wait()`` yourself.
     """
     def setUp(self):
         super(AsyncHTTPTestCase, self).setUp()