Small corrections.

pep-3156.txt

@@ -360,8 +360,10 @@ Basic Callbacks
 '''''''''''''''
 
 - ``call_soon(callback, *args)``.  This schedules a callback to be
-  called as soon as possible.  It guarantees that callbacks are called
+  called as soon as possible.  Returns a Handle representing the
-  in the order in which they were scheduled.
+  callback, whose ``cancel()`` method can be used to cancel the
+  callback.  It guarantees that callbacks are called in the order in
+  which they were scheduled.
 
 - ``call_later(delay, callback, *args)``.  Arrange for
   ``callback(*args)`` to be called approximately ``delay`` seconds in
@@ -371,9 +373,10 @@ Basic Callbacks
   time will be called in an undefined order.
 
 - ``call_at(when, callback, *args)``.  This is like ``call_later()``,
-  but the time is expressed as an absolute time.  There is a simple
+  but the time is expressed as an absolute time.  Returns a similar
-  equivalency: ``loop.call_later(delay, callback, *args)`` is the same
+  Handle.  There is a simple equivalency: ``loop.call_later(delay,
-  as ``loop.call_at(loop.time() + delay, callback, *args)``.
+  callback, *args)`` is the same as ``loop.call_at(loop.time() +
+  delay, callback, *args)``.
 
 Note: A previous version of this PEP defined a method named
 ``call_repeatedly()``, which promised to call a callback at regular
@@ -785,11 +788,11 @@ Handles
 -------
 
 The various methods for registering one-off callbacks
-(``call_soon()``, ``call_later()`` and ``call_at()``) all return an
+(``call_soon()``, ``call_later()``, ``call_at()`` and
-object representing the registration that can be used to cancel the
+``call_soon_threadsafe()``) all return an object representing the
-callback.  This object is called a Handle (although its class name is
+registration that can be used to cancel the callback.  This object is
-not necessarily ``Handle``).  Handles are opaque and have only one
+called a Handle (although its class name is not necessarily
-public method:
+``Handle``).  Handles are opaque and have only one public method:
 
 - ``cancel()``.  Cancel the callback.
 
@@ -834,10 +837,10 @@ public API is as follows, indicating the differences with PEP 3148:
   Difference with PEP 3148: The callback is never called immediately,
   and always in the context of the caller.  (Typically, a context is a
   thread.)  You can think of this as calling the callback through
-  ``call_soon()``.  Note that the callback (unlike all other callbacks
+  ``call_soon()``.  Note that in order to match PEP 3148, the callback
-  defined in this PEP, and ignoring the convention from the section
+  (unlike all other callbacks defined in this PEP, and ignoring the
-  "Callback Style" below) is always called with a single argument, the
+  convention from the section "Callback Style" below) is always called
-  Future object, and should not be a Handle object.
+  with a single argument, the Future object.
 
 - ``set_result(result)``.  The Future must not be done (nor cancelled)
   already.  This makes the Future done and schedules the callbacks.
@@ -1312,9 +1315,9 @@ task's exception.
 
 Cancelling a task that's not done yet prevents its coroutine from
 completing.  In this case a ``CancelledError`` exception is thrown
-into the coroutine that it may catch to further handle cancellation.
+into the coroutine, which it may catch to propagate cancellation to
-If the exception is not caught, the generator will be properly
+other Futures.  If the exception is not caught, the generator will be
-finalized anyway, as described in PEP 342.
+properly finalized anyway, as described in PEP 342.
 
 Tasks are also useful for interoperating between coroutines and
 callback-based frameworks like Twisted.  After converting a coroutine