Sprinkle some clarifications and TBDs in response to some private feedback.

pep-3156.txt

@@ -161,6 +161,10 @@ A conforming event loop object has the following methods:
   - No more registered file descriptors.  It is up to the registering
     party to unregister a file descriptor when it is closed.
 
+  Note: run() blocks until the termination condition is met.
+
+  TBD: run() may need an argument to start some work.
+
 - TBD: Do we need an API for stopping the event loop, given that we
   have the termination condition?  Is the termination condition
   compatible with other frameworks?
@@ -191,7 +195,7 @@ A conforming event loop object has the following methods:
   ``isinstance(callback, DelayedCall)``?  It should silently skip
   a canceled callback.
 
-Some methods return Futures:
+Some methods in the standard conforming interface return Futures:
 
 - ``wrap_future(future)``.  This takes a PEP 3148 Future (i.e., an
   instance of ``concurrent.futures.Future``) and returns a Future
@@ -254,6 +258,10 @@ Some methods return Futures:
 
   TBD: Be more specific.
 
+TBD: Some platforms may not be interested in implementing all of
+these, e.g. start_serving() may be of no interest to mobile apps.
+(Although, there's a Minecraft server on my iPad...)
+
 The following methods for registering callbacks for file descriptors
 are optional.  If they are not implemented, accessing the method
 (without calling it) returns AttributeError.  The default
@@ -366,6 +374,7 @@ a ``DelayedCall``, although the user never needs to instantiate
 instances of this class.  There is one public method:
 
 - ``cancel()``.  Attempt to cancel the callback.
+  TBD: Exact specification.
 
 Read-only public attributes:
 
@@ -398,6 +407,7 @@ are slight differences.  The supported public API is as follows,
 indicating the differences with PEP 3148:
 
 - ``cancel()``.
+  TBD: Exact specification.
 
 - ``cancelled()``.
 
@@ -432,6 +442,16 @@ when used in a coroutine.  This is implemented through the
 ``__iter__()`` interface on the Future.  See the section "Coroutines
 and the Scheduler" below.
 
+In the future (pun intended) we may unify ``tulip.Future`` and
+``concurrent.futures.Future``, e.g. by adding an ``__iter__()`` method
+to the latter that works with ``yield from``.  To prevent accidentally
+blocking the event loop by calling e.g. ``result()`` on a Future
+that's not don yet, the blocking operation may detect that an event
+loop is active in the current thread and raise an exception instead.
+However the current PEP strives to have no dependencies beyond Python
+3.3, so changes to ``concurrent.futures.Future`` are off the table for
+now.
+
 Transports
 ----------