bpo-33649: Polish asyncio subprocess and sync docs (GH-9285)

willingc · miss-islington · commit 4e824e96491f · 2018-09-13T18:28:19.000-07:00
Second pass for asyncio subprocess and sync docs. https://bugs.python.org/issue33649
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
@@ -62,8 +62,7 @@ Creating Subprocesses
 
    The *limit* argument sets the buffer limit for :class:`StreamReader`
    wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
-   (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr*
-   arguments).
+   (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
 
    Return a :class:`~asyncio.subprocess.Process` instance.
 
@@ -78,15 +77,14 @@ Creating Subprocesses
 
    The *limit* argument sets the buffer limit for :class:`StreamReader`
    wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
-   (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr*
-   arguments).
+   (if :attr:`subprocess.PIPE` is passed to *stdout* and *stderr* arguments).
 
    Return a :class:`~asyncio.subprocess.Process` instance.
 
    See the documentation of :meth:`loop.subprocess_shell` for other
    parameters.
 
-.. note::
+.. important::
 
    It is the application's responsibility to ensure that all whitespace and
    metacharacters are quoted appropriately to avoid `shell injection
@@ -98,7 +96,8 @@ Creating Subprocesses
 .. note::
 
    The default event loop that asyncio is pre-configured
-   to use on **Windows** does not support subprocesses.
+   to use on **Windows** does not support subprocesses. Subprocesses are
+   available for Windows if the :class:`ProactorEventLoop` is used.
    See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
    for details.
 
@@ -206,7 +205,7 @@ communicate with them.
       exception is ignored.  This condition occurs when the process
       exits before all data are written into *stdin*.
 
-      If its desired to send data to the process' *stdin*,
+      If it is desired to send data to the process' *stdin*,
       the process needs to be created with ``stdin=PIPE``.  Similarly,
       to get anything other than ``None`` in the result tuple, the
       process has to be created with ``stdout=PIPE`` and/or
@@ -265,8 +264,8 @@ communicate with them.
       Use the :meth:`communicate` method rather than
       :attr:`process.stdin.write() <stdin>`,
       :attr:`await process.stdout.read() <stdout>` or
-      :attr:`await process.stderr.read <stderr>`
-      to avoid deadlocks due to streams pausing reading or writing
+      :attr:`await process.stderr.read <stderr>`.
+      This avoids deadlocks due to streams pausing reading or writing
       and blocking the child process.
 
    .. attribute:: pid
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst
@@ -13,11 +13,11 @@ those of the :mod:`threading` module with two important caveats:
   be used for OS threads synchronization (use :mod:`threading` for
   that);
 
-* methods of synchronization objects do not accept the *timeout*
+* methods of synchronization primitives do not accept the *timeout*
   argument; use the :func:`asyncio.wait_for` function to perform
   operations with timeouts.
 
-asyncio has the following basic primitives:
+asyncio has the following basic sychronization primitives:
 
 * :class:`Lock`
 * :class:`Event`
@@ -72,7 +72,7 @@ Lock
 
       When the lock is *locked*, reset it to *unlocked* and return.
 
-      If the lock is *unlocked* a :exc:`RuntimeError` is raised.
+      If the lock is *unlocked*, a :exc:`RuntimeError` is raised.
 
    .. method:: locked()
 
@@ -97,7 +97,7 @@ Event
    Example::
 
       async def waiter(event):
-          print('waiting ...')
+          print('waiting for it ...')
           await event.wait()
           print('... got it!')
 
