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

2 files changed, 15 insertions, 8 deletions

diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
index bf68121..b797d6a 100644
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -15,7 +15,15 @@ Debug mode of asyncio
 ---------------------
 
 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
index 11d13c8..a4a997e 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -172,17 +172,16 @@ StreamWriter
 
       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)