From 42b38827b51390eb14ce212dc2fd228ddf8e0d03 Mon Sep 17 00:00:00 2001
From: "A. Jesse Jiryu Davis" <jesse@mongodb.com>
Date: Thu, 26 Mar 2015 06:31:57 -0400
Subject: [PATCH] Make specific example code for Condition.

---
 docs/locks.rst | 119 ++++++++++++++++++++++++-------------------------
 1 file changed, 59 insertions(+), 60 deletions(-)

diff --git a/docs/locks.rst b/docs/locks.rst
index 35441aa7..41c1e2bd 100644
--- a/docs/locks.rst
+++ b/docs/locks.rst
@@ -11,65 +11,64 @@ place of those from the standard library--they are meant to coordinate Tornado
 coroutines in a single-threaded app, not to protect shared objects in a
 multithreaded app.)*
 
-.. _the-wait-notify-pattern:
-
-The Wait / Notify Pattern
-=========================
-Tornado locks follow a "wait / notify pattern": one coroutine waits to be
-notified by another. Take `~tornado.locks.Condition` as an example:
-
-.. testcode::
-
-    from tornado import ioloop, gen, locks
-
-
-    io_loop = ioloop.IOLoop.current()
-    condition = locks.Condition()
-
-
-    @gen.coroutine
-    def waiter():
-        print("I'll wait right here")
-        yield condition.wait()  # Yield a Future.
-        print("I'm done waiting")
-
-
-    @gen.coroutine
-    def notifier():
-        print("About to notify")
-        condition.notify()
-        print("Done notifying")
-
-
-    @gen.coroutine
-    def runner():
-        # Yield two Futures; wait for waiter() and notifier() to finish.
-        yield [waiter(), notifier()]
-
-    io_loop.run_sync(runner)
-
-.. testoutput::
-
-    I'll wait right here
-    About to notify
-    Done notifying
-    I'm done waiting
-
-Wait-methods take an optional ``timeout`` argument, which is either an
-absolute timestamp::
-
-    io_loop = ioloop.IOLoop.current()
-
-    # Wait up to 1 second for a notification.
-    yield condition.wait(deadline=io_loop.time() + 1)
-
-...or a `datetime.timedelta` for a deadline relative to the current time::
-
-    # Wait up to 1 second.
-    yield condition.wait(deadline=datetime.timedelta(seconds=1))
-
-The method raises `tornado.gen.TimeoutError` if there's no notification
-before the deadline.
-
 .. automodule:: tornado.locks
+
+   Condition
+   ---------
+   .. autoclass:: Condition
     :members:
+
+    With a `Condition`, coroutines can wait to be notified by other coroutines:
+
+    .. testcode::
+
+        from tornado import ioloop, gen, locks
+
+
+        io_loop = ioloop.IOLoop.current()
+        condition = locks.Condition()
+
+
+        @gen.coroutine
+        def waiter():
+            print("I'll wait right here")
+            yield condition.wait()  # Yield a Future.
+            print("I'm done waiting")
+
+
+        @gen.coroutine
+        def notifier():
+            print("About to notify")
+            condition.notify()
+            print("Done notifying")
+
+
+        @gen.coroutine
+        def runner():
+            # Yield two Futures; wait for waiter() and notifier() to finish.
+            yield [waiter(), notifier()]
+
+        io_loop.run_sync(runner)
+
+    .. testoutput::
+
+        I'll wait right here
+        About to notify
+        Done notifying
+        I'm done waiting
+
+    `wait` takes an optional ``timeout`` argument, which is either an absolute
+    timestamp::
+
+        io_loop = ioloop.IOLoop.current()
+
+        # Wait up to 1 second for a notification.
+        yield condition.wait(deadline=io_loop.time() + 1)
+
+    ...or a `datetime.timedelta` for a deadline relative to the current time::
+
+        # Wait up to 1 second.
+        yield condition.wait(deadline=datetime.timedelta(seconds=1))
+
+    The method raises `tornado.gen.TimeoutError` if there's no notification
+    before the deadline.