Updates for cancelling handlers and remove_reader/writer/connector.

pep-3156.txt

@@ -371,9 +371,10 @@ i.e. no disk files.
   used to cancel the callback.  Note that, unlike ``call_later()``,
   the callback may be called many times.  Calling ``add_reader()``
   again for the same file descriptor implicitly cancels the previous
-  callback for that file descriptor.  (TBD: Returning a
-  ``Handler`` that can be cancelled seems awkward.  Let's forget
-  about that.)  (TBD: Change this to raise an exception if a handler
+  callback for that file descriptor.  Note: cancelling the handler
+  may be delayed until the handler would be called.  If you plan to
+  close ``fd``, you should use ``remove_reader(fd)`` instead.
+  (TBD: Change this to raise an exception if a handler
   is already set.)
 
 - ``add_writer(fd, callback, *args)``.  Like ``add_reader()``,
@@ -384,8 +385,8 @@ i.e. no disk files.
   currently set for the file descriptor.  (The reason for providing
   this alternate interface is that it is often more convenient to
   remember the file descriptor than to remember the ``Handler``
-  object.)  (TBD: Return ``True`` if a handler was removed, ``False``
-  if not.)
+  object.)  Returns ``True`` if a handler was removed, ``False``
+  if not.
 
 - ``remove_writer(fd)``.  This is to ``add_writer()`` as
   ``remove_reader()`` is to ``add_reader()``.