Update release notes and docs.

docs/gen.rst

@@ -20,11 +20,15 @@
 
    .. autofunction:: maybe_future
 
+   .. autofunction:: sleep
+
    .. autodata:: moment
       :annotation:
 
    .. autofunction:: Task
 
+   .. autoclass:: WaitIterator
+
    .. class:: Arguments
 
       The result of a `Task` or `Wait` whose callback had more than one

docs/releases/next.rst

@@ -87,3 +87,26 @@ In progress
 * Malformed ``multipart/form-data`` bodies will always be logged
   quietly instead of raising an unhandled exception; previously
   the behavior was inconsistent depending on the exact error.
+* `.websocket_connect` now has a ``on_message_callback`` keyword argument
+  for callback-style use without ``read_message()``.
+* New class `tornado.gen.WaitIterator` provides a way to iterate
+  over ``Futures`` in the order they resolve.
+* When a new `.IOLoop` is created, it automatically becomes "current"
+  for the thread if there is not already a current instance.
+* When the `~functools.singledispatch` library is available (standard on
+  Python 3.4, available via ``pip install singledispatch`` on older versions),
+  the `.convert_yielded` function can be used to make other kinds of objects
+  yieldable in coroutines.
+* It is now possible to yield ``asyncio.Future`` objects in coroutines
+  when the `~functools.singledispatch` library is available and
+  ``tornado.platform.asyncio`` has been imported.
+* It is now possible to yield ``Deferred`` objects in coroutines
+  when the `~functools.singledispatch` library is available and
+  ``tornado.platform.twisted`` has been imported.
+* New methods `tornado.platform.asyncio.to_tornado_future` and
+  `~tornado.platform.asyncio.to_asyncio_future` convert between
+  the two libraries' `.Future` classes.
+* New function `tornado.gen.sleep` is a coroutine-friendly
+  analogue to `time.sleep`.
+* ``tornado.curl_httpclient`` now uses its own logger for debug output
+  so it can be filtered more easily.

tornado/websocket.py

@@ -1000,11 +1000,26 @@ def websocket_connect(url, io_loop=None, callback=None, connect_timeout=None,
     ``compression_options`` is interpreted in the same way as the
     return value of `.WebSocketHandler.get_compression_options`.
 
+    The connection supports two styles of operation. In the coroutine
+    style, the application typically calls
+    `~.WebSocketClientConnection.read_message` in a loop::
+
+        conn = yield websocket_connection(loop)
+        while True:
+            msg = yield conn.read_message()
+            if msg is None: break
+            # Do something with msg
+
+    In the callback style, pass an ``on_message_callback`` to
+    ``websocket_connect``. In both styles, a message of ``None``
+    indicates that the connection has been closed.
+
     .. versionchanged:: 3.2
        Also accepts ``HTTPRequest`` objects in place of urls.
 
     .. versionchanged:: 4.1
-       Added ``compression_options``. The ``io_loop`` argument is deprecated.
+       Added ``compression_options`` and ``on_message_callback``.
+       The ``io_loop`` argument is deprecated.
     """
     if io_loop is None:
         io_loop = IOLoop.current()