PEP 554: minor cleanup and renames. (#405)

Raymond gave me some good feedback. Thanks, Raymond!

pep-0554.rst

@@ -68,8 +68,8 @@ concurrency model (e.g. CSP) which has found success elsewhere and
 will appeal to some Python users.  That is the core value that the
 ``interpreters`` module will provide.
 
-* stdlib support for subinterpreters adds extra burden
-  on C extension authors
+* "stdlib support for subinterpreters adds extra burden
+  on C extension authors"
 
 In the ``Interpreter Isolation`` section below we identify ways in
 which isolation in CPython's subinterpreters is incomplete.  Most
@@ -104,7 +104,7 @@ provide a high-level interface to subinterpreters and wrap the low-level
 
 The module provides the following functions:
 
-``enumerate()``::
+``list()``::
 
    Return a list of all existing interpreters.
 
@@ -137,13 +137,19 @@ The module also provides the following classes:
    destroy():
 
       Finalize and destroy the interpreter.  If called on a running
-      interpreter, RuntimeError will be raised.
+      interpreter then raise RuntimeError in the interpreter that
+      called ``destroy()``.
 
    run(code):
 
       Run the provided Python code in the interpreter, in the current
       OS thread.  If the interpreter is already running then raise
-      RuntimeError.
+      RuntimeError in the interpreter that called ``run()``.
+
+      The current interpreter (which called ``run()``) will block until
+      the subinterpreter finishes running the requested code.  Any
+      uncaught exception in that code will bubble up to the current
+      interpreter.
 
       Supported code: source text.
 
@@ -152,24 +158,38 @@ The module also provides the following classes:
       Return the FIFO object with the given name that is associated
       with this interpreter.  If no such FIFO exists then raise
       KeyError.  The FIFO will be either a "FIFOReader" or a
-      "FIFOWriter", depending on how "add_fifo()" was called.
+      "FIFOWriter", depending on which "add_*_fifo()" was called.
 
    list_fifos():
 
       Return a list of all fifos associated with the interpreter.
 
-   add_fifo(name=None, *, recv=True):
+   add_recv_fifo(name=None):
 
-      Create a new FIFO associated with this interpreter and return
-      the opposite end of the FIFO.  For example, if "recv" is True
-      then a "FIFOReader" is associated with this interpreter and a
-      "FIFOWriter" is returned.  The returned FIFO is also associated
-      with the interpreter in which "add_fifo()" was called.
+      Create a new FIFO, associate the two ends with the involved
+      interpreters, and return the side associated with the interpreter
+      in which "add_recv_fifo()" was called.  A FIFOReader gets tied to
+      this interpreter.  A FIFOWriter gets tied to the interpreter that
+      called "add_recv_fifo()".
 
       The FIFO's name is set to the provided value.  If no name is
       provided then a dynamically generated one is used.  If a FIFO
       with the given name is already associated with this interpreter
-      or with the one in which "add_fifo()" was called then raise
+      (or with the one in which "add_recv_fifo()" was called) then raise
+      KeyError.
+
+   add_send_fifo(name=None):
+
+      Create a new FIFO, associate the two ends with the involved
+      interpreters, and return the side associated with the interpreter
+      in which "add_recv_fifo()" was called.  A FIFOWriter gets tied to
+      this interpreter.  A FIFOReader gets tied to the interpreter that
+      called "add_recv_fifo()".
+
+      The FIFO's name is set to the provided value.  If no name is
+      provided then a dynamically generated one is used.  If a FIFO
+      with the given name is already associated with this interpreter
+      (or with the one in which "add_send_fifo()" was called) then raise
       KeyError.
 
    remove_fifo(name):
@@ -266,6 +286,12 @@ This suffers from the same problem as sharing objects between
 interpreters via queues.  The minimal solution (running a source string)
 is sufficient for us to get the feature out where it can be explored.
 
+timeout arg to pop() and push()
+-------------------------------
+
+Typically functions that have a ``block`` argument also have a
+``timeout`` argument.  We can add it later if needed.
+
 
 Interpreter Isolation
 =====================