Wordsmithing CHANGES and iwait docstring.

CHANGES.rst

@@ -7,21 +7,21 @@
 1.4.0 (unreleased)
 ==================
 
+- Build with Cython 0.29 in '3str' mode.
+
 - Add support for application-wide callbacks when ``Greenlet`` objects
   are started. See :pr:`1289`, provided by Yury Selivanov.
 
-- It is now possible to consume ready objects using `next(gevent.iwait(objs))`.
-  Previously such a construction would hang. See :pr:`1288`, provided by Josh
+- Fix consuming a single ready object using
+  ``next(gevent.iwait(objs))``. Previously such a construction would
+  hang because `iter` was not called. See :pr:`1288`, provided by Josh
   Snyder. This is not recommended, though, as unwaited objects will
-  have dangling links.
-
-- Build with Cython 0.29 in '3str' mode.
-
+  have dangling links (but see next item).
 
-- There is new documentation on the possibility that `gevent.iwait` can produce
-  memory leaks when not fully consumed. To prevent such situations,
-  `gevent.iwait` now provides optional contextmanager support, which will ensure
-  that all resources are cleaned up. See :pr:`1290`, provided by Josh Snyder.
+- Make `gevent.iwait` return an iterator that can now also be used as
+  a context manager. If you'll only be consuming part of the iterator,
+  use it in a ``with`` block to avoid leaking resources. See
+  :pr:`1290`, provided by Josh Snyder.
 
 
 1.3.7 (2018-10-12)

src/gevent/_hub_primitives.py

@@ -180,10 +180,13 @@ def iwait_on_objects(objects, timeout=None, count=None):
     Iteratively yield *objects* as they are ready, until all (or *count*) are ready
     or *timeout* expired.
 
-    This function allocates resources which must be cleaned up. Consuming the
-    iterator until it is exhausted will automatically clean them up, and it is
-    also possible to use the returned object as a context manager to ensure
-    cleanup occurs.
+    If you will only be consuming a portion of the *objects*, you should
+    do so inside a ``with`` block on this object to avoid leaking resources::
+
+        with gevent.iwait((a, b, c)) as it:
+            for i in it:
+                if i is a:
+                    break
 
     :param objects: A sequence (supporting :func:`len`) containing objects
         implementing the wait protocol (rawlink() and unlink()).