Change the definition of wait_for() to a more useful one.

(This is a change in the spec.  But I don't recall we ever seriously
discussed this part of the spec, and the new behavior is more useful
and more intuitive.  See discussion started by Gustavo Carneiro in
http://code.google.com/p/tulip/issues/detail?id=107 .)

pep-3156.txt

@@ -1582,11 +1582,10 @@ package are provided:
   your ``for`` loop may not make progress (since you are not allowing
   other tasks to run).
 
-- ``asyncio.wait_for(f, timeout)``.  This is a convenience to wait for a
-  single coroutine or Future with a timeout.  It is a simple wrapper
-  around ``asyncio.wait()`` with a single item in the first argument,
-  returning the result or raising the exception if it is completed
-  within the timeout, raising ``TimeoutError`` otherwise.
+- ``asyncio.wait_for(f, timeout)``.  This is a convenience to wait for
+  a single coroutine or Future with a timeout.  When a timeout occurs,
+  it cancels the task and raises TimeoutError.  To avoid the task
+  cancellation, wrap it in shield().
 
 - ``asyncio.gather(f1, f2, ...)``.  Returns a Future which waits until
   all arguments (Futures or coroutines) are done and return a list of