[Python-checkins] cpython (merge 3.4 -> default): (Merge 3.4) asyncio: update the doc

[victor.stinner]

http://hg.python.org/cpython/rev/eb2564a37a5c
changeset:   92235:eb2564a37a5c
parent:      92233:ed4ffd602f4e
parent:      92234:5df360612563
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Mon Aug 25 17:04:37 2014 +0200
summary:
  (Merge 3.4) asyncio: update the doc

* dev: mention that the logging must be configured at DEBUG level
* streams: drain() has no more a strange return value, it's just
  a standard coroutine

files:
  Doc/library/asyncio-dev.rst    |  10 +++++++++-
  Doc/library/asyncio-stream.rst |  13 ++++++-------
  2 files changed, 15 insertions(+), 8 deletions(-)


diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -15,7 +15,15 @@
 ---------------------
 
 To enable the debug mode globally, set the environment variable
-:envvar:`PYTHONASYNCIODEBUG` to ``1``. Examples of effects of the debug mode:
+:envvar:`PYTHONASYNCIODEBUG` to ``1``. To see debug traces, set the log level
+of the :ref:`asyncio logger <asyncio-logger>` to :py:data:`logging.DEBUG`.  The
+simplest configuration is::
+
+   import logging
+   # ...
+   logging.basicConfig(level=logging.DEBUG)
+
+Examples of effects of the debug mode:
 
 * Log :ref:`coroutines defined but never "yielded from"
   <asyncio-coroutine-not-scheduled>`
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -172,17 +172,16 @@
 
       Wait until the write buffer of the underlying transport is flushed.
 
-      This method has an unusual return value. The intended use is to write::
+      The intended use is to write::
 
           w.write(data)
           yield from w.drain()
 
-      When there's nothing to wait for, :meth:`drain()` returns ``()``, and the
-      yield-from continues immediately.  When the transport buffer is full (the
-      protocol is paused), :meth:`drain` creates and returns a
-      :class:`Future` and the yield-from will block until
-      that Future is completed, which will happen when the buffer is
-      (partially) drained and the protocol is resumed.
+      When the transport buffer is full (the protocol is paused), block until
+      the buffer is (partially) drained and the protocol is resumed. When there
+      is nothing to wait for, the yield-from continues immediately.
+
+      This method is a :ref:`coroutine <coroutine>`.
 
    .. method:: get_extra_info(name, default=None)
 

-- 
Repository URL: http://hg.python.org/cpython