Many edits in the spirit of PR #105.

pep-3156.txt

@@ -148,14 +148,14 @@ wait for a Future to complete by adding a callback to the Future.
 Likewise, the scheduler offers an operation to suspend a coroutine
 until a callback is called.
 
-In case of any other async framework cannot just use Future and Task
-as is for some reason the framework may reimplement
-``loop.create_future()`` and ``loop.create_task()`` calls by returning
-an object which implements a superset of Future/Task interfaces but
-adds a new functionality required by the framework.
+If such a framework cannot use the Future and Task classes as-is, it
+may reimplement the ``loop.create_future()`` and
+``loop.create_task()`` methods.  These should return objects
+implementing (a superset of) the Future/Task interfaces.
 
-``loop.set_task_factory()`` may be useful as well for adopting asyncio
-tasks without implementing own event loop by a framework.
+A less ambitious framework may just call the
+``loop.set_task_factory()`` to replace the Task class without
+implementing its own event loop.
 
 The event loop API provides limited interoperability with threads:
 there is an API to submit a function to an executor (see PEP 3148)
@@ -296,7 +296,7 @@ framework).  The default event loop policy is an instance of the class
 ``DefaultEventLoopPolicy``.  The current event loop policy object can
 be retrieved by calling ``get_event_loop_policy()``.
 
-TBD: decribe child watchers and UNIX quirks for subprocess processing
+TBD: decribe child watchers and UNIX quirks for subprocess processing.
 
 Passing an Event Loop Around Explicitly
 '''''''''''''''''''''''''''''''''''''''
@@ -390,7 +390,7 @@ still better than nothing. :-)
 - Wrapped socket methods: ``sock_recv()``, ``sock_sendall()``,
   ``sock_connect()``, ``sock_accept()``.
 
-- Tasks and futures support: ``create_future()``, ``create_task``,
+- Tasks and futures support: ``create_future()``, ``create_task()``,
   ``set_task_factory()``, ``get_task_factory()``.
 
 - Error handling: ``get_exception_handler()``, ``set_exception_handler()``,
@@ -462,7 +462,8 @@ stopped.  These methods deal with starting and stopping an event loop:
   subsequent calls are no-ops.
 
 - ``is_closed()``.  Returns ``True`` if the event loop is closed,
-  ``False`` otherwise.
+  ``False`` otherwise.  (Primarily intended for error reporting;
+  please don't implement functionality based on this method.)
 
 
 Basic Callbacks
@@ -970,36 +971,36 @@ traceback.  In some cases they are caught and re-raised.  (Examples of
 this category include ``KeyboardInterrupt`` and ``SystemExit``; it is
 usually unwise to treat these the same as most other exceptions.)
 
-The event loop passes caught but not handled exceptions into its
-*exception handler*.  The handler is a callback which accepts
-*context* dict as a parameter::
+The event loop passes the latter category into its *exception
+handler*.  This is a callback which accepts a *context* dict as a
+parameter::
 
    def exception_handler(context):
        ...
 
 *context* may have many different keys but several of them are very
-widely used and present in almost all contexts:
+widely used:
 
 - ``'message'``: error message.
-- ``'exception'``: exception instance, no exception on a stack if the
-  value is ``None``.
-- ``'source_traceback'``: a list of strigs for stack trace on the
-  failed object creation moment.
-- ``'handle_traceback'``: a list of strigs for stack trace on the
-  failed handle creation moment.
+- ``'exception'``: exception instance; ``None`` if there is no
+  exception.
+- ``'source_traceback'``: a list of strings representing stack at the
+  point the object involved in the error was created.
+- ``'handle_traceback'``: a list of strings representing the stack at
+  the moment the handle involved in the error was created.
 
 The loop has the following methods related to exception handling:
 
-- ``get_exception_handler()`` returns the current handler registered
-  in the loop.
+- ``get_exception_handler()`` returns the current exception handler
+  registered for the loop.
 
-- ``set_exception_handler(handler)`` assings new handler.
+- ``set_exception_handler(handler)`` sets the exception handler.
 
-- ``default_exception_handler(context)`` is *default* handler for the
-  loop implementation.
+- ``default_exception_handler(context)`` the *default* exception
+  handler for this loop implementation.
 
 - ``call_exception_handler(context)`` passes *context* into the
-  registered exception handler. The call allows to handle uncaught
+  registered exception handler.  This allows handling uncaught
   exceptions uniformly by third-party libraries.
 
   The loop uses ``default_exception_handler()`` if the default was not
@@ -1008,29 +1009,30 @@ The loop has the following methods related to exception handling:
 Debug Mode
 ----------
 
-By default the loop operates in *release* mode for sake of performance.
-But application may enable *debug* mode.
+By default the loop operates in *release* mode.  Applications may
+enable *debug* mode better error reporting at the cost of some
+performance.
 
-In this mode many additional checks are enabled, for example:
+In debug mode many additional checks are enabled, for example:
 
-- source tracebacks are available for unrolled exceptions in futures/tasks.
+- Source tracebacks are available for unhandled exceptions in futures/tasks.
 
-- loop checks callback execution time for blaming blocking code.
+- The loop checks for slow callbacks to detect accidental blocking for I/O.
 
-  ``loop.slow_callback_duration`` attribute controls maximum execution
-  time for callback or task iteration between two *yield points*. By
-  default the attribute's value is ``0.1`` (100 milliseconds) but it
-  may be tuned by user.
+  The ``loop.slow_callback_duration`` attribute controls the maximum
+  execution time allowed between two *yield points* before a slow
+  callback is reported.  The default value is 0.1 seconds; it may be
+  changed by assigning to it.
 
-There are two methods related to the subject:
+There are two methods related to debug mode:
 
 - ``get_debug()`` returns ``True`` if *debug* mode is enabled,
   ``False`` otherwise.
 
-- ``set_debug(enabled)`` enables *debug* mode if the parameter is ``True``.
+- ``set_debug(enabled)`` enables *debug* mode if the argument is ``True``.
 
-Debug mode is switched on if ``PYTHONASYNCIODEBUG`` *environment
-variable* is defined and not empty.
+Debug mode is automatically enabled if the ``PYTHONASYNCIODEBUG``
+*environment variable* is defined and not empty.
 
 
 Handles
@@ -1745,19 +1747,19 @@ slow things down considerably in the case where one coroutine calls
 another (and so on), as switching to a "bare" coroutine has much less
 overhead than switching to a Task.
 
-A Task is inherited from ``Future`` but adds new methods:
+The ``Task`` class is derived from ``Future`` adding new methods:
 
 - ``current_task(loop=None)``. A *class method* returning the
   currently running task in an event loop.  If *loop* is ``None`` the
-  method returns a current task for default loop.  Every coroutine is
-  executed inside a *task context* either by running it by
-  ``ensure_future()`` / ``loop.create_task()`` call or by calling a
-  nested coroutine by ``await nested()``.  The method may return
-  ``None`` if it's called *outside* of coroutine, e.g. in callback
-  scheduled by ``loop.call_later()``.
+  method returns the current task for the default loop.  Every
+  coroutine is executed inside a *task context*, either a ``Task``
+  created using ``ensure_future()`` or ``loop.create_task()``, or by
+  being called from another coroutine using ``yield from`` or
+  ``await``.  This method returns ``None`` when called *outside* a
+  coroutine, e.g. in a callback scheduled using ``loop.call_later()``.
 
 - ``all_tasks(loop=None)``. A *class method* returning a set of all
-  active tasks for the loop. The method uses default loop if *loop* is
+  active tasks for the loop.  This uses the default loop if *loop* is
   ``None``.